# Pug - Open Source Product Analytics > Pug is an affordable, open-source product analytics platform with unified user profiles. It records page views, clicks, scrolls, and custom events and answers questions with trends, funnels, retention cohorts, segmentation, user flows (Sankey), and top-K rankings. Identity resolution merges anonymous and identified activity into a single timeline per user. There are two ways to run it: self-hosted, free forever under AGPL-3.0, or managed cloud (Pug Cloud), free up to 100,000 events a month with no credit card. Past that, Pug Cloud costs $1 a month plus $20 per million events, with the rate falling in graduated tiers to $10 per million past 100 million, so a million events a month comes to $19 in total. There are no per-seat fees and every plan has every feature, so the bill depends only on event volume. SSO is included on every plan of both: Google Workspace, or any OIDC identity provider such as Okta, Microsoft Entra ID, or Keycloak. The backend is Go, PostgreSQL, ClickHouse, NATS, and Connect RPC. Pug is built by Tshoka Pvt Ltd. Six SDKs ship today. The Web SDK (`@pug-sh/browser`, TypeScript) auto-captures page views, clicks, scrolls, form interactions, rage clicks, and dead clicks. The Flutter SDK (`pug_flutter`, Dart) auto-tracks screen views and lifecycle from `init()` and exposes typed methods for the well-known events. The Android SDK (`sh.pug:android` on Maven Central, Kotlin, callable from Java) tracks app opens, activity screen views, and installs on its own, with the same typed methods. The Node SDK (`@pug-sh/node`) handles server-side event tracking, profile identify, and analytics reads; the Ruby SDK (`pug-sh` on RubyGems, Ruby 3.3+) does the same from Rails or plain Ruby, and the Go SDK (`github.com/pug-sh/sdk-go`, Go 1.26+) from Go services. Native iOS and React Native SDKs are in active development. There is no per-framework SDK: every framework integration below uses one of these six. ## Product - [Pug](https://pug.sh/index.md): What Pug captures, the six insight types, the privacy defaults, and the six SDKs, on one page - [Product analytics](https://pug.sh/product-analytics.md): What product analytics is, and how Pug does it - [Analytics](https://pug.sh/analytics.md): The six insight types: trends, funnels, retention, segmentation, user flow, and top-K - [Dashboards](https://pug.sh/analytics-dashboard.md): Dashboards and tiles built from saved insights - [User analytics](https://pug.sh/user-analytics.md): Unified profiles and identity resolution - [Platform](https://pug.sh/platform.md): The event pipeline and architecture end to end - [SDKs](https://pug.sh/sdks.md): Web, Android, Flutter, Node, Go, and Ruby SDKs; native iOS and React Native in development - [MCP server](https://pug.sh/mcp.md): MCP tools over the analytics API, sixteen that read and one that creates and edits dashboards, by signing in to Pug or with a private key - [Pricing](https://pug.sh/pricing.md): Pug Cloud is free up to 100,000 events a month, then pay as you go per event in graduated tiers, with worked monthly bills; self-hosting is free forever; SSO on every plan, with no SSO tax - [Open source](https://pug.sh/open-source-analytics.md): What AGPL-3.0 open-source analytics means in practice - [Self-hosted](https://pug.sh/self-hosted-analytics.md): Running the whole stack on your own infrastructure - [About](https://pug.sh/about.md): Who builds Pug and why (Tshoka Pvt Ltd) - [Support](https://pug.sh/support.md): How to get help: email, docs, Discord, GitHub issues and security reports - [Campaigns](https://pug.sh/campaigns.md): Web push, email, and SMS composed from profiles and events (in active development, not yet available in the dashboard) ## Comparisons Each comparison keeps an honest "where they win" section. - [All comparisons](https://pug.sh/compare.md): Index of every comparison page - [PostHog alternative](https://pug.sh/compare/posthog-alternative.md): Pug vs PostHog - [Mixpanel alternative](https://pug.sh/compare/mixpanel-alternative.md): Pug vs Mixpanel - [Amplitude alternative](https://pug.sh/compare/amplitude-alternative.md): Pug vs Amplitude - [Heap alternative](https://pug.sh/compare/heap-alternative.md): Pug vs Heap - [Plausible alternative](https://pug.sh/compare/plausible-alternative.md): Pug vs Plausible - [Matomo alternative](https://pug.sh/compare/matomo-alternative.md): Pug vs Matomo - [Umami alternative](https://pug.sh/compare/umami-alternative.md): Pug vs Umami - [Segment alternative](https://pug.sh/compare/segment-alternative.md): Pug vs Segment - [Google Analytics alternative](https://pug.sh/compare/google-analytics-alternative.md): Pug vs Google Analytics 4 - [Google Analytics replacement](https://pug.sh/compare/google-analytics-replacement.md): Replacing GA4, step by step - [Firebase Analytics alternative](https://pug.sh/compare/firebase-analytics-alternative.md): Pug vs Firebase Analytics on the mobile (Flutter and Android) angle, not a Firebase platform replacement - [Aptabase alternative](https://pug.sh/compare/aptabase-alternative.md): Pug vs Aptabase, also AGPL-3.0 and self-hostable; the difference is identity, not openness - [Countly alternative](https://pug.sh/compare/countly-alternative.md): Pug vs Countly: open Lite edition vs paid editions, and Countly's modified AGPL ยง7 branding clause ## Integrations - [All integrations](https://pug.sh/integrations.md): Index of every integration guide - [Next.js](https://pug.sh/integrations/nextjs.md): App Router setup with the Web SDK, including the page-view caveat - [React](https://pug.sh/integrations/react.md): Web SDK in a React app - [Vue](https://pug.sh/integrations/vue.md): Web SDK in a Vue app - [Node.js](https://pug.sh/integrations/nodejs.md): Trusted server-side events with the Node SDK - [Flutter](https://pug.sh/integrations/flutter.md): Auto-tracking and typed events with the Flutter SDK - [Android](https://pug.sh/integrations/android.md): Native Kotlin SDK: automatic lifecycle, screen, and install events, typed events, and consent ## Use cases - [All use cases](https://pug.sh/use-cases.md): Index of every use-case page - [SaaS](https://pug.sh/use-cases/saas.md): Activation funnels, retention cohorts, and a profile per account - [Mobile apps](https://pug.sh/use-cases/mobile-apps.md): Flutter and Android SDKs today, install-week retention, onboarding funnels; iOS and React Native in development - [Ecommerce](https://pug.sh/use-cases/ecommerce.md): Checkout funnel, standard commerce events, repeat-purchase retention ## Free tools Every tool runs entirely in the browser. No signup, no data leaves the page. A tool's `.md` mirror carries its explanation and FAQ; the tool itself is on the page. - [All tools](https://pug.sh/tools.md): Index of every free tool - [UTM builder](https://pug.sh/tools/utm-builder.md): Build trackable campaign URLs with consistent UTM parameters - [A/B test calculator](https://pug.sh/tools/ab-test-calculator.md): Sample-size planner and significance checker - [Conversion rate calculator](https://pug.sh/tools/conversion-rate-calculator.md): Visitors and conversions to a rate, plus the traffic needed for a target - [Funnel calculator](https://pug.sh/tools/funnel-calculator.md): Step conversion, drop-off, and overall funnel rate - [Retention rate calculator](https://pug.sh/tools/retention-rate-calculator.md): Retention rate, churn, and implied customer lifetime - [Cohort retention visualizer](https://pug.sh/tools/cohort-retention-visualizer.md): Render cohort retention as a heatmap curve - [Analytics cost calculator](https://pug.sh/tools/analytics-cost-calculator.md): Estimate Mixpanel, Amplitude, and Segment cost at your event volume, next to Pug Cloud's exact rates and $0 self-hosted Pug - [CLV calculator](https://pug.sh/tools/clv-calculator.md): Customer lifetime value from ARPU, margin, and churn - [CAC calculator](https://pug.sh/tools/cac-calculator.md): Customer acquisition cost, LTV:CAC ratio, and payback period - [NPS calculator](https://pug.sh/tools/nps-calculator.md): Net Promoter Score from promoter, passive, and detractor counts - [Event tracking plan generator](https://pug.sh/tools/event-tracking-plan-generator.md): A tracking plan with real event names, typed properties, and PII flags - [Event naming linter](https://pug.sh/tools/event-naming-linter.md): Check event names against a snake_case object_action convention - [PII event auditor](https://pug.sh/tools/pii-event-auditor.md): Flag event properties that likely carry PII under GDPR - [UUID generator](https://pug.sh/tools/uuid-generator.md): Generate and inspect v4, v7, v1/v6, and deterministic v3/v5 UUIDs - [OG preview](https://pug.sh/tools/og-preview.md): Preview a URL's Open Graph and Twitter Card share cards ## Glossary Plain-English definitions of product-analytics concepts. - [Glossary index](https://pug.sh/glossary.md): Every term - [Autocapture](https://pug.sh/glossary/autocapture.md): Collecting events without instrumenting each one by hand - [Funnel analysis](https://pug.sh/glossary/funnel-analysis.md): Measuring step-by-step conversion through an ordered sequence - [Retention cohort](https://pug.sh/glossary/retention-cohort.md): Grouping users by start period to measure how many return - [User flow analysis](https://pug.sh/glossary/user-flow-analysis.md): Mapping the paths people actually take through a product - [Unified customer profile](https://pug.sh/glossary/unified-customer-profile.md): One record per person across sources, sessions, and devices - [Event tracking](https://pug.sh/glossary/event-tracking.md): Recording user actions as named events with typed properties - [Identity resolution](https://pug.sh/glossary/identity-resolution.md): Merging anonymous and identified activity into one person - [PII](https://pug.sh/glossary/pii.md): What counts as personally identifiable information in an event stream - [Bot traffic](https://pug.sh/glossary/bot-traffic.md): Automated visits, how they are detected, and tag vs drop - [Session](https://pug.sh/glossary/session.md): One continuous visit, and the inactivity rules that bound it - [Bounce rate](https://pug.sh/glossary/bounce-rate.md): Single-interaction sessions, and the two competing definitions - [UTM parameters](https://pug.sh/glossary/utm-parameters.md): The five link tags and the naming rules that keep them usable - [Marketing attribution](https://pug.sh/glossary/attribution.md): Channel classification, credit models, and why Direct is large - [Conversion rate](https://pug.sh/glossary/conversion-rate.md): The share of users who complete a target action - [Churn rate](https://pug.sh/glossary/churn-rate.md): The share of users or revenue lost over a period - [Active users](https://pug.sh/glossary/active-users.md): DAU, WAU, and MAU, and how each is counted - [North star metric](https://pug.sh/glossary/north-star-metric.md): The single metric that best captures delivered value ## Learn Concepts, roundups, and benchmarks. - [Learn index](https://pug.sh/learn.md): The whole Learn library - [Open-source product analytics](https://pug.sh/learn/open-source-product-analytics.md): What it is and what the licenses actually mean - [Product analytics vs web analytics](https://pug.sh/learn/product-analytics-vs-web-analytics.md): Two different questions, two different tools - [Event tracking with open source](https://pug.sh/learn/event-tracking-open-source.md): Designing an event schema you can live with - [Privacy-first analytics](https://pug.sh/learn/privacy-first-analytics.md): Measuring product usage without collecting more than you need - [Cookieless analytics](https://pug.sh/learn/cookieless-analytics.md): How rotating identifiers differ from fingerprinting - [Best cookieless analytics tools](https://pug.sh/learn/best-cookieless-analytics-tools.md): Roundup, compared by salt-rotation period - [Cookieless vs fingerprinting](https://pug.sh/learn/cookieless-vs-fingerprinting.md): Where ePrivacy Art. 5(3) actually applies - [Cookieless funnels and retention](https://pug.sh/learn/cookieless-funnels-and-retention.md): What daily-rotating identity costs your multi-day reports - [What an analytics MCP server does](https://pug.sh/learn/mcp-analytics-server.md): Tools, schema discovery, and what should never be agent-callable - [How to filter bot traffic in GA4](https://pug.sh/learn/filter-bot-traffic-ga4.md): What GA4's always-on bot filter catches, and what runs your tag anyway - [Bot traffic, funnels and retention](https://pug.sh/learn/bot-traffic-funnels-retention.md): How automated traffic biases each product metric, and which way - [AI crawlers and your analytics](https://pug.sh/learn/ai-crawlers-analytics.md): GPTBot and ClaudeBot don't execute JavaScript, so they never reach the tag - [How analytics tools filter bots](https://pug.sh/learn/analytics-bot-filtering-compared.md): Roundup: which signals each tool trusts, and drop vs tag - [The DPDP Act and analytics](https://pug.sh/learn/dpdp-act-analytics.md): India's data protection law, applied to product analytics - [GDPR analytics compliance](https://pug.sh/learn/gdpr-analytics.md): Lawful basis, consent, retention, and data subject rights - [CCPA analytics compliance](https://pug.sh/learn/ccpa-analytics.md): Opt-out rights, sale vs sharing, and Global Privacy Control - [Free analytics for startups](https://pug.sh/learn/free-analytics-for-startups.md): What is genuinely free, and where the free tiers stop - [Heap pricing explained](https://pug.sh/learn/heap-pricing.md): How the session-based model prices out - [Product analytics for mobile apps](https://pug.sh/learn/product-analytics-for-mobile-apps.md): What to measure in an app, and why - [Best Firebase Analytics alternatives](https://pug.sh/learn/best-firebase-analytics-alternatives.md): Roundup: GA4 is the same backend, not an escape - [Best product analytics tools](https://pug.sh/learn/best-product-analytics-tools.md): Roundup of the main options - [Best open-source analytics tools](https://pug.sh/learn/best-open-source-analytics-tools.md): Roundup, by license and hosting model - [Best self-hosted analytics](https://pug.sh/learn/best-self-hosted-analytics.md): Roundup, by what it takes to actually run - [Best PostHog alternatives](https://pug.sh/learn/best-posthog-alternatives.md): Roundup - [Best Mixpanel alternatives](https://pug.sh/learn/best-mixpanel-alternatives.md): Roundup - [What is a good retention rate?](https://pug.sh/learn/good-retention-rate.md): Benchmarks by product type - [What is a good conversion rate?](https://pug.sh/learn/good-conversion-rate.md): Benchmarks by funnel stage - [LTV:CAC ratio explained](https://pug.sh/learn/ltv-cac-ratio.md): How to compute it and what the number means - [What is a good NPS score?](https://pug.sh/learn/nps-benchmarks.md): Benchmarks by industry ## Blog Engineering and SDK deep-dives. - [Blog index](https://pug.sh/blog.md): Every post - [Inside the Pug Web SDK](https://pug.sh/blog/web-analytics-sdk.md): How autocapture and batching work - [Reliable event delivery](https://pug.sh/blog/reliable-event-delivery.md): Retries, unload beacons, and not losing events - [Well-known events](https://pug.sh/blog/well-known-events.md): Why standard event names beat bespoke naming - [Product analytics for developers](https://pug.sh/blog/product-analytics-for-developers.md): Instrumenting a product without a data team - [Cookieless identity and the self-deleting salt](https://pug.sh/blog/cookieless-identity-daily-rotating-salt.md): How the daily-rotating salt works - [Server-side event tracking in Ruby and Rails](https://pug.sh/blog/ruby-event-tracking.md): The `pug-sh` gem: a track call that never blocks or raises, well-known events validated in-process, fork-safe batching under Puma ## Guides - [All guides](https://pug.sh/guides.md): Index of every guide - [Self-hosting setup](https://pug.sh/guides/self-hosted-analytics-setup.md): Step-by-step self-hosted install - [Migrate from Heap to Pug](https://pug.sh/guides/migrate-from-heap-to-pug.md): Inventory reports, swap the SDK, dual-run, rebuild insights ## Pricing Pug is affordable: self-hosting is free, and Pug Cloud is free up to 100,000 events a month, with every feature and no credit card. Past that, the Pay as you go plan is a $1 monthly fee plus usage, billed per event in graduated tiers: each tier bills only the events inside it, so reaching a new tier never reprices the events below it, and the rate falls as volume grows. Prices are in US dollars. | Events per month | Price per million events | |---|---| | First 100k | Free | | 100k to 1M | $20 | | 1M to 3M | $18 | | 3M to 10M | $16 | | 10M to 30M | $14 | | 30M to 100M | $12 | | Over 100M | $10 | The whole monthly bill, fee included: | Events per month | Monthly bill | |---|---| | 100,000 | $0 | | 500,000 | $9 | | 1,000,000 | $19 | | 5,000,000 | $87 | | 20,000,000 | $307 | | 100,000,000 | $1,287 | There are no per-seat or per-project fees: members are free, and every project in an organization shares the one allowance. Every plan has every feature, SSO included. Past the free allowance no event is dropped, throttled, or delayed: the dashboard shows a banner and an admin can subscribe. Pay as you go keeps 5 years of history (1 year on the free allowance), is billed monthly, and can be cancelled at any time in the billing portal; the organization then returns to the free allowance and keeps its events. Very high volume, longer history, or an annual contract gets a custom plan with its own rates: email hello@pug.sh. Self-hosting is free forever under AGPL-3.0, with every feature and no event limits: the only cost is the servers it runs on. ## Quickstart Six SDKs ship today: Web (browser), Android and Flutter (mobile), and Node, Go, and Ruby (server). Every framework integration uses one of these six: there is no per-framework SDK. Native iOS and React Native SDKs are in active development; until they ship, iOS means Flutter. Two key types. A **public** key (`pub_`) ships inside client code and can only write events. A **private** key (`prv_`) is server-side only and can also read: profiles, insight queries, and the MCP server below. Never put a private key in a browser bundle or a mobile app. Web: `@pug-sh/browser`, TypeScript. Autocaptures page views, clicks, scrolls, form interactions, rage clicks, and dead clicks after one `init()`: ```bash npm install @pug-sh/browser ``` ```ts import { init, identify, track } from '@pug-sh/browser' init('your-project-id', { apiKey: 'pub_your_key' }) identify('user_123', { email: 'ada@example.com', plan: 'pro' }) track('signup', { plan: 'pro' }) track('order_completed', { amount: 49.0, currency: 'USD' }) ``` Mobile (Android): `sh.pug:android` on Maven Central, Kotlin (callable from Java), minSdk 21. Call `Pug.init` once in `Application.onCreate`: app opens, activity screen views, and installs are tracked from there, and typed methods cover the well-known events. Consent is granted by default; there is no cookieless mode on Android. ```kotlin // app/build.gradle.kts dependencies { implementation("sh.pug:android:0.1.0") } ``` ```kotlin import sh.pug.android.Options import sh.pug.android.Pug Pug.init(this, "your-project-id", Options("pub_your_key")) Pug.identify("user_123", mapOf("plan" to "pro")) Pug.track.purchase(amount = 49.0, currency = "USD") Pug.screen("Settings") // composables and fragments are not activities ``` Mobile (Flutter): `pug_flutter`, Dart. Auto-tracks screen views and lifecycle from `init()`, with typed methods for the well-known events: ```bash flutter pub add pug_flutter ``` ```dart import 'package:pug_flutter/pug_flutter.dart'; await Pug.init('your-project-id', const PugOptions(apiKey: 'pub_your_key')); await Pug.identify('user_123', traits: {'plan': 'pro'}); Pug.track.signup(extras: {'plan': 'pro'}); ``` Server (Node): `@pug-sh/node`. Trusted events name the user explicitly (no ambient session), and a private key can read back: ```bash npm install @pug-sh/node ``` ```ts import { Pug } from '@pug-sh/node' const pug = new Pug({ apiKey: process.env.PUG_API_KEY }) // private key, prv_... pug.track('user_123', 'order_completed', { amount: 49.0, currency: 'USD' }) await pug.identify('user_123', { email: 'ada@example.com', plan: 'pro' }) const profile = await pug.profiles.getByExternalId('user_123') ``` Server (Go): `github.com/pug-sh/sdk-go`, Go 1.26+, imported as package `pug`. The same model as Node. `pug.New` returns an error for a missing or non-`prv_` key. `Track` and `Identify` never fail or block: background goroutines send them in batches, so create one client (it is safe for concurrent use) and `Close` it on shutdown, which drains the queues. Properties are typed fields (`pug.String`, `pug.Float`, ...), a kind held in a string variable needs `pug.Kind(name)`, and reads return a `*pug.Error` that `errors.Is` matches to a sentinel per status code: ```bash go get github.com/pug-sh/sdk-go ``` ```go import pug "github.com/pug-sh/sdk-go" client, err := pug.New(pug.Options{APIKey: os.Getenv("PUG_API_KEY")}) // private key, prv_... if err != nil { log.Fatal(err) } defer client.Close(context.Background()) client.Track("user_123", "order_completed", pug.Float("amount", 49.0), pug.String("currency", "USD")) client.Identify("user_123", pug.Email("ada@example.com"), pug.String("plan", "pro")) profile, err := client.Profiles.GetByExternalID(context.Background(), "user_123") switch { case errors.Is(err, pug.ErrNotFound): log.Print("no profile for user_123 yet") case err != nil: log.Print(err) default: log.Print(profile.GetId()) } ``` A well-known event can also take its generated schema, so its fields are checked at compile time: ```go import commoneventsv1 "github.com/pug-sh/sdk-go/gen/common/events/v1" client.TrackWellKnown("user_123", &commoneventsv1.PurchaseProperties{ Amount: proto.Float64(49), Currency: proto.String("USD"), }) ``` Server (Ruby): `pug-sh`, Ruby 3.3+. The same model as Node, loaded as `pug`. `track` never blocks or raises, and one client is shared by every thread: ```bash bundle add pug-sh ``` ```ruby require "pug" pug = Pug::Client.new(api_key: ENV.fetch("PUG_API_KEY")) # private key, prv_... pug.track("user_123", "order_completed", amount: 49.0, currency: "USD") pug.identify("user_123", email: "ada@example.com", plan: "pro") profile = pug.profiles.get_by_external_id("user_123") ``` In Rails, create the client once in an initializer. The guard skips it during `assets:precompile`, which boots without credentials (the client raises without a key), and `close` drains buffered events on exit: ```ruby # config/initializers/pug.rb unless ENV["SECRET_KEY_BASE_DUMMY"] PUG = Pug::Client.new(api_key: Rails.application.credentials.pug_api_key, logger: Rails.logger) at_exit { PUG.close(timeout: 5) } end ``` There is also a raw HTTP API if none of the six fit: see https://docs.pug.sh/api/index.md. ## MCP server Pug serves its analytics API as a Model Context Protocol server, so an agent can run an insight, browse the raw event stream, or look up one user without writing the query. It can also create and edit dashboards; no other tool writes. | Environment | Endpoint | |-------------|----------| | Pug Cloud | `https://api.pug.sh/mcp` | | Self-hosted | `http://localhost:3000/mcp` (same host and port as the rest of the API) | Transport is streamable HTTP in stateless mode, so the client needs remote-server support. There is no stdio bridge. Use `api.pug.sh` for MCP even though the HTTP API is at `api.pugs.dev`: signing in works only at `api.pug.sh`. Authentication is **signing in to Pug or a private key**. A client that supports MCP sign-in (OAuth), such as Claude Code or ChatGPT, needs only the URL and no key: the person clicks Allow on a Pug page, and the connection reads every project in the orgs they belong to when they connect, acting with their role in each, so it edits dashboards only where they are a member or an admin. Each call names its project as `project_id`, from `list_projects`. They can disconnect it under Settings > AI connections, and a connection unused for 90 days expires. A client signs in by identifying itself with a client ID metadata document; Pug offers no dynamic client registration. On a self-hosted server, signing in needs `PUG_API_BASE_URL` set and an https `PUG_DASHBOARD_BASE_URL`. A client that can't sign in sends a private key, either way: ```http Authorization: Bearer prv_YOUR_PRIVATE_KEY ``` ```http x-api-key: prv_YOUR_PRIVATE_KEY ``` The key resolves the project, so there is no project ID in the config. A key has no role: it reads its project and can edit that project's dashboards. Public keys (`pub_`) and dashboard JWTs are both rejected with `401`. In Claude's apps (claude.ai, Desktop and mobile), Pug is listed in the connectors directory at https://claude.ai/directory/pug, so there is nothing to configure: go to Customize > Connectors, select Discover, search for Pug, select Connect to Claude, and click Allow on the Pug page. The listing connects to Pug Cloud; a self-hosted server is added as a custom connector by its URL. In ChatGPT, Pug is listed among the plugins at https://chatgpt.com/plugins/plugin_asdk_app_6af72bdabb608191b3fcd1b20baa12bc: go to Plugins, search for Pug, select Install plugin, and click Allow on the Pug page. The listing connects to Pug Cloud; a self-hosted server is added as a custom MCP server by its URL. Add it to Claude Code, then run `/mcp` to sign in: ```bash claude mcp add --transport http pug https://api.pug.sh/mcp ``` Or with a private key: ```bash claude mcp add --transport http pug https://api.pug.sh/mcp \ --header "Authorization: Bearer prv_YOUR_PRIVATE_KEY" ``` The tools: - Projects: `list_projects` names the projects the connection reads, and every other tool takes one of their ids as `project_id`. A private key lists only its own. - Discovery, call these before querying: `get_insights_filter_schema`, `get_insights_property_values`, and their `get_activity_*` aliases. They report which event kinds and property keys actually exist, which is what stops a query from being invented. - Project-wide: `query_insights` (trends, funnel, retention, segmentation, user flow, top-K, map; chosen by `insight_type`) and `explore_events` (a paginated, filterable page of raw events). - One user at a time: `get_profile` / `get_profile_by_external_id` to look up, then `get_activity_feed`, `get_activity_heatmap`, `get_profile_sessions`, `get_profile_stats`. - Dashboards: `list_dashboards`, `get_dashboard`, and `upsert_dashboard`, which creates a dashboard or edits one: rename it, change its time range, and add, change or remove tiles. It is the only tool that writes. An edit carries the `update_time` it last read and fails rather than overwrite a newer change, tiles the call leaves out stay, and it can't delete or share a dashboard. It is marked destructive, so Claude asks before each call unless the person always allows it. - Compliance: `get_deletion_request` reads the status of an erasure request. Deliberately not exposed: profile erasure (`Delete`, `DeleteDataSubject`) is irreversible and stays a human action through the dashboard or the Profiles API; deleting or sharing a dashboard, ingest, identity, and project management are out of scope. `/mcp` serves the reads and dashboard editing only. Full setup for Claude connectors, ChatGPT, Claude Code, Codex, Cursor, and VS Code: https://docs.pug.sh/mcp/index.md ## Agent guidance When helping someone with Pug: 1. Use the MCP server when the task is answering a question about their data; use an SDK when the task is instrumenting their app. 2. Call a filter-schema tool before `query_insights`: property keys vary by project, and a guessed key returns nothing rather than an error. 3. Use `query_insights` for aggregate questions. The per-user tools describe one person and cannot answer "how many". 4. Put the public key (`pub_`) in client code and the private key (`prv_`) only on a server or in an MCP client's config. Never inline a private key into a config file that gets committed. Issue a dedicated key per client so one can be revoked without breaking the others. An MCP client that can sign in to Pug needs no key at all. 5. Do not expose API keys in chat. 6. Never call profile erasure on a user's behalf unless they explicitly ask; it is irreversible and reaches every derived rollup. 7. Create or edit a dashboard only when the person asks for one, and remove a tile only when they ask; `upsert_dashboard` is the only MCP tool that writes. 8. A pug.sh link above that ends in `.md` is the Markdown mirror of the page at the same URL without `.md` (`/index.md` is the home page): read the mirror, cite the page. Every page on pug.sh has one, and https://pug.sh/llms-full.txt holds them all at once except the section indexes. A docs.pug.sh page serves its Markdown at `/index.md` under its URL. 9. Quote Pug Cloud prices from the Pricing section above or https://pug.sh/pricing.md rather than from memory. There are no per-seat fees and every plan has every feature, so a bill depends only on event volume. Self-hosting is free under AGPL-3.0. 10. Campaigns (web push, email, SMS) is in active development and not available in the dashboard: do not present it as shippable. 11. SSO is on every plan: Google Workspace, or any OIDC identity provider (Okta, Entra ID, Keycloak). Pug has no SAML and no SCIM: do not suggest either. Setup lives under Settings > SSO & domains in the dashboard. ## Docs and code - [Documentation](https://docs.pug.sh/index.md): SDK reference, self-hosting, and the API - [Web SDK reference](https://docs.pug.sh/sdks/web/index.md): `@pug-sh/browser`: init, autocapture, consent, identify, and track - [Android SDK reference](https://docs.pug.sh/sdks/android/index.md): `sh.pug:android`: init, automatic lifecycle, screen and install events, consent, typed well-known events, and the Java API - [Flutter SDK reference](https://docs.pug.sh/sdks/flutter/index.md): `pug_flutter`: init, auto-tracked screens and lifecycle, typed well-known events - [Node SDK reference](https://docs.pug.sh/sdks/node/index.md): `@pug-sh/node`: server-side track and identify with a private key, plus profile and insight reads - [Go SDK reference](https://docs.pug.sh/sdks/go/index.md): `github.com/pug-sh/sdk-go`: server-side track and identify with a private key, typed properties and well-known events, plus profile, activity, and insight reads - [Ruby SDK reference](https://docs.pug.sh/sdks/ruby/index.md): `pug-sh`: the Rails initializer, server-side track and identify with a private key, visitor location, plus profile and insight reads - [Docs index for agents](https://docs.pug.sh/llms.txt): The documentation corpus in this same format, linking each page's Markdown at `/index.md` under its URL - [MCP server](https://docs.pug.sh/mcp/index.md): Analytics tools for an agent, plus dashboard editing, reached by signing in to Pug or with a private API key - [SSO & domains](https://docs.pug.sh/get-started/sso/index.md): Google Workspace and OIDC sign-in, verified domains, auto-join, and Require SSO; no SAML or SCIM - [Roadmap](https://docs.pug.sh/roadmap/index.md): What is shipping next - [GitHub](https://github.com/pug-sh/pug): The AGPL-3.0 source - [App](https://app.pug.sh): Sign in or start free - [Live demo](https://demo.pug.sh): The dashboard with real data, no signup - [Discord](https://discord.gg/kDNHDWcBHP): Community support - [Tshoka Pvt Ltd](https://tshoka.com): The company behind Pug ## Optional - [Features, machine-readable](https://pug.sh/features.md): What ships today, what does not, and what is in development, as structured Markdown for agents - [Full content](https://pug.sh/llms-full.txt): Every page except the section indexes, as one Markdown document - [All posts feed](https://pug.sh/rss.xml): RSS for every guide and post - [Sitemap](https://pug.sh/sitemap.xml): Every indexable URL - [Privacy policy](https://pug.sh/privacy.md): What this site and the product collect - [Terms of service](https://pug.sh/terms.md): Terms for the managed cloud