# Changelogs
Source: https://docs.mixpanel.com/changelogs



Get all the latest updates in your inbox.

<SubscribeButtonWithModal />

<Update label="2026-08-07">
  ## Session Replay: Mobile Autocapture (Screen Views)

  Mobile teams can now autocapture screen view and screen leave events across our React Native, Swift, Android, and Flutter SDKs, with a one-time setup instead of per-screen instrumentation.

  Previously, autocapture was only available in our JS SDK. Mobile teams had no low-lift way to start capturing behavior, so getting basic screen-level data meant hand-instrumenting a track call on every screen, in every SDK, before they could answer even simple "which screens do people visit" questions.

  Autocapture hooks into your routing library, so screen view and screen leave events fire automatically after a one-time setup, with no per-screen tracking code. Teams get screen-level navigation data on mobile from a single integration with their router, with no ongoing per-screen tracking to write or maintain.

  Live across all four mobile SDKs:

  * [React Native](/docs/tracking-methods/sdks/react-native#autocapture)
  * [Swift](/docs/tracking-methods/sdks/swift#autocapture)
  * [Android](/docs/tracking-methods/sdks/android#autocapture)
  * [Flutter](/docs/tracking-methods/sdks/flutter#autocapture)
</Update>

<Update label="2026-07-28">
  ## AI-Powered Data Governance: merge suggestions for duplicate events and properties

  Over time, the same concept often ends up tracked under several names — `Add to Cart`, `add_to_cart`, and `addToCart`, or `from_date` and `from-date`. These duplicates clutter Lexicon, split your data across reports, and make analysis harder. Mixpanel can now automatically discover these potential duplicates for you, so you no longer have to hunt for them by hand.

  With this update, you can:

  * **Automatically discover duplicates:** From **Lexicon → Tidy Up**, Mixpanel surfaces groups of near-duplicate events and event properties in your project — no manual searching required.
  * **Clean up in bulk:** Every suggested group comes with a canonical name and is selected by default, so you can review the list and merge them all in one submission instead of pair by pair.
  * **Stay in control:** Merges behave exactly like a manual Lexicon merge — the raw data is unaffected and the action can be undone. Unselected groups are dismissed on submit so they won't be suggested again.

  Merge suggestions cover events and event properties (not user/profile properties) and are available to organizations on an Enterprise plan with AI features enabled.

  [Learn more →](/docs/data-governance/ai-powered-data-governance#merge-suggestions)
</Update>

<Update label="2026-07-26">
  ## Mixpanel Agent updates

  A roundup of more recent updates to Mixpanel Agent based on what you've been telling us.

  **Retention curves:** Mixpanel Agent now builds retention curves by default for retention analysis.

  **Cohorts saved automatically:** Cohorts the Agent creates are now saved to Lexicon, making it easy to use Agent cohorts.

  **Board date ranges:** When you ask the Agent to create a report from a Board, it uses the date range you're already viewing. Data stays consistent when you add the report to the board.

  **Artifacts:** Everything the Agent generates now appears in an Artifacts section at the bottom of the response. Reports, cohorts, custom properties, all in one place.

  **Lookup table properties:** The Agent can now find and use lookup table properties in analysis.

  **Answers grounded in Mixpanel Docs:** When you ask the Agent how Mixpanel works, it pulls from the actual documentation.

  **More types of page context:** The Agent now knows what you're looking at on Users and Events pages, so you can use it in more places.
</Update>

<Update label="2026-07-23">
  ## Mixpanel Agent now works in the background

  Close the tab. Lose your connection. Start a new conversation. The Agent keeps going.

  Now you can send off a question to the Agent, go about your day, and the answer will be waiting whenever you're ready.
</Update>

<Update label="2026-07-20">
  ## MCP: New Tools added

  Several new tools are now generally available on MCP Server.

  Note that to access the new tools you need to disconnect and reconnect Mixpanel MCP to authorize the new scopes.

  **Cohorts**:

  * `Create-Cohort`
  * `Get-Cohort`
  * `Update-Cohort`
  * `Delete-Cohort`
  * `List-Cohorts`
  * `Describe-Cohort-Schema`

  **Lookup Tables**:

  * `Create-Lookup-Table`
  * `Get-Lookup-Table`
  * `Update-Lookup-Table`

  **Custom Properties**:

  * `Create-Custom-Property`
  * `Get-Custom-Property`
  * `Update-Custom-Property`

  **Duplicate/entity merging**:

  * `Find-Duplicate-Groups`
  * `Dismiss-Duplicate-Group`
  * `Merge-Group`

  **Experiments additions**:

  * `Explain-Experiment-Health-Check`
  * `Run-Experiment-Pre-Launch-Checks`
  * `Search-Prior-Experiments`

  See the full list of tools in the [MCP Server documentation](/docs/mcp#available-tools).
</Update>

<Update label="2026-07-17">
  ## Destinations: a simpler way to send data out of Mixpanel

  We've reworked the Integrations page to make it easier to create and manage Destinations, Cohort Syncs, and Data Pipelines.

  With this update:

  * **"Integrations" is now "Destinations":** The new name makes the page's purpose clearer — it's for connecting data flowing out of Mixpanel — and reduces confusion for users who came looking for ways to bring data in.
  * **Destinations lives in the Data menu:** Find it under **Data → Destinations** in the main nav. It's still available in the settings menu for now, but that entry point will be removed eventually.
  * **Onboard cohort syncs directly from Destinations:** No more bouncing between the Integrations page and Lexicon. Open a connected destination, go to the **Syncs** tab, and click **Add Cohort Sync**. Onboarding from Lexicon still works.
  * **Separate views for connected and available destinations:** Your connected destinations and the full library are now split, making it easier to see what's already connected and to add something new.

  [Learn more →](/docs/cohort-sync)
</Update>

<Update label="2026-07-14">
  ## Passkeys

  You can now sign in to Mixpanel with a passkey - no password and no one-time code. Register a passkey once and authenticate with the same Touch ID, Face ID, Windows Hello, or hardware security key you already use to unlock your device.

  Passkeys are built on the WebAuthn/FIDO2 standard. The credential never leaves your device and is cryptographically bound to Mixpanel's domain, so it can't be phished, replayed, or used on a fake login page.

  With this update, you can:

  * **Sign in without a password:** Enable "skip password" for a fully passwordless login (org-mandated SSO still applies)
  * **Manage your passkeys:** Register, name, and remove passkeys from Personal Settings, one per device
  * **Stay covered if you lose a device:** Generate single-use recovery codes to sign in when you can't present a passkey

  [Learn more →](/docs/access-security/login-methods#passkey-login)
</Update>

<Update label="2026-07-10">
  ## Feature Flags: React Native SDK

  Feature flagging is now generally available in the main React Native SDK (v3.5.0), with full parity to native iOS and Android.

  Previously, React Native customers had no supported native way to use feature flags — flags were beta-only and limited to JavaScript mode (Expo and RN Web), so teams on the main SDK couldn't gate features or run flag-based experiments.

  With this update, you can:

  * **Use flags across all RN modes:** Feature flagging works whether you're on the main React Native SDK, Expo, or RN Web.
  * **Get full native parity:** Evaluation, variant assignment, and automatic exposure tracking all work the same as they do on native iOS and Android.
  * **Gate features and run experiments:** Ship rollouts and flag-based experiments in React Native apps using the same workflow as the rest of your stack.

  Available in React Native SDK v3.5.0. [Learn more →](/docs/tracking-methods/sdks/react-native/react-native-flags)
</Update>

<Update label="2026-06-26">
  ## **Share Mixpanel Agent chats**

  Now you can send a link to any Agent chat and let your team read exactly what you asked and what it found.

  Chats are private by default. When you're ready to share, click the chat name and select "Share link."

  [Learn more →](/docs/mixpanel-agent#sharing)
</Update>

<Update label="2026-06-25">
  ## Introducing Mixpanel Agent: your always-on product analyst

  <Frame>
    <img alt="Introducing Mixpanel Agent: your always-on product analyst" />
  </Frame>

  Mixpanel Agent is now available for your team. It's an always-on product analyst that answers questions about your data in plain language, automatically investigates metric changes, and keeps you informed on the numbers you own.

  **Three ways to start using it today:**

  * **Self-serve answers:** Ask anything about your product and get an answer in seconds. No query builder, no data team required. *Try asking:*
    * *"How many users signed up for a trial last month"*
    * *"Summarize the insights from this analysis and give me top 3 takeaways."*
    * *"Build a dashboard for this new feature launch"*
  * **Root cause analysis:** When a metric moves unexpectedly, Mixpanel Agent automatically investigates the likely drivers and helps you get to the bottom of it. 
    * *Try asking: "Why did my activation rate drop last week?"*
  * **KPI monitoring:** Set up a monitor for any metric you own and Mixpanel Agent will surface what moved on your schedule, whether that’s daily, weekly, or monthly. 
    * *Try it: Open Automations and set up a monitor for a key metric you own today.*

  [Get started →](https://mixpanel.com/agent) |[Learn more from our docs →](/docs/mixpanel-agent)
</Update>

<Update label="2026-06-23">
  ## Session Replay: Flutter SDK for Android, iOS, and macOS

  Session Replay now supports Flutter. By many estimates, Flutter accounts for around 20% of all mobile apps being built — surpassing React Native and trailing only native — and until now, Flutter teams didn't have a way to capture replays from their apps.

  With this update, you can:

  * **Record replays across Flutter targets:** Capture sessions from Flutter apps running on Android, iOS, and macOS.
  * **Get parity with other mobile SDKs:** Flutter Session Replay matches the capabilities available on our other supported mobile platforms.
  * **Move seamlessly between reports and replays:** Filter Flutter replays with the same Mixpanel events, properties, and cohorts you already use.

  [Learn more →](/docs/tracking-methods/sdks/flutter/flutter-replay)
</Update>

<Update label="2026-06-18">
  ## Experiments: Breakdowns in Experiment Results

  You can now break experiment results down by a property — like country or platform — to spot per-segment effects that would otherwise be hidden in the aggregate.

  Previously, experiment results only showed the aggregate effect, hiding heterogeneous impact. A treatment could help mobile while hurting desktop, and you'd never see it. This was one of our most requested experiment enhancements.

  With this update, you can:

  * **Segment results by any property:** Break down experiment results by country, platform, plan, or any other property to see how the treatment lands across your user base.
  * **Get guardrails on post-hoc segmentation:** A built-in warning surfaces the risk of false positives when you segment after the fact.
  * **Trust the numbers:** Benjamini-Hochberg correction is applied automatically to control false discovery rate as the number of segment-level tests grows.

  [Learn more →](/docs/experiments#advanced-statistical-methods)
</Update>

<Update label="2026-06-18">
  ## Experiments: Benjamini-Hochberg Correction

  Segmented experiment results now use Benjamini-Hochberg correction to preserve statistical power while still guarding against false positives.

  When you break experiment results into segments, the number of statistical tests explodes. Bonferroni correction becomes far too strict once multiplied by segment counts, killing statistical power and hiding real effects.

  With this update, you can:

  * **Preserve power in segmented analysis:** Benjamini-Hochberg controls the false discovery rate instead of family-wise error, so real segment-level effects still show up as significant.
  * **Stay protected from false positives:** BH still applies a principled correction — it just does so without over-penalizing the way Bonferroni does at scale.
  * **Get it automatically:** BH correction is auto-enabled the moment you segment experiment results, with an undo toast if you want to revert.

  [Learn more →](/docs/experiments#advanced-statistical-methods)
</Update>

<Update label="2026-06-02">
  ## Experiments and Feature Flags: Multi-Environment Support

  You can now copy experiments and feature flags between Mixpanel projects, so promoting work from dev → staging → production no longer means recreating everything from scratch.

  Some teams run separate Mixpanel projects per environment, but Experiments and Feature Flags had no way to move work between them. Customers had to manually rebuild every flag and experiment in production, leading to typos, drift, and long debugging sessions when something didn't match.

  With this update, you can:

  * **Copy flags and experiments between projects:** Promote work from dev to staging to production without manual recreation.
  * **See which projects an item is linked to:** A new **Environments** dropdown in the Experiments and Feature Flags side panel shows the projects a given flag or experiment is linked to.
  * **Manage connections over time:** Remove inter-project connections when you no longer need them.
  * **Works with third-party flags too:** Multi-environment support applies to experiments backed by Mixpanel flags or third-party flags.

  Faster, safer promotion from dev to prod, fewer manual recreation errors, and a clear path to the multi-environment best practice you already follow elsewhere in your stack.

  Learn more: [Experiments](/docs/experiments#multiple-environments) | [Feature Flags](/docs/featureflags#multiple-environments)
</Update>

<Update label="2026-05-20">
  ## Feature Flags: Flag Persistence for Mobile and Web SDKs

  Client-side flags now resolve instantly on launch instead of blocking on a network round-trip.

  For mobile-first customers, every app launch meant the SDK had to wait for a network response before flag variants resolved. On slow or flaky connections, users would see the fallback experience before their assigned variant kicked in. Customers running large rollouts had been asking us: how do we serve the right experience during a slow or offline network connection, or a Mixpanel feature flag service outage?

  Client-side SDKs can now persist flag assignments locally and return them instantly on next launch.

  With this update, you can:

  * **Resolve flags instantly on launch:** Cached assignments are returned immediately, with no network round-trip required before variants are available.
  * **Stay resilient to network conditions:** Users see their assigned variant even on slow, flaky, or offline connections — and continue to during any service disruption.
  * **Ship consistent experiences:** Eliminate the fallback flash that occurs when a variant resolves after initial render.

  Learn more per SDK: [JavaScript](/docs/tracking-methods/sdks/javascript/javascript-flags#flag-persistence) | [Swift](/docs/tracking-methods/sdks/swift/swift-flags) | [Android](/docs/tracking-methods/sdks/android/android-flags#flag-persistence) | [Flutter](/docs/tracking-methods/sdks/flutter/flutter-flags#flag-persistence)
</Update>

<Update label="2026-05-19">
  ## Audit Log: 60+ New Log Types

  Self-serve audit logs [launched last month](/changelogs), and we've been expanding what's captured so customers can investigate activity without filing support tickets.

  With this update, the self-serve Audit Log now captures entries for:

  * **Access changes:** User, Team, Organization, and Project access changes
  * **Data exports:** Raw Export API requests
  * **Feature flags and experiments:** Configuration and lifecycle changes
  * **And much more:** Dozens of additional event types across the platform

  See the full list of captured events in the [Audit Log documentation](/docs/access-security/audit-log).
</Update>

<Update label="2026-05-15">
  ## Databricks Pipeline Integration is now Generally Available

  The **Databricks export destination** for Data Pipelines is now **Generally Available**.

  Since launching in Private Beta, we've worked with early customers to harden reliability and polish the setup experience. It's ready for production workloads.

  ### What you can do with it

  Export your Mixpanel event data directly to your Databricks workspace via Unity Catalog Managed Volumes — no third-party ETL tools or custom infrastructure required. Mixpanel loads raw events into a single-column table and automatically creates a typed view on top, so your data team can start querying with standard SQL immediately.

  A few things that make this integration particularly useful:

  * **Works across all Databricks clouds** — AWS, GCP, and Azure are all supported
  * **Date-clustered tables** — raw tables use liquid clustering on `event_date`, so date-range queries are fast without manual optimization
  * **Static IP support** — works with IP allowlisting if your Databricks workspace has network restrictions
  * **Serverless-friendly** — pairs well with Serverless SQL Warehouses for fast startup and pay-per-use pricing

  If your analytics and data science teams are already working in Databricks, this is the simplest way to get your Mixpanel data into that environment without stitching together intermediate storage or custom export scripts.

  The Databricks destination is available to any Mixpanel customer with the Data Pipelines add-on package.

  Get started with the [Databricks integration](/docs/data-pipelines/integrations/databricks).
</Update>

<Update label="2026-05-12">
  ## MCP Server: Support for Experiments and Feature Flags (Beta)

  You can now manage experiments and feature flags directly from the Mixpanel MCP Server. Ask your AI assistant to list, inspect, create, or update experiments and flags in natural language — no context switching required.

  **Experiments (Beta):**

  * **List Experiments:** List and search experiments in a project
  * **Get Experiment:** Retrieve experiment details, configuration, and results
  * **Create Experiment:** Create a new experiment
  * **Update Experiment:** Modify an experiment's configuration or manage its lifecycle
  * **Get Experiment Setup Guidance:** Best-practice guidance for designing an experiment
  * **Get Experiment Results Interpretation Guidance:** Best-practice guidance for interpreting experiment results

  **Feature Flags (Beta):**

  * **List Feature Flags:** List and search feature flags in a project
  * **Get Feature Flag:** Retrieve feature flag details and targeting rules
  * **Create Feature Flag:** Create a new feature flag
  * **Update Feature Flag:** Modify a feature flag's configuration or targeting
  * **Get Feature Flag Setup Guidance:** Best-practice guidance for creating and configuring a feature flag
  * **Get Feature Flag Lifecycle Guidance:** Best-practice guidance for rollout, kill-switch, and cleanup

  [Learn more →](/docs/mcp)
</Update>

<Update label="2026-05-11">
  ## Drop Filters

  Keep unwanted events out of your project — before they're stored. You can now define filters in Lexicon using event names and properties to drop events at ingestion, so they never hit storage or count toward your volume.

  With this update, you can:

  * **Define drop rules in Lexicon:** Filter by event name, properties, and values to catch the events you don't want.
  * **Drop at ingestion:** Matching events are discarded before storage — they don't consume volume and don't show up in reports.
  * **Improve data quality:** Keep noisy, irrelevant, or misfired events out of your project automatically.
  * **Control cost:** Reduce event volume by filtering junk at the source instead of paying to store it.
  * **Enable self-serve governance:** Give data teams a way to keep projects clean and the ratio of used-to-tracked events high, without engineering involvement.

  [Learn more →](/docs/data-governance/data-clean-up#3-drop-filters)
</Update>

<Update label="2026-05-11">
  ## Session Replay: Mobile Session Replay is now open source

  Session Replay for iOS and Android is now open source. The full source is public on GitHub alongside the rest of our SDK lineup.

  Android is now a single multi-module repo ([mixpanel-android](https://github.com/mixpanel/mixpanel-android)) covering analytics, session-replay, common, and openfeature-provider — one repo, one release flow, consistent versioning.

  With this update, you can:

  * **Debug Session Replay issues yourself:** Read the actual SDK source instead of filing a support ticket to understand behavior.
  * **Get better results from AI tooling:** Claude Code, Cursor, Copilot, and similar tools work dramatically better when they can read the SDK source directly.
  * **Contribute and inspect changes:** Follow development, open issues, and review changes in the open.

  On Android, cross-module changes are now a single PR instead of coordinated releases across multiple repos.

  Explore the repos: [iOS Session Replay](https://github.com/mixpanel/mixpanel-ios-session-replay-package) | [Android SDK](https://github.com/mixpanel/mixpanel-android)
</Update>

<Update label="2026-05-11">
  ## Verified Cohorts in Lexicon

  Cohorts can now be verified in Lexicon, giving your team a clear signal for which cohorts are trusted for analysis. Until now, users could verify events and behaviors but had no way to do the same for cohorts.

  With this update, you can:

  * **Verify cohorts in Lexicon:** Bulk-verify up to 100 cohorts at a time from the cohorts table, or verify individual cohorts via the overflow menu or edit modal.
  * **See verification status at a glance:** Verified cohorts display a verified icon — just like events. Hovering over the icon shows who verified it and when.
  * **Filter by verification status:** Quickly find verified cohorts using the verification filter in the Lexicon cohorts table, or filter by verification status in the query builder.

  [Learn more →](/docs/users/cohorts#verifying-cohorts)
</Update>

<Update label="2026-05-08">
  ## Experiments: Variant Screenshots, Configuration Tab, and Diagnostics Tab

  Reviewing and debugging experiments just got significantly easier. Previously, experiment variants were identified only by key name — reviewers couldn't see what was visually different between them. Health check alerts (SRM, Pre-Experiment Bias) were also unactionable, with no per-metric detail, no drill-through, and no way to inspect the underlying user population.

  This release brings visual context to variants, a redesigned configuration surface, and a new diagnostics workflow for investigating experiment health.

  With this update, you can:

  * **Attach screenshots to variants:** Give reviewers a visual reference for what each variant looks like, so approvals and QA don't rely on variant keys alone.
  * **Configure experiments in a full-width tab:** The new Configuration Tab replaces the sidebar, with room for cohort targeting and rollout group management alongside the rest of your setup.
  * **Investigate experiment health:** The new Diagnostics tab includes Health Checks (SRM and Pre-Experiment Bias) with per-metric breakdowns, actionable next steps, and drill-throughs into the underlying data.
  * **Inspect exposed users:** A new Exposed Users table surfaces the user population behind each experiment so you can validate assignments and troubleshoot unexpected results.

  [Learn more →](/docs/experiments#advanced-statistical-methods)
</Update>

<Update label="2026-05-07">
  ## Feature Flags: OpenFeature Providers Across Mixpanel SDKs

  Adopt Mixpanel Feature Flags without rewriting your flag-evaluation layer. Teams that have standardized on [OpenFeature](https://openfeature.dev/) — the vendor-agnostic feature flag API — can now plug Mixpanel in directly through official providers.

  With this update, you can:

  * **Keep your existing OpenFeature integration:** Swap Mixpanel in behind the standard OpenFeature interface with no application code changes.
  * **Standardize across languages:** Official providers are available for 8 languages — Web JS, Node.js, Go, Java, Python, Ruby, Kotlin, and Swift.
  * **Discover through the ecosystem:** All Mixpanel providers are listed on the [OpenFeature ecosystem page](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Bvendor%5D%5B0%5D=Mixpanel).
</Update>

<Update label="2026-05-05">
  ## Session Replay: UI Controls for Sampling

  Change sampling rates without shipping code. Previously, adjusting sampling required a code change and engineering effort — and on mobile, teams could be stuck with the wrong rate for months while waiting on app store review.

  Paid Session Replay customers can now manage sampling directly from the Mixpanel UI, with changes taking effect within the hour.

  With this update, you can:

  * **Set sampling rates from the UI:** Adjust replay sampling without touching code or waiting on a release.
  * **Add conditional rules:** Sample based on event, property, or URL to focus capture on the sessions that matter most.
  * **Iterate quickly on mobile:** Skip the app store review cycle when tuning replay volume on Android and iOS.

  **Availability:** Generally available on Web, Android, and iOS. Exclusive to paid Session Replay Add-On customers.

  [Learn more →](/docs/session-replay#ui-controls)
</Update>

<Update label="2026-04-29">
  ## Stripe Projects: set up Mixpanel without leaving your CLI

  <Frame>
    <img alt="Stripe Projects: set up Mixpanel without leaving your CLI" />
  </Frame>

  When you're building with Stripe, adding analytics shouldn't mean stopping to create a separate account. Mixpanel is now available in Stripe Projects — developers and AI agents can provision and configure Mixpanel directly from the Stripe Projects CLI, with account creation, authentication, and plan selection all handled in one place.

  With this integration, you can:

  * **Provision without context-switching:** Set up a Mixpanel account and project from the Stripe CLI. There's no separate signup flow and no manual implementation.
  * **Let your agent handle it:** AI agents assembling a project stack can now add Mixpanel automatically. Credentials flow directly to wherever they're needed, with no human intervention required.
  * **Go from zero to tracking fast:** Once provisioned, you get a fully configured Mixpanel project ready to receive events — skip the setup and start shipping.

  Search for Mixpanel in the [Stripe App Marketplace](https://marketplace.stripe.com/apps/mixpanel-provider-integration) or run the Stripe Projects CLI to discover and provision Mixpanel directly. See the [Stripe Projects documentation](https://docs.stripe.com/projects) for setup instructions.

  **Note:** Available for Free and Growth plans. Enterprise provisioning via Stripe Projects is not currently supported.
</Update>

<Update label="2026-04-20">
  ## Session Replay: Console Logs & Network Calls

  Debug faster with full visibility into what your app was doing during a replay. Previously, troubleshooting from a replay meant guessing at what went wrong under the hood — no console errors, no failed requests, no way to see why something broke. It was the single biggest gap our customers cited compared to competing tools.

  Session Replay now captures console output and network activity, synced to playback so you can see exactly what happened at the moment of an issue.

  With this update, you can:

  * **See console errors and warnings:** Console messages are captured alongside the replay and synced to the timeline, so you can jump straight to the error and see the surrounding context.
  * **Inspect network calls:** `fetch`, `XHR`, and resource loads are captured with full request and response detail — status codes, headers, payloads — available in dedicated drawers as the replay plays.
  * **Debug without leaving Mixpanel:** No more toggling between replay and browser devtools or piecing together logs from your monitoring stack.

  Learn more about [console logs](/docs/session-replay#console-logs) and [network calls](/docs/session-replay#network-calls).
</Update>

<Update label="2026-04-20">
  ## OpenAPI Specs for Feature Flags & Experiments APIs

  Feature Flags and Experiments management APIs are now fully documented with public OpenAPI specs at [developer.mixpanel.com](https://developer.mixpanel.com/reference).

  Previously, teams building automations against Flags and Experiments had to reverse-engineer network requests from the Mixpanel app or file support tickets to get endpoint details. Now, the full API surface is documented and ready to build against.

  With this update, you can:

  * **Automate flag and experiment management:** Programmatically create, update, and archive flags and experiments as part of your release workflows.
  * **Generate client code:** Use the OpenAPI specs to generate typed clients in your language of choice.
  * **Integrate with your stack:** Wire flag and experiment lifecycle into CI/CD, internal tools, or approval workflows without guesswork.

  Browse the specs at [developer.mixpanel.com](https://developer.mixpanel.com/reference).
</Update>

<Update label="2026-04-20">
  ## Experiments: Dynamic Config Support

  Ship variant changes without shipping code. Previously, running an experiment meant hardcoding the logic for each variation in your app — any tweak to copy, layout, or a threshold required a code change and a release. There was no way to remotely control experiment parameters from Mixpanel the way you already could with a Dynamic Config feature flag.

  Now, experiment variants can carry a JSON parameter, matching the Dynamic Config behavior already available on flags.

  With this update, you can:

  * **Attach JSON to any variant:** Define an arbitrary JSON object per variant directly in the experiment setup UI.
  * **Read parameters from your SDK:** Access the structured parameter from your SDK the same way you read a Dynamic Config flag — no new integration required.
  * **Drive multiple changes from one experiment:** Control copy, layout, pricing tiers, thresholds, and more from a single experiment, all remotely from the Mixpanel app.

  Available in all SDKs today. [Learn more →](/docs/experiments#experiment-json-parameters)
</Update>

<Update label="2026-04-14">
  ## Session Replay: Bookmarked Replays

  Save the replays that matter. Until now, Session Replay playlists only saved filters, not individual sessions — so there was no way to hold onto a specific replay inside Mixpanel.

  With Bookmarked Replays, you can save individual replays directly to a playlist for easy access later.

  With this update, you can:

  * **Bookmark individual replays:** Save any replay to a playlist so you can return to it without rebuilding filters or hunting through sessions.
  * **Keep expired replays visible:** Bookmarked replays that fall outside your retention window stay accessible in a separate "Expired" section, so you can see what you've lost and evaluate whether a longer retention window is worth it.

  [Learn more about bookmarking replays →](/docs/session-replay#bookmarking-replays)
</Update>

<Update label="2026-04-14">
  ## Custom Roles: Granular project-level permissions

  Custom Roles let you create specialized access profiles beyond the four default project roles (Owner, Admin, Analyst, Consumer). Define granular permissions tailored to specific job functions or workflows — each project supports up to 5 Custom Roles.

  With Custom Roles, you can:

  * **Define precise access:** Configure permissions across six categories — Analysis, Feature Flags and Experimentation, Data Management, Data Access/Exports/Alerts, Data Sources and Definitions, and Settings and Notifications.
  * **Start from templates:** Use an existing role as a starting point and adjust permissions as needed.
  * **Copy roles across projects:** Clone a Custom Role to another project in the same organization.
  * **Assign to project members, service accounts and teams:** Custom Roles work with service accounts and organization-level teams for bulk role assignment.

  **Classified Data Access changes:** Previously managed via a separate per-user toggle, classified data access is now a permission within roles. No default role — including Owner and Admin — has classified data viewing access by default. This ensures access is always an explicit decision.

  Custom Roles is available to organizations on **Enterprise** plans. See our [pricing page](https://mixpanel.com/pricing/) for more details.

  For full documentation, see [Roles & Permissions → Custom Roles](/docs/orgs-and-projects/roles-and-permissions#custom-roles).
</Update>

<Update label="2026-04-13">
  ## Glean integration: Mixpanel insights inside your enterprise AI

  <Frame>
    <img alt="Glean integration: Mixpanel insights inside your enterprise AI" />
  </Frame>

  Mixpanel is now live as an MCP app in [Glean Assistant](https://www.glean.com/blog/mcp-apps-assistant-apr-drop-2026). You can ask Glean about conversion rates, retention trends, and feature adoption and get live Mixpanel data back — in the same conversation as your Slack threads, Jira tickets, and Google Docs. No separate tab. No query builder.

  With this integration, you can:

  * **Root-cause incidents faster:** Ask "conversion dropped last Thursday — what happened?" and get Mixpanel's event-level breakdown alongside the deploy log and the Slack thread about the bug, all in one answer.
  * **Analyze launches in context:** Ask how a new flow is performing and Glean auto-brackets the right date range based on when it shipped — no manual date-picking required.
  * **Put data in reach of everyone:** Non-analysts — CS leads, marketing, execs — can get product metrics in the tools they already live in, without learning the query builder.

  Mixpanel is available in Glean's out-of-the-box MCP Apps template library today. Search for Mixpanel in the [Glean connectors directory](https://www.glean.com/connectors) and follow the setup instructions to connect your workspace.

  **Note:** This integration is available to all Mixpanel plans at no additional cost.
</Update>

<Update label="2026-04-10">
  ## Postgres Connector is now Generally Available

  The **Postgres Connector** is now **Generally Available**.

  Since launching in Public Beta earlier this year, we've worked closely with early users to refine reliability, performance, and setup experience. It's ready for production.

  ### What you can do with it

  Connect your Postgres database directly to Mixpanel and start analyzing your transactional data alongside your product usage — no ETL pipelines, no CDPs, no custom scripts required.

  This is especially useful if your most important data (user records, subscription state, AI model logs) lives in a transactional database and hasn't been making it into your analytics. The Postgres Connector closes that gap with minimal setup.

  Works with all major managed Postgres providers, including Amazon RDS, Google Cloud SQL, Supabase, Neon, and DigitalOcean Managed PostgreSQL.

  Get started with the [Postgres Connector](/docs/tracking-methods/warehouse-connectors).
</Update>

<Update label="2026-04-09">
  ## Alerts: Take control with scheduling, history, and webhooks

  <Frame>
    <img alt="Alerts: Take control with scheduling, history, and webhooks" />
  </Frame>

  A well-configured alert can be the difference between catching a problem before it becomes a crisis and spotting an opportunity before it passes. That's why we've enhanced Mixpanel Alerts to give you more precision over when alerts fire, more visibility into how they're working, and more flexibility in where notifications go.

  With these improvements, you can:

  * **Schedule when alerts evaluate:** Notification windows let you define specific days, time ranges, or multiple schedules with different thresholds, so alerts fire when something is genuinely unexpected — not when your data follows its normal pattern
  * **Test before you enable:** Run a retroactive simulation over any time window to see how often an alert would have fired and at what values, before it reaches anyone's inbox
  * **See the full trigger history:** Every alert trigger is now logged with the exact metric value at that moment, so you can spot patterns without digging through email or Slack
  * **Manage everything in one place:** The enhanced alerts management hub shows status, last triggered time, trigger count, and sync health for every alert in your project
  * **Know when alerts break:** When a report change breaks an alert, Mixpanel notifies the owner immediately rather than going dark
  * **Route notifications via webhook:** Send alerts to any HTTP endpoint in your stack: incident management platforms, workflow tools like Zapier or Make, and custom dashboards
  * **More context in every notification:** Alert emails and Slack messages now include a trend chart at trigger time

  Less noise, more signal. [Learn more](/docs/features/alerts)

  **Note:** Alerts improvements are available on all plans. Growth plan customers are limited to 5 alerts per project. Enterprise customers have unlimited alerts.
</Update>

<Update label="2026-04-06">
  ## Audit Log: Track activity across your organization and projects

  We've introduced Audit log to help you maintain visibility, security, and compliance across your Mixpanel organization and projects.

  Audit log provides a record of activity — who made changes, when they occurred, and what was modified. Whether you're investigating an issue, ensuring compliance, or monitoring security, audit log gives you the transparency you need.

  **What's tracked:**

  * **Alerts, Boards, Cohorts, & Reports:** Creation, updates, and deletions
  * **Data management:** Event deletions, data exports, and user data requests
  * **Access & security:** User authentication, service account management, and role changes
  * **Integrations:** Data pipeline and warehouse source configuration changes

  Audit log is available at both the organization and project level. Organization audit logging includes organization-wide events like user logins and service account creation in addition to project level logging. Audit log is available to organization owners and admins only.

  **Key features:**

  * **CSV export:** Download audit logs for analysis
  * **Event filtering:** Quickly find specific actions or changes by event type or user
  * **Retention:** 90 days for Free and Growth plans, 2 years for Enterprise plans

  Access audit log from Organization Settings or Project Settings.

  [Learn more about audit log →](/docs/access-security/audit-log)
</Update>

<Update label="2026-04-05">
  ## Experiments: CUPED

  Reach significance faster on high-variance metrics. Engagement, revenue, and retention often take a long time to reach statistical significance because of natural user-to-user variance — slowing down decisions on real effects.

  CUPED (Controlled-experiment Using Pre-Experiment Data) uses each user's pre-experiment behavior to strip out that baseline variance from the analysis.

  With this update, you can:

  * **Tighten confidence intervals without shifting means:** CUPED removes variance driven by pre-existing user differences, so treatment effects surface more clearly.
  * **Ship decisions sooner:** With less noise, experiments cross the significance threshold with fewer users and less time.
  * **Apply it broadly:** CUPED is available for primary, secondary, and guardrail metrics.

  [Learn more →](/docs/experiments#advanced-statistical-methods)
</Update>

<Update label="2026-04-05">
  ## Experiments: Winsorization

  Stop outliers from dominating your experiment results. A single extreme value — one \$100k order, one user who binged 10,000 events — can swamp revenue and value metrics and mask the real treatment effect.

  Winsorization caps values beyond a chosen percentile so results reflect the typical user, not rare extremes.

  With this update, you can:

  * **Cap extreme values:** Set a percentile threshold and let Winsorization clip outliers on either tail before computing the metric.
  * **See the typical user's experience:** Results reflect what most users saw, not what a handful of extreme cases pulled the average toward.
  * **Diagnose outlier-driven conclusions:** If your significance or direction flips materially after applying Winsorization, that's itself a signal your original result was outlier-driven.

  [Learn more →](/docs/experiments#advanced-statistical-methods)
</Update>

<Update label="2026-04-05">
  ## Experiments: Pre-Experiment Bias Health Check

  Catch bad randomization before you act on it. Lift observed during an experiment might be a pre-existing difference between the assigned groups — bad randomization or biased assignment logic — rather than a true treatment effect. Until now, there was no built-in way to spot this.

  Pre-Experiment Bias runs a "Retro A/A" on a pre-experiment window you choose (1, 2, or 4 weeks) before exposure and re-applies the same analysis.

  With this update, you can:

  * **Detect non-equivalent groups:** Significant "lift" in the pre-experiment period is a red flag that your variant groups weren't actually equivalent going in.
  * **Choose the right window:** Configure a 1, 2, or 4 week pre-experiment window based on how much stable history you have.
  * **Fix it with confidence:** When bias is detected, the check prompts you to apply a CUPED correction or review your assignment logic before trusting the primary results.

  [Learn more →](/docs/experiments#advanced-statistical-methods)
</Update>

<Update label="2026-04-05">
  ## Experiments: Sample Ratio Mismatch (SRM) Health Check

  Detect bucketing bugs before they invalidate your results. A bug in bucketing, tracking, or assignment can skew the observed variant split — you configured 50/50 but got 60/40 — silently invalidating everything downstream.

  SRM is an opt-in health check that flags when the observed allocation drifts from the configured split beyond what chance would explain.

  With this update, you can:

  * **Catch skewed splits early:** A Chi-squared test compares observed vs. configured allocation and warns when the deviation is beyond chance.
  * **Opt in per experiment:** SRM isn't always-on — you enable it (and can disable it) so it doesn't fire on experiments where a mismatch is expected.
  * **Take corrective action:** When SRM triggers, pause the experiment, fix the root cause, and restart with confidence.

  [Learn more →](/docs/experiments#advanced-statistical-methods)
</Update>

<Update label="2026-04-05">
  ## Experiments: Bonferroni Correction

  Guard against false positives when testing multiple metrics or variants. Testing many metrics at 95% confidence inflates the odds that at least one "win" is a false positive — the classic many-dice problem.

  Bonferroni correction tightens the significance threshold based on the number of comparisons you're running.

  With this update, you can:

  * **Control family-wise error:** Bonferroni divides your confidence threshold by the number of comparisons (metrics × non-control variants), reducing false positives across the whole experiment.
  * **Trust multi-metric readouts:** When you track many metrics at once, Bonferroni makes sure a single flashy result isn't just noise.
  * **Pair with the right method:** For segmented results, Mixpanel automatically switches to Benjamini-Hochberg, which preserves more power at scale.

  [Learn more →](/docs/experiments#advanced-statistical-methods)
</Update>

<Update label="2026-03-24">
  ## Mixpanel MCP: Talk to Your Data

  <Frame>
    <img alt="Mixpanel MCP: Talk to Your Data" />
  </Frame>

  Mixpanel MCP brings your product data into the AI tools you already use - Claude, ChatGPT, Gemini, Cursor, Notion, and more. Ask questions in natural language, get answers backed by real data, and take action without switching context.

  [Connect your first AI tool →](/docs/mcp)

  ## What you can do

  * Build boards and reports in natural language. Ask a question, get an answer — and a Mixpanel report to go with it.
  * Combine behavioral data with qualitative context in a single conversation. Pull up a specific user's replays alongside their event history to understand not just *what* they did, but *how* they experienced it.
  * Project Owners and Admins can manage event and property metadata directly through MCP — generating descriptions, verifying data, tagging events, and hiding or dropping properties at scale.

  ## Try these prompts

  * *"In the last three months, which channels have driven the most new users?"*
  * *"User X submitted negative feedback on \[date]. Analyze their session replays to understand what happened."*
  * *"Show me signup conversion rates by acquisition source for the last 30 days."*
  * *"Generate event descriptions for all of my events in Lexicon."*

  [Learn more about Mixpanel MCP →](https://mixpanel.com/blog/mixpanel-mcp/)
</Update>

<Update label="2026-03-13">
  ## Feature Flags + Experiments: Now on Go and Flutter

  Feature Flags and Experiments are now supported in Go (server-side) and Flutter (client-side) SDKs.

  Mixpanel Feature Flags help you control rollouts, deliver variants for A/B tests, and change application behavior without redeploying code. Experiments build on those variants with measurement and analysis.

  Now, Feature Flags and Experiments are available in the Go and Flutter SDKs:

  * **Go (server-side):** Use the Mixpanel Go SDK to evaluate flags on the backend. Choose local evaluation for low-latency use cases, or remote evaluation when you want server-side evaluation with Mixpanel cohort targeting and sticky variants.
  * **Flutter (client-side):** Use the Mixpanel Flutter SDK across iOS, Android, and Web to fetch flag variants, evaluate gates, and automatically track exposure events for experiment analysis.

  Learn more →

  * [Go SDK](/docs/tracking-methods/sdks/go/go-flags) | [Github](https://github.com/mixpanel/mixpanel-go)
  * [Flutter SDK](/docs/tracking-methods/sdks/flutter/flutter-flags) | [Github](https://github.com/mixpanel/mixpanel-flutter)
</Update>

<Update label="2026-03-12">
  ## Metric Trees: Build your first draft instantly with AI

  <Frame>
    <img alt="Metric Trees: Build your first draft instantly with AI" />
  </Frame>

  Metric Trees are a structured way to map how your business actually grows, connecting your north star metric to the bets, drivers, and inputs that move it. [Learn more about Metric Trees →](https://mixpanel.com/blog/mixpanel-metric-trees/)

  AI Metric Trees gets you to a strong, structured first draft fast, so you can spend less time on setup and more time turning strategy into action. Just provide your company website and a bit of context, and AI handles the rest.

  ## With AI Metric Trees, you can:

  * **Discover metrics you might miss:** Surface drivers, bets, and input metrics you may not have considered, organized around your growth model
  * **Start in seconds:** Just enter your company website and an optional description of your business or growth focus
  * **Get a thoughtful structure:** Receive a first draft with your north star, outputs, strategic bets, and input metrics
  * **Make it yours:** Edit the structure and connect nodes to your real Mixpanel metrics

  Generate your first AI Metric Tree and turn a blank canvas into a working foundation. [Learn more →](/docs/metric_tree#option-build-with-ai)

  **Note:** Metric Trees are available as an add-on for Enterprise customers.

  AI Metric Trees does not use your Mixpanel data. Generation is powered by OpenAI and based on industry best practices, common growth models, and the context you provide.
</Update>

<Update label="2026-03-03">
  ## Feature Flags: Target users using real-time behavior with Runtime Events

  Target feature variants based on what users do, not just who they are.

  Mixpanel Feature Flags supports several targeting options, including cohorts (audiences based on behavior or attributes) and runtime properties (conditions like OS, app version, or browser).

  With Runtime Events, you can **target users based on specific Mixpanel events in real time**. When a user triggers a designated event, they receive the active variant on the next flag evaluation, without waiting for a cohort refresh.

  This unlocks serving features based on time-sensitive, behavior-driven patterns such as:

  * **Onboarding flows:** Show tutorial content after a user completes their first action
  * **Progressive feature unlocking:** Unlock advanced features after users complete key milestones
  * **Conditional promotions:** Display special offers after a user makes their first purchase
  * **Behavior-gated experiments:** Run experiments only on users who have demonstrated engagement

  You can also fine-tune Runtime Events with optional settings like First Time triggers (with session vs. indefinite duration) and event property filters (for example, triggering only on purchases over a certain amount or specific page paths).

  **Availability:** Runtime Events are designed for client-side SDKs that can monitor events in real time. Server-side implementations are not supported.

  * **Web SDK:** available now
  * **Mobile SDKs:** coming soon

  [Learn more →](/docs/featureflags/runtime-events)
</Update>

<Update label="2026-02-27">
  ## Feature Flags: Exposures on User Profiles

  See which feature flags a user was exposed to — and which variant they saw — directly on their profile.

  With Mixpanel Feature Flags, you can target users [via](/docs/featureflags#types-of-feature-flags) Dynamic Configs, Experiments, and Feature Gates. When something looks off, the fastest way to debug is knowing exactly which flags a user saw and which variant they were served.

  Until now, validating targeting or troubleshooting support issues often meant digging through reports and stitching together the answer manually.

  Now, User Profiles include a new **Feature Flags** section that shows the enabled flags a user was most recently exposed to, including:

  * Variant assignment
  * Flag type (Experiment, Feature Gate, Dynamic Config)
  * A searchable table that loads progressively as you scroll

  This makes it much easier to confirm rollout behavior, validate experiment enrollment, and triage unexpected end-user experiences. [Learn more →](/docs/featureflags#identifying-user-exposures)
</Update>

<Update label="2026-02-26">
  ## Security Protocol Update: Phasing Out TLS 1.0 and 1.1

  To ensure we provide the most robust protection against evolving threats, we are upgrading our network security configuration.

  **Starting April 2026, we will be deprecating support for legacy TLS 1.0 and 1.1 protocols and configuring TLS in accordance with NIST SP 800-52 Rev 2 across our APIs and web app.**

  After this date, all API requests must use at least TLS 1.2. Using at least TLS 1.2 is a recommended security best practice to improve data integrity and maintain compliance with industry standards.

  ### Updated TLS Protocols Support

  | TLS Protocol Version | Support Status | Notes                     |
  | :------------------- | :------------- | :------------------------ |
  | **TLS 1.0**          | ❌ Disabled     | No longer supported       |
  | **TLS 1.1**          | ❌ Disabled     | No longer supported       |
  | **TLS 1.2**          | ✅ Enabled      | Minimum supported version |
  | **TLS 1.3**          | ✅ Enabled      | Preferred where available |

  ### Updated Mixpanel Cipher Suite Support by TLS version

  Mixpanel will also mirror the commonly accepted standards for TLS 1.2 and TLS 1.3 Cipher Suite compatibility, as listed in this [external resource](https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_\(recommended\)).

  | TLS Version | ✅ Supported Cipher Suite                            |
  | :---------- | :-------------------------------------------------- |
  | **v1.2**    | TLS\_ECDHE\_ECDSA\_WITH\_CHACHA20\_POLY1305\_SHA256 |
  |             | TLS\_ECDHE\_ECDSA\_WITH\_AES\_256\_GCM\_SHA384      |
  |             | TLS\_ECDHE\_ECDSA\_WITH\_AES\_128\_GCM\_SHA256      |
  |             | TLS\_ECDHE\_RSA\_WITH\_CHACHA20\_POLY1305\_SHA256   |
  |             | TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384        |
  |             | TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256        |
  |             | TLS\_DHE\_RSA\_WITH\_CHACHA20\_POLY1305\_SHA256     |
  |             | TLS\_DHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384          |
  |             | TLS\_DHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256          |
  | **v1.3**    | TLS\_AES128\_GCM\_SHA256                            |
  |             | TLS\_AES256\_GCM\_SHA384                            |
  |             | TLS\_CHACHA20\_POLY1305\_SHA256                     |

  ## <u>What’s the impact of this change?</u>

  Any data sent to Mixpanel’s Ingestion API endpoints after **April 1, 2026** via TLS 1.0 and 1.1 will not be accepted, meaning you will not receive analytics information from users who engage with your applications using the 1.0 and 1.1 versions of TLS.

  While the vast majority of modern traffic uses TLS 1.2 or 1.3, data can be sent to Mixpanel via TLS 1.0 and 1.1 when end-users access your application from older browsers or devices with operating systems that don’t support or enforce modern TLS versions.

  ### Commonly Affected Examples

  The following browsers and OS may still use TLS 1.0 or 1.1:

  | Category                | Impacted Versions / Environments        | Examples & Notes                      |
  | :---------------------- | :-------------------------------------- | :------------------------------------ |
  | **Mobile**              | Android \< 5.0 (pre-Lollipop)           | 2012 Samsung Galaxy S4                |
  |                         | iOS \< 9                                | 2010 iPhone 4                         |
  | **Desktop OS**          | Windows XP, Vista, early Windows 7      | Without critical security updates     |
  |                         | macOS \< 10.9                           | Legacy Apple systems                  |
  | **Browsers / Runtimes** | Internet Explorer ≤ 10                  |                                       |
  |                         | Firefox \< 78                           |                                       |
  |                         | Chrome \< 84                            |                                       |
  |                         | Java 6 / early Java 7                   |                                       |
  |                         | Python \< 2.7.9                         | OpenSSL without TLS 1.2 support       |
  |                         | Old OpenSSL versions (\< 1.0.1)         |                                       |
  | **Embedded / IoT**      | Legacy firmware                         | Hardcoded TLS stacks / Non-upgradable |
  | **Protocol Specific**   | Devices supporting only SSLv3 / TLS 1.0 |                                       |

  Please Note: While we’ve listed some common versions above, compatibility can vary. For example, Chrome 30-32 started supporting TLS 1.2.

  For a comprehensive list of environments that may still use TLS 1.0/1.1, we recommend visiting the Browser/OS Official Documentation or referring to the [TLS Support Version History](https://en.wikipedia.org/wiki/Version_history_for_TLS/SSL_support_in_web_browsers) (External Resource).

  ## <u>How to identify affected users</u>

  More than 99% of Mixpanel Web and API Traffic use TLS 1.2+; however, to assess how many users are potentially affected by this change in your projects:

  1. In an Insights report, select `All Events` as the primary metric
  2. Break down by the [following properties](/docs/data-structure/property-reference/default-properties), depending on your tracking SDK(s)
     * JavaScript (Web): Browser (`$browser`) and Browser Version (`$browser_version`)
     * Mobile: Operating System (`$os`), OS Version (`$os_version`)

  Tip: You can create a [Custom Property](/docs/features/custom-properties) to quickly bucket users. For example, the following Custom Property can help check against Chrome and Firefox.

  <Frame>
    <img alt="Custom Prop Example" />
  </Frame>

  ## <u>Recommended Actions</u>

  * **Client-Side Tracking:** Where possible, we recommend encouraging users to update their browsers or OS to a version that communicates using TLS 1.2+.
  * **Server-Side Tracking:** Verify your server environments are configured to use TLS 1.2+.
  * **Protocol Migration:** If your application currently utilizes legacy TLS versions, we recommend deprecating them in favor of TLS 1.2+ to ensure long-term security and compatibility.
  * **Proxying:** We understand that some devices have hardware/software limitations that may not be able to use TLS 1.2+. In these cases, if you would like to maintain tracking for these devices, you could consider implementing a proxy server that accepts TLS 1.0/1.1 from end users and forwards the tracking data to Mixpanel Ingestion APIs via TLS 1.2+.

  ## <u>Support & Inquiries</u>

  We have notified users whose projects were detected receiving legacy TLS 1.0/1.1 Ingestion traffic. If you have questions about your project’s compatibility or need general assistance, please reach out to [Mixpanel Support](/docs/response-times#contacting-mixpanel-support).

  For technical questions about TLS protocols or broader security questions, please contact our GRC Team at [grc@mixpanel.com](mailto:grc@mixpanel.com).
</Update>

<Update label="2026-02-24">
  ## Postgres Connectors now in Public Beta

  <Frame>
    <img alt="Postgres Connectors now in Public Beta" />
  </Frame>

  ## New: Postgres Connector (Public Beta)

  We’re pleased to announce the **Postgres Connector**, now available in **Public Beta** — a simpler way to bring your transactional data into Mixpanel.

  ### What it does

  The Postgres Connector enables you to connect your Postgres database directly to Mixpanel and begin analyzing your data without needing intermediate tools or custom pipelines. This means you can get your most important user and product data into Mixpanel much faster and with less engineering effort.

  Unlike traditional ingestion approaches that require CDPs, ETL tools, or custom scripts, the Postgres Connector is built to work right from your database to Mixpanel. Early-stage teams, especially those without a data warehouse, can now include more complete data in their analytics workflows with minimal setup.

  ### Why this matters

  Many small and growing customers have told us it’s hard to get **complete user context** into Mixpanel because:

  * Existing options often require costly third-party tools.
  * Building custom sync scripts takes significant engineering time.
  * Important data lives only in transactional databases.

  That’s especially true for AI-centric products where app and model usage logs are often stored in Postgres and aren’t feeding into analytics today. The Postgres Connector helps close that gap.

  ### How it works

  * Connect your Postgres database directly from the Mixpanel UI.
  * Sync tables from Postgres into Mixpanel without intermediate services.
  * Compatible with all Postgres versions and major managed providers including:
    * DigitalOcean Managed PostgreSQL
    * Google Cloud SQL
    * Supabase
    * Neon
    * Amazon RDS
    * and more!

  This connector builds on Mixpanel’s Warehouse Connectors framework, which already supports popular data warehouses like Snowflake, BigQuery, Redshift, and Databricks. With this beta, we’re extending those same sync capabilities to transactional databases and bringing more of your source-of-truth data into Mixpanel for analysis. Learn more and get started [here](/docs/tracking-methods/warehouse-connectors).

  ### Try it today

  The Postgres Connector is now available in Public Beta. We encourage you to give it a try. It’s designed to make your data ingestion smoother and your analytics richer, with less friction.
</Update>

<Update label="2026-02-24">
  ## SSO, Data Views, and Sensitive Data Classification now available on Growth Plans

  <Frame>
    <img alt="SSO, Data Views, and Sensitive Data Classification Are Now Available on All Growth Plans" />
  </Frame>

  Growth customers now have access to powerful security and governance capabilities that give teams more control, protection, and flexibility as they scale.

  ### What’s now included in Growth?

  #### Secure access with SSO

  Strengthen authentication and simplify user management with Single Sign-On across your organization. Learn more [here](/docs/access-security/single-sign-on).

  #### Control visibility with Data Views

  Create tailored views of your data so teams see exactly what they need — while maintaining appropriate boundaries. Learn more [here](/docs/data-governance/data-views-and-classification#data-views-overview).

  #### Protect data with Sensitive Data Classification

  Identify and manage sensitive data with greater precision to support compliance and responsible data practices. Learn more [here](/docs/data-governance/data-views-and-classification#data-classification).

  ### Raising the standard for self-serve analytics

  Security and governance shouldn’t be an afterthought — or an obstacle to growth.

  By bringing these capabilities to all Growth plans, we’re raising the bar for what teams should expect from a self-serve analytics platform. Organizations no longer have to choose between ease of use and robust data controls.

  At the same time, our Enterprise plans continue to provide even deeper levels of governance, customization, support, and scale for organizations with the most advanced requirements.

  This update ensures that as our customers grow, Mixpanel grows with them, delivering strong security foundations at every stage.

  If you’re on Growth, these features are available now.

  You can find more details on our growth plans [here](https://mixpanel.com/pricing/).
</Update>

<Update label="2026-02-24">
  ## AI-Powered Event Suggestions for Templates

  Setting up a new board just got a little easier.

  We’ve introduced **AI-Powered Event Suggestions for Templates** to help streamline the process of mapping your events to templates, reducing guesswork and saving time during setup.

  ### Smarter event recommendations

  When selecting a template, it’s not always obvious which events in your project correspond to each slot. Now, Mixpanel automatically suggests the best-fit events based on your existing data.

  You can accept the recommendations as-is or swap in different events at any time, you’re always in control.

  This update is designed to smooth out one of the more common onboarding friction points: figuring out what events you have and how to use them. With AI-powered suggestions, getting from setup to insight takes less manual effort, and less second-guessing.

  You can give it a try the next time you create a board from a template.
</Update>

<Update label="2026-02-20">
  ## Deprecation Notice: Legacy US-to-EU Data Forwarding ends July 2026 for EU Projects

  > **🚨 UPDATE: July 1, 2026 – US-to-EU Data Forwarding has officially ended.** <br /><br />
  >
  > As scheduled, we have sunset US-to-EU data forwarding. <br /> **For EU Projects that still send data to the US, to help you assess the impact, events sent to US endpoints will be temporarily hidden from your UI and Query API endpoints until August 1, 2026.**<br /><br />
  >
  > **How events are being filtered**<br />
  >
  > \[July 1, 2026 - August 1, 2026]: New US->EU Forwarded events have not been deleted. However, they are temporarily hidden from the UI and Query API endpoints if they match all of the following criteria:
  >
  > * The event was processed after July 1st (UTC) (`mp_processing_time_ms` > `<July 1st UTC>`).
  > * The event was forwarded from the US (`$mp_is_forwarded` is defined).
  >
  > These events are not deleted — they remain accessible via the Raw Export API during this period, and will be un-hidden on August 1, 2026, so your reporting counts may change at that time. <br /><br />**Events that are still being sent to the US after August 1, 2026 for EU Projects will not be accepted.** <br /><br /> **If you are affected, please ensure your implementation is updated to point to Mixpanel's EU Servers `api-eu.mixpanel.com` immediately to prevent permanent data loss after August 1, 2026.**<br /><br />
  >
  > *Need help or want to opt out? If you wish to opt out of this UI preview and un-hide your forwarded events early, please [contact support](https://mixpanel.com/get-support).*
  >
  > > ⏳ **Note:** Some projects have an extended timeline through **December 31, 2026**. These projects are not affected by the temporary event-hiding described above. If this applies to your project, we've already reached out with a notification. If you did not receive a notification, your deadline is **August 1, 2026**.

  Starting July 2026, we will be sunsetting the legacy automated US-to-EU Data Forwarding process for [EU Data Residency projects](/docs/privacy/eu-residency) to align with data residency best practices and improve ingestion performance. After this date, data sent to our US Ingestion Servers for EU Data Residency projects will no longer be forwarded, which can result in data loss.

  ## Is my project affected?

  * **EU Projects created before August 18, 2025: If your implementation sends data to Mixpanel's US Ingestion Servers (`api.mixpanel.com`), you may be affected by this change. Please review the action required below.**
  * EU Projects created on or after August 18, 2025: These projects already require direct ingestion to our EU Servers. No action is needed.

  ## Required Action for EU Projects sending data to US Servers

  To avoid any disruption to data ingestion for your EU Projects, **please review and update your implementations to use the dedicated Ingestion API EU Subdomain (`api-eu.mixpanel.com`).** This ensures your data is routed directly to its intended destination.

  **Guidance**

  1. **Verify which projects have EU Data Residency:** Navigate to [Organization Settings](/docs/orgs-and-projects/managing-projects#viewing-project-information) > Projects and click into each Project to confirm whether Data Residency is set to EU.
  2. **Identify Traffic:** In your EU Project(s), create an Insights Report and break down “All Events” by the API Endpoint (`$mp_api_endpoint` ) event property to determine which Ingestion Servers your events came from. `$mp_api_endpoint=api-eu.mixpanel.com` is EU and `$mp_api_endpoint=api.mixpanel.com` or `api-js.mixpanel.com` is US.
  3. **Update and Review Implementation:** If your project has EU Data Residency, please follow the guides below that apply to your setup to ensure your data routes to our EU Servers.

  If you are using Mixpanel’s SDKs, the documentation linked below has instructions on updating your implementation code to EU:

  * [Javascript](/docs/tracking-methods/sdks/javascript#eu-data-residency)
  * [React Native](/docs/tracking-methods/sdks/react-native#eu-data-residency)
  * [Android](/docs/tracking-methods/sdks/android#eu-data-residency)
  * [iOS (Objective-C)](/docs/tracking-methods/sdks/ios#eu-data-residency)
  * [iOS (Swift)](/docs/tracking-methods/sdks/swift#eu-data-residency)
  * [Flutter](/docs/tracking-methods/sdks/flutter#eu-data-residency)
  * [Unity](/docs/tracking-methods/sdks/unity#eu-data-residency)
  * [Python](/docs/tracking-methods/sdks/python#eu-data-residency)
  * [Node.js](/docs/tracking-methods/sdks/nodejs#eu-data-residency)
  * [Ruby](/docs/tracking-methods/sdks/ruby#eu-data-residency)
  * [PHP](/docs/tracking-methods/sdks/php#eu-data-residency)
  * [Go](/docs/tracking-methods/sdks/go#eu-data-residency)
  * [Java](/docs/tracking-methods/sdks/java#eu-data-residency)

  If you are using Mixpanel’s Ingestion API Endpoints, Proxy Server, or an Implementation not listed above:

  * Please update your Ingestion API Base URL to the [EU Residency Server](/reference/overview): `api-eu.mixpanel.com`

  If you are using Partner Integrations that send data into Mixpanel (e.g., CDPs, Messaging, AB Testing):

  * Please contact the Partner’s Support Team for instructions on how to set the integration to point to Mixpanel’s EU Server URL.

  If you have questions about which specific projects we have observed US Traffic on or need further assistance, please don’t hesitate to reach out to [Mixpanel’s Support Team](/docs/response-times#contacting-mixpanel-support).
</Update>

<Update label="2026-02-17">
  ## Feature Flags — Group Cohort Targeting

  <Frame>
    <img alt="Feature Flags — Group Cohort Targeting" />
  </Frame>

  Feature flag rollout groups can now target **group cohorts** — cohorts built on a group key dimension such as Company, Organization, or any custom group entity.

  **What's new:**

  * **Target groups, not just users:** When a flag's Variant Assignment Key is set to a group key (e.g., `company_id`), the cohort builder automatically shifts its identity-dimension to that group (instead of users).
  * **B2B-ready rollouts:** Build cohorts like "Enterprise companies with >50 seats" or "Organizations on the Pro plan" and target them directly for rollouts.
  * **Same cohort builder:** Group cohorts are created in the existing cohort builder, scoped to the relevant group key — no new tools to learn.
  * **Combine with [runtime targeting](/docs/featureflags#runtime-targeting):** Layer runtime properties (e.g., platform, region) on top of group cohort targeting with AND conditions for precise control.

  Group cohorts follow the same \~2-hour refresh cadence as user cohorts.

  [Learn more about Group Cohort Targeting →](/docs/featureflags#rollout-groups)
</Update>

<Update label="2026-01-30">
  ## Custom Alerts via webhook

  Custom Alerts can now send notifications via webhooks, enabling you to integrate Mixpanel alerts with any third-party platform or custom system in your stack.

  Previously, alerts were limited to Email and Slack notifications. With webhook support, you can now route alert notifications to incident management tools, custom dashboards, monitoring systems, or any HTTP endpoint you configure.

  What's new:

  * Project-level webhook configuration: Add and manage webhook endpoints in Settings > Integrations > Webhooks
  * HTTP Basic Authentication: Secure your webhooks with username and password authentication
  * Test connection: Verify webhook connectivity before saving your configuration
  * Easy alert integration: Select your configured webhook from the "via Webhook" dropdown when creating or editing alerts

  When an alert triggers, Mixpanel automatically sends a JSON payload containing alert details to your specified endpoint.

  More details on how to get started in our [docs](/docs/features/alerts#webhook-alerts).
</Update>

<Update label="2026-01-28">
  ## Annotations Timeline: Visualize Your Business Context

  Annotations enable you to add time-stamped notes, allowing you to view metrics with the context that matters to you. We've seen teams add valuable context about everything from product launches, marketing campaigns, outages, and holidays.

  Now, you can visualize all your annotations in a dedicated timeline view that shows how different types of events align across your data.

  ## Timeline Visualization

  A new chart view displays annotations grouped by tag in separate rows, making it easy to see patterns and relationships across different event types. See at a glance when your Marketing campaigns overlapped with Product releases, or how Outages coincided with traffic spikes.

  ## Automatic Alignment

  The timeline automatically syncs with your main chart, working seamlessly with both line and column visualizations to show annotations exactly where events occurred. No manual configuration needed - the timeline stays perfectly aligned as you zoom, change date ranges, or switch chart types.

  ## Interactive Exploration

  * **Hover** over any annotation to preview its details
  * **Click** to view the full annotation list, edit existing notes, or create new ones right from the timeline
  * **Filter by tag** to focus on specific event types and hide the rest

  ## Tag-Based Organization

  Use the tag filter to quickly analyze how particular categories of events impact your metrics. Focus on just Marketing campaigns, just Product releases, or any combination of tags that helps you tell your story.

  [Learn more →](/docs/features/annotations)

  If you have any questions or need assistance, please reach out to our [Support Team](https://mixpanel.com/get-support).
</Update>

<Update label="2026-01-27">
  ## Data Volume Monitoring Default On for New Enterprise Customers

  <Frame>
    <img alt="Data Volume Monitoring Default On for New Enterprise Customers" />
  </Frame>

  New Enterprise accounts now have Data Volume Monitoring (DMV) enabled by default. Enterprise projects automatically monitor event volume, detect sudden or significant spikes, and notify admins so they can take corrective action quickly. No manual setup is required during project.

  You can enable or disable DMV at any time from Lexicon > Data Volume Monitoring.

  Learn more about DMV and configuration options in our [documentation](/docs/data-governance/data-volume-monitoring).
</Update>

<Update label="2026-01-26">
  ## Retiring /decide Endpoint Used in Older Mixpanel SDK Versions

  Starting April 2026, we will be fully retiring the `/decide` endpoint, which was used in older versions of Mixpanel SDKs. We began deprecating this in 2022; newer SDK versions no longer rely on it.

  **If you’re running an SDK version from 2022 or earlier, please review the details below.**

  ## How to check your project's current SDK Version:

  1. In an Insights Report, select "All Events" as your primary metric
  2. Break down by ["Mixpanel Library" and "Library Version"](/docs/data-structure/property-reference/default-properties) event properties

  Tip: You can find a list of all Projects in your Organization in [Organization Settings > Projects](/docs/orgs-and-projects/managing-projects#viewing-project-information), and use the above check to confirm which SDK and versions are in use.

  ## Mobile SDKs

  The `/decide` endpoint controlled whether [Legacy Automatically Tracked Mobile Events](/docs/tracking-methods/sdks/ios#legacy-automatically-tracked-events) `$ae_first_open`, `$ae_updated`, `$ae_crashed`, `$ae_session`, and `$ae_iap` were enabled or disabled for a Mixpanel Project.

  If you currently collect these events and your Mobile SDK version does not meet the minimum versions listed below, your application will stop tracking the Automatic Mobile events after April 2026. To keep collecting the Automatic Mobile events, please complete the following:

  1. **Update to at least the minimum SDK** **versions listed below** and
  2. **Explicitly enable this tracking in your initialization code via `trackAutomaticEvents`**

  Minimum Version and Guides:

  * **Android:**  [v7.0.0+](https://github.com/mixpanel/mixpanel-android/releases/tag/v7.0.0) | [Initialization Guide](/docs/tracking-methods/sdks/android#library-configuration)
  * **React Native:** [v.2.0.0+](https://github.com/mixpanel/mixpanel-react-native/releases/tag/v2.0.0) | [Initialization Guide](/docs/tracking-methods/sdks/react-native#library-configuration)
  * **iOS (Objective-C):** [v.5.0.0+](https://github.com/mixpanel/mixpanel-iphone/releases/tag/v5.0.0) | [Initialization Guide](/docs/tracking-methods/sdks/ios#library-configuration)
  * **iOS (Swift):** [v.4.0.0+](https://github.com/mixpanel/mixpanel-swift/releases/tag/v4.0.0) | [Initialization Guide](/docs/tracking-methods/sdks/swift#library-configuration)
  * **Flutter:** [v.2.0.0+](https://github.com/mixpanel/mixpanel-flutter/releases/tag/v2.0.0) | [Initialization Guide](/docs/tracking-methods/sdks/flutter#library-configuration)

  ## JavaScript (Web) SDK

  If your JavaScript SDK version is older than the minimum version below, there will be no functionality change; however, your application will begin receiving `410` Response Error Codes from this endpoint. We strongly recommend updating to the minimum version below.

  Minimum Version:

  * **JavaScript:** [v.2.45.0+](https://github.com/mixpanel/mixpanel-js/releases/tag/v2.45.0)

  If you have any questions or need assistance with checking your Mixpanel Project's SDK versions, you can reach out to [Mixpanel’s Support Team](/docs/response-times#contacting-mixpanel-support).
</Update>

<Update label="2026-01-20">
  ## Mixpanel Data Inspector, now available for all Mixpanel JavaScript SDK users

  <Frame>
    <img alt="Mixpanel Data Inspector Browser Extension" />
  </Frame>

  The Mixpanel Data Inspector Browser Extension is now available for all [JavaScript SDK users](/docs/tracking-methods/sdks/javascript), making it easier to debug issues and validate your Mixpanel implementation in real time, right in your browser. The extension can also now be used in each Chrome's DevTools window, enabling continuous usage even if the page refreshes.

  Get the improved extension today on [Chrome](https://chromewebstore.google.com/detail/mixpanel-data-inspector/camknfenboildigjgpmhojlcnejppooh) and [Firefox](https://addons.mozilla.org/en-US/firefox/addon/mixpanel-data-inspector/).

  For installation and usage instructions, see [Mixpanel Data Inspector documentation](/docs/tracking-methods/data-inspector).
</Update>

<Update label="2025-01-15">
  ## 📱 Session Replay is now available for React Native

  <Frame>
    <img alt="📱 Session Replay is now available for React Native" />
  </Frame>

  Now you can replay user sessions for React Native apps, bringing Session Replay to your cross-platform mobile development workflow. With React Native Session Replay, you can:

  * Answer the what and why in one place by moving seamlessly between reports and replays
  * Find what matters faster by filtering replays with trusted Mixpanel events, properties, or cohorts
  * Watch the complete user journey across your React Native iOS and Android apps

  Session Replay is free to try. Check out the resources below to get started!

  [View Docs →](/docs/session-replay/implement-session-replay)
</Update>

<Update label="2025-12-22">
  ## Feature Flagging: Runtime Targeting

  <Frame>
    <img alt="Feature Flagging: Runtime Targeting" />
  </Frame>

  Use Runtime Targeting to evaluate feature flags using a live evaluation context, without storing data in Mixpanel.

  With runtime targeting, you can:

  * **Target instantly:** Evaluate flags using runtime properties like plan, device, or platform, or when they perform specific events tracked at runtime
  * **Stay accurate:** Ensure flag decisions always reflect a user’s current state
  * **Reduce overhead:** No persistence, no backfills, no user history required

  Ship more precise rollouts with runtime targeting. [Learn More →](/docs/featureflags#rollout-groups)

  Note: Runtime targeting is available as part of the Feature Flagging add-on for Enterprise customers. Reach out to your account team to learn more.
</Update>

<Update label="2025-12-17">
  ## Updated Date Range and Metric Block Guardrails for Insights Reports

  To enable a great self-serve experience and quick queries, we have updated guardrails for Insights Reports as described below.

  ## Updated Date Range Guardrails for 'All Events' and Line & Column Charts

  * For Line/Columns charts using “Hour” Unit, the report date range can be a maximum of 31 days
  * For Line/Columns charts using “Day” Unit, the report date range can be a maximum of 12 Months
  * For Insights Reports using “All Events”, the report date range can be a maximum of 93 days
  * For Insights Reports using “Cohort Over Time” with Line/Column charts, the report date range can be a maximum of 93 Unit Intervals (i.e., 93 Days for Day Unit, 93 Weeks for Week Unit)

  If your existing reports reach the guardrail, we recommend the following approaches to update your reports and receive the same analysis:

  * Combine events into [Custom Events](/docs/features/custom-events) or [Saved Behaviors](/docs/features/saved-metrics-and-behaviors), which are not subject to the 93-day “All Events” limit.
  * Utilize [Time Period Comparisons](/docs/reports/insights#time-period-comparisons) for year-over-year analysis.
  * Reduce the report date range, or create multiple reports with smaller date ranges in a single [Board](/docs/boards).

  ## Updated Metric Block Guardrails

  Insights Reports will have a 40 metric/behavior block limit. This includes all metric and behavior blocks, such as hidden metrics and formulas.

  If you hit this limit, you can:

  * Migrate some metrics to a new report.
  * Utilize [Saved Formulas](/docs/reports/insights#save-formulas-for-re-use) if your report contains formulas.
  * Combine multiple events into [Saved Behaviors](/docs/features/saved-metrics-and-behaviors#simple-behaviors).

  If you have any questions or need assistance building a report, please don’t hesitate to reach out to our [Support Team](https://mixpanel.com/get-support).
</Update>

<Update label="2025-12-11">
  ## Dynamic Config for Flexible Feature Rollouts

  Use dynamic config to update your application in real-time and target users with different experiences, without changing code, all from one JSON payload. With dynamic config, you can:

  * **Go beyond on/off:** Control UI, logic, and defaults with structured parameters
  * **Iterate faster:** Update configuration instantly without redeploys
  * **Deliver tailored experiences:** Serve different configurations to different users
  * **Reduce risk:** Adjust behavior in production with minimal blast radius

  Build more adaptable product experiences with dynamic config. [Learn More →](/docs/featureflags#types-of-feature-flags)

  Note: Dynamic config is available as part of the Feature Flagging add-on for enterprise customers.
</Update>

<Update label="2025-11-20">
  ## Dynamic Segments

  <Frame>
    <img alt="Dynamic Segments" />
  </Frame>

  You can now choose between Dynamic and Manual Segments in all reports and visualizations when you add Breakdowns.

  Dynamic Segments automatically stay up to date based on how your report is sorted as your data changes. With Dynamic Segments you can create reports like:

  * Funnels broken down by your top 5 app versions
  * Top 15 brands by weekly purchases
  * Bottom 10 pages by visits

  With added flexibility for Dynamic and Manual segments, you now have control over how segments update across your reports.
</Update>

<Update label="2025-11-20">
  ## Expanded regional support for MCP

  <Frame>
    <img alt="Expanded regional support for MCP" />
  </Frame>

  ## MCP Support for India and EU Projects

  The Mixpanel MCP Server is now available for projects hosted in India and the EU. Teams in these regions can now access the MCP server to talk with their data in natural language and democratize analytics across their organization, all while complying to local regulations.

  ### Getting Started

  Organization administrators can enable MCP Server access in Settings > Organization > Overview.

  Learn more about the MCP Server and how to get started in our [documentation](/docs/features/mcp).
</Update>

<Update label="2025-11-14">
  ## Session Replay: Heatmap Comparison Mode

  <Frame>
    <img alt="Session Replay: Heatmap Comparisons" />
  </Frame>

  ## See engagement differences at a glance with side-by-side heatmap comparisons

  Now you can compare two Heatmaps (web only) side by side to see how user engagement differs across any cut of your data, including:

  * **Cohort:** Free vs. Paid
  * **Experiment Group:** Test vs. Control
  * **Browser:** Chrome vs. Safari
  * **Time:** Current quarter vs. Last quarter

  To get started, click `Compare` in the top-right corner of your Heatmap.

  With **Heatmap Comparison Mode**, it's easier than ever to validate design changes, spot patterns, and identify what drives better engagement, all within Mixpanel.

  Note: Heatmaps are currently only available on web.
</Update>

<Update label="2025-11-14">
  ## Session Replay: Frustration Signals

  <Frame>
    <img alt="Session Replay Frustration Signals" />
  </Frame>

  ## Find user friction fast—view frustration signals in replays and analyze them in your reports

  Mixpanel now detects **Rage Clicks** and **Dead Clicks** automatically in Session Replay (web only), helping you instantly see where users experience friction.

  * **Rage Click:** When a user clicks the same spot multiple times in quick succession
  * **Dead Click:** When a user clicks an interactive element that produces no visible response

  These frustration signals are automatically tracked as events:

  * `[Auto] Dead Click`
  * `[Auto] Rage Click`

  You can analyze them in reports, funnels, and dashboards just like any other event data. Find the "why" behind drop-offs and fix issues before they impact more users.

  Note: Rage Clicks and Dead Clicks are currently only available on web.
</Update>

<Update label="2025-11-14">
  ## Session Replay: AI Summaries

  <Frame>
    <img alt="Session Replay AI Summaries" />
  </Frame>

  ## Let AI do the watching for you with accurate summaries that help you understand the "why" instantly

  Skip the manual replay review. With **AI Summaries**, Mixpanel automatically highlights key moments and summarizes every session, helping you get the "so what" behind user behavior in seconds.

  Summaries appear right beside your replays, giving you an instant read on what happened and why. Powered by your governed event data, they're uniquely accurate, so you can trust the insights and move faster from understanding to action.
</Update>

<Update label="2025-11-13">
  ## Filter at Item Level

  <Frame>
    <img alt="Filter at item level" />
  </Frame>

  Mixpanel now allows you to choose “Matching items” to filter and aggregate only the list elements that meet your condition. Previously, when filtering on list properties like cart, filters used to apply to the entire list — not the individual items inside it. For example, if you filtered for cart.category = Garden, Mixpanel would include the entire cart’s revenue if just one item was from Garden, even if the rest were not.

  For example, if you filter on cart.sale\_price > 25 and were aggregating by taking the sum of cart.price then the sum would only be on elements that have cart.sale\_price > 25.

  <VideoButtonWithModal />
</Update>

<Update label="2025-11-04">
  ## Connect Your LLM Metrics to Mixpanel with Langfuse

  <Frame>
    <img alt="Connect Your LLM Metrics to Mixpanel with Langfuse" />
  </Frame>

  We're excited to announce our integration with [Langfuse](https://langfuse.com), the open-source LLM engineering platform. Now you can automatically sync your AI application metrics from Langfuse directly into Mixpanel.

  This integration brings three new event types into Mixpanel:

  * **`[Langfuse] Trace`** - Complete LLM interactions with cost, latency, and observation counts
  * **`[Langfuse] Generation`** - Individual model calls with token usage and performance metrics
  * **`[Langfuse] Score`** - User feedback and quality evaluations

  Answer critical questions about your AI features:

  * How do AI interactions impact user retention and conversion?
  * Which users are driving the most LLM costs?
  * Does user feedback on AI outputs correlate with product engagement?

  **Set up in minutes:**

  1. Add your Mixpanel Project Token in Langfuse project settings
  2. Select your Mixpanel region (US, EU, or India)
  3. Enable the integration

  Data syncs automatically every hour with full historical backfill.

  [View full documentation →](/docs/tracking-methods/integrations/langfuse)

  Install our [Analytics for AI dashboard template](https://mixpanel.com/p/NaKPyubj6EuA4oV75taqrq) to see pre-built reports for adoption, cost analysis, performance metrics, and more.

  *Questions? Reach out to [Langfuse support](https://langfuse.com/support) or check the docs for setup details and troubleshooting.*
</Update>

<Update label="2025-10-13">
  ## Feature Flagging — Precision control for every rollout

  <Frame>
    <img alt="Feature Flagging — Precision control for every rollout" />
  </Frame>

  Feature flagging gives teams fine-grained control over who sees what and when — so you can test new features safely, measure their impact, and roll out with confidence.

  **What's new:**

  * **Own every stage of your rollout:** Target specific audiences and ship with confidence. Start small, expand gradually, and stay in control at every phase of your release.
  * **Launch what matters, to who matters most:** Gate features by subscription tier, geography, or behavior — using dynamic Mixpanel cohorts that update automatically as users engage.
  * **Move fast without breaking things:** Safeguard reliability with kill switches, throttles, and instant rollbacks — plus audit trails, QA testers, and special role-based permissions to ensure stability and confidence at scale.
  * **One place to launch, learn, and grow:** Run roll outs and experiments, analyze results, watch replays and tie them directly to real user behavior — all without leaving Mixpanel.

  Ship safely and with clarity starting today. [Learn More →](/docs/featureflags)

  NOTE: Feature Flagging is available as a paid add-on for customers on the Enterprise plan. Reach out to your account team to learn more.
</Update>

<Update label="2025-09-26">
  ## Mixpanel Data Inspector Browser Extension

  <Frame>
    <img alt="Mixpanel Data Inspector Browser Extension" />
  </Frame>

  Validate your Mixpanel tracking implementation with a new browser extension that provides real-time visibility into events being sent from your website.

  **Why this matters**: Debugging tracking issues and validating implementation just became much easier. Instead of guessing whether events are firing correctly, you can now see exactly what data is being sent to Mixpanel in real-time.

  **What you'll see**: The Data Inspector shows events as they're sent from the Mixpanel SDK, complete JSON payloads you can copy and examine, and search functionality to quickly find specific properties across events.

  This enhancement streamlines the development and QA process, helping teams identify tracking issues before they reach production and ensuring data quality with greater confidence.

  Try out the extension today on [Chrome](https://chromewebstore.google.com/detail/mixpanel-data-inspector/camknfenboildigjgpmhojlcnejppooh) and [Firefox](https://addons.mozilla.org/en-US/firefox/addon/mixpanel-data-inspector/).

  For installation and usage instructions, see [Mixpanel Data Inspector documentation](/docs/tracking-methods/data-inspector).
</Update>

<Update label="2025-09-22">
  ## Session Replay automatically appears in Event Metadata

  <Frame>
    <img alt="Session Replay automatically appears in Event Metadata" />
  </Frame>

  Event details now include relevant Session Replays directly in Query Builder, Lexicon, and Event pages.

  **Why this matters**: Understanding the full context of when and where events occur just got much easier. Instead of manually connecting events to session replays, you'll automatically see the relevant replay footage right alongside your event data.

  **What you'll see**: When exploring any event, relevant Session Replays will appear directly in the event details view, giving you immediate visual context for user behavior.

  This enhancement makes Session Replay a powerful tool for data governance, helping teams understand their data with less manual work and more confidence.

  For more details on this feature, see [Session Replay in Event Metadata](/docs/data-governance/lexicon#session-replay-in-event-metadata).
</Update>

<Update label="2025-09-17">
  ## Annotations, Now with Tags & Filters

  <Frame>
    <img alt="Annotations, Now with Tags & Filters" />
  </Frame>

  Annotations let you add time-stamped notes so you can see metrics with context that matters to you. We’ve seen teams add valuable context about everything from product launches, marketing campaigns, outages, to holidays.

  Now, you can tag and filter Annotations, enabling you to review metrics against different layers of context. Curious how your Marketing initiatives have moved Signups? Or how all the launches for a specific team have moved a KPI? Annotations with tags and filters makes this easy.

  **What's new:**

  * **Tag & Filter:** Add tags to your Annotations to categorize them and filter in your report so you only see what's relevant.
  * **New Annotations sidebar:** See all annotations for your report’s date range in one place.
  * **Annotations on all chart types:** Previously, Annotations were restricted to time-based charts. Now, you can access this valuable context from any of your reports.
</Update>

<Update label="2025-09-10">
  ## Mixpanel Model Context Protocol (MCP) Beta

  <Frame>
    <img alt="Mixpanel Model Context Protocol (MCP) Beta" />
  </Frame>

  What if you could talk to your data using natural language? Now you can with Mixpanel MCP Server beta, democratizing analytics access across your entire organization.

  ### How It Works

  The MCP Server serves as a bridge between AI tools (i.e., Claude) and your Mixpanel data. Connect your AI assistant and ask questions in plain English, such as "What's the retention rate for users who completed onboarding?" or "Show me our top converting events this quarter".

  ### Key Benefits

  Chat with your data like your most helpful coworker. Improve time-to-insight from "let me build you a dashboard" to "here is your answer". Empower non-technical team members to ask data questions without requiring analytics support.

  ### Getting Started

  Organization administrators enable MCP Server access in **Settings > Organization > Overview**. Then connect your AI tool and start asking questions in natural language. [Learn more in our documentation](/docs/features/mcp).
</Update>

<Update label="2025-09-08">
  ## Cohorts now in Lexicon

  <Frame>
    <img alt="Cohorts now in Lexicon" />
  </Frame>

  Cohorts have now been integrated into Lexicon, making it easier to manage and reference them alongside your other saved definitions like metrics, custom events, and custom properties.
</Update>

<Update label="2025-09-02">
  ## Updated Billing & Data Retention: Simpler Pricing, Enhanced Privacy

  <Frame>
    <img alt="Updated Billing & Data Retention: Simpler Pricing, Enhanced Privacy" />
  </Frame>

  We're making two important updates to improve your Mixpanel experience:

  We're transitioning to ingestion-time based billing. This change makes pricing more predictable and transparent—you'll be billed based on when data arrives in Mixpanel, eliminating confusion around backdated events and making it easier to track your usage in real-time.

  We're updating our default data retention period to 2 years. This change reflects our commitment to data privacy and security best practices, ensuring your customer data is stored only as long as needed for meaningful analysis.

  These changes take effect on September 1, 2025. You can see if your account is on ingestion time billing in [Organization Settings](https://mixpanel.com/settings/org/plan).

  If you have specific retention needs beyond 2 years, please contact your account team to discuss custom retention options.
</Update>

<Update label="2025-08-22">
  ## Expand Event Images in Context Panel

  <Frame>
    <img alt="Expand Event Images in Context Panel" />
  </Frame>

  Expand images in Query Builder's context panel for a clearer view. When hovering over the event name, you can click associated images to easily view without leaving Query Builder.

  Whether you're validating an event property or reviewing metadata details, expanded images give you the full picture without breaking your flow. No more switching tabs or guessing from a thumbnail.
</Update>

<Update label="2025-08-18">
  ## Growth customers can now buy custom volumes of session replay

  <Frame>
    <img alt="Growth customers can now buy custom volumes of session replay" />
  </Frame>

  Growth customers can now buy custom volumes of Session Replay in addition to their 20k free replays!

  You've asked and we've answered: using more than 20k monthly replays is core to understanding your users. Growth customers can now purchase up to 500K monthly / 6M annual replays directly online.

  To purchase more replays:

  * Existing customers: you can manage your plan directly, including purchasing additional replays, from the pricing page or from your organization details page.
  * New customers: during your plan purchase, you can now directly add additional replays as you build your plan.

  You can view Session Replay pricing in our [plan builder](https://mixpanel.com/settings/org/plan?show-modal=plan-builder\&pb-step=session-replay). For questions about billing, check out our documentation [here](/docs/pricing#how-mixpanel-pricing-works)
</Update>

<Update label="2025-08-13">
  ## 📱 Session Replay is now available for iOS and Android

  <Frame>
    <img alt="📱 Session Replay is now available for iOS and Android" />
  </Frame>

  Now you can replay user sessions for web and mobile (iOS + Android), all in one unified platform alongside your analytics. With Mobile Session Replay, you can:

  * Answer the what and why in one place by moving seamlessly between reports and replays
  * Find what matters faster by filtering replays with trusted Mixpanel events, properties, or cohorts
  * Watch the complete user journey for web, iOS, and Android

  Session Replay is free to try. Check out resources below to get started!

  [View Docs →](/docs/session-replay/implement-session-replay)
</Update>

<Update label="2025-08-11">
  ## Metric Trees

  <Frame>
    <img alt="Metric Trees" />
  </Frame>

  Metric Trees gives you a complete picture of what drives success, helping you make data backed decisions in the context of your growth strategy.

  With Metric Trees, you can:

  * **Rally around KPIs:** Align leaders to contributors on how every initiative ladders up to impact
  * **See impact instantly:** Spot what’s changed, and why, from inputs to outputs
  * **Create accountability:** Assign clear owners to each key metric and track progress
  * **Adapt with your strategy:** Keep your tree up-to-date as priorities shift
  * **Drive action:** Jump from metrics to contextual reports, discuss in real time, and log insights for traceability

  Map your path forward and drive meaningful growth. [Learn More →](/docs/metric_tree)

  NOTE: Metric Trees add-on is available for customers on the Enterprise plan. Reach out to your account team to learn more.
</Update>

<Update label="2025-08-11">
  ## Experimentation Reporting 2.0 - Trusted Insights, Maximum Impact

  <Frame>
    <img alt="Experimentation Reporting 2.0 - Trusted Insights, Maximum Impact" />
  </Frame>

  With Mixpanel’s new Experimentation Reports, you can monitor every experiment with any Mixpanel Metric — business, performance, or behavioral — and ensure you’re making decisions based on statistically significant results.

  **What’s new:**

  * **All metrics supported:** Measure impact on any new or existing Mixpanel metric
  * **Decisions you can trust:** Analyze multi-variant experiments with robust statistical significance.
  * **Diagnose results:** See the “why” with integrated experiment data in your behavioral analytics flow.
  * **One place for all your experiments:** View and filter all active and past experiments, their results, and decisions made.
  * **See the complete picture:** Link results with user behavior, cohorts, and session replays for the complete picture.

  **Test, learn, and innovate faster** — all in one solution for turning data into confident decisions. [Learn More →](/docs/experiments)

  NOTE: Experimentation Reporting is available as a paid add-on for customers on the Enterprise plan. Reach out to your account team to learn more.
</Update>

<Update label="2025-08-10">
  ## Save Column Widths in Tables

  <Frame>
    <img alt="Save Column Widths in Tables" />
  </Frame>

  Create stakeholder-ready reports that are polished and clear. You can now save custom column widths for the segments in table visualizations so your data always looks the way you want it to.

  Whether you're analyzing top-performing pages by URL or error rates by message content, you can resize segments to see the full value and save that setting. No more clipped text, and no need to reformat every time you open a report or board.
</Update>

<Update label="2025-08-05">
  ## Saved Metrics

  <Frame>
    <img alt="Saved Metrics" />
  </Frame>

  Saved Metrics lets you standardize and reuse your KPIs throughout Mixpanel. No more data inconsistencies or wasted effort. Saved Metrics empowers your entire organization to define your most important metrics.

  What’s new with Saved Metrics:

  * **Standardize Definitions:** Define and save a metric definition once
  * **Share Metrics:** Share your saved metrics with specific teams, individuals, or across your entire project to ensure everyone is using the same metric
  * **Reuse Across Workflows:** Apply saved metrics across your reports, boards, and other Mixpanel features. Save time by using the source of truth.
  * **Update with a Click:** When a metric's definition changes, update it once and those changes will automatically reflect everywhere the metric is used.
  * **Clear Context:** Automatically see more details about what’s in a metric definition before you select it
  * **Multi-Group Analysis:** For customers with the Groups Add-on, you can now analyze metrics across different groups in the same report. More details [here](/docs/data-structure/group-analytics).

  Saved Metrics enables your team to move faster, make more informed decisions, and focus on what truly matters: driving impactful business outcomes.

  Learn more in our documentation [here](/docs/features/saved-metrics-and-behaviors).

  Plan Availability: Saving Metrics is available on all plans. Sharing Saved Metrics is available on Growth and Enterprise Plans only. Saved Metrics are also compatible with purchased add-ons.
</Update>

<Update label="2025-07-30">
  ## Heatmaps for Web

  Now available in Mixpanel: Heatmaps, a better  way to visually understand your customers.

  Quickly see where users are clicking (and where they aren’t), spot friction points, and identify hot spots and dead zones at a glance. Use these insights to optimize page layouts, CTAs, and content based on real user interactions.

  Heatmaps come included with Session Replay and are easy to enable - just change one line of code ([Read more](/docs/session-replay/heatmaps)). **Don’t have Session Replay enabled yet?** [Learn more](/docs/session-replay), or reach out to your account team to get started.

  <VideoButtonWithModal />
</Update>

<Update label="2025-07-15">
  ## Customize Your Project Homepage

  <Frame>
    <img alt="Customize Your Project Homepage" />
  </Frame>

  Tailor your Mixpanel experience to suit the needs of your organization. Now, project admins can set any Board in the project as the default project homepage. This means a personalized and productive start for every employee logging into Mixpanel.

  Since Mixpanel Boards are incredibly flexible, you can craft a homepage that suits your project. Here’s how a dedicated Homepage Board can improve your team's workflow:

  * **Access Key Information:** Direct your team to important documentation, onboarding guides, or key project data.
  * **Streamline Onboarding:** Guide new users to intro reports and content that’s specific to your organization.
  * **Highlight KPIs:** Put key KPIs front and center for your team by adding them to the Homepage Board.

  Users with the project admin role can configure the project's homepage in Project Settings. Removing the Homepage Board reverts the project to the default Mixpanel Home.
</Update>

<Update label="2025-05-19">
  ## Track key AI metrics

  <Frame>
    <img alt="Track key AI metrics" />
  </Frame>

  When building AI products and features, we want to help you measure impact and effectiveness. You need clear answers to questions like:

  * Are customers even using my chatbot?
  * How much value do they get from AI outputs?
  * Do improvements to my agent drive higher retention?

  Our new template helps you answer these questions quickly. Get a dashboard with proven AI metrics up and running with a few clicks, so you can start understanding how AI impacts user and business outcomes.

  Learn how to set up templates in our [help docs](/docs/boards/templates).
</Update>

<Update label="2025-04-22">
  ## Optimized Funnel Re-entry

  When Optimized Re-entry mode is enabled, we actively evaluate all funnel entry attempts - even if the user’s previous funnel is still in progress. This allows us to capture potential conversions which might occur from subsequent entries, maximizing total conversions. If any user funnel entries within the report date range result in a conversion, we count the user as converted.

  With this mode, we are able to answer

  * How many unique users converted irrespective of if it was their first attempt or not?
  * How many total conversions were there, while counting simultaneous ongoing funnels?
  * Which webpages led to drop-offs?

  Learn more in our [help docs](/docs/reports/funnels/funnels-advanced#optimized-re-entry)

  <VideoButtonWithModal />
</Update>

<Update label="2025-04-16">
  ## Global Sidenav

  <Frame>
    <img alt="An easier way to navigate" />
  </Frame>

  We’ve reorganized Mixpanel’s navigation into a persistent left-side panel to make getting around simpler and more intuitive. Here’s what’s new:

  * **More Screen Space:** We’ve removed the top navigation bar to give you more space to work.
  * **Effortless Navigation:** All your navigation is now on the left - making it easier to switch projects, create new content, and access Events, Users, Lexicon, and Cohorts seamlessly.
  * **Always Accessible:** The navigation panel is always available as your navigate through Mixpanel - making it easier to get around.

  How it’s organized:

  * **Top:** Project switching, creating new content, search, and quick links to Events, Users, Lexicon, and Cohorts
  * **Middle:** Boards - grouped into Pinned, Favorites, and Your Boards
  * **Bottom:** Settings, Help, and advanced reporting features.

  **Keyboard shortcuts:** `CMD + K` Open search, \`\`\` Expand or collapse the side navigation, `Esc` Close a report to return to your Board

  <VideoButtonWithModal />
</Update>

<Update label="2025-03-27">
  ## Enforce better governance with Data Standards

  <Frame>
    <img alt="Enforce better governance with Data Standards" />
  </Frame>

  ### **Enforce better governance with Data Standards**

  We’ve made it easier than ever for teams to enforce trustworthy, consistent data with our new Data Standards feature — now available for Enterprise customers. This update empowers Data Governors to define event naming and metadata requirements for their projects, and instantly spot events that don’t comply.

  The new Data Standards feature includes:

  * **Custom Rules**: Define rules for naming conventions, event owners, descriptions, and uploaded images — all from the new Data Standards tab in Lexicon.
  * **Compliance Statuses in Lexicon**: Events are automatically evaluated and flagged as compliant or non-compliant, with visual indicators for events that are misnamed or missing metadata
  * **Filters for Fast Cleanup**: Quickly surface and fix non-compliant events using a new, dedicated filter view in Lexicon

  Data Standards gives Data Governors peace of mind — and makes it easier for everyone else to trust, explore, and analyze clean, reliable data.

  This feature is available exclusively for Enterprise plans. Learn more in our documentation [here](/docs/data-governance/data-standards).

  PS: Up next is automation! We’re exploring ways to apply automated actions when your Data Standards are met or violated — such as auto-hiding non-compliant events, or automating Event Approval. Interested in early access? Reach out to your Mixpanel Account Manager today.
</Update>

<Update label="2025-03-25">
  ## Mirror Sync Mode for Redshift Warehouse Connectors

  [Mirror](/docs/tracking-methods/warehouse-connectors#mirror) — a sync mode keeps your data in Mixpanel fully in sync with any changes that occur in the warehouse — is now generally available for the [Redshift Warehouse Connector](/docs/tracking-methods/warehouse-connectors).

  With Mirror, any time data is modified in your underlying warehouse table, that change is automatically reflected in Mixpanel through change data capture (CDC). You can iteratively implement, rename or remove columns, or reconcile transactions in your warehouse without any worry of data divergence in Mixpanel. This sync enables accurate analysis for all data types, including business data that changes often such as purchases.

  The Redshift Warehouse Connector is an add-on for Enterprise plans. Contact your account team to inquire about access

  <VideoButtonWithModal />
</Update>

<Update label="2025-02-10">
  ## New features for enhanced B2B account analytics!

  <Frame>
    !\[New features for enhanced B2B account analytics!]\(/images/changelog/B2B - Summary.png)
  </Frame>

  [Two new features built for B2B analysis](/docs/data-structure/group-analytics#how-is-b2b-company-analytics-different-than-group-analytics) are now available for customers with the [Group Analytics](/docs/data-structure/group-analytics) add-on! You can now improve adoption and reduce churn risk by monitoring strategic accounts with out-of-the-box **Account Profiles** and **Activation Metrics**.

  You can now answer questions such as:

  * Who are the power users within our strategic accounts?
  * How active are users within our strategic accounts?
  * How are users within our strategic accounts flowing through our activation funnels?
  * What are potential upsell opportunities for our strategic accounts?

  To access the new features, customers will need the Group Analytics add-on. In addition, you will need to turn on the advanced B2B Account Analytics functionality, steps for which are [here](/docs/data-structure/group-analytics#setup-b2b-company-key).

  Once done, [Account Profiles](/docs/features/advanced#company-profiles) will automatically be created per each account, and can be accessed in the Users tab. You can also share Account Profiles with key stakeholders for simple account health reporting, such as Sales teams, Customer Success teams, and executives.

  To identify your [Account Activation Metrics](/docs/features/advanced#activation-metrics), head over to an insights report and use the new computed property now available: **Number of users who did… (then select an event)**. This property makes it easy to create reports to track account activation, i.e., their adoption progress as an account.

  ***

  We have also deprecated the Revenue App as of Dec. 31, 2024. Thanks to our recently released [Revenue Analytics](/changelogs/2024-10-08-revenue-analytics), you can rebuild this report (and more) and save anything you create to dashboards. This [help document](/docs/features/revenue-analytics#metrics-definitions) guides you through step-by-step.

  \*Requires ingesting revenue data from [Data Warehouse Connectors](/docs/tracking-methods/warehouse-connectors).
</Update>

<Update label="2025-02-04">
  ## Introducing Autocapture from Mixpanel

  <Frame>
    <img alt="Set up analytics in minutes with Autocapture" />
  </Frame>

  Introducing Autocapture from Mixpanel! With just a single code snippet, you can now track common events like pageviews, button clicks, and form fills without custom code, enabling you to get started with analytics in less than 2 minutes.

  Mixpanel’s Autocapture is a great starting point for analytics, getting you to critical user insights quickly. It’s also designed to work well in tandem with precision tracking — so you can go deeper and add more refined tracking over time.

  Learn more about Autocapture and setting it up in Mixpanel [here](/docs/tracking-methods/autocapture).
</Update>

<Update label="2025-02-04">
  ## Our Growth plan just got 100x more generous

  <Frame>
    <img alt="No more feature limits. Get 1M monthly events free on Mixpanel’s Growth plan." />
  </Frame>

  No more getting stuck on arbitrary feature limits—get 1M monthly events free on Mixpanel’s Growth plan by simply putting down a credit card. Powerful analytics, unlimited reports, 20K session replays, cohorts for behavioral segmentation, and more… now starting at the affordable price of free.

  Read more on our [blog](https://mixpanel.com/blog/mixpanel-pricing-1m-free-events-autocapture/), and check out our new pricing [here](https://mixpanel.com/pricing/).
</Update>

<Update label="2025-01-31">
  ## Watch replays for any event — even backend events

  <Frame>
    <img alt="Watch replays for any event — even backend events" />
  </Frame>

  ### **Watch replays for any event—even server-side**

  Coming soon on all plans, exclusively at Mixpanel: **Server-Side Stitching**!

  Session Replays now work for **all** your data, not just client-side or front-end events. That means you can jump straight from reports to replays, even for events tracked via APIs, sent from your data warehouse, or sent from the server-side.

  Here’s what’s new:

  * **Replays for your most important events** like purchases or signups—events typically tracked server-side or sent from the data warehouse. Now, you can see exactly what users did leading up to those moments.
  * **No more dead ends** – Product teams track data in many ways, and now, instead of hitting empty playlists for many of your events, you can watch replays seamlessly across all data sources.
  * **Complete view of the user journey** – Diagnose issues, optimize funnels, and improve your product experience with replays that work across client-side **and** server-side data.

  With **Server-Side Stitching**, you get a **fuller picture of user behavior**, helping you better diagnose issues, optimize funnels, and hone your product.

  This feature is **only available with Mixpanel**—no other session replay provider offers this level of visibility.

  You can learn more in our documentation [here](/docs/tracking-methods/sdks/javascript/javascript-replay#server-side-stitching).
</Update>

<Update label="2025-01-21">
  ## Mixpanel for Startups now provides over \$150k in value

  <Frame>
    <img alt="Mixpanel for Startups now provides over \$150k in value" />
  </Frame>

  The [Mixpanel for Startups](https://mixpanel.com/startups/) program has been revamped to ensure founders and product teams have the tools they need to build and scale, from day one.

  Eligible companies receive their first year of Mixpanel free on the Startup Plan — a new plan designed exclusively for participants in the program. This includes:

  * Advanced analytics capabilities
  * No feature gates
  * 500K Session Replay recordings
  * 1B annual events
  * Unlimited team seats
  * World-class support
  * And more!

  The new offer is worth over \$150k in value and startups who meet the eligibility criteria are welcome to [apply here](https://mixpanel.com/startups/).

  Note: The Startup Plan is not eligible for BAAs or MSAs. Additional details can be found in our [docs here](/docs/pricing/startup-program).
</Update>

<Update label="2024-12-19">
  ## Pin Filters to Boards

  <Frame>
    <img alt="Pin Filters to Boards" />
  </Frame>

  Mixpanel has new customization options for the filters applied to your Boards. These Board-wide filter settings give you more control and flexibility over how people interact with your Boards.

  Board-wide filter settings:

  * Limit Filter Values: Improve Board clarity by limiting the number of filter values displayed. This is particularly helpful when you have a filter with a large number of values, allowing you to show only the most relevant options. For example, limit a "Country" filter to only include countries within a specific region.
  * Start Filter with Nothing Selected: Guide users towards specific filtering options by pinning a filter option to the top of a board without applying any filter values. This gives anyone using the Board quick access to a filter without automatically updating the data in the Board for all users. For example, pin a "Region" filter to a board with nothing selected. By default, users will see global data and will have quick access to filter the reports down to a particular region.

  Note: Currently available only for enterprise plans.
</Update>

<Update label="2024-12-02">
  ## Session Replay is now available on Free and Growth plans

  <Frame>
    <img alt="Session Replay is now available on Free and Growth plans" />
  </Frame>

  Session Replay is now available on Free and Growth plans!

  * Customers on the Free plan have access to 10k free replays per month.
  * Customers on the Growth and Enterprise plans have access to 20k free replays per month.
  * Additional custom volumes of Session Replay are available as an add-on purchase for Enterprise plans.

  To access free replays, customers will need to ensure they’re on the latest Mixpanel plans.

  For customers on an existing Free plan:

  * Switch your plan to the latest Free plan, which includes 1M monthly events and 10k session replays. You can make this switch directly from the pricing page.

  For customers on an existing Growth plan:

  * You’re on the latest plan if you purchased or edited your plan after April 2024. If you’re not sure if you’re on the latest plan, you confirm on the pricing page - if you see ‘Make the Switch’ on the Growth plan, then you are on an older version.
  * You can make the switch to our latest plan directly from the pricing page.

  Enterprise customers should contact their account manager to determine their plan status.

  Read more about Session Replay in our [docs here](/docs/tracking-methods/sdks/javascript/javascript-replay).
</Update>

<Update label="2024-11-14">
  ## Add verification tags to your data

  <Frame>
    <img alt="Add verification tags to your data" />
  </Frame>

  Introducing Verified Content!

  We’ve now made it easy for teams to identify and use “verified” metrics, events, and formulas confidently. This feature helps governors mark vetted content, making it crystal clear which metrics are trusted across the organization.

  The new Verified Content feature includes:

  * Badges in Lexicon: We've added a badge next to verified Events, Behaviors, Formulas, and Custom Events
  * Verification Context: Hovering over badges displays who verified the item and when, adding accountability and transparency
  * Verification Button in Details Page: On each item’s details page, you can verify it with a single click
  * Dedicated Category in Query Builder: We introduced a Verified category in Query Builder so users can quickly filter to see only trusted content
  * Verified Badge in Query Builder Context Panel: In the footer of the Query Builder’s context panel, the verified badge shows up, reassuring users that they’re working with golden metrics

  You can learn more in documentation [here](/docs/data-governance/lexicon#verify-data)

  Note: this feature is available only for enterprise plans currently.
</Update>

<Update label="2024-10-11">
  ## India Data Residency for Mixpanel

  <Frame>
    <img alt="India Data Residency for Mixpanel" />
  </Frame>

  Like our EU Data Residency, Mixpanel's India Data Residency helps you process, protect, and manage personal data securely and according to local requirements.

  Our Data Residencies are overseen by our dynamic Global Privacy Program, which is a dedicated team at Mixpanel monitoring trends and developing solutions to ensure that Mixpanel can meet your privacy and data transfer needs, now and in the future.

  Read more on our Blog: [https://mixpanel.com/blog/india-data-residency/](https://mixpanel.com/blog/india-data-residency/)
</Update>

<Update label="2024-10-09">
  ## Choose colors for your segments

  <Frame>
    <img alt="Choose colors for your segments" />
  </Frame>

  Mixpanel now allows you to select the colors of various segments in your reports. You can choose the color for a particular segment by clicking the legend at the top of the chart. Choose between colors that exist in the theme, or choose an entirely separate color.

  Some common uses for this:

  * Highlight a particular segment for emphasis
  * On boards with the same breakdown repeatedly, set the colors for segments so they can be aligned across the board

  Color selection is available on both boards and reports, so you can easily update the segment colors for a report on a board as well. You can learn more in documentation [here](/docs/features/chart-customization#segment-coloring)

  Note: this feature is available only for enterprise plans currently.

  <VideoButtonWithModal />
</Update>

<Update label="2024-10-09">
  ## Set units for your metrics

  <Frame>
    <img alt="Set units for your metrics" />
  </Frame>

  Mixpanel now allows you to set the units for each of your metrics. You can set the unit, the precision, and whether or not you want an abbreviated value. This gets updated for tooltips as well as in the table below the chart.

  Some common uses for this:

  * Create a % based formula, and add the % unit so it's clear what the metric is measuring
  * Revenue based metrics, adding a \$ symbol to know what currency is involved

  You can also save the unit to a formula so that future uses of that formula will already be configured with the right unit. You can learn more in documentation [here](/docs/features/chart-customization#metric-units)

  Note: this feature is available only for enterprise plans currently.

  <VideoButtonWithModal />
</Update>

<Update label="2024-10-08">
  ## Mixpanel Revenue Analytics

  Mixpanel now helps you analyze the impact of your product and marketing initiatives on your key company revenue metrics. You can now answer questions like

  * How much new revenue has been generated by this product launch? Has it grown by more than 5%?
  * Why has LTV/CAC reduced, i.e why has cost of acquiring a valuable customer gone up? Which user segments are driving this?
  * Which product SKUs is contributing to the most upsell revenue? Is NRR (net revenue retention) also going up accordingly? Does it differ by company size?

  Irrespective of whether you have a transaction-based business model or a subscription-based business model, you can measure and monitor your top metrics in Mixpanel. We have built the analysis capabilities and underlying data model to ensure the differences in business models are accounted for throughout, providing 100% accurate revenue metrics analysis. Check out our [help docs](/docs/features/revenue-analytics) to learn more about when and how to use these new capabilities.

  You can also read more about [why we’re launching Mixpanel Revenue Metrics](https://mixpanel.com/blog/introducing-mixpanel-revenue-analytics-ltv-arpu-roas/) on our blog.

  NOTE: Revenue analytics features are only available to customers who have [setup Mixpanel using Warehouse Connectors](/docs/tracking-methods/warehouse-connectors)

  <VideoButtonWithModal />
</Update>

<Update label="2024-09-23">
  ## Mixpanel in your language

  <Frame>
    <img alt="Mixpanel in your language" />
  </Frame>

  Mixpanel is now available to use in additional languages, including Français, Español, Português, 한국어, 日本語, 繁體中文, 简体中文, and Bahasa Indonesia. You can choose your language from the settings menu in the top right of the page.

  <Frame>
    <img alt="localization-settings" />
  </Frame>

  Everything in Mixpanel other than events, properties, and named entities (such as board and cohorts) are translated. Mixpanel intentionally won't translate your data or named entities because you may attach your own meaning, and you have the ability to rename, or set a display name. If you have any feedback on translations, whether that is a missing translation or incorrectly translated words, please submit feedback to use [here](http://mixpanel.com/submit-feedback).
</Update>

<Update label="2024-09-11">
  ## Mixpanel Session Replay is Now Available

  <Frame>
    <img alt="Mixpanel Session Replay is Now Available" />
  </Frame>

  Mixpanel Session Replay is officially out of beta!

  With a unified platform for quantitative and qualitative insights, you can now make faster and more informed product decisions. Quickly pinpoint drop-offs in your funnels and instantly dive into replays to understand exactly why users get stuck. From improving conversions to driving team alignment with visual stories, Mixpanel Session Replay helps you watch and learn from your users.

  Note: this feature is currently available to enterprise plans only.

  Read more on our [blog announcement.](https://mixpanel.com/blog/mixpanel-session-replay/)
</Update>

<Update label="2024-07-17">
  ## Pick time ranges down to the minute

  <Frame>
    <img alt="Pick time ranges down to the minute" />
  </Frame>

  You choose date ranges that are specified up to the minute. If there's a metric that you want to drill in on for only a few hours, you can set your time range and see only that exact range. This saves you work from having to create a detailed time filter or custom property to do the same thing. Use this new feature to:

  * Look at a metric as a trend for under a day
  * Zoom into your data on trends
  * Share insights on a smaller timeframe without having to zoom in again

  This is supported for all chart types in Insights, Funnels, Flows and Retention.

  <VideoButtonWithModal />
</Update>

<Update label="2024-06-27">
  ## Color Themes

  <Frame>
    <img alt="Color Themes" />
  </Frame>

  You can now set the color theme of your charts in Mixpanel. We have a few preset themes for you, but you can also create and save your own theme. You use a different theme for every report, and even have a dashboard with reports using different themes. You'll also be able to set a project wide default for color themes.

  You can learn more in documentation [here](/docs/features/chart-customization#theme-customization)

  <VideoButtonWithModal />
</Update>

<Update label="2024-06-27">
  ## Axis Customization

  <Frame>
    <img alt="Axis Customization" />
  </Frame>

  You can now customize the axes of your charts. Using this, you can build better dashboards and tell the story you want more easily. Any changes you make can be saved and will be reflected on the dashboard. To access these new options, go to the "Chart" tab of the query builder.

  You'll be able to:

  * create a secondary y axis on the right hand side to show data of different scales
  * determine the axis thresholds, so you can zoom in or out
  * add labels to make what you're measuring more clear
  * determine the unit and decimal precision of your axes

  You can learn more in documentation [here](/docs/features/chart-customization#axis-customization)

  <VideoButtonWithModal />
</Update>

<Update label="2024-06-18">
  ## Know where you are with a persistent navigation panel

  <Frame>
    <img alt="Know where you are with a persistent navigation panel" />
  </Frame>

  Now when switch between Boards or reports, you will always see the side navigation panel and keep your context. Your current Board will also be highlighted on the side as you're viewing a report within a Board. You'll be able to see where you are with respect to your Boards, and easily create a new Board, search, or go to Home.

  As part of these changes, the query builder has moved to the right of your screen. This allows for consistent placement of report tools, and makes access to report level controls easier. If you prefer to keep the query builder on the left side, you can press the button on the bottom right of the panel to switch it back to left. This setting will be persisted for any future visit to Mixpanel.

  As part of these changes we've also added keyboard shortcuts: \`\`\` to expand or collapse the side navigation, `Esc` to close out of a report and return the your Board.
</Update>

<Update label="2024-06-18">
  ## Mirror Sync Mode for Warehouse Connectors

  Mirror is a new mode on Warehouse Connectors that keeps Mixpanel in perfect sync with your warehouse. Any time data is modified in your underlying warehouse table, that change is automatically reflected in Mixpanel through change data capture (CDC). You can iteratively implement, rename or remove columns, or reconcile transactions in your warehouse without any worry of data divergence in Mixpanel. This sync enables accurate analysis for all data types, including business data that changes often like purchases.

  Supported for BigQuery and Snowflake today. Contact your account team to get access.

  <VideoButtonWithModal />
</Update>

<Update label="2024-05-09">
  ## Home

  <Frame>
    <img alt="Home" />
  </Frame>

  Home is the new landing experience in Mixpanel. It’s for you to jump back into your workflows and get a glimpse into what’s happening across your product and your project in Mixpanel.

  The main sections of Home includes:

  * **Your Recents**: your most recently viewed reports and boards
  * **Your Product**: this section is default populated with the top insights reports in your project, you can customize and change which insight report you’d like to display on Home
  * **Top Boards**: the most popular boards in your project
  * **Suggested Creators**: people in Mixpanel who are building boards and reports that we recommend checking out
  * **Recent Users**: a list of recently seen users on your product
  * **New Events**: a list of newly tracked events in your project
  * **Resources**: a list of resources that are also available in the top navigation
</Update>

<Update label="2024-05-09">
  ## Column Chart Visualization

  <Frame>
    <img alt="Column Chart Visualization" />
  </Frame>

  You can now view your time series as a column or stacked column chart in Insights report. You can use Column charts to:

  * Visualize and compare customer segments by behaviors or engagement over time
  * Compare product sales performance across different regions or customer types
  * Compare funnels or retention metrics
  * Visualize monthly new sign-ups, active users, and churn rates
  * Present financial trends and health over time

  Column charts give you another way to visualize your data. Column charts tend to be better when visualizing data over shorter time frames.

  <VideoButtonWithModal />
</Update>

<Update label="2024-04-08">
  ## AI Chatbot and Search in Mixpanel Docs

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/3407a37ce1634f51b94b380c40c96306)

  Mixpanel has added AI to the search tool in our docs! Now, get instant AI answers to technical questions about Mixpanel, any time you’d like. Try it now with questions like:

  1. What should be the first event I track?
  2. How do I migrate off Google Analytics?
  3. How do I calculate time spent?
  4. How do I import Snowflake data?
</Update>

<Update label="2024-04-03">
  ## Save and Reuse Funnel and Retention Behavior definitions

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/e84c62b2454d496b960fb0fdb09b9785)

  You can now save a funnel or retention behavior definition, and reuse it across your reports. This allows you standardize on a definition and feel confident in not missing any changes if you need to update a definition. This also saves time from not having to redefine your funnel or retention behavior for every report.

  Note that the [behavior](/docs/reports#behaviors) is saved, and not the [metric](/docs/reports#metrics), so you can use the same funnel to in your conversion rate metric, as well as your time to convert metric.

  You can save and share your behavior definitions just like a custom event or custom property. You'll be able to see all saved behaviors in Lexicon. See [docs](/docs/features/saved-metrics-and-behaviors) for more information on saved behaviors.
</Update>

<Update label="2024-04-03">
  ## Plot Insights, Funnels, and Retention on the same chart

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/81c25f63005d4d0da8d06c1558ac1c70)

  You can now plot any funnel or retention metric in Insights, and you can plot any combination of them together. Insights is where you can see how any of your metrics are doing and how different metrics are doing side by side.

  With these changes you can now:

  * compare retention of different actions on the same retention curve chart
  * see how the conversion rate for different steps in a funnel trend over time in the same chart
  * see funnel and retention metrics in a table visualization of your board
  * use table, pie, stacked bar and stacked line visualizations for funnel and retention metrics
  * build a detailed table of funnel metrics in one space
  * plot different types of metrics on the same line chart
  * make formulas that use funnel and retention metrics

  You can see [here](https://mixpanel.com/p/FN3F4aWpunCKSuZNxQQz38) to see some examples of new types of reports you can now build in Mixpanel.
</Update>

<Update label="2024-03-27">
  ## Ask your questions in natural language with Spark AI

  <Frame>
    <img alt="spark" />
  </Frame>

  Spark is now available on Boards. Launch a Spark card and use it to ask any question in natural language. You’ll be able to iterate on the prompt and jump in to see what was produced.

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/d6d2919a4c0649d18c35a218cf343d0a)

  You can learn more in docs [here](/docs/features/spark).
</Update>

<Update label="2024-03-14">
  ## Merge data from different events on-the-fly with Borrowed Properties

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/d45c325a7ee544a9965e90c3a5127257?sid=0cc8f226-72a4-4817-bd6d-13732a3b4237)

  Introducing Borrowed Properties, where you can ‘borrow’ a property from another event on-the-fly and leverage it for analysis as though you’ve tracked it all along. No re-tracking or complicated joins required.

  Here’s some scenarios where Borrowed Properties makes life a whole lot easier:

  ### Merging data from client-side to server-side

  * **Scenario**: You want to understand which restaurant category leads to the most confirmed purchases.
    * “Order placed” is a client-side event that has a property called restaurant category.
    * “Transaction completed” is the server-side event of interest that you’d like to break down by restaurant category.
  * **Solution**: Borrow the restaurant category property from “Order placed” onto “Transaction completed” and poof! It’s like “Transaction completed” always had the restaurant category property.

  ### Analyzing across two different teams

  * **Scenario**: One team created a “Speed Mode” feature that runs the app faster. There’s a “Speed Mode” event with the property Speed Mode Enabled.
    * Another team wants to know how Speed Mode impacts how many pages are viewed. But the “Page View” event doesn’t have the Speed Mode Enabled property.
  * **Solution**: Borrow the Speed Mode Enabled property onto “Page View” and teams can instantly understand how page views differed when Speed Mode was turned on.

  All these use cases, without engineers needing to re-track data or develop complicated workarounds.

  Borrowed Properties is available for customers on Growth & Enterprise plans. For more information, check out our [help docs.](/docs/features/custom-properties#borrowed-properties)
</Update>

<Update label="2024-03-11">
  ## Subscribe to Boards for ongoing notifications on metrics

  Boards are a useful tool to collect a series of reports in one place, but they shouldn't be a set and forget experience. It's important to stay in the loop with how these key metrics are moving.

  To keep you and your team up to date on how much progress you're making towards your metrics, you can [Subscribe to a Board](/docs/boards#board-subscriptions).

  All it takes is setting the schedule of how often you want to receive this information and selecting where you want to read it (email or Slack). Teams that are collectively informed on their data can stay on the same page, and using Subscribe to Boards can help them get there.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  You can also subscribe people outside of your team to continuously provide them a quick and meaningful insight into key metrics.
</Update>

<Update label="2024-03-11">
  ## See what actions lead to retention with Behavioral Properties in Retention

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/dd4042654e6f46039d011a680fe93948)

  Now in Retention, we’ve made it possible to breakdown users by what they do, not just who they are. This unlocks the ability to find the actions you can influence that will increase the long term retention of a user finding value. At its core, Behavioral Properties in Retention allows you to:

  * Summarize user activity after the starting event, whether it is a count of events, or a summary of properties on those events.
  * Set that summary of activity in a timeframe, for example, the number of times a user does the specified activity within 7 days / 1 hour / 30 minutes of the starting event.
  * Uncover what activities within a certain timeframe correlate with the how often your users do the action you want them to do in the long term.

  A powerful use case for Behavioral Properties in Retention is finding the “aha” moment in your product, which describes the actions a new user does after signup that lead them to become an active user of your product. A classic example is Facebook’s “aha" moment, which was “adding 10 friends within 7 days results in a huge jump in daily active usage”.

  In our own example, you can dig into what actions a user does within 7 days after signup that lead them to watch more videos long term. The result we find is that the more channels they subscribe to, the more likely they are to retain. This insight can drive a strategy to create an experience that prompts users to subscribe to popular channels when they first signup.

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2024-03-07">
  ## Compare against the best with the Benchmarks 2024 Report

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Find out what good versus great performance looks like and put your own performance in perspective. Try out our new Company KPIs template to see how your key metrics in 2023 directly measure up to those of your peers. Simply click "New board", select "Use a Template", and pick the Company KPIs template - Benchmarks 2024 edition. After inputting your signup and value moment events, you'll see your last year's growth, retention, stickiness, and engagement metrics next to your industry's benchmarks. Use these to shape your product plans and visions for 2024. You can also download the [Benchmarks report](https://mixpanel.com/benchmarks/)to explore product benchmarks by industry. From layoffs in the Tech space, to a surge in mobile users in Gaming, to consumer trends in Ecommerce, 2023 performance varied greatly. We examined data from over 7,500 companies to understand what growth, retention, engagement, and marketing metrics looked like last year across six key industries.
</Update>

<Update label="2024-03-05">
  ## Set your visualization to WTD/MTD/QTD/YTD

  Mixpanel now supports the ability to set the timeframe of your visualization by “X”-to-date:

  * Week to Date (WTD): The period from the beginning of the current week up to the present day.
  * Month to Date (MTD): The interval starting from the first day of the current month up until the current date.
  * Quarter to Date (QTD): The time span from the start of the current quarter (three-month period) to today.
  * Year to Date (YTD): The duration from the beginning of the current calendar year to the present day.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Adjusting your visualizations to these time frames can be a useful way to align to the way you track progress in your business.

  You can select the start of the week and the start of the quarter in your project settings.

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2024-03-05">
  ## Measure revenue drop-off at each funnel step

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/e041e17a02d4429b84304ba0ce1345dc)

  It’s always been possible to view a series of events through a funnel, but now, we’ve added the functionality to [sum a property](/docs/reports/funnels#property-sum) on those events and visualize those values through a funnel. This type of analysis sets the focus on the outcome of the funnel being completed, not just that the conversion rate of the funnel is high.

  The most exciting use case unlocked from being able to view the sum of a property moving through a funnel is what we call Revenue Conversion. This analysis can help answer the question: “a segment of users might all convert, but how much dollar value of items did they have at each step, at which steps was this money lost, and how much did they ultimately convert with?” <img alt="changelog Image" />

  A couple instances where Revenue Conversion analysis can be useful are:

  1. Can determine which page a user lands on (sale, men’s wear, etc) ends up with the most money spent at checkout. All pages might have similar conversion rate to purchase, but some might drive more revenue at checkout.
  2. Can shift marketing spend to the industry (Healthcare, Fintech, etc) that have the highest average revenue when they purchase.
</Update>

<Update label="2024-03-05">
  ## Expanded Time To Convert functionality in Funnels

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/5150be7a7b194de0ac538ff85c35c3ce)

  Understanding how long it takes users to do actions or convert is key in building an efficient product that gets users to value fast, or, timing marketing strategies. We’ve improved this analysis by opening up new ways to answer questions on the time it takes users to complete a series of actions — this is made possible with our new expanded functionality of [TTC in Funnels](/docs/reports/funnels#time-to-convert).

  Now, you can measure the amount of time it takes a user to convert in **all of our aggregations** (Average, Median, Percentile, Min & Max) to learn whether the adjustments to a workflow are decreasing the friction it takes to get to a moment of value.

  * Who are the users that look the lowest amount of time to signup after viewing our new landing page?

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Can also bucket any of these funnel metrics by the Time To Convert on the whole funnel or a certain step.

  * How many users converted through our signup funnel based on how quickly they went from step 3 (Upload Media) to step 4 (Invite Friends)?

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Finally, you can decouple the time to convert metric from the time to convert breakdown based on a specific step in the funnel to understand which actions lead users to reach value faster.

  * Do prospects purchase faster when their time to convert from viewing a product to adding it to cart is quick?

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2024-03-05">
  ## Segment users by their behaviors in Funnels

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/e6e9806db88b448bb82044033ac052cf)

  Now in Funnels, we’ve made it possible to breakdown users by what they do, not just who they are. This unlocks the ability to find the actions you can influence that will increase the likelihood of users converting through a funnel or completing a specific step.

  The core functionality of Behavioral Properties in Funnels is as follows:

  1. You can analyze how often one step of a funnel was done and how that contributes to overall conversion:

  * Insight: users who watch more videos subscribe to channels at a faster rate.
  * Result: when a user finishes a video, autoplay another similar video in an attempt to keep them watching more.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  2. It’s also possible to learn how actions outside of your funnel influence overall conversion or certain steps. We’ve built this workflow so that you don’t have to put arbitrary steps into your funnel:

  * Insight: for the users who completed the signup funnel, most of them read help docs over 10 times before doing so.
  * Result: make help docs more apparent at the beginning of the funnel.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  3. The other unique functionality to Funnels Behavioral Properties is the ability to decouple the breakdown step from the metric step. This is useful to answer questions about whether the frequency of a step in a funnel influenced a different step:

  * Insight: users \*\*\*\*who complete step 1 (product view) to step 2 (add to cart) more often have a higher rate of converting from step 2 (add to cart) to step 3 (purchase).
  * Result: when a user adds an item to the cart, show them a pop up with other related items they might also want to add to cart.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  4. Use the *Aggregate Property per User* breakdown to segment metrics by things like time, cost, or “variety”.

  * Insight: Users who add a wider variety of brands to cart have a higher rate of purchase.
  * Result: Create Black Friday landing page to have an assortment of goods rather than focused on one specific category.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  5. Set a Behavioral Property as a filter to dig deep into a select group of users who are behaving a specific way in the funnel

  * Metric: Users that added at least five items to their cart before purchasing.
  * Result: Can grab their email and send them a note when there is an offer for another five items at a different date.

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2024-03-05">
  ## Get alerted when product experiences break

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/0284fcd216c74397966996fbb558b053)

  We’ve expanded the amount of funnel metrics you can set an [Alert](/changelogs/2023-03-29-custom-alerts) on so you can have full coverage into knowing whether your product is running smoothly:

  * Conversion Rate
  * Unique Converting Users
  * Total Conversions
  * Time to Convert
  * Sum of a property
  * The metrics above, but for specific step ranges in a funnel

  When your funnel metric is visualized as a line chart, it is also possible to use our [Anomaly Detection](/changelogs/2023-05-05-anomaly-detection-and-root-cause-analysis) feature.
</Update>

<Update label="2024-02-27">
  ## Track your ad performance metrics in less than 10 minutes

  Note: this is our latest offering for [Mixpanel Marketing Analytics](https://mixpanel.com/m/mixpanel-marketing-analytics/)

  Ad-performance metrics are key to help marketers adjust their marketing spend and create the most return on investment. On a daily basis, it’s important to measure ROAS, CPC, CPM and ad-spend — and now, Mixpanel has made it quick and easy to bring this data into Mixpanel.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Our solution was built based on two key market trends:

  1. The number of Ad platforms has grown, and marketers want to leverage these channels. Rarely do you advertise only on 2 platforms: Google and Meta.
  2. Warehouses have fast become the central location of housing all a company’s data. Considering this, ad-networks are making it easier to export ad performance data (spend, clicks, impressions) to the warehouse.

  In line with these trends, we’re launching the new Ad-Spend Warehouse Connector, which makes it easy to bring ad data from the warehouse and into Mixpanel. Our solution provides a simple setup experience to send data from all of your ad networks into Mixpanel, and it only takes a few minutes to do so.

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/69dbc98ffeca415aafb10ede7a52b925)
</Update>

<Update label="2024-02-13">
  ## New Experience and Features in Funnels and Retention

  Mixpanel's funnels and retention reports are where you can see user behavior through a series of events. With our next set of changes, we are making funnels and retention reports more powerful, while making them easier to use and keeping our controls in a place consistent with insights.

  You can try the new funnels and retention experience in our demo projects, [here](https://mixpanel.com/project/3018488/view/3536632/app/funnels).

  ## Funnels Report Changes

  <VideoButtonWithModal />

  [New Funnels Report Walkthrough](https://www.loom.com/share/7905e588beea48c5bc757ce8c43aae8b)

  Here is a quick summary of changes:

  * Funnels is getting revamped so that your funnel definition as well as the way you measure your funnel will be displayed in the query builder at all times.
  * You can explicitly define which steps of the funnel you are interested in.
  * More chart types are available across all different funnel metric measurements.
  * [Time to Convert is available as a measurement](/docs/reports/funnels/funnels-advanced#time-to-convert-measurement), if you are looking to see a trend or summary of your conversion times.
  * Time to Convert is available as a breakdown, if you are interested in seeing something like a distribution of conversions, by their conversion time.
  * Frequency per User is available as a breakdown.

  ## Retention Report Changes

  <VideoButtonWithModal />

  [New Retention Report Walkthrough](https://www.loom.com/share/45ddc28851aa494ead99bccafe1f9a37)

  Here is a quick summary of changes:

  * Retention is getting updated so that your retention behavior definition as well as the way you measure your retention behavior will be displayed in the query builder at all times.
  * You can explicitly define which retention group you are interested in.

  ## New Analysis Capabilities

  ### Build and Visualize More Metrics, Faster

  <VideoButtonWithModal />

  [Funnels and Retention Reports: Build and Visualize Metrics Faster](https://www.loom.com/share/bee5153decf441c49d141f8b68f161e4)

  Insights, Funnels and Retention now all follow the same structure. In the query builder on the left, you can define the behavior you want to measure, as well as the way to measure it. Each query builder now has its own self contained definition of a [metric](/docs/reports#metrics). We’ll be leveraging this concept more in the future. More chart types are available across funnels and retention, allowing you to visualize funnel and retention metrics in more way than before.

  ### See Revenue Drop off in Funnels

  <VideoButtonWithModal />

  [Revenue Funnel Drop-off for E-commerce Companies](https://www.loom.com/share/e041e17a02d4429b84304ba0ce1345dc)

  For e-commerce companies, the most important thing is their sales funnel. Seeing how many users convert is great, but the real end goal is seeing how many dollars converted. With revenue drop off, you can now see the revenue at each stage in the funnel, and not just the users. This helps identify which steps are seeing the most lost dollars and which segments are performing or not.

  ### More Time to Convert Options

  <VideoButtonWithModal />

  [New Funnels Time to Convert Analysis Capabilities](https://www.loom.com/share/5150be7a7b194de0ac538ff85c35c3ce)

  See how your funnels are performing beyond just average time to convert over time, and median time to convert as a bar chart. We have added the ability to see median, average, P25, P75, P90, P99, min and max time to convert, using any visualization you’d like.

  You also have more power in [Time to Convert breakdowns](/docs/reports/funnels/funnels-advanced#time-to-convert-breakdown). You can choose the step range you would like the breakdown to apply to, while using a different step range for your measurement. This can allow you to see if converting quick on step 1 → 2 leads to higher conversion overall, and draw more insights from time to convert.

  ### Alerts of Funnel Metrics

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/0284fcd216c74397966996fbb558b053)

  Alerts are much more powerful in funnels now. Instead of only being able to alert on conversion rate, you can now alert on any funnel metric, such as time to convert, or the number of conversions. You also get the power of anomaly detection, if you’d like us to detect when there’s something strange happening.

  ### Behavioral Properties in Funnels

  <VideoButtonWithModal />

  [New Funnels Alerts Features](https://www.loom.com/share/e6e9806db88b448bb82044033ac052cf)

  You are no longer limited to only seeing the number of times a certain step was performed in a funnel. You can now choose any event, and see how that influences your funnel. This is especially useful if you have a set funnel definition, and you’re interested in how non-core actions might affect your conversion rate. You no longer have to add and remove steps in between your funnel to see how different events affect your funnel.

  You can also see how the properties of events done between funnel steps affects funnel conversion. For example, you can see how many different categories of items were viewed in a purchase funnel, which may be more telling than a raw count of items viewed.

  [See more about Frequency Per User in Funnels](/docs/reports/funnels/funnels-advanced#frequency-per-user).

  ### Behavioral Properties in Retention

  <VideoButtonWithModal />

  [New Funnels Alerts Features](https://www.loom.com/share/dd4042654e6f46039d011a680fe93948)

  Have you wondered if doing certain actions affect retention? With the new Frequency per User and Aggregate Property per User options available in breakdowns, you can summarize user activity and see how it affects retention. Mixpanel will summarize activity after the starting event, whether it is a count of events, or a summary of properties on those events. You can answer questions like: how many song plays does it take after sign up before my retention is 50%? Being able to analyze what actions correlate with retention will give you new insight on how to improve your product.
</Update>

<Update label="2024-02-08">
  ## Be notified of major shifts in data volume

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/eae9ce08b2e94104afe2f41b634d82ea)

  Our new governance setting makes it easier to get ahead of data issues in your overall Mixpanel project. With data volume monitoring, you can be notified via Slack or email whenever any tracked event unexpectedly spikes or drops in volume.

  Instead of getting asked about suspicious data, you can jump in and resolve issues before anyone notices or loses trust.

  This setting is available for all organizations on an enterprise plan. For more information, check out our [docs](/docs/data-governance/data-volume-monitoring).
</Update>

<Update label="2024-01-26">
  ## Event Approval now supports new property detection

  Event Approval now supports notifications for new properties on existing events, in addition to notifications for newly tracked events. You can turn on new property detection in project settings. For more information, check out our [docs](/docs/data-governance/event-approval). Available for all enterprise plans today.
</Update>

<Update label="2024-01-17">
  ## Easier to use Event & Property Menus

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/2ebb3ec708334fd69e27130cf6bfc3db)

  The Events Menu and Properties Menu is where you find the events and properties needed to craft your metrics, charts, or graphs. Mixpanel users spend a lot of time searching within these menus to find the right building blocks, so, we’ve made some adjustments to make the experience simpler and get you to value faster.

  ## Event Menu

  An important feature we have available to organize your events is Tagging. In our old experience, it wasn’t clear as to where to find Tagged events. Now, Tags are easily discoverable on the left side of the menu. You can leverage Tagging to hone in on a set of behaviors you’re interested in analyzing (setup, mobile, payment, etc) and quickly find the events related to those behaviors.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  ## Property Menu

  Similar to tagging, we’ve categorized all of your properties on the left side of the Properties menu based on what they’re related to. For example, if you want to filter your metric by a property that’s on a user, you can simply click the User category and find all the related properties. A category you might not be familiar with is Computed - these will create a calculation of any property to frame your analysis in a unique way. The Computed Properties we have available today are:

  * Frequency per User: understand how often users did an action and correlate it to another action
  * Aggregate Property per User: understand the value of an action and correlating it to another action
  * Attributed by: understand which touchpoints in a user journey impacted conversion
  * Duration: find the time spent between two continuous events, like Page View

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2023-11-22">
  ## Find the right data more easily with Event Context

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/f7e0cbde17d04c6eac858f3d7e69aacf?sid=ef579161-ad52-46f4-96e9-a5ad2c500dcf)

  You can now see rich context about an event, such as an image of the event, frequent users, reports that query it, or an owner for follow-up questions. With these contextual details, teams can build reports more quickly by trusting that they’re using the right event.

  Types of Event Context now available:

  * Embedded image of the event
  * Teammates that recently queried the event
  * Other reports that query the event
  * Event Owner, who you can contact for follow-up questions

  In addition to having easy access to this context via the query builder, you can also leverage Event Context throughout the product. You can filter the Discover page to see existing analyses about an event.

  Event Context is available for all customers on all plans.
</Update>

<Update label="2023-11-16">
  ## Track your Web Analytics on one Board

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/a8940230695943ecb743dda421fef673)

  Our new Web Analytics Template gets you up and running with all your core website performance metrics in just a few seconds. You’ll be able to make informed decisions about what to highlight, improve, or remove from your site to build a more engaging & relevant user experience.

  Simply select your Page View event and Page Title property (note: these are automatically tracked if you implemented Mixpanel with the Javascript SDK) and you’ll get everything you need:

  * User Metrics: understand more about the users that visit your website (how many new users, how many returning users, where are they from, and more)
  * Session Metrics: track all the key session metrics (session start/end, bounce rate, average session duration, what source did they come from, and more)
  * Page Metrics: find which pages provide the most valuable and engaging content to users (page exits, average page views per user, and more)

  Checkout the Web Analytics Template for yourself on one of our demo datasets: [https://mixpanel.com/project/3018488/view/3536632/app/boards#id=6020908](https://mixpanel.com/project/3018488/view/3536632/app/boards#id=6020908)
</Update>

<Update label="2023-11-16">
  ## Measure how long users view webpages

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/19461fe6014c48c3806721e735daac30?sid=3b6a69c3-3618-4300-8ce8-25d437ba32d4)

  Tracking the number of views your website pages get is a useful way to learn if users have landed on your page. But, it doesn’t tell the complete story of whether these users got value from their visit:

  * Your blog might have 100s of views, but how do you know if users are actually reading all the content?
  * Users are reaching your signup page, but are they moving through that experience quickly or getting stuck?
  * Two different pages are getting similar views, but one is converting more sales than the other - are users finding content more engaging on that page?

  The missing piece of the puzzle is understanding how long users visit your page, and to access this data **we’ve added a *Duration* property on your *Page View* event** that tracks your users’ “time spent on a page”.

  It takes no additional setup — *Duration* is auto-computed by calculating the time between *Page View* events.

  Checkout the video above to learn how you can answer questions like:

  * What blog content are our users finding the most engaging? (find the average time spent on blog pages)
  * Which pages are users not finding any value from? (find the pages that have an average visit time of less than 10 seconds)
</Update>

<Update label="2023-11-16">
  ## Manage channel definitions with Channel Classifier

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/0e773e307f574f398e5a3609462cfa01)

  Breaking down your analysis by *Channels* is a useful way to answer key questions like:

  * which channels drive most of the traffic towards our website?
  * which channels send users that are more likely to make a purchase?

  There are many directions you can go with a simple breakdown of channels, and now, we’ve made it much faster to setup your *Channels* property.

  1. Add a new Breakdown and select “Create Custom”
  2. Select “Insert Example” in the next menu, and choose “Channel Classifier”
  3. Make any edits you need to channel definitions, change the title to “Channels”, and click save

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  This initial setup needs to happen once so that all members of your organization can access the *Channels* property.

  Our Channel Classifier definitions align with standard practices used in other tools, such as GA4. Most users will keep the out-of-the-box definitions we provide, but you can also add in new properties to a channel (ex. adding DuckDuckGo in to the “Search” channel), as well as tweak any definitions to your liking.

  [Visit our help doc](/docs/features/custom-properties#grouping-marketing-channels) for more information on how to group your marketing channels.
</Update>

<Update label="2023-11-09">
  ## Save Formulas for reuse and metric standardization

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/8579c1ac4e2a4b06a0a12e4416b07918?sid=7a3ccce7-5513-455f-8397-fb1269c807f1)

  Sometimes your analysis calls for a calculated metric, meaning a metric that’s computed from existing metrics or data. An example would be Bounce Rate (Total Sessions less than 10s / Total Session Starts), where we are trying to calculate the percent of site visitors who left without reaching any value. In analytics tools, a typical workflow is to use a “formula” to create a metric like Bounce Rate, but there are some issues with that route:

  * Every time you need to calculate Bounce Rate in a new report, you have to create a formula from scratch
  * Other people in your organization don’t know how to define Bounce Rate, so they will figure out their own definition that might not fit the context of your business
  * There’s no way for the person in your organization that manages the analytics tool to set a standardized Bounce Rate metric that everyone can trust is accurate

  To solve these pain points, Mixpanel is introducing Saved Formulas, which allows you to save a Formula for reuse across your organization.

  After creating a new metric using a Formula, you can save it. This allows you and others to reuse it once you start a new analysis - no need to rebuild it from scratch. Simply navigate to Metric, click on Formulas, and you’ll find you Saved Formula.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  You can also expand the Saved Formula to see the components that contribute to the calculation. Other tools might come with calculated metrics built in (like Bounce Rate), but you can’t see how they’re calculated or adjust the calculation to your use case.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Once you have your Saved Formulas, your organization can trust them as standardized metrics. There’s no pressure for you and your team to have to figure out how to build this metric again and again, simply add it to the visualization just like you’d do any other event, metric, or cohort.

  [Visit our help doc](/docs/reports/insights#save-formulas-for-re-use) on Saved Formulas to learn more.
</Update>

<Update label="2023-11-07">
  ## Databricks now supported with Warehouse Connectors

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/56a21b31e75342498317cbb6f31285eb?sid=5cd6c82c-87d4-48c3-9f19-1e44b8327923)

  Today, all customers can leverage Warehouse Connectors to import data via Databricks, in addition to Snowflake, BigQuery, and Redshift. You can set up recurring syncs from Databricks and ensure that Mixpanel is always in sync with your trusted data. You can import event, User, Group profile, and lookup table data.

  Navigate to Project Settings > Warehouse Sources to get started today. For more information, check out our [docs on Warehouse Connectors](/docs/tracking-methods/warehouse-connectors).
</Update>

<Update label="2023-11-07">
  ## Lookup Tables Import now supported with Warehouse Connectors

  Today, all customers can use Warehouse Connectors to import Lookup Tables from their warehouse. For a list of supported warehouses, check out this [list](/docs/tracking-methods/warehouse-connectors). This capability allows you to periodically enrich Mixpanel with data from your source-of-truth.

  For more information, check out our [docs](/docs/tracking-methods/warehouse-connectors#lookup-tables).
</Update>

<Update label="2023-11-02">
  ## Count a Unique user towards one segment

  In the past, when breaking down an event counted by *Uniques*, you often came across this question: why is the sum of users in segments not equating the the overall uniques? In the below example, unique users is 1760, but sum of users in segments Chrome + Firefox + all others = 1900. Why don’t these numbers match?

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  While there are 1,760 unique users who made a purchase, one of those unique users might make a purchase on two different browsers, and so the user gets counted in both the browsers (segments). The focus was on the segment, so you were looking at how many users were part of each segment.

  With this new feature addition, you can choose to associate a user to only one segment, either their first or last segment in the time interval. This way your sum of users across segments will total to the overall 1760. The focus with this counting type is on the user, so you are looking at how are these 1760 users distributed across the segment. This approach also reduces ambiguity and ensures that users aren't double-counted across multiple segments.

  How do you choose which approach to use?

  * If you are looking to answer questions focused on the segment - how many users watched Taylor Swift’s Movie or watched Squid Game, you want to count a user across every video they have watched. Choosing the count “per segment” option here
  * If you want to understand the "last value of" - what was the last item that my users purchased in the past seven days? You would select the "last time" option within Uniques to answer this question.
  * If you are looking to answer how your users are distributed across segments - I have 2000 users, how are they distributed across video category? Also, I’d like to consider their last watched category as their most recent preference to target them? Choose the count “last time” option here

  [Visit our help doc](/docs/features/computed-properties#attribution#what-does-attribution-on-unique-users-mean) for more information on how to leverage this new Uniques setting, and how it applies to [Attribution](/docs/features/computed-properties#attribution).
</Update>

<Update label="2023-10-20">
  ## Iterate on existing reports faster than ever with a new workflow

  <VideoButtonWithModal />ß

  [Link to Demo](https://www.loom.com/share/9d992239e7ba498a99ae3442cd639b8d?sid=abff6216-3323-4811-9d67-bb31037d87c9)

  Our new report iteration workflow makes it easier to explore existing reports and save new iterations, through simplified duplication, clearer permissions, and better auto-naming. It’s now faster to build on existing work or go down exploratory deep-dives without losing your flow.

  An example streamlined workflow:

  * On an existing Board, you see a purchase conversion funnel filtered for United States in the last 60 days, and broken down by age group.
  * You want to examine what the funnel looks like when broken down by city instead of age group.
  * After changing the breakdown, the results look significant to track, so in 1 click you can save this iteration as a new saved report.
  * On the original Board, the new report iteration is automatically added to the bottom of the Board.

  This report iteration workflow is available for all customers. If you still wish to duplicate Boards as in the previously supported workflow, you can access the Duplicate button in the 3 dot menu in the top right.
</Update>

<Update label="2023-10-04">
  ## Redshift now supported with Warehouse Connectors

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/76f4658dd850457e9634c706ee0d9430?sid=2cc72a2a-ca9b-406e-80d3-86500a29f48e)

  Today, all customers can leverage Warehouse Connectors to import data via Redshift, in addition to Snowflake and BigQuery. You can set up recurring syncs from Redshift and ensure that Mixpanel is always in sync with your trusted data. You can import event, User, and Group profile data.

  Navigate to Project Settings > Warehouse Sources to get started today. For more information, check out our [docs](/docs/tracking-methods/warehouse-connectors) on setting up Redshift.
</Update>

<Update label="2023-09-25">
  ## Plot Profile Metrics alongside other Metrics

  Profiles have always been a powerful tool to slice & dice your user-base to learn key insights about where your users are from, what browser they’re using, or any other property. The new functionality we’ve added to Profiles allows for more depth of analysis - specifically, you can compare these metrics alongside other events in the same view.

  In the past, Mixpanel was switched into a different “mode” in order to access Profile Metrics. While in this mode, you weren’t able to add other events or cohorts to your visualization, and you could not plot a Profile Metric as a trend (ex. line chart).

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Now, Profile Metrics behave like any other Event, Cohort, or Formula metric. You add them to your visualization in the same spot, and can compare them in the same chart type and date range. Profile metrics can also be used in a Formula with other events.

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2023-09-25">
  ## Workflow Improvements in Insights Report

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/f0d467f6b10247838f2edac6e8e4fca4)

  Recently, we worked on improving upon some of the core workflows you could do in our Insights report. Some of these changes added metric building functionality that open up new analysis possibilities, and some of these changes refreshed existing workflows to help Mixpanel become simpler to use - all in all, we’ve working hard to polish our existing workflows and setup Mixpanel’s design for long term success.

  **Improvements to the measurement menu**

  * The default measurement has changed from Total Events to Unique Users
  * Total Per User has been updated to Frequency Per User

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  * DAU/WAU/MAU has moved under Unique Users (click on the “>” button)

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  **Individual metrics can now be measured as Rolling or Cumulative**

  * Metrics can be measure to Rolling or Cumulative in the “Advanced” menu, which means it’s now possible to compare a rolling/cumulative metric with metrics using a different count
  * You can also set a Formula to be Rolling or Cumulative
  * This allows for comparisons that aren’t bottle necked by needing all metrics to be Rolling or Cumulative, for example, you can set a “target metric” in the same analysis as multiple cumulative metrics to visualize how long it will take for a trend to reach a goal.

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2023-09-19">
  ## Focus on the right metrics with Hide/Unhide

  It’s now possible to hide or unhide events from your visualization so you can focus on the metrics that matter.

  For example, when you have two events and one formula, your formula metric might be difficult to analyze since it’s a significantly smaller number than the other events. By hiding the other events, your visualization can scale appropriately to view the formula properly.

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2023-09-19">
  ## Formulas now behave as metrics

  Formulas have forever been an integral part of Mixpanel to create new metrics (Bounce Rate, Conversion) from existing data — and now, we’ve improved the usability of Formulas to help you encounter less roadblocks and speed up your analysis workflow.

  In the past, Formulas behaved as their own entity in the query builder, and you had to create separate Formulas (A = Product Added, B = Purchase Completed) to resurface the original events in the visualization.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Now, Formulas are added through the Metric button, and they behave like a metric. This means that the original events aren’t removed from the visualization when you add a Formula (note: you can hide the original metrics to focus on just the Formula).

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Since Formulas behave like a Metric, you can also reorder them without any adjustments and setup your ideal visualization.

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2023-09-07">
  ## Finding a template is easier than ever

  Templates are supposed to make your life easier, but we heard that figuring out how to access templates was confusing and difficult. So we’ve rolled out phase one of our plan to make finding templates easier, starting with when you click the New Board button.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Instead of a greyed out button, you’re greeted with a nice tile welcoming you to the template world. From there, you can follow the same process as before: select your template and input your events. You can start building analyses more easily with a clear entry point into templates.

  Templates are available to all users on all plans and are designed for both new and power users alike. You can read more about templates in our [docs](/docs/boards/templates).
</Update>

<Update label="2023-09-07">
  ## Automagically answer questions with Starter Board

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Now when creating a new project, you will be prompted to view your automatically generated 🌱Starter Board. You’ll be greeted by empty reports, but they won’t stay that way for long. Starter Board automatically populates when you connect data to the new project. This means that once data is flowing, you can get things going by answering key questions about your active users in seconds.

  Starter Board is available for all organizations on all plans. To see Starter Board in action, you can check out this [loom overview](https://www.loom.com/share/677846ecfe094d74bb174dcca43baa2c?sid=fefa476e-ea56-4a5e-ab04-159071d351bb).
</Update>

<Update label="2023-09-05">
  ## Warehouse Connectors now supports importing Users & Groups

  You can now use Warehouse Connectors to import User and Group tables from your warehouse. With this capability, you can extend source-of-truth data about users and groups into Mixpanel for analysis.

  This importer leverages the same modal as the event importer so that there is one cohesive experience for event, user, and group data. We support importing user and group tables where properties are stored as columns or JSON objects. For more information, check out our [docs](/docs/tracking-methods/warehouse-connectors).
</Update>

<Update label="2023-08-30">
  ## Manage implementations more easily with event metadata

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/d68d2f2f213144d8817d414eddd88f46?sid=04b74494-7aea-4eb7-aeb3-943e41ac7ec3)

  Our latest data governance improvement makes it easier to investigate and fix data discrepancies, with peace of mind that you’re not disrupting your team’s workflows.

  You can now see event usage context in Lexicon, such as:

  * Who first queried an event?
  * When was it first tracked?
  * Which people queried it most recently? When?

  With this event metadata, data teams can not only sort events to identify your highest volume / least queried events, but also identify relevant stakeholders to confirm whether this event is still necessary.

  Less fear of disrupting the team, less time spent cleaning data.
</Update>

<Update label="2023-08-29">
  ## Fluid, flexible organization with Boards on Boards

  You can now nest Boards within other Boards for more flexible, contextual organization of your analyses.

  Boards on Boards allows you to customize your workspace in whatever way that best suits how your company works. Rigid folders or spaces don’t account for the fact that people at modern organizations collaborate across teams, projects, or topics. Spend less time figuring out organizational hierarchy, and more time sharing ideas.

  Some ideas for how you can nest Boards:

  * Product Focus Area Boards on General Product Team Board
  * Feature Launch Boards on Enterprise Team Board
  * Landing Page Deep-dive Board on Growth Team Board, on Company Board

  The beauty of Boards on Boards is that you get the organizational benefit of folders with the rich functionality of Boards, such as contextual text or media cards.

  This setting available for all organizations on an enterprise plan. For more information, check out our [docs](/docs/boards/boards-on-boards).
</Update>

<Update label="2023-08-14">
  ## Find what's impacting conversion with Attribution

  Your users will experience a multitude of touchpoints along their journey to a conversion moment like signup or purchase. But, how do you know which touchpoints are valuable - should you invest more budget in certain ads, or, are there certain banners on your website that get lots of clicks? With our long awaited Attribution feature, you can answer the million dollar question to make these critical decisions — which touchpoints contributed the most to conversion?

  Our multi-touch attribution models allow you to to assign fractional credit to each touchpoint in a user journey and find the highest performers. It’s also possible to compare how these models affect your conversion moment in one table.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  You can also adjust the Lookback Window of your Attribution calculation to take into account a shorter or longer period for users to reach a touchpoint. This can be useful when analyzing your marketing campaigns that have a longer lasting impact on customer decision making.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  We hope you enjoy Attribution, and stay tuned — we’ll soon be bringing this feature to both the Funnels and Retention reports.
</Update>

<Update label="2023-08-10">
  ## Introducing Warehouse Connectors: Sync event data from Snowflake & BigQuery

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/04f4ea75310744cdab477e1b47684db3?sid=ae77291d-d61a-4f91-9be0-887206896b18)

  Today, all customers have access to Warehouse Connectors, which allows you to natively import data from Snowflake or BigQuery into Mixpanel. With this feature, you can set up recurring syncs from your data warehouse and ensure that Mixpanel is always in sync with your trusted data.

  This native connection not only simplifies event implementation by eliminating the need for engineering resources to manually track events, but it also makes analyzing all types of company data in Mixpanel easier, providing a holistic view of your customers.

  For example, you can bring into Mixpanel:

  * **Application database tables**: Signups, Reports Created, Dashboards Created
  * **Salesforce data**: Opportunity Created, Account Created, Account Upsell
  * **Support data**: Ticket Created, Ticket Resolved
  * **Billing/Consumption data:** Invoice paid, subscription renewed
  * **Ad spend data:** Click-through rate, cost per click, Google Ads spend
  * **Clickstream data from Snowplow:** Views, clicks, etc.

  This lets you answer questions like:

  * What is the % of sales opportunities do we win? What is the average deal size in North America?
  * Which campaigns account for the most revenue? What is the breakdown of the ARR of customers that use this feature?
  * What is our average time to resolve a ticket?

  Navigate to Project Settings > Warehouse Sources to get started today. For more information, check out our docs on [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors).
</Update>

<Update label="2023-08-02">
  ## Troubleshoot better with a new design for Boards without data

  We’re excited to announce that we have released a new design for Boards without data. Now when a report can’t populate, it will display one of two states: a faded out sample report or a “no data” status.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  * Charts that show "no data" occur when an event has been tracked in the last 30 days, but a selected filter or date range result in no data for the report.
  * If the report is configured with an event that hasn't been tracked in past 30 days or has never existed, the faded sample report will appear.

  For example: you are an ecommerce company with a new Start Subscription event and you'd like to make a report to track subscriptions over time.

  * If you set up a report before this event starts being tracked, the report you create will show a faded out sample report like above.
  * As data starts flowing, the report will populate as expected.
  * If you set the date range on the report to a day where no one signed up for a subscription, the report will show “no data” because there were no subscription events tracked that day.

  This change is designed to make the experiences of creating a new Board and moving a Board to a new project easier to navigate and understand. Nothing needs to be done to experience this new state - it is live for all users on all plans.
</Update>

<Update label="2023-07-27">
  ## You can now move Boards between projects with Move

  Introducing Move, a powerful new feature that allows you to move Boards from one project to another, or one organization to another. Simply hover over the menu icon in the top right corner and mouse over “Move to” to move a Board to a new project. This feature is available on all plan types at no additional charge. Permissions for this feature are managed by group admins, who have the ability to allow moving Boards between projects, or even organizations. It's important to note that if you would like a version of the Board to stay in the parent project, duplicate it and move the new duplicate Board. Moving boards from projects based in the US -> EU as well as EU -> US is unavailable at this time.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  For example:

  1. An organization has Project A and Project B that support different products and teams within the organization.
  2. Team A has some fantastic Boards that have been well received by leadership and executives.
  3. Team B would like to replicate these reports without having to build them all from scratch.

  This is where Move comes in. With the right permissions, Team A can move copies of their Boards to Team B’s project, allowing Team B to fill in their events and be up and running quickly, saving everyone time and energy.

  Coming soon: moving Boards to and from demo projects, saving you even more time.
</Update>

<Update label="2023-06-16">
  ## Discover purchase behaviors with Cart Analysis

  For ecommerce companies, understanding the purchase behavior of your users is vital when creating any revenue-driving strategy — whether that’s through website changes, marketing tactics, or product offerings. That’s why we built Cart Analysis to allow you to surface details about the items in your user’s cart (brand, category, price, etc) at different moments in their purchase journey (viewed product, added to cart, purchased). This is made possible by being able to look at any sub-property within a list of objects.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  An example question you can ask in Mixpanel with the power of Cart Analysis might be “how many cart checkouts with a total of over \$75 have a sneaker product as an item?”

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  A key feature we used to create the above visualization was the "Sum" computed property, which select a numeric property contained within the objects of the list and sums those values together (in this case, price). The other computed properties available with Cart Analysis are:

  * **Size**: Buckets carts by the number of items they contain.
  * **Distinct Count**: Count the number of carts that contain a specific brand or category.

  Getting the answer to this question can help inform a product offering strategy, like if you wanted to consider offering discounts or incentives for customers who purchase sneakers along with other products to encourage cart values over \$75.

  If you want to learn more about how Cart Analysis can upgrade your ecommerce analytics, read our help doc on the [List of Objects data type](/docs/data-structure/property-reference/data-type#list-of-objects), the [analysis unlocked with List of Objects](/docs/data-structure/property-reference/data-type#list-of-objects-property-support) , and watch the demo video below.

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/ff350b78206a4eb6948f86ed67e62ac3)
</Update>

<Update label="2023-06-07">
  ## Correlate user actions to key outcomes with Behavioral Breakdowns

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/c0cc228cb4bc4e6c8ce25084178f8d30)

  Actions speak louder than demographics, especially when it comes to finding what behaviors lead users to key outcomes.

  That’s why we built Behavioral Breakdowns — a new way to segment users by what they do, not just who they are. Now, you have the ability to measure the correlation between a user's actions and their level of engagement, monetization, or other essential metrics.

  Here are a few examples of how you can leverage Behavioral Breakdowns to inform your approach in getting users to perform a key action:

  * When trying to get users to follow more accounts, you see that users who comment on 5 pieces of content within a week have a higher rate of following others. So, you make the comment button more accessible to decrease the friction it takes to comment.
  * To get more users signed up for your credit card, you target your emails to users that spend, on average, over \$100 every time they shop on your eCommerce store because that segment is more likely to apply for a credit card.
</Update>

<Update label="2023-06-06">
  ## Learn how users engage with your marketing tactics

  <Frame>
    <img alt="webtracking" />
  </Frame>

  Your analysis is only as good as the data you capture, and we work hard to make it easy to setup the right data tracking to get you to insights quick and easy.

  That’s why we’ve updated our our [Mixpanel Javascript SDK](/docs/tracking-methods/sdks/javascript) to automatically collect:

  * UTM Tags (default: on) — automatically adds these parameters to all events:
    * utm\_source: track the source where traffic is coming from, including a website or advertiser
    * utm\_medium: track the advertising medium, including email and banner ads
    * utm\_campaign: track the campaign name associated with the traffic
    * utm\_content: track the specific link within in an ad that a user clicked
    * utm\_term: track keywords associated with campaigns
    * Initial UTM: tracks the first time a user reaches any of the above parameters Tracking UTM tags help fuel attribution analysis so you can understand which campaigns, ads, or content is contributing the most, or least, to conversion.
  * Page Views (default: off) —  auto-track page views to build metrics like:
    1. Total Views: identify top performing pages to learn what content your users like best
    2. Bounce Rate: percentage of visitors who leave your website within 10s of viewing it
    3. Conversion Rate: percentage of visitors who complete a key action after visiting a page. Tracking the performance of your pages is the main way to understand if your website is driving value to your users and business. If you want to get started with web analytics, turning on auto-tracking pages can help you get started.
</Update>

<Update label="2023-06-06">
  ## Track key ad metrics

  <Frame>
    <img alt="ad_spend" />
  </Frame>

  It’s easier than ever to start sending ad network data to Mixpanel with our [how-to guide](/docs/tracking-methods/integrations/ad-spend).

  We walk you through every step of implementation so you can start analyzing your ad data in no time and monitor key ad performance metrics like (CPC) cost-per-click, (CPM) cost-per-impression and (CTR) click-through-rate. It’s a one time setup for a lifetime of tracking ad metrics.

  It’s vital to understand whether your digital advertising is worth the money, and these metrics help inform whether your ads are driving return on investment so you can get informed on where to adjust ad spend to maximize results.

  Here are a few ways you can leverage ad performance metrics:

  * Compare campaigns and how they affect cost-per-click to borrow strategies from well performing campaigns into poor performing campaigns
  * Track the return-on-ad-spend across all ads to determine what channels need an increase in investment
  * Compare different versions of an ad and compare which one has the higher click-through-rate to learn what copy, imagery, or other aspects resonate most with your audience
</Update>

<Update label="2023-06-01">
  ## Vet new events and ensure data trust with Event Approval

  <VideoButtonWithModal />

  [Link to Demo](https://www.loom.com/share/afa48331dd3f44deb3f4e63327bf2389)

  Our new data governance setting ensures that only trustworthy data is surfaced to your team. Event Approval allows you to hide newly tracked events by default, and notify admins of these new events.

  With Event Approval, you can:

  1. Provide a “stamp of approval” by making an event visible
  2. Let an event continue to be hidden if you’re unsure if it was implemented correctly
  3. Delete events that are mistakes

  This setting available for all organizations on an enterprise plan.
</Update>

<Update label="2023-05-05">
  ## Get ahead of issues with Anomaly Detection and Root Cause Analysis

  [Anomaly Detection Demo](https://www.loom.com/share/572a0f59d22e43069ba0c3bc1b4210f4)

  <VideoButtonWithModal />

  [Root Cause Analysis Demo](https://www.loom.com/share/53fd92c89b394e0c92324a4515e88443)

  <VideoButtonWithModal />

  Introducing Anomaly Detection and Root Cause Analysis, two new features to help you save time staying on top of metrics and getting ahead of potential issues in your product, data, or company.

  In addition to [Custom Alerts](https://help.mixpanel.com/docs/features/alerts) where you can manually set a threshold for alerting, you can now use Anomaly Detection to be automatically alerted in Slack or email when your data falls outside an expected range. We use a robust open-source tool [Prophet](https://facebook.github.io/prophet/) to forecast your time series data and determine whether the data point falls outside of your selected confidence interval.

  With any fired alert, you can create a Root Cause Analysis in one click that will automatically generate a Board with 12 reports broken down by popular properties of the event. This Board helps you quickly investigate potential causes of the metric change, and each alert is tethered to one Root Cause Analysis so you aren’t duplicating work if you see that others already diagnosed the issue.

  Ways you can catch and diagnose regressions faster with Mixpanel:

  * Alerted in #marketing Slack channel of a major drop in traffic for a key content landing page. From the Root Cause Analysis, see from last touch breakdown that there’s an issue in a paid ad campaign no longer driving traffic.
  * Alerted via email of a major drop in your team’s recent feature launch engagement. From the Root Cause Analysis, see from browser breakdown that there’s a severe drop-off for Safari due to a new bug.
  * Alerted in #engineering Slack channel of a major drop in DAU. From the Root Cause Analysis, see that the drop is driven by users in APAC, coinciding with holiday of Lunar New Year.

  With Anomaly Detection and Root Cause Analysis, you can stay on top of metrics and get your team moving quickly to a solution, without all the manual labor.
</Update>

<Update label="2023-04-14">
  ## Explore analysis better with Discover

  Our new Discover feature makes it easier to explore popular analyses to springboard your own work. The Discover page automatically surfaces top analyses and creators and provides more search controls to filter reports & Boards.

  [Link to Demo](https://www.loom.com/share/5353fc9abb624e2685d787f43b003dc2)

  <VideoButtonWithModal />

  Here are a few ways to use Discover:

  * Find existing analyses: filter searches by the teammate or object type (Board, Insights, Flows, etc.). Build off someone’s previous work instead of redoing an analysis.
  * Onboard new teammates: new people can quickly get their bearings by discovering the most popular analyses, or by exploring what top builders in the organization are measuring.
  * Get inspired: browse what your teammates measure or how they organize their Boards, and be inspired to create similar high-quality analyses
</Update>

<Update label="2023-04-06">
  ## Compare metrics side-by-side in one table

  With Mixpanel’s revamped Tables report, you can compare your key metrics side-by-side to understand how your segments are performing.

  [Link to Demo](https://www.loom.com/share/f3e4791604fb48f9bfad4bee2021decf)

  <VideoButtonWithModal />

  Tables are often the best visualization to process a lot of data at once — so, we made sure to include controls that can quickly get you to the most readable layout, fast:

  * Focus on the performance of a specific metric by 1) selecting a metric to sort your segments by, and 2) specifying it as ascending or descending order.
  * Treat each data point as its own row in Ungrouped View, or preserve the hierarchy of your breakdowns in Grouped View.
  * Control how many segments are displayed, so you can focus on the most relevant data.

  This unique flexibility of our Tables allow you to spend less time setting up your visualization and get to your takeaway quicker.

  Here are a few ways you can leverage our new Tables:

  * As a product manager, you can consider offering localized content that is tailored to the needs of users in specific countries and cities that are not performing well.

  <Frame>
    ![image](https://user-images.githubusercontent.com/2077899/233897155-abf1ba47-a39e-4b1b-9997-a5623e349140.png)
  </Frame>

  * As a growth marketer, you can compare how an increase in marketing spend since last month has effected the key metrics across marketing channels.

  <Frame>
    ![image](https://user-images.githubusercontent.com/2077899/233897168-56a31677-ae64-4e91-b9d8-9e6e5bc8a355.png)
  </Frame>

  * As a product manager in e-commerce, you can determine what product you no longer want to sell by surfacing which items have the worst performing conversion.

  <Frame>
    ![image](https://user-images.githubusercontent.com/2077899/233897180-8f336ee6-a336-4827-b5e8-9040e9ef95b2.png)
  </Frame>
</Update>

<Update label="2023-03-29">
  ## Easily create and manage Custom Alerts

  We’ve revamped Custom Alerts to make it easier for you to notify your team when a metric significantly changes.

  [Link to Demo](https://www.loom.com/share/2feb00896e90458e8d085495a2e62f14)

  <VideoButtonWithModal />

  With just one click, you can set up Slack or email alerts for:

  * When an important metric reaches a target, such as if "sign-ups" in "Japan" reaches 1000
  * Monitoring unexpected behavior (or potentially faulty data), such as when any event in any segment changes by more than 25%

  As a bonus, we’ve also improved admin controls so that you can better organize your workspace through bulk deletion and clearer invalid alert symbols.
</Update>

<Update label="2023-03-28">
  ## Explore new questions with Custom Buckets

  Introducing **Custom Buckets**, a super simple way to group existing breakdowns to form meaningful segments. This added power can help you explore new, complex questions about your product usage by slicing & dicing like never before - all on the fly in an easy-to-use interface. Here are a few types of analysis you can build with Custom Buckets:

  **Age Cohorts:** Group an age breakdown to determine how a new feature has affected a key usage metric for different generations (Gen Z = ages 18-26, Millennial = ages 27-41) since last month.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  **Channel Source:** Group all social channel segments into a single value (Social Media Channels = Facebook + Instagram + Twitter) to determine if your investment in social is driving signups.

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2023-02-28">
  ## Calculate retention based on a calendar interval

  Our new Calendar Retention setting allows our users to define retention on their own terms - now, you can switch your retention calculations from a rolling time window to calendar interval in just one click. Whether you want to align your retention data to internal records or other analysis tools, you can now create a reliable retention analysis that you and your team can trust to be accurate with your business’s needs.

  You might enjoy Calendar Retention if:

  * Your app or service has one engagement a day, so you want to capture the daily sessions that fall outside of the 24-hour window but occur on the next calendar day.
  * There’s a marketing campaign running week-to-week, so you can scale weekly marketing spend based on calendar week retention increasing or decreasing.
  * You need to align your retention metric to a monthly or quarterly calendar interval when sharing out retention performance to investors.

  Please checkout our help document if you would like to learn more on how to use Calendar Retention.

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2023-01-31">
  ## Embed Mixpanel in Figma, Notion, Coda, and more

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  You can now embed Mixpanel across your favorite product tools like Figma, Notion, Coda, Jira, and more. Specifically, Mixpanel Boards and reports can be embedded in any third party tool that supports embedding, unlocking integrations with many apps at no additional cost.

  A few ideas to get started on collaborating with data:

  Add OKRs to your team hub Embed success metrics in your PRDs Check in on metrics progress for your weekly syncs

  Check out more use cases in [our blog](https://mixpanel.com/blog/introducing-embeddable-reports/).
</Update>

<Update label="2023-01-23">
  ## View Users now available in Flows & more charts

  Back in March of 2022, we upgraded Mixpanel’s user insights analysis with View Users - a simple way to discover who’s contributing to a point on a chart or metric. Since then, Mixpanelers have leveraged this feature to learn more about their users who are driving product growth or stagnation.

  With so many people enjoying the power of View Users, we’re excited to bring this functionality to additional areas of Mixpanel:

  * **Flows report**
  * **Trends Chart** in Funnels, Retention, and Retention Frequency report
  * **Frequency Chart** in Funnels report
  * **Top Paths Chart** in Funnels report
  * **Time To Convert Chart** in Funnels report
  * **Metric Chart** in Insights and Funnels report
  * **Pie Chart** in Insights report

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2023-01-18">
  ## Add your Insights Table to Boards

  If you’re a fan of visualizing data in table format, you can now save your table to a Board and preserve your analysis. To leverage this new capability, simply add a table to your Board or switch an existing Insights chart into its table format.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  ## Other Updates

  URLs are meant to be short and sweet - now, sharing your Mixpanel analysis is super easy with shortened URLs supported on all reports and Boards.
</Update>

<Update label="2022-12-13">
  ## Collaboration just got easier with Boards

  We’re excited to introduce Mixpanel Boards, a new collaborative workspace that replaces our existing dashboards. Unlike an inflexible dashboard that only shows product metrics, Boards empowers teams to share complete context, dig into the data, and make better product decisions together. **What's included in Boards:**

  * **Text cards:** Add text to share the reasoning behind tracking any metric (with support for rich text formatting!)
  * **Media cards:** Give more color with a screenshot or feature walkthrough with YouTube, Vimeo, or Loom, or just spice things up with great memes
  * **Adjustable card height and width:** Insert, drag, and resize cards to make your analyses more organized and readable
  * **Viewer transparency:** Hover over the top right corner to quickly see who has recently viewed your Board, so you can know your impact

  Check out more use cases for collaboration in our [blog](https://mixpanel.com/blog/boards-collaborate-cards-mixpanel-feature-update/).
</Update>

<Update label="2022-12-01">
  ## Mixed Improvements in Mixpanel

  [Perfecting Mixpanel’s workflows are a top priority for us](https://mixpanel.com/blog/mixpanel-product-polish-updates-user-friction/), and that’s why our customers appreciate our best-in-class design when answering their everyday product questions. We take pride in focusing on the small, but vital incremental improvements that help Mixpanel become faster, more intuitive, and an overall joyous experience for our users.

  This month, we’re introducing our **Mixed Improvements**: updates that enhance Mixpanel’s workflows and upgrade your product analytics experience.

  **Query builder refinements**

  * Report tabs have been adjusted and color-coded to help you easily recognize where you are during an analysis.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  * The query builder is much easier to scan, all thanks to the new way of adding event and cohort blocks via the header of each section.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  * Query blocks feel super reactive with their new design that reflects all the possible states they can be in.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  * Headers, like **Event & Cohorts**, stick to the top so you don’t have to scroll back up to add other query blocks.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  * We’ve added arrow controls for a quicker way to input your number of steps in Flows report.
  * Dragging and dropping query blocks that are partially populated (uncompleted) is now possible across the query builder.

  ## Other updates

  * Flows report has been made even more intuitive - hover over a path to find the percent of users who performed that next step, and left-click on an event to pull up the action menu.

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  * Dashboards feel quicker than ever now that loading times for report editing in a Dashboard have decreased considerably.
  * Build and rebuild your Dashboards faster than ever with supported Undo (⌘+Z) & Redo (Shift+⌘+Z).
  * Render optimizations to data tables have helped them feel snappier and scroll much smoother.
  * All dates in Mixpanel have been streamlined to one format, for example, *Thu Jul 14, 2022 7:00 AM*.
</Update>

<Update label="2022-11-07">
  ## Accurate Event Ordering with Millisecond Precision

  Say hello to accurate event ordering with Millisecond Precision. Now, even if you have multiple events happening within the same second, Mixpanel has the power to decipher the exact sequence in which those events occurred.

  Check out any Flows report to view millisecond level of precision firsthand!

  **Before you can view events at Millisecond Precision, please make a note of two key points:**

  1. You need to update your SDK to ingest events with millisecond timestamps. All previous versions only track at second precision. The *minimum versions* that support *ms* time stamps are as follows:

  * Swift - 3.3.0
  * Obj-C - 4.2.0
  * Android - 6.3.0
  * Flutter - 1.6.0
  * React Native - 1.5.0
  * Unity - 3.3.0
  * Javascript - historical versions have already been tracking ms timestamp. No action is to be taken if using this SDK.

  > Note: If you are sending data into Mixpanel via a CDP or the DWH, no change is required at your end if you’re already tracking data at ms precision.

  2. Only forward-looking data will be tracked at ms precision. This means that once you update your SDK, it will take some time to accumulate data with ms precision before you can see it reflected in your analysis.
</Update>

<Update label="2022-11-03">
  ## Sessions improvements and new functionality

  We’ve added two updates to session tracking in Mixpanel for more flexibility when defining your sessions and a simpler process to slice and dice this data. With Property Based Sessions and Sessions Properties, you can take advantage of a whole new way to analyze how users engage with your product:

  * **Property-Based Sessions:** have your own parameters that define a session? No worries - simply attach a Session ID property to your events, and Mixpanel will register all instances when a session starts and ends. Even if your sessions are complex — start from multiple events, have a max duration of 6 hours, and end after 30 minutes of inactivity — Property-Based Sessions can manage these parameters.
  * **Session Properties:** borrow any property from the events that define a Session Start or Session End to break down your user engagement data like never before.

  For example, you can now set the property “City” to your session events to compare how users across different cities start and end sessions as well as the duration of these sessions.
</Update>

<Update label="2022-07-08">
  ## Reorient your view of charts and tables

  Mixpanel’s charts and tables both provide a unique way to view data and capture insights. But, sometimes you’re only in need of the table. Or, you need both the chart and table for a holistic analysis. That’s why we’ve introduced **Layout Controls** and **Visual Grouped** Sort to give you control over the orientation of your report.

  ## Layout Controls

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  We’ve added three buttons to give you control over the viewable area of your charts and tables:

  1. Chart Focus: expand your chart so it is the only focus
  2. Split View: split screen between both your chart and table
  3. Table Focus: hide the chart completely to view the full, un-collapsed table

  Now, you don’t have to scroll around trying to find the most relevant data view. Simply click your desired orientation and voila - the perfect view is automatically adjusted. Otherwise, you can drag the dividing handle to your preferred destination.

  ## Visual Grouped Sort

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  Across all reports, data tables now include hierarchal structures that reduce repetitive information. This update makes it easier to group together the same metric so you can compare the results side-by-side. Checkout the before and after:

  ### Before

  <Frame>
    <img alt="changelog Image" />
  </Frame>

  ### After

  <Frame>
    <img alt="changelog Image" />
  </Frame>
</Update>

<Update label="2022-07-01">
  ## Uncover user insights with View Users

  Making sense of your data just got a whole lot easier. In just two clicks, you can now View Users contributing to any event, at any point in time, across Insights, Funnels, and Retention reports. Save this list as a cohort. Export it as a CSV. And just like that, you have the data to find groups of users experiencing friction or dig deeper into what specific users are driving feature adoption. You can expect View Users to help:

  **Learn what type of users are driving growth or stagnation:** Each user’s properties and recent activities are readily accessible in View Users. This makes uncovering user themes fast - plus, you don’t have to leave the context of your Mixpanel report for this deep level of exploration.

  **Take action on a group of users:** View Users also helps with turning discoveries into actionable next steps. For example, you can leverage the Export to CSV button to grab the emails of a specific user group and plug them into an email campaign. Then, save that same group as a cohort in order to track their product usage after you send an email.
</Update>

<Update label="2022-06-16">
  ## Faster Workflows for Speedy Report Building

  Undo mistakes, shift query blocks and switch reports with lightning speed. Now, Mixpanel workflows are even faster with tools to quickly build, rebuild, and explore your reports.

  **Undo / Redo** We’ve added shortcuts to make iterating between changes in your analysis blazingly fast. Cmd + Z to undo; Cmd + Shift + Z to redo. Change filters, date ranges, line vs bar chart, and go back in one second to compare before and after, or fix the view. Speed is the only constant.

  **Drag & Drop Query Blocks**

  Save valuable time by dragging and dropping an existing query block into a different section. Want to change your breakdown by cities into a filter by those same cities? Click and drag your query block from the breakdown section, place it into the filter section, and voila - no need to recreate your queries, simply drag and drop existing ones.

  **Fluid Report Transitions**

  Realized you can find the answer to your question in a different report? No worries - Fluid Report Transitions preserves the parameters of your original question for quick, stress-free report switching. Start in Insights and switch into Funnels, then into Flows, and back to Insights all while keeping the events, filters, breakdowns and date ranges you set originally - zero rebuilding required.
</Update>

<Update label="2022-05-31">
  ## Improved conversion analysis in Flows

  We’ve boosted Flows so you can better see which actions affect conversion. You can seamlessly switch from Funnels to Flows now, carrying over criteria like excluded steps, and you can break down paths by conversion & drop-off — all in a single, smooth visualization.

  [Read more here.](https://help.mixpanel.com/hc/en-us/articles/360057520772-Conversion-and-Drop-off-Flows)
</Update>

<Update label="2022-05-24">
  ## Clarify context with more Lexicon support

  You can now use Lexicon descriptions for group profile properties, helping you add more context to your metrics. No more guesswork about what a property means.

  [Read more here](https://help.mixpanel.com/hc/en-us/articles/360001307806-Lexicon-Overview#adding-or-changing-descriptions).
</Update>

<Update label="2022-04-18">
  ## Measure performance better with relative comparisons

  With our improved relative comparisons, you can now calculate & visualize metrics for specific segments relative to others. We’ve also enhanced time comparisons, adding visualizations like comparing percent change over baseline or plotting metrics like YoY.

  [Read more here.](https://help.mixpanel.com/hc/en-us/articles/4485419360916)
</Update>

<Update label="2022-03-29">
  ## Tell a richer story with text on dashboards

  You can now add text to dashboards, making it easier to share the context behind your analysis or tell a compelling story around your data. Sometimes, a word is worth a thousand pictures.
</Update>


# Access Security
Source: https://docs.mixpanel.com/docs/access-security



Mixpanel is committed to keeping your data and access secure.

<CardGroup>
  <Card title="Login Methods" href="/docs/access-security/login-methods" />

  <Card title="Two-Factor Authentication" href="/docs/access-security/two-factor-authentication" />

  <Card title="Single Sign-On" href="/docs/access-security/single-sign-on" />
</CardGroup>


# Audit Log
Source: https://docs.mixpanel.com/docs/access-security/audit-log



Mixpanel's audit log tracks activity within your organization and projects, providing visibility into who made changes, when they occurred, and what was modified. The audit log helps teams maintain security, troubleshoot issues, and meet compliance requirements.

<Note>
  The audit log is available on all plans. Free and Growth plans retain logs for 90 days. Enterprise plans retain logs for 2 years. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Accessing the Audit Log

You can access the audit log at two levels:

* **Organization-level logs** — Found in Organization Settings. Accessible to organization admins and owners, these log all events across the organization, including user authentication, service account management, and more.
* **Project-level logs** — Found in Project Settings. Accessible to project admins and owners, these logs include project-specific events like report creation and data exports.

Some events appear only at the organization level. Most appear in both organization and project logs.

1. **Navigate to Organization Settings or Project Settings** by clicking the gear icon in the bottom left navigation > Settings.
2. **Select Audit Log** from the sidebar menu.
3. **View the activity log** showing recent events, who performed them, and when they occurred.

<Frame>
  <img alt="image" />
</Frame>

## Tracked Events

See [Audit Log Reference](/docs/access-security/audit-log-reference) for a complete list of all tracked events, including descriptions and availability dates.

## Exporting the Audit Log

You can export the audit log to CSV or NDJSON (newline-delimited JSON) for further analysis or archival. The export contains the raw data for each event. CSV is convenient for spreadsheets and quick analysis. NDJSON preserves the full nested structure of each event, which suits programmatic processing or ingestion into log pipelines.

1. **Navigate to the audit log** page in Organization Settings or Project Settings.
2. **Click the Export button** and choose your format—**CSV** or **NDJSON**—from the dropdown to download the current view of the audit log.
3. The export includes all visible events within the selected time range.

## Limitations

* **Retention periods** vary by plan:

  * Free & Growth plans: 90 days
  * Enterprise plans: 2 years
* **Organization-only events** (service account management, login/logout, two-factor auth) are only visible in Organization Settings, not Project Settings.

## FAQ

#### Who can access the audit log?

Only users with Admin or Owner roles in an organization or project can view the audit log for that organization or project. You can configure custom roles to include audit log access as well.

#### Can I filter the audit log by event type or user?

Yes, the audit log interface provides filtering options to help you find specific events or actions by particular users.

#### What's the difference between the organization and project audit logs?

Most events appear in both places. The organization audit log contains additional organization-wide events like user authentication and service account creation. The project audit log is limited to project-specific events. The scope field on the audit log reference page indicates which audit log will contain the event. If there is no scope column in a table, the event appears in both the organization and project audit logs.


# Audit Log Reference
Source: https://docs.mixpanel.com/docs/access-security/audit-log-reference



Mixpanel's Audit Log tracks activity within your organization and projects, providing visibility into who made changes, when they occurred, and what was modified. This page is the authoritative catalog of every event type the Audit Log records.

For an overview of the Audit Log — how to access it in the UI, retention by plan, the CSV export workflow, and FAQ — see the [Audit Log overview](/docs/access-security/audit-log).

The events Mixpanel records are listed below. The **Available Since** date on each event is the first calendar day on which the event is available.

## Events

### Agentic Workflows

| Event Type             | Display Name               | Description                                                                                   | Scope                    | Available Since |
| ---------------------- | -------------------------- | --------------------------------------------------------------------------------------------- | ------------------------ | --------------- |
| `agent_flow.activated` | Agent Automation Activated | An agentic automation was activated.                                                          | Project and organization | June 9, 2026    |
| `agent_flow.created`   | Agent Automation Created   | A new agentic automation was created.                                                         | Project and organization | June 9, 2026    |
| `agent_flow.deleted`   | Agent Automation Deleted   | An agentic automation was deleted.                                                            | Project and organization | June 9, 2026    |
| `agent_flow.paused`    | Agent Automation Paused    | An active agentic automation was paused.                                                      | Project and organization | June 9, 2026    |
| `agent_flow.triggered` | Agent Automation Triggered | An agentic automation run was triggered, either manually or based on the configured schedule. | Project and organization | June 9, 2026    |
| `agent_flow.updated`   | Agent Automation Updated   | An existing agentic automation was updated.                                                   | Project and organization | June 9, 2026    |

### Alerts

| Event Type        | Display Name    | Description                                | Scope                    | Available Since  |
| ----------------- | --------------- | ------------------------------------------ | ------------------------ | ---------------- |
| `alert.created`   | Alert Created   | A new alert was created on a report.       | Project and organization | February 1, 2026 |
| `alert.deleted`   | Alert Deleted   | An alert was removed.                      | Project and organization | February 1, 2026 |
| `alert.updated`   | Alert Modified  | An existing alert's settings were changed. | Project and organization | February 1, 2026 |
| `alert.triggered` | Alert Triggered | An alert condition was met and triggered.  | Project and organization | February 7, 2026 |

### Billing Info

| Event Type                                 | Display Name                        | Description                               | Scope             | Available Since |
| ------------------------------------------ | ----------------------------------- | ----------------------------------------- | ----------------- | --------------- |
| `billing_info.receipt_preferences_updated` | Billing Invoice Preferences Updated | Billing invoice preferences were updated. | Organization only | May 20, 2026    |
| `billing_info.payment_info_updated`        | Billing Payment Information Updated | Billing payment information was modified. | Organization only | May 20, 2026    |
| `billing_info.tax_info_updated`            | Billing Tax Information Updated     | Billing tax information was modified.     | Organization only | May 20, 2026    |

### Boards

| Event Type                    | Display Name                | Description                                       | Scope                    | Available Since |
| ----------------------------- | --------------------------- | ------------------------------------------------- | ------------------------ | --------------- |
| `board.created`               | Board Created               | A new board was created.                          | Project and organization | April 5, 2026   |
| `board.deleted`               | Board Deleted               | A board was permanently removed.                  | Project and organization | April 5, 2026   |
| `board.duplicated`            | Board Duplicated            | A copy of an existing board was created.          | Project and organization | April 5, 2026   |
| `board.exported`              | Board Exported              | Board data was exported.                          | Project and organization | April 5, 2026   |
| `board.shared`                | Board Shared                | A board was shared with users or teams.           | Project and organization | April 5, 2026   |
| `board_subscription.created`  | Board Subscription Created  | A scheduled board email subscription was set up.  | Project and organization | April 5, 2026   |
| `board_subscription.deleted`  | Board Subscription Deleted  | A board subscription was removed.                 | Project and organization | April 5, 2026   |
| `board.unshared`              | Board Unshared              | Sharing access to a board was revoked.            | Project and organization | April 5, 2026   |
| `board.updated`               | Board Updated               | Board settings or content were modified.          | Project and organization | April 5, 2026   |
| `board.public_access_updated` | Public Board Access Updated | Public sharing settings for a board were changed. | Project and organization | April 5, 2026   |

### Cohorts

| Event Type            | Display Name        | Description                                   | Scope                    | Available Since |
| --------------------- | ------------------- | --------------------------------------------- | ------------------------ | --------------- |
| `cohort.created`      | Cohort Created      | A new cohort was created.                     | Project and organization | April 5, 2026   |
| `cohort.deleted`      | Cohort Deleted      | A cohort was removed.                         | Project and organization | April 5, 2026   |
| `cohort.shared`       | Cohort Shared       | A cohort was shared with users or teams.      | Project and organization | April 5, 2026   |
| `cohort_sync.created` | Cohort Sync Created | A new cohort sync integration was configured. | Project and organization | May 20, 2026    |
| `cohort_sync.updated` | Cohort Sync Updated | Cohort sync settings were modified.           | Project and organization | May 20, 2026    |
| `cohort.unshared`     | Cohort Unshared     | Sharing access to a cohort was revoked.       | Project and organization | April 5, 2026   |
| `cohort.updated`      | Cohort Updated      | Cohort criteria or settings were modified.    | Project and organization | April 5, 2026   |

### Custom Roles

| Event Type            | Display Name        | Description                                            | Scope                    | Available Since |
| --------------------- | ------------------- | ------------------------------------------------------ | ------------------------ | --------------- |
| `custom_role.created` | Custom Role Created | A new custom role was created.                         | Project and organization | April 5, 2026   |
| `custom_role.deleted` | Custom Role Deleted | A custom role was deleted.                             | Project and organization | April 5, 2026   |
| `custom_role.updated` | Custom Role Updated | A custom role's permissions or settings were modified. | Project and organization | April 5, 2026   |

### Data Exports

| Event Type                    | Display Name                | Description                               | Scope                    | Available Since |
| ----------------------------- | --------------------------- | ----------------------------------------- | ------------------------ | --------------- |
| `audit_log_export.created`    | Audit Log Export Created    | An audit log export was initiated.        | Project and organization | April 5, 2026   |
| `audit_log_export.downloaded` | Audit Log Export Downloaded | An audit log export file was downloaded.  | Project and organization | April 5, 2026   |
| `event_export.downloaded`     | Events Exported             | Event data was exported from the project. | Project and organization | April 5, 2026   |
| `profile_export.downloaded`   | Profile Data Exported       | User profile data was exported.           | Project and organization | April 5, 2026   |
| `raw_event_export.requested`  | Raw Event Export Requested  | A raw event export was requested.         | Project and organization | May 20, 2026    |
| `user_data_export.created`    | User Data Export Requested  | A user data export request was submitted. | Project and organization | April 5, 2026   |

### Data Management

| Event Type                    | Display Name                 | Description                                                                                                                                                                            | Scope                    | Available Since |
| ----------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | --------------- |
| `event_definition.created`    | Event Definition Created     | A new event definition was created.                                                                                                                                                    | Project and organization | May 20, 2026    |
| `event_definition.deleted`    | Event Definition Deleted     | An event definition was deleted.                                                                                                                                                       | Project and organization | May 20, 2026    |
| `event_definition.updated`    | Event Definition Updated     | An event definition was modified.                                                                                                                                                      | Project and organization | May 20, 2026    |
| `event_deletion.canceled`     | Event Deletion Canceled      | A pending event deletion request was canceled.                                                                                                                                         | Project and organization | April 5, 2026   |
| `event_deletion.created`      | Event Deletion Requested     | A request to delete events was submitted.                                                                                                                                              | Project and organization | April 5, 2026   |
| `profile.deleted`             | Profile Deleted              | A user profile was removed. Only tracked when initiated through the Mixpanel web application. API calls and direct updates using the Mixpanel SDK are not currently logged.            | Project and organization | May 20, 2026    |
| `profile.updated`             | Profile Updated              | A user profile was updated. Only tracked when initiated through the Mixpanel web application. API calls and direct updates using the Mixpanel SDK are not currently logged.            | Project and organization | May 20, 2026    |
| `profile.batch_deleted`       | Profiles Batch Deleted       | A batch of user profiles were removed. Only tracked when initiated through the Mixpanel web application. API calls and direct updates using the Mixpanel SDK are not currently logged. | Project and organization | May 20, 2026    |
| `profile.batch_updated`       | Profiles Batch Updated       | A batch of user profiles were updated. Only tracked when initiated through the Mixpanel web application. API calls and direct updates using the Mixpanel SDK are not currently logged. | Project and organization | May 20, 2026    |
| `property_definition.created` | Property Definition Created  | A new property definition was created.                                                                                                                                                 | Project and organization | May 20, 2026    |
| `property_definition.deleted` | Property Definition Deleted  | A property definition was deleted.                                                                                                                                                     | Project and organization | July 2, 2026    |
| `property_definition.updated` | Property Definition Updated  | A property definition was modified.                                                                                                                                                    | Project and organization | May 20, 2026    |
| `user_data_deletion.canceled` | User Data Deletion Canceled  | A pending user data deletion request was canceled.                                                                                                                                     | Project and organization | April 5, 2026   |
| `user_data_deletion.created`  | User Data Deletion Requested | A request to delete user profile data was submitted.                                                                                                                                   | Project and organization | April 5, 2026   |

### Data Pipelines

| Event Type              | Display Name          | Description                                 | Scope                    | Available Since |
| ----------------------- | --------------------- | ------------------------------------------- | ------------------------ | --------------- |
| `data_pipeline.created` | Data Pipeline Created | A new data pipeline integration was set up. | Project and organization | April 5, 2026   |
| `data_pipeline.deleted` | Data Pipeline Deleted | A data pipeline was removed.                | Project and organization | April 5, 2026   |
| `data_pipeline.updated` | Data Pipeline Updated | Data pipeline configuration was modified.   | Project and organization | April 5, 2026   |

### Data Views

| Event Type               | Display Name                | Description                               | Scope                    | Available Since |
| ------------------------ | --------------------------- | ----------------------------------------- | ------------------------ | --------------- |
| `workspace.team_added`   | Team Added to Data View     | A team was granted access to a data view. | Project and organization | May 20, 2026    |
| `workspace.team_removed` | Team Removed from Data View | A team's data view access was revoked.    | Project and organization | May 20, 2026    |
| `workspace.user_added`   | User Added to Data View     | A user was granted access to a data view. | Project and organization | May 20, 2026    |
| `workspace.user_removed` | User Removed from Data View | A user's data view access was revoked.    | Project and organization | May 20, 2026    |

### Experiments

| Event Type              | Display Name                 | Description                           | Scope                    | Available Since |
| ----------------------- | ---------------------------- | ------------------------------------- | ------------------------ | --------------- |
| `experiment.archived`   | Experiment Archived          | An experiment was archived.           | Project and organization | May 20, 2026    |
| `experiment.concluded`  | Experiment Concluded         | An experiment was concluded.          | Project and organization | May 20, 2026    |
| `experiment.created`    | Experiment Created           | A new experiment was created.         | Project and organization | May 20, 2026    |
| `experiment.decided`    | Experiment Decision Recorded | A decision was made on an experiment. | Project and organization | May 20, 2026    |
| `experiment.deleted`    | Experiment Deleted           | An experiment was deleted.            | Project and organization | May 20, 2026    |
| `experiment.duplicated` | Experiment Duplicated        | An experiment was duplicated.         | Project and organization | May 20, 2026    |
| `experiment.launched`   | Experiment Launched          | An experiment was launched.           | Project and organization | May 20, 2026    |
| `experiment.restored`   | Experiment Restored          | An archived experiment was restored.  | Project and organization | May 20, 2026    |
| `experiment.updated`    | Experiment Updated           | Experiment settings were modified.    | Project and organization | May 20, 2026    |

### Feature Flags

| Event Type                | Display Name            | Description                            | Scope                    | Available Since |
| ------------------------- | ----------------------- | -------------------------------------- | ------------------------ | --------------- |
| `feature_flag.archived`   | Feature Flag Archived   | A feature flag was archived.           | Project and organization | May 20, 2026    |
| `feature_flag.created`    | Feature Flag Created    | A new feature flag was created.        | Project and organization | May 20, 2026    |
| `feature_flag.deleted`    | Feature Flag Deleted    | A feature flag was deleted.            | Project and organization | May 20, 2026    |
| `feature_flag.duplicated` | Feature Flag Duplicated | A feature flag was duplicated.         | Project and organization | May 20, 2026    |
| `feature_flag.restored`   | Feature Flag Restored   | An archived feature flag was restored. | Project and organization | May 20, 2026    |
| `feature_flag.updated`    | Feature Flag Updated    | Feature flag settings were modified.   | Project and organization | May 20, 2026    |

### Organization Settings

| Event Type                                        | Display Name                          | Description                                               | Scope             | Available Since |
| ------------------------------------------------- | ------------------------------------- | --------------------------------------------------------- | ----------------- | --------------- |
| `organization_spark_setting.updated`              | Organization AI Settings Changed      | Organization AI settings were updated.                    | Organization only | May 20, 2026    |
| `organization_setting.updated`                    | Organization Settings Changed         | Organization settings were modified.                      | Organization only | May 20, 2026    |
| `organization_access_security.twofactor_disabled` | Organization Two-Factor Auth Disabled | Organization-wide two-factor authentication was disabled. | Organization only | May 20, 2026    |
| `organization_access_security.twofactor_enabled`  | Organization Two-Factor Auth Enabled  | Organization-wide two-factor authentication was enabled.  | Organization only | May 20, 2026    |

### Project Settings

| Event Type            | Display Name        | Description                                                     | Scope                    | Available Since |
| --------------------- | ------------------- | --------------------------------------------------------------- | ------------------------ | --------------- |
| `project.transferred` | Project Transferred | A project was transferred to a different organization or owner. | Project and organization | May 20, 2026    |

### Reports

| Event Type                       | Display Name                 | Description                                       | Scope                    | Available Since |
| -------------------------------- | ---------------------------- | ------------------------------------------------- | ------------------------ | --------------- |
| `bookmark.deleted`               | Report Deleted               | A saved report was removed.                       | Project and organization | April 5, 2026   |
| `bookmark.moved`                 | Report Moved                 | A saved report was moved to a different location. | Project and organization | May 20, 2026    |
| `bookmark.created`               | Report Saved                 | A new report was saved to a dashboard.            | Project and organization | April 5, 2026   |
| `bookmark.screenshot_downloaded` | Report Screenshot Downloaded | A screenshot of a report was downloaded.          | Project and organization | May 20, 2026    |
| `bookmark.updated`               | Report Updated               | A saved report's configuration was changed.       | Project and organization | April 5, 2026   |

### Service Accounts

| Event Type                             | Display Name                         | Description                                            | Scope                    | Available Since |
| -------------------------------------- | ------------------------------------ | ------------------------------------------------------ | ------------------------ | --------------- |
| `service_account.added_to_project`     | Service Account Added to Project     | A service account was granted access to a project.     | Project and organization | April 5, 2026   |
| `service_account.created`              | Service Account Created              | A new service account was created.                     | Organization only        | April 5, 2026   |
| `service_account.deleted`              | Service Account Deleted              | A service account was removed.                         | Organization only        | April 5, 2026   |
| `service_account.removed_from_project` | Service Account Removed from Project | A service account's project access was revoked.        | Project and organization | April 5, 2026   |
| `service_account.role_changed`         | Service Account Role Changed         | A service account's role or permissions were modified. | Project and organization | April 5, 2026   |

### Teams

| Event Type                     | Display Name                      | Description                                | Scope             | Available Since |
| ------------------------------ | --------------------------------- | ------------------------------------------ | ----------------- | --------------- |
| `team.service_account_added`   | Service Account Added to Team     | A service account was added to a team.     | Organization only | May 20, 2026    |
| `team.service_account_removed` | Service Account Removed from Team | A service account was removed from a team. | Organization only | May 20, 2026    |
| `team.created`                 | Team Created                      | A new team was created.                    | Organization only | May 20, 2026    |
| `team.deleted`                 | Team Deleted                      | A team was deleted.                        | Organization only | May 20, 2026    |
| `team.updated`                 | Team Updated                      | Team settings were modified.               | Organization only | May 20, 2026    |
| `team.user_added`              | User Added to Team                | A user was added to a team.                | Organization only | May 20, 2026    |
| `team.user_removed`            | User Removed from Team            | A user was removed from a team.            | Organization only | May 20, 2026    |

### User Authentication

| Event Type                | Display Name                  | Description                                       | Scope             | Available Since |
| ------------------------- | ----------------------------- | ------------------------------------------------- | ----------------- | --------------- |
| `user.twofactor_disabled` | User Disabled Two-Factor Auth | A user deactivated two-factor authentication.     | Organization only | August 16, 2026 |
| `user.twofactor_enabled`  | User Enabled Two-Factor Auth  | A user activated two-factor authentication.       | Organization only | April 5, 2026   |
| `session.logged_in`       | User Logged In                | A user successfully logged into the organization. | Organization only | April 5, 2026   |
| `session.logged_out`      | User Logged Out               | A user logged out of the organization.            | Organization only | April 5, 2026   |
| `session.login_failed`    | User Login Failed             | A user login attempt failed.                      | Organization only | May 20, 2026    |

### User Management

| Event Type                       | Display Name                   | Description                                            | Scope                    | Available Since |
| -------------------------------- | ------------------------------ | ------------------------------------------------------ | ------------------------ | --------------- |
| `invitation.accepted`            | Accepted Invitation            | A user accepted an invitation to the organization.     | Organization only        | May 20, 2026    |
| `project.default_access_granted` | Default Project Access Granted | Default access for all users to a project was granted. | Project and organization | May 20, 2026    |
| `project.default_access_revoked` | Default Project Access Revoked | Default access for all users to a project was revoked. | Project and organization | May 20, 2026    |
| `invitation.sent`                | Invited User to Organization   | An invitation was sent to a new user.                  | Organization only        | May 20, 2026    |
| `project.team_added`             | Team Added to Project          | A team was granted access to a project.                | Project and organization | May 20, 2026    |
| `project.team_removed`           | Team Removed from Project      | A team's project access was revoked.                   | Project and organization | May 20, 2026    |
| `organization.user_added`        | User Added to Organization     | A user was added to the organization.                  | Organization only        | May 20, 2026    |
| `project.user_added`             | User Added to Project          | A user was granted access to a project.                | Project and organization | May 20, 2026    |
| `organization.user_removed`      | User Removed from Organization | A user was removed from the organization.              | Organization only        | May 20, 2026    |
| `project.user_removed`           | User Removed from Project      | A user's project access was revoked.                   | Project and organization | May 20, 2026    |
| `user.role_changed`              | User Role Changed              | A user's role or permissions were modified.            | Project and organization | May 20, 2026    |

### Warehouse Sources

| Event Type                      | Display Name                  | Description                                       | Scope                    | Available Since |
| ------------------------------- | ----------------------------- | ------------------------------------------------- | ------------------------ | --------------- |
| `warehouse_source.created`      | Warehouse Source Created      | A new warehouse data source was connected.        | Project and organization | April 5, 2026   |
| `warehouse_source.deleted`      | Warehouse Source Deleted      | A warehouse source connection was removed.        | Project and organization | April 5, 2026   |
| `warehouse_source_sync.created` | Warehouse Source Sync Created | A warehouse source sync job was created.          | Project and organization | May 20, 2026    |
| `warehouse_source_sync.deleted` | Warehouse Source Sync Deleted | A warehouse source sync job was deleted.          | Project and organization | May 20, 2026    |
| `warehouse_source_sync.updated` | Warehouse Source Sync Updated | Warehouse source sync configuration was modified. | Project and organization | May 20, 2026    |
| `warehouse_source.updated`      | Warehouse Source Updated      | Warehouse source configuration was changed.       | Project and organization | April 5, 2026   |


# Login Methods
Source: https://docs.mixpanel.com/docs/access-security/login-methods



## Overview

Users must authenticate themselves through a login process to access Mixpanel. Mixpanel supports multiple login methods.

## Magic Link Login

<Callout icon="lightbulb">
  If you do not see the magic link email in your inbox/junk/spam mailbox, you may need to create an account or your account may be associated with a different email address.
</Callout>

By default, Mixpanel users authenticate in a password-less manner using Magic Link. After entering your email and clicking continue in the log in screen, we send an email to your inbox that contains a Magic Link, which will log you in directly.

<Frame>
  <img alt="image" />
</Frame>

## Password Login

<Warning>
  Once you set a password, the magic link login option will be permanently disabled for your account.
</Warning>

You can set a password for your user account if you prefer to log in by providing an email and password instead of the Magic Link.

To set a password for your account:

1. Click the settings button (gear icon) in the bottom left corner of the UI
2. Select “Personal Settings”
3. Navigate to “Your Profile”
4. Click the pencil icon to set your password.

<Frame>
  <img alt="image" />
</Frame>

## Passkey Login

Passkeys offer a modern, phishing-resistant way to sign in to Mixpanel without a password. Instead of typing a password or a one-time code, you authenticate with something you already use to unlock your device - Touch ID, Face ID, Windows Hello, or a hardware security key.

Passkeys are built on the WebAuthn/FIDO2 standard. The credential never leaves your device, and it is cryptographically bound to Mixpanel's domain, so it cannot be phished, reused on a fake login page, or replayed by an attacker.

To set a passkey for your account:

1. Click the settings button (gear icon) in the bottom left corner of the UI
2. Select “Personal Settings”
3. Navigate to “Your Profile”
4. Under the Passkeys section, click the "Register passkey" button
5. Follow your device’s prompt to confirm with your fingerprint, face, PIN, or security key

<Frame>
  <img alt="image" />
</Frame>

Once created, the passkey is immediately available for login. You can optionally enable skip password so Mixpanel uses your passkey as the primary login method, giving you a fully passwordless sign-in experience (this does not bypass org-mandated SSO requirements.)

### Logging in with a passkey

1. On the [login page](https://mixpanel.com/login), click "Login with passkey", or enter your email and continue
2. When prompted, choose to sign in with your passkey
3. Confirm with your device (fingerprint, face, PIN, or security key). You're in!

<Frame>
  <img alt="image" />
</Frame>

### Recovery codes

When you enable passkeys, Mixpanel generates a set of single-use recovery codes. These let you sign in if you ever lose access to the device that holds your passkey.

<Warning>
  Recovery codes are shown only once. Save them somewhere safe (a password manager is ideal) - Mixpanel cannot show them to you again after this point.
</Warning>

Each recovery code can be used only once. You can regenerate your recovery codes at any time from the Passkeys section of your personal settings; regenerating invalidates the previous set. To sign in with a recovery code, choose the "Use recovery code" option on the login screen and enter one of your saved codes.

## Organization-wide Access Settings

Additional access security requirements may be configured across an Organization that impacts how a user logs in to Mixpanel. Organization Owners and Admins can require users who are inside of their organization to use 2FA, and force any users with an email from a claimed domain to use SSO for login.

**Two-Factor Authentication**: Whenever users sign in with a username and password, they also need to enter a security code generated on their mobile device. Users do not need a security code when signing in through the organization's identity provider (SSO).

**Single Sign-On**: Enable users of your organization to log in with single sign-on. Can also require users to login using SSO and assign roles/permissions via IdP.

Read more about Two-Factor Authentication [here](/docs/access-security/two-factor-authentication) and Single Sign-On [here](/docs/access-security/single-sign-on).

## FAQ

**1. Why am I not receiving the magic login link after I click in?**

Check the junk/spam inbox for the email or click the resend the email from the login page.

If you are not seeing the email even after checking spam and resending the email, it is possible that your account may be associated with a different email. In this case, try signing up for a new account using your provided email. If your account already exists, this is another way to send the magic login link to your email. If your account does not exist, it will create one for you.

**2. Why don't I see my team's data and reports?**

If you signed up via an invitation from a teammate, it is possible that the invitation was sent with the incorrect access permission. Reach out to your teammate and have them follow [these instructions](/docs/orgs-and-projects/roles-and-permissions#invite-users) to grant you access.

**3. I forgot my password. How can I login?**

You can navigate to the [login page](https://mixpanel.com/login/) and click the button at the bottom to set up a new password.


# Single Sign-On
Source: https://docs.mixpanel.com/docs/access-security/single-sign-on

Use SSO to access Mixpanel

<Note>
  Users on a Growth plan or above can enable Single Sign-On for authentication. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

Single sign-on (SSO) allows users to log into multiple platforms, services, or systems using a single ID and password combination. Mixpanel supports SSO and works with any SAML 2.0-compliant SSO provider.

## Access SSO Settings

You will need to be in the **Organization Owner** or **Admin role** to access the SSO settings.

To access SSO settings in Mixpanel, navigate to your **Organization Settings** (gear icon on the bottom-left side of the screen -> 'Settings' menu), and then click on the **Access Security** tab.

## Claim a Domain

Claiming a domain will add security to an SSO implementation by allowing only members with a claimed domain in their email address to access Mixpanel. SSO only works on domains that are claimed.

To claim a domain, add a TXT record to your domain's DNS records with a verification key provided by Mixpanel. The verification key is available after you submit to claim a domain in your Organization Settings.

<Note>
  A single domain can be claimed by only one Mixpanel organization. If you have multiple Mixpanel organizations with separate billing accounts but need to share SSO settings and email domains for login, please see the [documentation for the Shared SSO beta](/docs/access-security/single-sign-on/shared-sso) to see how you can share those settings with an "Admin" Organization.
</Note>

### Generate Verification Key by Claiming Domain

To claim a domain, click **Access Security** in your Organization Settings.

<Frame>
  <img alt="SSO Access Security Image" />
</Frame>

Click **Domain Claiming** in the Access Security menu.

<Frame>
  <img alt="SSO Domain Claiming Image" />
</Frame>

Click **Add a Domain** found in the Domain Claiming sub-menu. You will be prompted to enter your Mixpanel password.

<Frame>
  <img alt="SSO Add Domain Image" />
</Frame>

Enter the domain you wish to claim in the pop-up modal. Click **Submit Claim**.

<Frame>
  <img alt="SSO Submit Claim Image" />
</Frame>

### Check Verification Status

It may take up to 24 hours for Mixpanel to verify ownership after you claim a domain.

The claimed domain is listed in the Domain Claiming menu. It will appear as pending until it is successfully verified.

<Frame>
  <img alt="SSO Check Verification Status Image" />
</Frame>

It will indicate as verified after Mixpanel verifies the domain.

### Add Verification Token to your DNS

For Mixpanel to verify that you own the domain claimed, Mixpanel must detect the verification token in a TXT record in your domain's DNS.

The verification token is available in the Domain Claiming menu after you claim a domain. Use the verification token in the TXT record that you add to your domain's DNS record.

Add `mixpanel-domain-verify=<your-token>` as the TXT record.

**Note that you will need to leave the verification token in your DNS records permanently**, or the domain will unverify after a week. Only remove the verification token TXT record from domains with which you no longer wish to use SSO.

## Set Up Your IDP

You must configure your Identity Provider (IDP) to connect to Mixpanel to use SSO if you are not using custom-built SSO. This requires that you directly configure your SSO settings.

See the supported IDPs below:

### Okta

Set up SSO with Okta using the "Mixpanel" app within the OIN or by configuring a custom app in Okta. [Follow these instructions](/docs/access-security/single-sign-on/okta) to configure the "Mixpanel" app or a custom app.

### OneLogin

OneLogin only requires that you get the Postback URL. The "Mixpanel" application is in the OneLogin application store and supports auto-provisioning. You will just need to copy a SCIM token from Mixpanel into the provisioning token box in the OneLogin app. You can learn how to generate a token [here](/docs/access-security/single-sign-on/overview#scim).

### G-Suite

Google has an official integration with Mixpanel with instructions [here](https://support.google.com/a/answer/7553416). Unfortunately, we do not have an auto-provisioning integration with G-Suite. You will need to rely on [Just In Time Provisioning](/docs/access-security/single-sign-on/overview#just-in-time-provisioning).

### Azure

There are instructions here to set up SSO with Azure [here](/docs/access-security/single-sign-on/azure). Azure also has an auto-provisioning integration with Mixpanel, which you can find more info [here](https://learn.microsoft.com/en-us/azure/active-directory/saas-apps/mixpanel-provisioning-tutorial).

### Other IDPs

It is possible to set up Mixpanel SSO with IDPs not listed above. [Contact support](https://mixpanel.com/get-support) for further assistance in such cases.

## Postback URL

You likely will need to provide your IDP with a postback URL. The postback URL is accessible from the **Access Security** menu. To obtain your postback URL, navigate to Access Security in your Organization Settings and toggle on the Single Sign-On button.

<Frame>
  <img alt="SSO Postback URL Image" />
</Frame>

## SAML Certificate

This needs to be a **.cert** or **.pem** file for a valid X509 certificate.

* Note that .xml files are not valid. If you have downloaded an .xml file from your IDP, it will not work.
* It's important to note that this certificate will expire after a certain number of years. At the moment, we do not send any notifications when it is about to expire. Please make sure you have a system set up to cycle your certificate every so often if you wish to avoid disruption.

## Require Users to Log In Using SSO

Optionally toggle on **Require Single Sign-On** to require your users to log in using SSO and to prevent your users from logging in using a username and password.

* Please note that Organization Owners and Admins will still be able to log in using username and password in the case that SSO is not set up correctly.
* Note that external users (with an email of an unclaimed domain) who were invited to projects will *not* be able to log in if Require SSO is toggled on.

## IDP Managed Access

This feature determines whether you are using your IDP to manage which users should be allowed in the organization or whether you are using the IDP purely as an authentication method and want to leave user management within Mixpanel.

If you enable this feature:

* All users of your verified claimed domain(s) who log into Mixpanel will be prompted to use SSO, whether they are in your organization or not.
* If they successfully log in through your SSO setup, they will be automatically added to the organization with no permissions except those granted to all users ([JIT provisioning](/docs/access-security/single-sign-on/overview#just-in-time-provisioning)).
* It will also redirect anyone signing up for a Mixpanel account with your claimed domain or anyone requesting access to a project in your organization to log in via SSO first. This helps ensure all users in your organization who try to use Mixpanel get routed to your IDP, where you can then assign them access to the Mixpanel app. This also prevents needing to manually invite users to Mixpanel from within Mixpanel's Organization Settings.

We recommend enabling IDP Managed Access for most customers.

Enable the feature in the Access Security tab of your Organization Settings. Toggle on **IDP Managed Access** at the bottom. The toggle is purple when enabled.

<Frame>
  <img alt="SSO IDP Managed Access Image" />
</Frame>

## Just in Time Provisioning

Just-in-Time (JIT) provisioning using SAML will let users sign in automatically upon the initial login event. This removes the need for the organization admin to invite individual users to an Organization. This is part of the **IDP Managed Access** feature.

To use JIT provisioning, go to Access Security and toggle on the **IDP Managed Access** toggle. The toggle will be purple if the feature is enabled.

Users added using the IDP will have first names and last names populated by the `firstName` and `lastName` profile attributes provided via SAML at login time. These users will also have no roles to start off except those given to **all users** in your organization.

To give these provisioned users default access to projects, invite **All Users in the Organization** to the project.

<Frame>
  <img alt="image" />
</Frame>

## SCIM

The SCIM menu in the Access Security tab of the Organization Settings lets you generate a token used to hit the SCIM endpoints. **Remember to save this token, as you will see it only once.**

Note that only accounts with an **Enterprise plan** have access to SCIM at the moment.

You can find the official SCIM spec subset that Mixpanel implements [here](https://datatracker.ietf.org/doc/html/rfc7644). The base endpoint is `https://mixpanel.com/api/app/scim/v2`, which you can hit using the SCIM token as an Authentication Bearer token. For instance, a GET call on `https://mixpanel.com/api/app/scim/v2/Users` using the SCIM token will get you a list of all users in your organization.

<Note>
  The SCIM endpoint affects only users whose email has a domain in the list of your verified claimed domains.
</Note>

<Frame>
  <img alt="SSO SCIM Image" />
</Frame>

While you can hit the SCIM endpoints directly, the most common use case would be to use it for auto-provisioning within an IDP that has an integration with Mixpanel provisioning. This will let your IDP and Mixpanel stay in sync - when you assign users to Mixpanel in your IDP, they will be provisioned in Mixpanel, and optionally, you can deprovision users within Mixpanel who lose access in your IDP. IDPs that currently have an auto-provisioning integration with Mixpanel are Okta, OneLogin, and Azure.

If you wish to revoke your SCIM Provisioning token, you can generate a new one, which will kill the previous token.

We recommend enabling **IDP Managed Access** when using SCIM; otherwise, your IDP and Mixpanel can get out of sync.

## Remove SSO Configuration

If you need to remove all of your SSO configuration, you can do so with the "Remove SSO Configuration" button. This option is available if you had previously configured SSO and then disabled SSO. This will clear the settings and SAML certificate, as well as entries that facilitate the SSO process.

<Frame>
  <img alt="SSO Remove Configuration" />
</Frame>

<Warning>
  Removing SSO Configuration is permanent and cannot be undone.
</Warning>


# Setup Azure SSO
Source: https://docs.mixpanel.com/docs/access-security/single-sign-on/azure



## Overview

You can set up Microsoft Azure Single Sign-On to use with your Mixpanel account. Before using this document, read the [general Mixpanel SSO set-up instructions](/docs/access-security/single-sign-on) as well as [Azure's documentation on setting up a new application](https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/mixpanel-provisioning-tutorial).

### Add Mixpanel as a New Application

For more information, read [this Microsoft Azure article](https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/mixpanel-provisioning-tutorial) about configuring Mixpanel for automatic user provisioning.

1. Navigate to **Enterprise Applications** on the Microsoft Azure home page under **Default Directory**.
2. Click **New Application**.
3. Search and select **Mixpanel** to add as an application.

### Edit SAML Config in Microsoft Azure

1. Click **Single sign-on** under **Manage**.
2. Enter the following information in the SAML Configuration:

* **Entity ID:** [https://mixpanel.com/security/sso/v2/authorize/](https://mixpanel.com/security/sso/v2/authorize/)
* **Reply URL:** [https://sso.mixpanel.com/sso/saml2](https://sso.mixpanel.com/sso/saml2)
* **Sign on URL:** Postback URL from Mixpanel ([https://mixpanel.com/security/sso/v2/authorize/?org\_id=YOUR\_ORG\_ID](https://mixpanel.com/security/sso/v2/authorize/?org_id=YOUR_ORG_ID))

<Frame>
  <img alt="Azure Config 1 Image" />
</Frame>

3. Click **Edit** under **User Attributes & Claims** to add the required `email` claim (`firstName` and `lastName` are used for provisioning and optional).

| Claim name |          Value |
| ---------: | -------------: |
|      email |      user.mail |
|  firstName | user.givenname |
|   lastName |   user.surname |

<Frame>
  <img alt="Azure Config 2 Image" />
</Frame>

4. Make sure to clear out the **Namespace** field as well, or else it won't work!

<Frame>
  <img alt="Azure Config 3 Image" />
</Frame>

5. Download the SAML certificate under **SAML Signing Certificate** by clicking **Download** next to the **Certificate (Base64)** field. If you downloaded an .xml file, then you have clicked the wrong button. Make sure it is a **.cer** or **.pem** file. This will be uploaded to Mixpanel in the next step.

### Copy Certificate into Mixpanel

1. Navigate to the **Access Security** section in your Mixpanel **Organization Settings**.
2. Upload the certificate in the **SAML Certificate** field.
3. Input the **Azure AD Identifier** into the **Issuer URL** field.
4. Input the **Azure Login URL** in the **Identity Provider Sign-in URL** field.
5. Assign your team members this new application.

### SCIM Provisioning

Azure has an auto-provisioning integration with Mixpanel that allows you automatically add users to Mixpanel upon giving them access in Azure. The integration also allows you to remove access within Mixpanel when you remove access in Azure. You can find more information [here](https://learn.microsoft.com/en-us/azure/active-directory/saas-apps/mixpanel-provisioning-tutorial).

* New users provisioned from Azure will be automatically added as an Organization Member.
* You will need to provision other [Organization Roles](/docs/orgs-and-projects/roles-and-permissions#organization-roles) to users within the Mixpanel product.
* You will not be able to set the user's Organization Role and Project access within Azure.

You can also provision Groups of users in Azure to Mixpanel [Teams](/docs/orgs-and-projects/roles-and-permissions#teams) with SCIM.

* Use the same name for the Group in Azure as the Team in Mixpanel.
* In the Mixpanel Team, set the Organization Role and access to projects for the group of users.
* You will not be able to provision Organization Role and Project access for the Group within Azure.

Note that it is advised you turn on **IDP Managed Access** if you are using SCIM Provisioning. Otherwise, Okta and Mixpanel might fall out of sync.

Tenant URL: `https://mixpanel.com/api/app/scim/v2`


# Setup Google Workspace SSO
Source: https://docs.mixpanel.com/docs/access-security/single-sign-on/google



## Overview

Before using this document, read the [general Mixpanel SSO set-up instructions](/docs/access-security/single-sign-on).

You have two setup options to use Single Sign-On (SSO) for Mixpanel through Google Workspace IDP:

A.  For most use cases, you can use the **Mixpanel app** within Google Workspace's app store.

B.  If you have a custom setup, follow Google Workspace's documentation on setting up a new application to create a custom Mixpanel app.

### Configure SSO in Mixpanel

Follow the [general SSO set-up instructions](/docs/access-security/single-sign-on).

Make sure to collect your postback URL and successfully claim your domain.

### Configure the Mixpanel App in Google Workspace

A.  Use the [Mixpanel app within Google Workspace's app store](https://admin.google.com/ac/apps/unified), or

B.  Follow [Google Workspace's documentation on setting up a new application](https://support.google.com/a/answer/6087519?hl=en) to create a custom Mixpanel app.

#### Configure SAML

A. If you use the Mixpanel app from the store, the following SAML configuration is already built into the app.

<Frame>
  ![use\_existing\_app](https://github.com/user-attachments/assets/4d42cf48-9b1e-4be2-8b56-ec76edaad118)
</Frame>

B. If you create a custom app, you must fill out the form found in the **Configure SAML** menu in Google Workspace. Make sure that the following fields are adjusted to exactly match the corresponding values:

* **ACS URL:** [https://sso.mixpanel.com/sso/saml2](https://sso.mixpanel.com/sso/saml2)
* **Entity ID:** [https://mixpanel.com/security/sso/v2/authorize/](https://mixpanel.com/security/sso/v2/authorize/)
* **Start URL:** [https://mixpanel.com/security/sso/v2/authorize/?org\_id=YOUR\_ORG\_ID](https://mixpanel.com/security/sso/v2/authorize/?org_id=YOUR_ORG_ID)

The following screenshot highlights what you should place in the fields:

<Frame>
  ![custom\_saml\_app](https://github.com/user-attachments/assets/be8660ff-084f-409e-9dec-49e17b7563e6)
</Frame>

Additionally, it is required that you use `email` as an attribute statement; other attributes we recommend include `firstName` and `lastName`.

<Frame>
  ![attr\_mapping](https://github.com/user-attachments/assets/b10ea8bf-ff1a-4270-8b97-0d078ae46fde)
</Frame>

### Obtain Information From Google Workspace

To configure Mixpanel use with Google Workspace, you must first obtain your **Public Certificate**, **SSO URL**, and **Entity ID**.

To access this information, access the Mixpanel app in Google Workspace (or create a custom app) first select **DOWNLOAD METADATA**. Then, grab the **SSO URL** and **Entity ID** as well as the certificate to upload in Mixpanel (we recommend adding the expiration date to the file name to make it easier to manage in Mixpanel).

<Frame>
  ![google\_metadata](https://github.com/user-attachments/assets/d1ea2115-eaf7-4cde-a01d-b9bb248314e3)
</Frame>

### Enable SSO

From Mixpanel, navigate to your **Organization Settings** and then the **Access Security** tab. From the **2FA & SSO** menu, upload your **Public Certificate** and add your **SSO URL** and **Entity ID** to the **Identity Provider Sign-In URL** and **Issuer URL**, respectively.

<Frame>
  ![sso\_settings\_in\_mp](https://github.com/user-attachments/assets/e97be4c6-dc1f-44d1-adb4-530679bca9ba)
</Frame>

Optionally, toggle **Require Single Sign-On** to prevent your users from logging in with a username and password. Organization Owners and Admins will still be able to log in using username and password in case SSO is not set up correctly.

### Troubleshooting

1. If a Mixpanel account has already been created with the Google Workspace user's email (their Google Workspace Username) and that account is **not a member** of your Mixpanel organization, provisioning setup for that Google Workspace user will fail. To resolve this, manually invite the existing user to your organization.
2. Provisioning will also fail if the domain of the user's email has not been claimed by your organization. To resolve this, manually invite the existing user to your organization.
3. If seeing the "Error 403: app\_not\_configured" message when trying to log in, please follow [these instructions](https://knowledge.workspace.google.com/admin/apps/saml-app-error-messages#403_app_not_configured) to grant the necessary permissions to the user's account.


# Setup JumpCloud SSO
Source: https://docs.mixpanel.com/docs/access-security/single-sign-on/jumpcloud



## Overview

Before using this document, read the general Mixpanel SSO set-up instructions.

### Configure SSO in Mixpanel

Follow the general SSO set-up instructions.

Make sure to collect your postback URL and successfully claim your domain.

### Configure the Mixpanel App in JumpCloud

Go to JumpCloud and create a custom application with the following values:

SP Entity ID: [https://mixpanel.com/security/sso/v2/authorize/](https://mixpanel.com/security/sso/v2/authorize/)

ACS URL: [https://sso.mixpanel.com/sso/saml2](https://sso.mixpanel.com/sso/saml2)

Login URL: \<Mixpanel's Postback URL from your org settings>

IDP Entity ID: The value itself doesn't matter much but it must be unique across all Mixpanel customers and must also be a URL, so something like `https://sso.jumpcloud.com/saml2/<your-company-name>-mixpanel` would work swapping in your company name. You will paste this into Mixpanel's Issuer URL field.

IDP URL: You will paste this into Mixpanel's Identity Provider Sign-in URL field

You will also want to download the IDP certificate to upload into Mixpanel

Make sure to pass through the attributes: email, firstName and lastName. Only email is required but the other two are useful if you want to provision new users with SSO via IDP Managed Access.

Here is a screenshot of an example setup:

<Frame>
  <img alt="JumpCloud Info Image" />
</Frame>

Optionally toggle “Require Users to Log In using SSO” to prevent your users from using a username and password to log in. Click **Enable**. Organization owners and admins will still be able to log in using username and password if SSO is not set up correctly.

### SCIM

Use SCIM with JumpCloud at your own risk. There have been problems reported with the JumpCloud setup process hard deleting users unexpectedly.


# Setup Okta SSO
Source: https://docs.mixpanel.com/docs/access-security/single-sign-on/okta



## Overview

Before using this document, read the [general Mixpanel SSO set-up instructions](/docs/access-security/single-sign-on).

You have two setup options in order to use Single Sign-On (SSO) for Mixpanel through Okta:

A.  For most use cases, you can use the **Mixpanel app** within the OIN (Okta's app store).

B.  If you have a more custom setup, follow Okta's documentation on setting up a new application to create a custom Mixpanel app.

### Configure SSO in Mixpanel

Follow the [general SSO set-up instructions](/docs/access-security/single-sign-on).

Make sure to collect your postback URL and successfully claim your domain.

### Configure the Mixpanel App in Okta

A.  Use the [Mixpanel app within the OIN (Okta's app store)](https://www.okta.com/integrations/mixpanel/), or

B.  Follow [Okta's documentation on setting up a new application](https://help.okta.com/en-us/Content/Topics/Apps/Apps_Apps_Page.htm) to create a custom Mixpanel app.

#### Configure SAML

A. If you use the Mixpanel app from the OIN, the following SAML configuration is already built into the app.

B. If you create a custom app, you must fill the form found in the **Configure SAML** menu in Okta. Make sure that the following fields are adjusted to exactly match the corresponding values:

* **Single sign on URL:** Postback URL from Mixpanel ([https://mixpanel.com/security/sso/v2/authorize/?org\_id=YOUR\_ORG\_ID](https://mixpanel.com/security/sso/v2/authorize/?org_id=YOUR_ORG_ID))
* **Requestable SSO URLs:** [https://sso.mixpanel.com/sso/saml2](https://sso.mixpanel.com/sso/saml2)
* **Recipient URL:** [https://sso.mixpanel.com/sso/saml2](https://sso.mixpanel.com/sso/saml2)
* **Destination URL:** [https://sso.mixpanel.com/sso/saml2](https://sso.mixpanel.com/sso/saml2)
* **Audience URI:** [https://mixpanel.com/security/sso/v2/authorize/](https://mixpanel.com/security/sso/v2/authorize/)

The following screenshot highlights what you should place in the fields:

<Frame>
  <img alt="Okta Config SAML 1 Image" />
</Frame>

To add the Requestable SSO URLs field, navigate to Advanced Settings:

<Frame>
  <img alt="Okta Config SAML 2 Image" />
</Frame>

Additionally, it is required that you use `email` as an attribute statement, other attributes we recommend include `firstName` and `lastName`.

|      Name |          Value |
| --------: | -------------: |
| firstName | user.firstName |
|  lastName |  user.lastName |
|     email |     user.email |

<Frame>
  <img alt="Okta Config SAML 2 Image" />
</Frame>

### Obtain Information From Okta

In order to configure Mixpanel use with Okta, you must first obtain your **Public Certificate**, **Authentication URL**, and **Issuer URL**.

To access this information, first select the select the Mixpanel app under the **Applications** tab in Okta. Click on the **Sign On** tab.

In the right **About** column under the **SAML Setup** section, click **View SAML setup instructions**.

<Frame>
  <img alt="Okta Info 1 Image" />
</Frame>

#### Public Certificate

The X.509 certificate allows users signing in through a third-party identity provider to be authenticated by Mixpanel without supplying a username and password. Each identity provider account has a unique X.509 certificate that will need to be uploaded to Mixpanel during the SSO setup process.

Click **Download Certificate** in the second entry to download your certificate.

<Frame>
  <img alt="Okta Info 2 Image" />
</Frame>

You can also find the Public Certificate in the **Sign On** tab of the **Mixpanel** app. Scroll down to the **SAML Signing Certificates** section. Click **Actions** for the SHA-2 certificate and **Download certificate**.

<Frame>
  <img alt="Okta Certificate Download Image" />
</Frame>

If you Public Certificate is expired or compromised, click **Generate new certificate** to generate a new certificate to upload in Mixpanel.

#### Authentication URL

Your Authentication URL is in the third entry labeled **Redirect Login URL**.

<Frame>
  <img alt="Okta Info 3 Image" />
</Frame>

#### Issuer URL

You will find your Issuer URL in the third entry labeled **Identity Provider Issuer**.

<Frame>
  <img alt="Okta Info 4 Image" />
</Frame>

### Enable SSO

From Mixpanel, navigate to your **Organization Settings** and then the **Access Security** tab. From the **2FA & SSO** menu, insert your **Public Certificate**, **Authentication URL**, and **Issuer URL**.

Optionally toggle **Require Single Sign-On** to prevent your users from logging in with a username and password. Organization Owners and Admins will still be able to log in using username and password in case SSO is not set up correctly.

### Configuring SCIM Provisioning

SCIM provisioning uses [the Mixpanel app within the OIN (Okta's app store)](https://www.okta.com/integrations/mixpanel/).

The following prerequisites must be met to set up SCIM provisioning:

* You must have an active Enterprise plan subscription with Mixpanel.
* You must have Okta SSO set up with Mixpanel.
* The `Username` value in Okta must be an email address with a domain that you've claimed.
* You need to have generated a SCIM OAuth token to use with the app. This token is located in **SCIM** menu of the **Access Security** tab in your Organization Settings. You will need to be an Organization Owner or Admin to access this.

<Frame>
  <img alt="Okta SCIM 1 Image" />
</Frame>

The following provisioning features are supported:

* **Push New Users:** New users created through Okta and assigned to the application will be created in Mixpanel.
* **Push Profile Updates:** Updates made to the assigned user's supported profile attributes (First Name, Last Name, Email) through Okta will be pushed to Mixpanel.
* **Push User Deactivation:** Deactivating the user or removing the user from the application through Okta will deactivate the user in Mixpanel (or delete the account if specified).
* **Reactivate Users:** Reassigning a previously unassigned user to the application will reactivate the user's account in Mixpanel.

Please note the following when provisioning users from Okta to Mixpanel with SCIM:

* New users provisioned from Okta will be automatically added as an Organization Member.
* You will need to provision other [Organization Roles](/docs/orgs-and-projects/roles-and-permissions#organization-roles) to users within the Mixpanel product.
* You will not be able to set the user's Organization Role and Project access within Okta.

You can also provision Groups of users in Okta to Mixpanel [Teams](/docs/orgs-and-projects/roles-and-permissions#teams) with SCIM.

* Use the same name for the Group in Okta as the Team in Mixpanel.
* In the Mixpanel Team, set the Organization Role and access to projects for the group of users.
* You will not be able to provision Organization Role and Project access for the Group within Okta.

Note that it is advised you turn on **IDP Managed Access** if you are using SCIM Provisioning. Otherwise, Okta and Mixpanel might fall out of sync.

#### Configuration Setup

1. Click the **Configure API Integration** button in Okta to begin.

<Frame>
  <img alt="Okta SCIM 2 Image" />
</Frame>

2. Check the **Enable API Integration** box, then enter your SCIM token.

Select the supported features (Create / Update / Deactivate) you wish to enable:

<Frame>
  <img alt="Okta SCIM 3 Image" />
</Frame>

3. The following profile attributes are required to be sent from Okta to Mixpanel:

* Username
* Given name
* Family name
* Primary email

<Frame>
  <img alt="Okta SCIM 4 Image" />
</Frame>

4. Select and assign the users you wish to provision:

<Frame>
  <img alt="Okta SCIM 5 Image" />
</Frame>

#### Troubleshooting

1. If a Mixpanel account has already been created with the Okta user's email (their Okta Username) and that account is **not a member** of your Mixpanel organization, provisioning setup for that Okta user will fail. To resolve this, manually invite the existing user to your organization.
2. Provisioning will also fail if the domain of the user's email has not been claimed by your organization. To resolve this, manually invite the existing user to your organization.


# Shared SSO
Source: https://docs.mixpanel.com/docs/access-security/single-sign-on/shared-sso

Use the same SSO setting for multiple Mixpanel organizations

## Overview

If you have multiple Mixpanel [Organizations](/docs/orgs-and-projects/organizations) with separate billing accounts, but need to share SSO settings and email domains for login, you can share those settings with an "Admin" Organization.

With a shared SSO setup, Single Sign-On settings and Claimed Domains are administered via this "Admin" Organization, and Organizations can be linked to the "Admin" Organization in order to utilize those settings. Administrators need administrative privileges in the Admin Organization to make changes to the shared SSO and Domain settings.

This feature is available to customers on an Enterprise Plan.

<Note>
  Shared SSO is available by request. Please contact your Account Manager if you are interested in enabling this feature.
</Note>

## Admin Organizations

An Admin Organization is a special type of Organization that contains Single Sign-On settings and Claimed Domains. It can have Organization Members, but you should only add administrative users to the Admin Organization to manage security. The [SCIM](/docs/access-security/single-sign-on#scim) process will add Users as Organization Members.

An "Admin" Organization is different from a regular Organization in that it will not have Projects, Teams, a Plan or Billing, or Service Accounts. Other than administrators (those with Admin or Owner roles), any Organization Members will not see the Admin Organization or interact with it directly.

An Admin Organization can have multiple Linked Organizations which will share SSO settings. A regular Organization can only be linked to one Admin Organization.

<Frame>
  <img alt="SSO Admin Organization Image" />
</Frame>

## How It Works

Any Organization linked to an Admin Organization will use the Single Sign-On settings from that Admin Organization - **any Single Sign-On settings or Claimed Domains the Linked Organization may have had are now ignored**.

SSO settings and Claimed Domains are managed in the Admin Organization. Administrative users who manage SSO settings in the Admin Organization do not need to be members of the Linked Organization(s), and vice-versa.

This configuration supports [SCIM](/docs/access-security/single-sign-on#scim).

## Differences From Single-Organization SSO

* In single-Organization SSO, SSO is configured in each Organization. In Shared SSO, SSO is configured in the "Admin" Organization, and shared by any Linked Organizations.
* In single-Organization SSO, claimed domains belong to each Organization. In Shared SSO, claimed domains belong to the Admin Organization and are shared by any Linked Organizations.
* In single-Organization SSO, SCIM groups in the IDP map to Teams in Mixpanel, with the IDP group name matching the Mixpanel Team **name**. In Shared SSO, SCIM groups in the IDP map to Linked Organizations, with the IDP group name matching the Linked Organization's **SCIM Name**.

|        ---        | **Single-Organization SSO** |                **Shared SSO**                |
| :---------------: | :-------------------------: | :------------------------------------------: |
| SSO Configuration |     In each Organization    |           In the Admin Organization          |
|  Claimed Domains  |     In each Organization    |           In the Admin Organization          |
|        SCIM       | IDP Groups = Mixpanel Teams | IDP Groups = Mixpanel Linked Organizations\* |

\* With Shared SSO, SCIM cannot manage Mixpanel Team membership. Team membership will need to be managed manually.

## Setting Up Shared SSO

<Warning>
  If you already use Azure for SSO with Mixpanel, you must [remove existing SSO configuration](/docs/access-security/single-sign-on#remove-sso-configuration) before migrating, due to constraints with “Issuer URL” and “Identifier (Entity ID).” Contact Mixpanel by [opening a Mixpanel support ticket](https://mixpanel.com/get-support).
</Warning>

### 1. Create an Admin Organization in Mixpanel

For an existing Organization in Mixpanel, go to Organization Settings > Access Security > Shared SSO.

<Frame>
  <img alt="SSO Create Admin Organization Image" />
</Frame>

<Frame>
  <img alt="SSO Create Admin Organization Image" />
</Frame>

The new Admin Organization will be listed in the left nav in Organization Settings.

<Frame>
  <img alt="SSO Admin Organization Navigation Image" />
</Frame>

### 2. [Set up SSO](/docs/access-security/single-sign-on) for the Admin Organization

Follow the steps to set up SSO in the Admin Organization as you would for a regular Organization. [SSO documentation](/docs/access-security/single-sign-on).

### 3. Link any Organizations to the Admin Organization in Mixpanel

<Warning>
  Any existing SSO settings in the "Linked" Organization will be ignored after this step.
</Warning>

Start by generating a linking code in the new Admin Organization. In the "Linked Organizations" section, click "Link Organization", then copy the generated linking code.

<Frame>
  <img alt="SSO Generate Linking Code Image" />
</Frame>

Then complete the linking by entering the linking code in the Organization to be linked.

<Frame>
  <img alt="SSO Enter Linking Code Image" />
</Frame>

The Organizations are now linked. The Linked Organization will now follow the SSO settings and claimed domains from the Admin Org.

### 4. (Optional) Transfer Existing Domains

Once your organizations are linked, you can then transfer any domains you might have claimed from the Linked Organization to the Admin Organization. Go to domain claiming on the Linked Organization and click the “Transfer domain” button for all the domains you want to transfer.

<Frame>
  <img alt="SSO Domain Transfer Image" />
</Frame>

### 5. (Optional) Set up [SCIM](/docs/access-security/single-sign-on#scim)

The configurable "SCIM Name" for the Linked Organization must match a group in your IDP. Members of the matching group will be added to the Linked Organization.

<Frame>
  <img alt="SSO Linked Organizations Image" />
</Frame>

## SCIM With Shared SSO

Mixpanel supports using SCIM to administer users while using Shared SSO. With single-Organization SSO, the SCIM process would push users into the Mixpanel Organization, it would create Mixpanel Teams with the names of Groups in the IDP, and it would assign Mixpanel Users to those Teams.

With Shared SSO, the SCIM process works a little differently. Users are pushed to the Admin Organization. Groups in the IDP are pushed to Organizations Linked to the Admin Organization. Groups are mapped by matching an editable “SCIM Name” field in an Organization to the name of the Group in the IDP. Users that are members of the IDP Group are assigned to the linked Organization whose SCIM Name matches the name of the Group.

With Shared SSO, SCIM cannot manage Mixpanel Team membership. Team membership will need to be managed manually.

<Note>
  With Shared SSO, the SCIM process cannot create, delete or alter the linked Organizations in Mixpanel like it would with a Mixpanel Team. The SCIM process can only add and remove Users, and assign those users to the linked Organization.
</Note>

## Migrating To Shared SSO

<Warning>
  If you already use Azure for SSO with Mixpanel, you must [open a Mixpanel support ticket](https://mixpanel.com/get-support) before migrating, due to constraints with “Issuer URL” and “Identifier (Entity ID)”
</Warning>

If you have Single Sign-On configured for an Organization, and want to use the same email domains with a Shared SSO; you will need to follow these steps to migrate and minimize the time Single Sign-On is unavailable for your users.

Be sure to follow these steps in this order, or there will be more downtime for Single Sign-On.

1. In Mixpanel, [Create an Admin Organization](#1-create-an-admin-organization-in-mixpanel)
2. In Mixpanel, Set up SSO for the Admin Organization and configure an application in your IDP with the corresponding settings. You can refer to the [Single Sign-on Overview section](/docs/access-security/single-sign-on) in our docs or to the respective IDP docs for [Azure](/docs/access-security/single-sign-on/azure) or [Okta](/docs/access-security/single-sign-on/okta)
3. In your IDP, assign all users (who will be using Mixpanel in any Linked Organization) into the newly configured app
4. (Optional) In your IDP, set up SCIM for the newly configured app, but **do not start pushing groups**
5. In Mixpanel, [link the original Organization to the Admin Organization](#3-link-any-organizations-to-the-admin-organization-in-mixpanel). Users should be able to log in via SSO again.
6. In Mixpanel, transfer claimed Domains from the original Organization to the Admin Organization. (see [Transfer Existing Domains](#4-optional-transfer-existing-domains) above)
7. Deactivate the original SSO application in your IDP
8. (Optional) Finish setting up SCIM

   1. In your IDP, establish a Group for the users who have access to the original Organization
   2. In Mixpanel, edit the SCIM name of the original Organization to match the name of this group
   3. Configure your IDP to push this group to Mixpanel


# Two-Factor Authentication
Source: https://docs.mixpanel.com/docs/access-security/two-factor-authentication



## Overview

Two-factor authentication (2FA) is a security process that requires users to provide two different authentication factors, such as passwords or tokens, to verify their identity.

When you enable 2FA for your organization, all users will be prompted for a 2FA code, including users who log in with Google social login (OAuth) and traditional username/password login methods. If a user hasn't set up 2FA yet, they will be prompted to set it up on their next login.

This is distinct from [SSO](/docs/access-security/single-sign-on) (SAML-based Single Sign-On) users, who are exempt from 2FA prompts.

### Enable Two-Factor Authentication for your Organization

If you are an organization admin, you can enable two-factor authentication by doing the following:

1. In your "Organization Settings", select **Access Security**.

<Frame>
  <img alt="2FA Access Security Image" />
</Frame>

2. In “Two Factor Authentication”, if the icon is gray, click it to enable. If the icon is purple, click it to disable.

**Note: If your organization has SSO enabled, your organization will not have access to 2FA.**

<Frame>
  <img alt="2FA Enable Image" />
</Frame>

3. The “Verify Mixpanel password” box will appear.

**Note: If you do not have a password because you use Magic Link or Google Sign In, please go to your personal settings to set up your password.**

<Frame>
  <img alt="2FA Verify Password Image" />
</Frame>

4. Enter your password and click **Confirm** to finalize changes.

### Setting up your Two-Factor Authentication Method

Once two-factor authentication has been enabled for your organization, an individual member of your organization can set up two-factor authentication via the methods below.

#### Setup via second login

On their second login, Mixpanel Users will be prompted to set up two-factor authentication via an authentication app.

##### Authentication App

1. In order to set up two-factor authentication via an authentication app, select the authentication app option and ensure you have your preferred authentication app downloaded. We recommend using apps such as Google Authenticator, Authy and Microsoft Authenticator.

<Frame>
  <img alt="2FA Authentication App 1 Image" />
</Frame>

2. Scan the QR code via your Authentication App in order to complete the setup.

<Frame>
  <img alt="2FA Authentication App 2 Image" />
</Frame>

If you are unable to scan the QR code, click on “Can’t scan QR code?” This will provide you a two-factor secret to set up your authentication app manually.

<Frame>
  <img alt="2FA Authentication App 2b Image" />
</Frame>

3. Before you log in into Mixpanel, download or copy your recovery codes. These are essential for you to log in if you happen to lose your phone.

**Note: This is the only location you can save your recovery codes, please ensure you save them in a safe place.**

<Frame>
  <img alt="2FA Authentication App 3 Image" />
</Frame>

#### Setup via personal settings page

An individual user can also set up their two-factor authentication via their personal settings. In order to setup two-factor authentication, follow these steps:

1. Go to the settings icon > personal settings> your profile, then click on "Set Up Method".

<Frame>
  <img alt="2FA Personal 1 Image" />
</Frame>

2. You will be asked to log out in order to set up two-factor authentication. Log in to Mixpanel and follow the setup process.

<Frame>
  <img alt="2FA Personal 2 Image" />
</Frame>

### Changing your Two-Factor Authentication Method

An individual user can switch between different authentication apps for their two-factor authentication method via their personal setting. (i.e. Authy to Google Authenticator)

**Note: Changing your two-factor method will reset it**

Users can switch their method via the following steps:

1. Go to settings cog > personal settings> your profile, then click "**Change Method**".

<Frame>
  <img alt="2FA Change 1 Image" />
</Frame>

2. To change your method, log out and log back in to Mixpanel to start the setup process for your new authentication method.

<Frame>
  <img alt="2FA Change 2 Image" />
</Frame>

### Login via backup methods

If you are unable to log in due to two-factor authentication because you lost your phone, we have a couple backup methods you can use to log in depending on your authentication method.

**Note: Contact support if none of these backup methods work for you.**

#### Login via recovery codes (authentication app)

If an authentication app is your preferred method of authentication, you can login via your saved recovery codes if you don’t have access to your phone. A user can login via a recovery code by doing the following:

1. Click on “Need help? Use a recovery code to sign in”

<Frame>
  <img alt="2FA Backup 1 Image" />
</Frame>

2. Enter your recovery code and click "Login".

<Frame>
  <img alt="2FA Backup 2 Image" />
</Frame>

**Note: If you use all your recovery codes, you will be asked to reset your two-factor authentication method on your next login.**

### Resetting Two-Factor Authentication for Users

As an organization admin, you can reset two-factor authentication (2FA) for users within your organization. To do this, follow these steps:

1. Navigate to the Access Security section within your "Organization Settings".
2. Click on the 2FA tab.
3. Select the users whose 2FA needs to be reset.
4. Click Reset Two-Factor Authorization

This will reset their two-factor authentication, allowing them to set up 2FA again the next time they log in.


# Agentic Automations
Source: https://docs.mixpanel.com/docs/agentic-automations



## Overview

Mixpanel Agentic Automations are sub-agents of Mixpanel Agent that you configure once to do recurring analysis work for you, and deliver the result where you already work.

## Types of Agentic Automations

* **KPI Monitoring** — Watches a metric you own and ships a personalized digest on the cadence you choose. See [below](#kpi-monitoring) for details.

In the future, we're also exploring Research, Event-Triggered, and Data Governance automations. To get early access or help shape these, reach out to your account manager and ask to be connected with our product team.

## KPI Monitoring

A KPI Monitor watches a metric you care about and ships a personalized digest on the cadence you choose. Each digest summarizes what changed in the last window, calls out shifts the agent considers notable, and gives you a way to give feedback so we can improve what the agent surfaces over time.

### Create a KPI Monitor

You can also create and manage Automations by asking Mixpanel Agent — see [below](#manage-automations-with-mixpanel-agent).

<Steps>
  <Step title="Launch the Automation creation workflow">
    Click '+ Create New' button in your side navigation bar. At the bottom of the 'Analysis' section, click the Automation button.\\

    <Frame>
      <img alt="Image" />
    </Frame>

    <Note>
      Don't see this button? Your organization may not have Mixpanel AI enabled. See the [Mixpanel Agent FAQ](/docs/mixpanel-agent#faq) for how to enable Mixpanel AI features in settings.
    </Note>
  </Step>

  <Step title="Name the Automation">
    Pick the automation type and give it a name. The Automation is created as a **Draft** right away, before you configure anything, and won't run until you activate it. You'll set up everything else on the Automation's **Configuration** tab.
  </Step>

  <Step title="Set the trigger">
    Digests can be delivered daily, weekly, or monthly, at a time of day you choose. Daily schedules can run on specific weekdays, weekly schedules on a single weekday, and monthly schedules on either a day of the month or an nth weekday. You can also repeat every few weeks or months instead of every one. Weekly is a balanced default cadence for most teams.

    Changing the cadence resets the analysis window to the new cadence's default.
  </Step>

  <Step title="Configure the metric analysis">
    **Metric.** Choose any Insights-style event metric — sums, counts, or unique counts over an event you've already instrumented. The agent will use the metric's existing definition as the source of truth for what it watches.

    **Breakdown (optional).** Pick one property to break the metric down by, and each digest ranks its segments alongside the overall number. See [Break a KPI down by a property](#break-a-kpi-down-by-a-property).

    **Instructions.** Use the **Instructions** field to tell the agent how to interpret results and what to call out. For example: "Flag anything that deviates more than 2 standard deviations from the 30-day average" or "Focus on week-over-week change, not absolute values."

    Instructions shape the digest's commentary, not the underlying query. The agent runs a single, fixed query based on the metric you selected. It cannot run additional queries, pull in other metrics, or take actions. Instructions guide how the agent frames its summary: which comparisons to emphasize, what thresholds matter to you, and what language to use when describing shifts.

    **Analysis window.** Set how much history each digest analyzes. The options available depend on the cadence you picked, and each cadence has a sensible default.
  </Step>

  <Step title="Set up delivery">
    Digests can land in Slack, email, or both — you can add multiple email recipients and multiple Slack channels at the same time. Slack delivery requires the [Slack integration](/docs/features/slack-integration) to be configured for your project.

    Delivery is optional. With no channel configured, results only appear on the Automation's overview page.
  </Step>

  <Step title="Save and activate">
    Save your configuration, then flip the **Activate** toggle to start the schedule — your first digest arrives at the next cadence boundary. Activation requires a name, a valid metric, and a cadence, with no unsaved changes. You can pause, edit, or delete the Automation at any time.
  </Step>
</Steps>

### Break a KPI down by a property

If you track a KPI across many segments — regions, fulfillment centers, products, accounts — you don't need one Automation per segment. Pick a single property to break the metric down by, and every digest ranks that property's segments for you.

Each digest leads with the overall metric, then surfaces the **top 5 and bottom 5 performing segments**. So a daily monitor on Orders Completed broken down by `fulfillment_center_id` tells you both how order volume is doing overall and which centers are pulling ahead or falling behind — even on a day when the total looks unremarkable.

Breakdowns work on any cadence, and the digest is delivered wherever your other KPI digests land.

<Note>
  Set the breakdown in the breakdown field, not the **Instructions** field. Asking for "break down by location" in your instructions won't create a breakdown — and it's ambiguous which property you meant. Choosing the property explicitly guarantees the digest ranks the one you intended.
</Note>

### What's in a digest

* A short summary of what the metric did in the last window vs. baseline.
* Any shifts the agent considers notable, with the agent's reasoning.
* If you set a breakdown, the top 5 and bottom 5 performing segments for that property.

## Manage Automations with Mixpanel Agent

You can set up and manage Automations by asking [Mixpanel Agent](/docs/mixpanel-agent) in plain language, from anywhere the Agent is available. Ask it to:

* **List** your Automations. This returns the Automations you own, not your teammates'.
* **Inspect** one — its settings, schedule, analysis window, breakdown, and delivery. From an Automation's details page, the Agent picks up which one you mean from the page you have open.
* **Create** a new one — metric, breakdown, cadence, analysis window, instructions, and delivery.
* **Update** one — rename it, change the cadence, adjust the analysis window, add or change the breakdown, revise instructions, or change delivery.
* **Activate** or **pause** it.
* **Check run history** — when it last ran, and whether the run succeeded, failed, or partially completed. Both scheduled and manual runs are included.
* **Delete** it.

For example: *List my automations*, *Create a daily automation for Signups delivered to email at 9am*, *Break my Orders Completed monitor down by fulfillment\_center\_id*, or *Show me the run history for my WAU monitor*.

When you ask for a breakdown, name the property explicitly. "Break it down by location" is ambiguous if your project has several location properties, and the Agent will ask which one you meant.

**Run Now** is an action on the Automation's page in Mixpanel. The Agent can report on runs, but can't trigger one for you.

<Note>
  Every change the Agent makes requires your approval. Creating, updating, activating, pausing, and deleting each surface an approval step showing exactly what will change, and nothing is applied until you approve it.

  Automations the Agent creates land as **Draft** — the Agent never activates one as part of creating it. Activating is a separate action with its own approval.

  Edits are scoped to what you asked for: approving a rename changes only the name, and leaves the metric, cadence, window, and delivery untouched. The one exception is delivery, which is replaced as a set rather than merged — asking to add a recipient replaces the existing delivery configuration.
</Note>

## Limits

* **Automations per user per project.** Free: 5, Growth: 10, Enterprise: 20.
* **Metric types.** KPI Monitors today support Insights-style event metrics, as well as funnel, retention, saved metrics, and formulas
* **Delivery channels.** Slack and email are available today
* **Cadence.** Daily, weekly, or monthly.
* **Analysis window.** The options available depend on the cadence you picked.
* **Breakdowns.** One property per Automation. Digests show the top 5 and bottom 5 segments; the number of segments isn't configurable yet.
* **Time zone.** Schedules run in the project's time zone. There's no per-user local delivery time yet.

<Note>
  Have feedback or want to help shape what's next for Agentic Automations? Reach out to your account manager and ask to be connected with our product team.
</Note>


# Boards
Source: https://docs.mixpanel.com/docs/boards

Collect your reports into a single view

<Frame>
  <img alt="/Screen_Shot_2022-01-07_at_2.07.26_PM.png" />
</Frame>

A Board is a collection of reports, text, and images or videos, which allow you to view all your most important metrics at a glance. Add Insights, Flows, Funnels, and Retention reports to a board to be able to track those metrics both regularly and simultaneously.

Boards can also be created using the [Templates](/docs/boards/templates) feature.

## Use Cases

Boards can be used to keep your whole company on top of your KPIs. Additionally, you can add text to your boards to help tell a compelling story, or highlight specific interpretations of the other reports on boards.

Create personal boards or project boards and share them with your team to help you and your colleagues understand and stay on top of your metrics.

<Frame>
  <iframe />
</Frame>

## Quick Start

### Step 1: Navigating Boards

Before creating a board of your own, it's best to explore existing boards within your Mixpanel project. There's a good chance that someone has already created a board that may be of interest to you. The best way to navigate to existing boards within your Mixpanel project is the directory on the left-hand side of the page. This directory makes it easy to access your most-used boards by organizing them into several sections:

<Frame>
  <img alt="/11441973595156" />
</Frame>

**Favorites**: to favorite a board, click the "Favorite" button at the top right of that board. Once you've done so, it will appear in the favorites section at the top left of the board's page.

**Pinned**: pinned boards are important boards for your organization. Mixpanel users with the [Admin or Owner roles](/docs/orgs-and-projects/roles-and-permissions#organization-roles) will be able to pin a board such that it appears in the Pinned section for every project member.

**Your Boards**: any boards you create will appear in this section. To create a new board, click "+ New Board" at the top of the directory.

Finally, you can search for all boards, or recently viewed boards, at the top of the directory.

### Step 2: Creating a new Board

Once you've decided that you want to create a board of your own, on the Boards page, click "+ New Board" at the top of the left side directory. The new untitled board will be created immediately, but you may wish to give it a name. To do so, click the current title, then type the desired name. At this point, your empty board will look like this:

<Frame>
  <img alt="/11442046149268" />
</Frame>

### Step 3: Adding content to Boards

There are 3 types of content that you can add to a board:

1. An existing report that has already been created
2. A new report that you can make from Insights, Funnels, Flows or Retention
3. A text or media card to give context to your board

<Frame>
  <img alt="/11442000560788" />
</Frame>

There are a few ways to add an existing report to a board. You can either start on a board, and add reports to it directly, or start from a report and choose the boards to which the report should be added.

* Starting from a board, adding a report can be done via the "Add" button near the top right of the board, or if the board is empty, from the center of the page. This will open a popup from which you can choose to create a new report of any type or add an existing report.
* Starting from an existing report, adding the report to a board can be done via the board breadcrumb dropdown at the top left of the report, next to the report's title. Click into the dropdown, then select "Add to another Board." Choose your board, and a copy of the report will be added to it.
* Starting from another board, select the overflow menu of a report you'd like to add. Select "Make a Copy" and then choose the board you would like to add it to.

Note that adding an existing report always creates a [linked copy](/docs/boards/sharing-and-permission#linked-reports).

Text cards support rich text formatting. After highlighting the text in a text card, you'll see a menu pop up where you can apply the following:

* Font size (title, subtitle, text)
* List type (bullets or ordered)
* Bold, Highlight, Italic, Strikethrough, Underline
* Quote block
* Hyperlinks
* Dividers

Note that some options (ordered lists, quote blocks, underline, and dividers) are available in the "three dots" overflow menu on the right-hand side of the formatting popup.

<Frame>
  <img alt="/Screen_Shot_2022-06-15_at_3.32.32_PM.png" />
</Frame>

Media cards support local images and embedded videos. Media cards are able to be resized horizontally or vertically, similar to Report cards.

<Frame>
  <img alt="/Screen_Shot_2022-08-17_at_10.56.02_AM.png" />
</Frame>

For images, the supported upload file types are PNG, JPG and GIF. GIFs will loop automatically. The upload limit is 5MB. For videos, the supported embedded video links are Vimeo, YouTube and Loom. In order for your team to be able to see uploaded videos, ensure that video settings are not set to private. See the following articles to understand video privacy settings:

* [Vimeo's Video Privacy Explain](https://vimeo.com/blog/post/video-privacy-explained/)
* [Share videos with unlisted links with Vimeo](https://vimeo.com/blog/post/share-unlisted-videos-with-private-links/)
* [Change video privacy settings on YouTube](https://support.google.com/youtube/answer/157177?hl=en)
* [How to use Loom's privacy settings](https://support.loom.com/hc/en-us/articles/360016527597-How-to-use-Loom-s-privacy-settings)

### Step 4: Arrange Board Content

#### A Row-Based System

Content is arranged within rows. To add a card (either a report or text) to a row, click the "+" button that appears on the left of a row when you hover over that row.

<Frame>
  <img alt="/Screen_Shot_2022-06-29_at_11.49.22_AM.png" />
</Frame>

To add a row, click the "+ Add Row" button below the last existing row in the board.

<Frame>
  <img alt="/Screen_Shot_2022-06-29_at_11.49.58_AM.png" />
</Frame>

#### Moving Cards

To change the order of reports, simply click and drag any report to your desired position, via the gripper icon at the top right of the report.

#### Resizing Cards

Cards on a row will automatically expand to fill the width of that row, but once two or more cards are on the row, you can adjust each card's width by clicking and dragging the control between any two cards. Hover between the cards to surface the drag control.

<Frame>
  <img alt="/Screen_Shot_2022-06-29_at_11.50.42_AM.png" />
</Frame>

Up to four cards (either reports or text) can exist within a row, and the content in a row will automatically expand to fill the horizontal width of that row. Cards can be horizontally resized within a row, and will snap to positions 1/12th of the width of the row - the minimum width of a card is 3/12th, or one quarter of the width of the row. This makes it easy to fill a row with 1, 2, 3, or 4 cards of equal size.

#### Resizing Rows

Row heights can now be adjusted to either show more report content, or hide empty space. To vertically resize a row, click and drag the control under that row. Hover under the row to surface the control.

<Frame>
  <img alt="/Screen_Shot_2022-06-29_at_11.51.48_AM.png" />
</Frame>

A row's height is initially determined by the tallest card within that row. Text cards can be very short if they contain only one line of text, or very tall if they contain many lines. Meanwhile, reports always start at their minimum height but may warrant expansion in order to show more data (more bars on a bar chart, for example).

A row will start life at the minimum possible height.

### Step 5: Board-wide Date Ranges and Filters

Boards allow you to alter some aspects of the queries within each of the reports on that board, making it simple to ensure every report is showing results from a consistent set of data.  Both date ranges and filters can be added by clicking "Add Filter" at the top right of the board. 

<Frame>
  <img alt="/Screen_Shot_2022-01-07_at_2.35.49_PM.png" />
</Frame>

The date ranges and filters applied to the board are temporary unless saved. This allows you to explore the data without altering the Board for other users.

To make permanent changes to the board filters, use the Mixpanel [Pinned Filters](/changelogs/2025-01-10-pinned-filters), which can be accessed by clicking the overflow menu on the filter and then clicking "Edit". Note that changes are not saved automatically, so make sure to click the "Save" button on the right after editing.

<Frame>
  <img alt="/Board_Pinned_Filters-Edit.png" />
</Frame>

#### **Board Dates**

"Default" means each report uses its own saved date range.

Choosing any other date range at the Board level sets all reports on that Board to use the same date.

Use "Default" when you want reports to show different time windows (e.g., one report showing last 30 days, another showing last 60 days). Set a specific Board-level date range when you want all reports to use the same timeframe, such as from a product launch date.

## Board Subscriptions

Board Subscriptions allow you to receive a snapshot of a board sent as an email or a slack message. Subscriptions allow members to share recent data with both project members and external audiences, providing quick and meaningful insight into a Mixpanel project.

You must be a Project Owner, Admin, or Analyst to create a subscription.

Subscriptions will send the board on a recurring schedule. You can choose a daily, weekly or monthly interval. Note that subscriptions only show the 8 reports that are on the top of a board.

To create a Subscription:

1. Select **Subscribe** from the header at the top right of the board. You can see a list of existing subscriptions for the board here as well. Select "Create New".

<Frame>
  <img alt="/subscribe1.png" />
</Frame>

2. Fill out the resulting form, selecting the desired email recipients or Slack channel, as well as the sending frequency (daily, weekly, or monthly).

<Frame>
  <img alt="/subscribe2.png" />
</Frame>

* Any email address will receive the email, whether or not they are internal or external to your organization
* Private Slack Channels are not available at this time

3. Click "Subscribe".

### Seeing All Subscriptions

<Frame>
  <img alt="/subscribe3.png" />
</Frame>

You can access this by clicking the "Subscribe" button at the top right of the board. Then select "View All". This gives you a view of all subscriptions across all users.

## TV Mode

The **Enter TV Mode** option enables displaying a Board on a big screen (such as a TV in the office) where top-level company metrics / KPIs can be constantly monitored. The Board will auto-refresh every 10 minutes when in TV mode.

<Frame>
  <img alt="image" />
</Frame>

## Deleting Boards

To delete a Board, click the "..." button in the top-right of the UI, then select "Delete". Be aware that any reports that were saved to this Board any any [linked reports](/docs/boards/sharing-and-permission#linked-reports) will be also be deleted once the original Board is deleted.

Learn more about how [Boards are used to manage sharing and permission](/docs/boards/sharing-and-permission) of reports.


# Boards on Boards
Source: https://docs.mixpanel.com/docs/boards/boards-on-boards

Organize your analyses with nested Boards.

For organizations on the enterprise plan, you can nest Boards within other Boards to organize your teams and analyses.

> You must have an active **Enterprise** plan with Mixpanel to access this feature.

### How to nest Boards

To place a Board on Board, you can:

* Drag and drop directly from the side navigation. For permissions, see limitations below.

  <Frame>
    <img alt="nested.gif" />
  </Frame>
* Use the “Move to” option, which is accessible from 3 locations:

  * From the side navigation, click on the 3 dots next to the desired Board name
  * From the current Board that is open, click on the 3 dots in the top right in the header menu

    <Frame>
      <img alt="move.gif" />
    </Frame>
  * If a Board is already on a Board and you’d like to move it elsewhere, you can click on the 3 dots in the card menu of the nested Board

    <Frame>
      <img alt="moveee.gif" />
    </Frame>

To remove a Board from nesting, you can:

* Use the “Move” button and select “Move out of all Boards.”
* Drag the child Board out of the parent in the side navigation.

### Nesting limitations

* The maximum depth of nesting allowed is 3 levels, meaning you can have a grandparent, parent, and child Board.
* No cycles allowed. You cannot nest a Board under its own child Board.

### Permissions

* You must have edit access to the parent Board in order to nest or remove another Board under it. This is similar to reports permissions - you cannot add or remove any report or text from a Board if you don’t have edit access.
* Nesting a Board does not currently affect permissions.

  * This means parent Board permissions will not override the child Board’s permissions.
  * Board level permissions will only cascade for reports on a given Board.


# Move Boards
Source: https://docs.mixpanel.com/docs/boards/move-boards

Reuse Boards across different projects

## Overview

Move helps teams organize their work and easily replicate Boards across projects and organizations. Using Move, you can find a Board you want to copy, duplicate it, and move it to a different project.

Let's take an example situation:

1. An organization has Project A and Project B that support different products and teams within the organization.
2. Team A has some fantastic Boards that have been well received by leadership, executives, and investors.
3. Team B would like to replicate these reports without having to build them all from scratch.

This is where Move comes in. With the right permissions, Team A can move copies of their Boards to Team B's project, allowing Team B to fill in their events and be up and running quickly.

**Please note: Moving boards from projects based in the US -> EU as well as EU -> US is unavailable at this time.**

### Turning Move Off and On

<Note>
  To enable or disable the setting to move board, you will need an admin or own project role. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

1. Go to Project Settings
2. Select Moving Boards from the left hand menu
3. Select how freely you want boards to be able to be moved: not at all, within the organization, or between organizations.

   * Not at all: no Board can be moved to any other project, no matter the organization
   * Within organization: a Board can be moved to any other project in the same organization
   * Any organization: a Board can be moved to any other project, even one in a different organization This setting does not affect whether you can move a Board into a project, only whether you can move a Board out of a project.
4. On this page, you can also see who last updated the permissions and when.

<Frame>
  <img alt="Move-screenshot.png" />
</Frame>

### Using Move

<Frame>
  <img alt="Demo_mv_x_proj.gif" />
</Frame>

Step 1: Go to the Board you wish to move.

Step 2: Hover over the `Move to` option.

Step 3a: Enterprise users: select "projects", then select the specific project that you want to move the board to. Once you've selected a project, then list will populate with Boards you can place the current Board in if you wish.

Step 3b: Non-enterprise users: hover over the "Move To" option, and the project menu will appear immediately. From there, you can choose “Move to your Boards” or another location and select your choice.

Step 3c: You can also use Move to use Boards from a demo project in your own. Get your free Mixpanel demo account and click [here](https://mixpanel.com/api/app/demo_project?show-demo-dataset-modal=true) to access the demo datasets. Once you're in, you can set up a new Board easily using a [template](/docs/boards/templates), or you can build a report from scratch. If you like what you see and want to use the analysis in your own project, you can click the button that says "Use this Board." You'll then select the project to which you want to move the board.

Step 4: If there are events and properties used in the old project but not the new project, the affected reports will remain empty or say “no data” until new events and properties are selected.

When a report can't populate, it will display one of two states: a faded out sample report or a “no data” status.

* Charts that show "no data" occur when an event has been tracked in the last 30 days, but a filter or date range result in no data for the report.
* For the sample report to appear, the report would have to be configured with an event that hasn't existed or at least hasn't been tracked in past 30 days.

For example: a join membership club event happened 100 times yesterday, but 0 so far today. If you create a report for today, it will show “no data”. But if this is day one of the program and it has never been tracked before, it will show a dummy sample report. From this empty state, you can set up your new reports like any other report.

**NOTE:** If you would like a version of the Board to stay in the parent project, duplicate it and move the new duplicate Board.


# Public Boards
Source: https://docs.mixpanel.com/docs/boards/public-boards

Share analyses with stakeholders outside your company

With Public Boards you can now share your favorite Mixpanel metrics across your entire organization — regardless of whether your teammates have a Mixpanel login or not. Show stakeholders your latest insights with the click of a button, collaborate cross-functionally in new, heightened ways, and make better product decisions, faster, with everyone's buy-in.

Want to flex your data outside of your org? No problem. Share it with investors, agencies, customers, or post it on Twitter for all to see. Best of all, with optional password protection, your boards are only as public as you want them to be.

#### Enabling/Disabling For Your Project

Public Boards is **disabled** by default, meaning no one can make a board public without first enabling the feature in [Project Settings](https://mixpanel.com/settings/project). Only Project Owners can enable/disable this feature.

Navigate to the Public Boards tab to enable Public Boards for the project:

<Frame>
  <img alt="/public_db_settings_view.png" />
</Frame>

<Frame>
  <img alt="/Screen_Shot_2021-07-27_at_10.48.08_AM.png" />
</Frame>

To disable, just click the "Disable for Project" button. It will turn off ALL currently publicly shared boards and will disallow the creation of any new ones.

<Frame>
  <img alt="/Screen_Shot_2021-06-09_at_2.50.01_PM.png" />
</Frame>

<Frame>
  <img alt="/Screen_Shot_2021-06-09_at_2.51.08_PM.png" />
</Frame>

#### Creating a Public Link

If the Public Boards feature is enabled for your project, then you can create a Public Link from the Share Modal on the Boards page.

All project users, except project consumers, with edit access to the board can make the board public.

**Important Note:** Public Board Links are created with the context of the Data View in which the link is generated. Make sure to check the Data View you are currently in to ensure it is the one you want to share publicly.

<Frame>
  <img alt="/Screen_Shot_2021-06-09_at_2.54.06_PM.png" />
</Frame>

<Frame>
  <img alt="/Screen_Shot_2021-06-09_at_2.57.00_PM.png" />
</Frame>

**Free Plans:** As Free plans do not have full access to the Sharing Modal, it will look slightly different than that on Paid plans. To make a board public, also click the Share button and switch the "Make Public" toggle on (purple).

#### Management of Public Board Links

To get a view of all current Public Boards links, go to the Public Boards section in [Project Settings](https://mixpanel.com/settings/project). You'll see a list of all boards shared publicly, the Data View to which each Public Link is associated, creator and creation time of the Public Link, and the Public Link URL. You can disable the individual Public Links from this view. You can also disable Public Links at once by turning off the Public Boards feature for the project (see Enabling/Disabling For Your Project).

<Frame>
  <img alt="/Screen_Shot_2021-06-09_at_2.59.53_PM.png" />
</Frame>

#### Password Protection

For additional security, create a password that will be required for anyone viewing your public board.

<Frame>
  <img alt="/Screen_Shot_2021-06-09_at_3.08.09_PM.png" />
</Frame>

Go to the Share Modal > Public Board Details to manage the Public Board's password:

<Frame>
  <img alt="/Screen_Shot_2021-06-09_at_3.06.54_PM.png" />
</Frame>

Check "Require Passcode" to enable password protection for the specific Public Link. The password will be shown only upon creation. If you forget the passcode, you will need to provide a new password.

<Frame>
  <img alt="/Screen_Shot_2021-06-09_at_3.07.27_PM.png" />
</Frame>

<Frame>
  <img alt="/Screen_Shot_2021-06-09_at_3.08.45_PM.png" />
</Frame>

Use the copy button next to the public URL if you want require passcode. Use the Embed Link button to copy the public URL with the passcode embedded.

<Frame>
  <img alt="/Screen_Shot_2021-06-09_at_3.09.17_PM.png" />
</Frame>

#### Embedding Public Boards

Public Boards are embeddable in an iFrame, so you can add them to your docs (Notion, Coda, Confluence, etc.).

If you are requiring a passcode for the Shared Link, please use the Embed Link.

<Frame>
  <img alt="/Screenshot_Capture_-2021-05-06-_13-31-57.png" />
</Frame>

<Frame>
  <img alt="/Screenshot_Capture_-2021-05-06-_13-31-32.png" />
</Frame>

<Frame>
  <img alt="/embed.gif" />
</Frame>


# Sharing 
Source: https://docs.mixpanel.com/docs/boards/sharing-and-permission



<Note>
  Growth and Enterprise plan users can control who views and edits reports in a board. Free plan users have view and edit permissions for all boards and reports in a project. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

Reports are always saved to boards. When you save a report, you'll be prompted to save it to a specific board. In essence, the board now acts as a folder, with many potential purposes, including:

* A centralized place to track numerous metrics related to a product launch
* A chain of analyses digging into a particular behavior or issue
* A set of draft reports you're working on

This will make it easy to keep reports organized, and reduce time wasted recreating the same reports again and again.

## Sharing

Every Boards is accessible by all project members. Board-level sharing settings control how Boards are surfaced in Mixpanel and who can edit.

Sharing is done at the board level. All reports saved on a board inherit the same sharing settings of that board. To share a board, click the Share button at the top right of the board.

<Frame>
  <img alt="/GIF3__light_.gif" />
</Frame>

You can set access for specific individuals, Teams, and everyone in the project.

**Individuals and Teams Sharing:**

* Viewers: Board discoverable in Mixpanel search. Any changes Viewers make will not be saved
* Editors: Able to make and save changes to the Board

**Project Sharing:**

* Off: The Board does not surface in Mixpanel for users who are not Viewers or Editors of the Board. Note, even when project sharing is Off, any project member with the direct link can still view the Board
* Viewer: Board discoverable in Mixpanel. Any changes Viewers make will not be saved
* Editor: Able to make and save changes to the Board

The **Copy URL** button copies a short link to a Board or report. Anyone with the link who has access to the project can open it. What they can do is always governed by the permissions above.

<Frame>
  <img alt="/Screen_Shot_2021-11-08_at_11.01.00_AM.png" />
</Frame>

If a Board contains sensitive data, restrict access to the underlying data through [Data Views and Data Classification](https://docs.mixpanel.com/docs/data-governance/data-views-and-classification).

Default settings for project sharing can be set by admins in Project Settings.

## Linked Reports

Every report in Mixpanel has a board where it was originally saved to. This is called the original board. However, in the interest of being able to use the same report across a variety of boards and sharing the same insight across your team and company, Mixpanel has introduced the concept of a "linked report". A linked report is denoted by the arrow in the icon of the report. Any time an existing report is added to a board or a copy is made, a linked report is made. Any changes to the report will get reflected in all of the linked reports associated with the report.

<Frame>
  <img alt="/Screen_Shot_2022-07-11_at_6.06.58_PM.png" />
</Frame>


# Templates
Source: https://docs.mixpanel.com/docs/boards/templates

Generate a board using customizable templates

<Frame>
  <video>
    <source type="video/mp4" />
  </video>
</Frame>

Mixpanel’s Templates make it simple for anyone to get answers to important questions as soon as data is available in Mixpanel. Our templates create out-of-the-box and fully customizable Boards designed to guide you section by section. They help you better understand your user base and monitor metrics like adoption, retention, virality, and product impact.

To get started, click the icon in the left-hand navigator to create a new Board, and select `Use a Template`. You’ll then select your desired template and click `Start from Template`.

## Adding Your Events

The Company KPI template uses two events: “Sign Up” and “Value Moment.”

* [Sign Up](https://developer.mixpanel.com/docs/plan-your-implementation#sign-up-event): Select the event where a new user—free or paid—is acquired by creating a new account. For products that do not include an account creation step, a similar “[Session Start](https://help.mixpanel.com/hc/en-us/articles/115004695223)” event can be used as a proxy.
* [Value Moment](https://developer.mixpanel.com/docs/plan-your-implementation#value-moment-event): Select an event that indicates that a user is experiencing value in your product. For a social media platform, it could be creating a post; for a streaming service, it's watching a video; for e-commerce, it might be completing a purchase.

The Lifecycle cohort analysis template uses one event: “Value Moment.”

* [Value Moment](https://developer.mixpanel.com/docs/plan-your-implementation#value-moment-event): Select an event that indicates that a user is experiencing value in your product. For a social media platform, it could be creating a post; for a streaming service, it's watching a video; for e-commerce, it might be completing a purchase.

The Feature Launch template uses four inputs, two of which are events: “Feature Name,” “Launch Date,” “New Feature,” and “Value Moment.”

* Feature Name: Whatever you want to name your feature. It will be populated throughout the template so we recommend something on the shorter side. Including the feature name will help you better keep track of your Boards when you have multiple feature launches.
* Launch Date: Choose the date your feature went live. Some reports show the percentage of active users engaging with the feature, so be aware that if you’re doing a partial rollout, those numbers might be skewed, as the report will be using your total active user base.
* New Feature: Pick an event that captures the adoption of your new feature. For adding reviews to a streaming service, the event could be publishing a review. For e-commerce, it might be creating a “save for later” collection.
* [Feature Value Moment](https://developer.mixpanel.com/docs/plan-your-implementation#value-moment-event): Select an event that indicates that a user is experiencing value in your feature. For a social media platform, it could be liking a new type of content; for a streaming service, it could be sharing a playlist; for e-commerce, it might be purchasing from the “save for later” collection.

The AI Company KPI template uses several events and properties:

* Sign Up: An event triggered the first time a user is identified in your system, typically upon account creation or registration.
* Launch AI: An event triggered when a user first begins interacting with an AI feature, such as opening a chatbot interface or engaging a virtual assistant.
* AI Prompt Sent: An event recorded each time a user submits a prompt or query to an AI system. Include the prompt content as a property.
* AI Response Sent: An event triggered when the AI system sends a response back to the user. Include properties such as api token usage (API Tokens Used), estimated cost (API Cost), and latency (API Response Time).
* API Error: An event that logs runtime errors encountered by the AI feature or its underlying APIs during user interaction. This should capture relevant error metadata for diagnostics.
* User Feedback Submitted: An event triggered when a user provides feedback on an AI-generated response. Include properties for the Feedback Text and Sentiment, which could be structured (e.g., thumbs up/down) or unstructured (e.g., free-text).
* AI Dismissed: An event triggered when a user ends their interaction with an AI feature, such as closing a chatbot or exiting an assistant interface.
* [Conversion Event](https://developer.mixpanel.com/docs/plan-your-implementation#value-moment-event): Select an event that indicates that a user is experiencing value in your feature. For a social media platform, it could be liking a new type of content; for a streaming service, it could be sharing a playlist; for e-commerce, it might be purchasing from the “save for later” collection.

For projects that have already been implemented and have data, you will select your events, which will enable the `Create` CTA, and your Board will be generated.

For projects that do not have data, please refer to our [dev docs](https://developer.mixpanel.com/docs/plan-your-implementation) and [implementation](https://help.mixpanel.com/hc/en-us/categories/115001197206-Data-and-Implementation) resources.

## Key Metrics

These templates monitor a number of metrics for you. A few are highlighted below.

### Engagement

User engagement measures how users find value in a product or service. Engagement can be measured by a variety of activities such as clicks, shares, and more. Highly engaged users are more likely to lead to higher user growth because they are more likely to share the product or service with their network. Tracking engagement helps evaluate:

* How many users are finding value in your product?
* Who are your most engaged users?
* What is your product’s activation rate?
* What happens to users who don’t reach your product’s value moment?

### Retention

Retention is the metric that shows whether your product has staying power. Retention measures how many people are coming back, which is also a key indicator that users are realizing value in your product. Tracking retention helps identify:

* How many engaged users come back?
* Who are your dormant users?

### Growth

Growth is about finding people who need your product and showing them that your product can bring value to them. Tracking growth helps you answer:

* How many new users are signing up?
* Which channels are generating the most signups?
* What is your DAU (Daily Active Users) and WAU (Weekly Active Users)?

### Adoption

Feature adoption is when a customer actually uses your feature. It could be purchasing an add-on, leaving a review, saving a video to a collection, or even using a new template. Tracking your feature adoption helps you answer questions like:

* How many users used the new feature this month?
* What percentage of my users have used the new feature?
* How many times do users use the new feature in a month?

### Product Impact

Product impact metrics give you a full look at how your feature is helping or hurting your overall product. At the end of the day, every feature should be working to drive growth to the product. The product impact metric can help you evaluate:

* Is this feature’s adoption driving product growth?
* Is this feature’s engagement hurting another part of the product?
* Is this feature increasing product retention?

### User Base

The Lifecycle Cohort Analysis Template breaks down your user base into the parts that make up the active user calculation:

* New users: user who performed the value moment action for the first time ever during the current period
* Retained users: user who performed the value moment action this current period and the previous period
* Resurrected users: user who has performed the value moment before, didn't perform it last period, but performed the value moment again this current period

## Other Examples

In this section, you will find other example Boards built out in our demo data sets to highlight examples of how our most successful and data-mature customers monitor their implementation and drive adoption of Mixpanel across their organizations. The examples in this section are meant to be used as inspiration for additional Boards you can create to make sure your team is effectively monitoring your implementation as well as enabling end users to feel confident implementing and using Mixpanel.

### Implementation Monitoring & Data Governance

This template is meant to be used largely by teams that implemented Mixpanel instrumentation and will be monitoring the data governance of the implementation on an on going basis. The two sections in the Board cover best practices for:

* Monitoring the health of your implementation and nuances to look out for that could be a sign of poor implementation health.
* Driving consistency in naming convention best practices and a better general understanding of how to manage data governance of your Mixpanel implementation

[Implementation Monitoring & Data Governance Example Board Here](https://mixpanel.com/project/3018488/view/3536632/app/boards/#id=6664368)

<img alt="Implementation Monitoring and Data Governance" />

### Training Board for Champions to use to Educate Users

This template is meant to be used by Mixpanel Champions looking to train their team on what metrics they can report on out of Mixpanel. The three main sections of the board are:

* An overview of the Mixpanel Data Model and tips for how to familiarize yourself with your Mixpanel project
* Summaries of each core Mixpanel report (Insights, Funnels, Flows, & Retention) and clear examples articulating which Mixpanel reports/features users can leverage given the type of metric on which they’re wanting to report.
* Links to support articles so users can self-serve education on nuances of Mixpanel’s functionality

[Training Board for Champions Example Here](https://mixpanel.com/project/3018488/view/3536632/app/boards#id=7198653)

<img alt="Training Board for Champions to use to Educate Users" />

### Data Troubleshooting Guide for End Users

This template is meant to be used as a guideline for us to follow if we discover anything unusual about the data. The goal is that end users in Mixpanel are able to correctly identify whether there is an issue with the data or a misunderstanding in Mixpanel functionality, and if there is an issue, notify the appropriate team and individual.

When we find something strange about the data, we can classify it as a **Mixpanel functionality question** or an **implementation issue**.

Below are various examples of some common questions or issues that Mixpanel end users face - especially when they weren’t involved in the initial data design & implementation - and what can users do to troubleshoot

* Is the property typecast to the wrong data type?
* What does it mean that the property value is `(not set)`?
* What are the properties available in each event?
* Who should I talk to about reporting questions and Mixpanel UI misunderstandings?
* Who should I report a data issue or bug to?

[Data Troubleshooting Guide Example Here](https://mixpanel.com/project/3018488/view/3536632/app/boards#id=6664372)

<img alt="Data Troubleshooting Guide for End Users" />


# Business Context
Source: https://docs.mixpanel.com/docs/business-context

Help your AI assistant understand your business

Business Context is markdown text that AI assistants read through MCP to ground their answers in your organization's structure and goals. Add context at the organization level (who you are as a company) and at the project level (how a specific project is set up).

When an AI assistant connected to your [Mixpanel MCP server](/docs/mcp) starts a session, it pulls the relevant business context first — so it knows your north star metric, what a "qualified user" means in your data, which project to default to, and the conventions your team uses. The result: less back-and-forth defining terms, more answers grounded in how you actually run your business.

## Levels of Context

Mixpanel supports two levels of business context. AI assistants read whichever is relevant to the project they're working in.

| Level            | What to include                                                                              | Who can edit              |
| ---------------- | -------------------------------------------------------------------------------------------- | ------------------------- |
| **Organization** | Company background, business model, north star metrics, customer segments, internal acronyms | Organization admins       |
| **Project**      | Events, properties, naming conventions, key dashboards, team norms, default project hints    | Project owners and admins |

A typical setup uses both: org context tells the AI what business you're in, and project context tells it how this specific project tracks data.

## Edit Organization Context

Organization-level context applies to every project in your org and is shared across everyone who connects via MCP.

1. **Open Organization Settings**, then go to **Settings → Org → Business Context**.
2. **Write your context** in the markdown editor. Aim for short, structured notes — what your business does, how you measure success, the language your team uses internally.
3. **Click Save.** The context becomes available to AI assistants on their next MCP session.

<Frame>
  <img alt="Organization Business Context settings with a markdown editor describing a business model and product features" />
</Frame>

<Note>
  Only **organization admins** can edit organization-level context. Other users in your org will see the context but won't be able to modify it.
</Note>

## Edit Project Context

Project-level context describes how an individual project is structured — its events, conventions, and the people working in it.

1. **Open the project** you want to add context to.
2. **Go to Settings → Project → Business Context**.
3. **Write your context** in the markdown editor.
4. **Click Save.**

Project owners and admins can edit project context. Anyone with project access can read it.

## What to Include in Project Context

Good project context covers what an AI assistant would otherwise have to guess at. Useful sections include:

* **Product overview** — what the project tracks and the main user actions
* **Event taxonomy** — naming conventions, what each major event represents
* **Property conventions** — units, formats, what specific properties mean
* **Key dashboards** — where to find canonical reports for common questions
* **Team norms** — how you define active users, churned users, qualified leads, etc.
* **Operating shortcuts** — "MCP usage data lives in the Infra Metrics project", "use the v2 cohort for marketing analyses"

Keep it focused. AI assistants pull this context on every relevant request, so longer context means slower responses and higher token cost.

## Edit Context via MCP

Any AI assistant connected to your [Mixpanel MCP server](/docs/mcp) can read and update business context using two tools:

| Tool                      | Description                                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `Get-Business-Context`    | Returns the business context for the organization, optionally combined with the context for a specific project. |
| `Update-Business-Context` | Replaces the business context at the organization or project level.                                             |

Ask your AI assistant in plain language:

* *"Add to project context: events prefixed with `srv_` are server-side. Client-side events have no prefix."*
* *"Update org context to note that our north star metric is weekly active analyzers, not daily active users."*
* *"What context do you have on this project? Suggest improvements based on what you've learned about the data so far."*

<Frame>
  <img alt="Claude using the Get-Business-Context tool from the Mixpanel MCP integration to answer a question about which metrics to prioritize" />
</Frame>

<Warning>
  Updating context via MCP performs a **full replace** — the new content overwrites whatever existed before. Other people on your team may have authored the current context, so always have your AI assistant confirm what's there before overwriting.

  `Update-Business-Context` will fail with a permission error if your account doesn't have edit access to the org or project you're updating.
</Warning>

## Limitations

* **Markdown only** — context must be plain markdown text. Images, structured data, and links inside the context aren't fetched or rendered for the AI assistant.
* **Full-replace updates** — `Update-Business-Context` overwrites the entire context at the level you target. There is no append or merge mode.
* **Edit permissions** — organization context can only be edited by organization owners and admins. Project context can only be edited by project owners and admins. Anyone with project access can read both.
* **Size limit** — each context (organization and project) is capped at 50,000 characters.

## FAQ

#### Who can read business context?

Anyone in your organization with access to a project can read the context for that project, and the org context that applies to it, through MCP or in Mixpanel Settings. Permissions match your existing project permissions.

#### Does business context get sent to my AI provider?

Yes. When your AI assistant fetches business context via MCP, that content is sent to whichever AI provider you're using (Claude, ChatGPT, etc.) as part of the conversation. Avoid putting credentials, customer PII, or other sensitive information in your context.

#### Can I generate project context automatically?

Not yet from the in-product UI. For now, write context manually based on what your AI assistant most often needs to know about your project.

#### How do I clear context?

Either delete the text in the Settings editor and save, or ask your AI assistant to call `Update-Business-Context` with an empty string at the level you want to clear.

#### How does Mixpanel Agent decide to use Organization or Project level context?

Mixpanel Agent looks at both. Project context is meant to refine Organization context. If there are contradicting details in Project and Organization context, then Mixpanel Agent will give preference to Project context. If there are complementary details (e.g. Org defines terms, Project adds specifics), then the Agent uses both together.


# Cohort Sync
Source: https://docs.mixpanel.com/docs/cohort-sync



## Overview

Cohort Sync is a feature in Mixpanel that allows you to export dynamic groups of users (called [Cohorts](/docs/users/cohorts)) who meet specific behavioral or property-based criteria, to external tools and platforms. This enables you to seamlessly connect your analytics insights with marketing automation, engagement, and advertising platforms such as Braze, Facebook Ads, Google Ads, and more.

With Cohort Sync, you can:

* Automatically and continuously sync user cohorts to third-party destinations, ensuring that your external tools always have the most up-to-date audience segments.
* Choose from various sync cadences, including one-time, scheduled (hourly or daily), and real-time syncs, depending on your use case and the requirements of the destination platform.
* Use these synced cohorts for targeted messaging, re-engagement campaigns, lookalike audience creation, and personalized user experiences in downstream platforms.
* Reduce manual effort and maintenance, as the sync process is automated and updates as users enter or exit the cohort in Mixpanel.

The value of Cohort Sync lies in its ability to bridge analytics and action: you can quickly act on user insights by targeting the right users in the right channels, improving campaign effectiveness and operational efficiency. This integration is especially useful for marketing, product, and growth teams who want to leverage behavioral data for personalized outreach and engagement without manual data exports or engineering support

## Using Cohort Sync

### Establishing Connection

Before you can use Cohort Sync to export Mixpanel cohorts, you must establish a connection between Mixpanel and your Cohort Sync destination. Mixpanel integrates natively with several third-party destinations (such as Segment and Braze). If you need to sync cohorts to a different destination, you can use Custom Webhooks to export cohort payloads to any destination of your choice.

Refer to the Cohort Sync Destination Directory below for partner-specific setup guides, or use the Custom Webhooks guide to export cohorts to destinations without a native integration.

<CardGroup>
  <Card title="Cohort Sync Destinations Directory" href="/docs/cohort-sync/integrations" />

  <Card title="Custom Webhooks" href="/docs/cohort-sync/webhooks" />
</CardGroup>

### Initialize Cohort Sync

Once a connection has been established between your Mixpanel project and your Cohort Sync destination/Webhooks, you can initialize a cohort sync export. The Destinations page is now the primary way to manage cohort syncs; the Lexicon flow is still available.

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    <Steps>
      <Step title="Navigate to 'Data' in the nav bar and select 'Destinations'" />

      <Step title="Find the connected destination in the list and click on it" />

      <Step title="Click the 'Syncs' tab, then click 'Add Cohort Sync'" />

      <Step title="Select the cohort you want to sync and configure the sync">
        Choose a one-time export or a recurring export. Learn more about the [types of syncs](/docs/cohort-sync/webhooks#sync).
      </Step>
    </Steps>
  </Tab>

  <Tab title="From Lexicon">
    <Steps>
      <Step title="Navigate to Lexicon and select 'Cohorts' in the left-hand sidebar" />

      <Step title="Click the &#x22;...&#x22; button next to the Cohort you want to sync, and select &#x22;Export to...&#x22;" />

      <Step title="Select one of your connections to open the export modal" />

      <Step title="Choose a one-time export or a recurring export">
        Learn more about the [types of syncs](/docs/cohort-sync/webhooks#sync).
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Limits

<Note>
  Only customers on a paid plan can save cohorts; therefore, the cohort sync feature is available exclusively to paid plan customers.
</Note>

Each project is limited to 60 dynamic (recurring) cohort syncs across all destinations. This limit helps ensure that syncs are fast and reliable. We recommend pruning older unused syncs to stay within the limit. There are no limit on the number of cohorts for static, or 1-time, syncs.

When exporting, each cohort is limited to 10 million users. We do this to keep syncs real-time and to avoid overloading downstream tools. If you exceed the limit, we recommend that you add a filter to the cohort to narrow the criteria, or break up the cohort into multiple cohorts and create multiple syncs.

The exported user data is limited to the following properties:

```text theme={"system"}
$distinct_id
$first_name
$last_name
$partner_user_id
$email
$phone
```

If these properties are not present in your project, users might not be matched in the systems. If an integration partner doesn't use a property to match, it is dropped before ingestion. Please refer to the individual Cohort Sync Help Center pages for the behavior for specific partners.

The email address and phone number properties will only show in the manual CSV exports for Google Ads and Facebook integrations.

<Note>
  Exporting group-level cohorts (Group Analytics) is not currently supported.
</Note>

## Troubleshooting

Sometimes, you may find that the number of users shown in your cohort in Mixpanel does not reflect the number of users in the integration partner's interface. Please see below what could be causing this and how you can find out which users were successfully exported from Mixpanel.

### Discrepancies in user count

If you see a discrepancy between the count of your users in a Mixpanel cohort and in the integration partner, the first thing to check is if all your users were eligible to be exported. To match users in both systems, we require a partner ID, e.g. `$braze_external_id` for Braze cohort exports. You can easily confirm this by querying for your cohort in the User report, then adding the filter `$braze_external_id` is set. This will show all eligible users that can be exported from Mixpanel to Braze.

When accessing the "View in Explore" option, you will see the required partner ID added by default for the following integrations:

ABTasty, Airship, Blitzllama, Braze, Clevertap, Flagship, Insider, Iterable, Kameleoon, LaunchDarkly, Leanplum, Moengage, OneSignal, Optimize, Pushwoosh, SalesforceMC, Segment, VWO, Xtremepush

It is also added by default to any integration where the join key is not the \$distinct\_id. The added partner ID filter will show up as a [custom property](/docs/features/custom-properties) called "Defined Properties Required for Cohort Selection" whose properties will appear when hovering over the property:

<Frame>
  ![image](https://user-images.githubusercontent.com/13734965/233539618-3ac2c97e-d3fd-4c44-8dc3-847ecdfe50bb.png)
</Frame>

### Inspect exported cohorts via CSV download

To find out which and how many users have been exported from your cohort to the integration partner, you can now download a CSV containing all users that have been exported. When accessing the cohort export overview by navigating to the integration in your Destinations page, then clicking on the cohort, you will be navigated to this overview:

<Frame>
  ![image](https://user-images.githubusercontent.com/13734965/233539646-5057fdb4-5c15-412a-8390-1bed8d44f136.png)
</Frame>

You will find a summary of the total count of users exported and removed and a CSV download button. In the CSV, you can find the list of distinct\_ids of the users in the export and an operation column. This operation column can contain one of three values; add when the user profile was newly added to the cohort, remove when the user was removed from the cohort and no-op when the user remains in the cohort. In the column next to the distinct\_id, you will see the partner ID for that user. If the numbers between Mixpanel and the integration partner mismatch, you can confirm if a user has been exported by looking at the CSV file.

### Export is paused

If you notice your cohorts are not being exported, you can view the reason for the pause in your Destinations page. When accessing the integration, you will see the status (either Active or Paused). If the status says Paused, you can hover over the Paused text to see the reason for the pause:

<Frame>
  ![image](https://user-images.githubusercontent.com/13734965/233539691-d36370b1-880a-4aa6-a64c-399175c02388.png)
</Frame>

Some integrations have common pause reasons (e.g. [Facebook's authentication pause](/docs/cohort-sync/integrations/facebook-ads#troubleshooting-errors)). You can usually resolve the paused reason on your side by confirming the authorization for the integration is still valid, and dis- and reconnecting.

### View sync error

To find more details on Failure errors, you can click in the Cohort within the Destinations page to display errors.

1. Under the integration section, select the cohort:

<Frame>
  ![image](https://user-images.githubusercontent.com/13734965/233539867-3bd94f9f-b50c-4939-9eb9-5879e0b2e8cf.png)
</Frame>

2. If an error is available, you will see the “View Error” button:

<Frame>
  ![image](https://user-images.githubusercontent.com/13734965/233539900-58b14423-bdfd-4fb7-98ff-17576d54a5d8.png)
</Frame>

3. Click on the “View Error” button to get more details.

Currently the “View Error” button will only display if there is an error available. In the case that you do not see a “View Error” button but the sync did not finish successfully, you can reach out to the Support team to help get more details on the error.

### Delay in Sync

If your recurring cohort syncs are taking more time than expected, we recommend creating multiple connections and spreading your syncs across them. Cohort syncs under one connection are executed in a sequential order; to increase parallelism, you should create multiple connections covering different types of sync.

In general, if you see the cumulative user count of all cohorts synced under a connection breach \~5 million, we would recommend that you create a new connection.

<Frame>
  <img alt="image" />
</Frame>


# Partners: Build a Cohort Sync Integration with Mixpanel
Source: https://docs.mixpanel.com/docs/cohort-sync/build-an-integration



Building an integration with Mixpanel is a powerful way to provide value to your customers that also use Mixpanel. If your company is interested in becoming a Certified Technology Partner, building an integration is also the first step.

## Setting up a Sandbox

Sign up for a [free Mixpanel account](https://mixpanel.com/pricing), which you can use as a sandbox when building and testing your integration.

## Create an Integration ID

In order to properly understand API usage and provide you with resources as part of our Technology Partner Program, you must first define your **Integration ID** and pass it along when sending event data or calling Mixpanel’s APIs.

Your Integration ID should be a string representing your company’s or solution’s name. If Mixpanel were a developer, our Integration ID would be “mixpanel”.

Note: Always include your integration ID -- this will help customers better understand the source of their event data in Mixpanel.

### Event Tracking

For event data, you will include your Integration ID as the `$source` property value.

This can be added to the [Event Object](doc:data-model-deep-dive#anatomy-of-an-event)  when using the [Ingestion API](/reference/ingestion-api):

```json theme={"system"}
{
    “event”: “Sign up”,
    “properties”: {
        “distinct_id”: “123”,
        “time”: 1321499371,
        “$source”: “your_integration_id”,
        “token”: “<YOUR_PROJECT_TOKEN>”
    }
}
```

### API Usage

If you choose to leverage our APIs for your integration, you must pass along your Integration ID with every API as the **X-Mixpanel-Integration-ID** header value.

```sh theme={"system"}
curl --request GET \
  --url https://mixpanel.com/api/app/projects/12345/schemas/event/my_event/1-0-0 \
  --header ‘accept: application/json’ \
  --header ‘X-Mixpanel-Integration-ID: your_integration_id’
```

## Integration Opportunities

### Connect to Mixpanel's EU Servers

Give your customers the option to send data to [our EU servers](/reference/overview) when they activate your Mixpanel integration.

### Receive Cohort Syncs from Mixpanel

Use this [webhook spec](/docs/cohort-sync/webhooks) to process inbound cohorts Mixpanel syncs to your product, allowing your customers to engage more effectively with the right users at the right time. **Note**: This spec is intended for partner SaaS companies looking to build integrations with Mixpanel. If you are yourself a Mixpanel customer looking to query on Cohorts, refer to the [cohorts query API](/reference/cohorts-list).

### Auto-populate Experiments

If you are offering experiments or A/B tests to your customers, add support for [auto-populating our Experiments report](/docs/experiments) to your integration in order to reduce time-to-value for our mutual customers.

### Sync your Schemas

Sync your internal data dictionary or tracking plan with Mixpanel using the [Lexicon Schemas API](/reference/lexicon-schemas-api). Schemas that you upload will be used to populate Lexicon and provide additional context for your data across the query UI.

# Make your Integration Successful

### QA your Code

For integrations sending events to Mixpanel, our [Events page](https://mixpanel.com/report/events) can be a great way to test if everything is working as expected.

### Document Your Integration

Customer-facing documentation that explains, which use cases your integration helps to solve and how to set it up, will increase the utilization of your integration.

### Get Listed on mixpanel.com

Finally, submit your integration to [create a listing](https://mixpanel.com/partners/integrations/get-listed/form) on our Integrations Directory and to let our customers discover your solution and the integration.


# Destinations
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations

Export your cohorts to a third-party tool

<Note>
  This page highlights integrations that sends Mixpanel Cohorts to external destinations. Learn more about [integrations that imports data from other destinations into Mixpanel](/docs/tracking-methods/integrations) and [integrations that exports data from Mixpanel to data warehouses](/docs/data-pipelines/integrations/).
</Note>

These integrations allow you to send your [Cohorts](/docs/users/cohorts) to other destinations for audience targeting. You may review our complete integrations directory [here](https://mixpanel.com/partners/integrations). If you don't see what you're looking for [reach out to us](https://mixpanel.com/get-support).

## Featured Destinations

<CardGroup>
  <Card title="AB Tasty" href="/docs/cohort-sync/integrations/abtasty" />

  <Card title="Airship" href="/docs/cohort-sync/integrations/airship" />

  <Card title="Appcues" href="/docs/cohort-sync/integrations/appcues" />

  <Card title="Apptimize" href="/docs/cohort-sync/integrations/apptimize" />

  <Card title="Braze" href="/docs/cohort-sync/integrations/braze" />

  <Card title="Chameleon" href="/docs/cohort-sync/integrations/chameleon" />

  <Card title="CleverTap" href="/docs/cohort-sync/integrations/clevertap" />

  <Card title="Facebook Ads" href="/docs/cohort-sync/integrations/facebook-ads" />

  <Card title="Google Ads" href="/docs/cohort-sync/integrations/google-ads" />

  <Card title="Insider" href="/docs/cohort-sync/integrations/insider" />

  <Card title="Intercom" href="https://www.intercom.com/help/en/articles/299-import-your-mixpanel-contacts" />

  <Card title="Iterable" href="/docs/cohort-sync/integrations/iterable" />

  <Card title="Kameleoon" href="/docs/cohort-sync/integrations/kameleoon" />

  <Card title="Leanplum" href="/docs/cohort-sync/integrations/leanplum" />

  <Card title="Mailchimp" href="/docs/cohort-sync/integrations/mailchimp" />

  <Card title="Marketo" href="/docs/cohort-sync/integrations/marketo" />

  <Card title="MoEngage" href="/docs/cohort-sync/integrations/moengage" />

  <Card title="mParticle" href="/docs/cohort-sync/integrations/mparticle" />

  <Card title="OneSignal" href="/docs/cohort-sync/integrations/onesignal" />

  <Card title="Salesforce Marketing Cloud" href="/docs/cohort-sync/integrations/salesforce-marketing-cloud" />

  <Card title="Segment" href="/docs/cohort-sync/integrations/segment" />

  <Card title="Taplytics" href="/docs/cohort-sync/integrations/taplytics" />

  <Card title="VWO" href="/docs/cohort-sync/integrations/vwo" />

  <Card title="WebEngage" href="/docs/cohort-sync/integrations/webengage" />

  <Card title="Xtremepush" href="/docs/cohort-sync/integrations/xtremepush" />
</CardGroup>


# AB Tasty
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/abtasty



## Overview

The Mixpanel and AB Tasty integration provides a bidirectional data sync, allowing you to export Mixpanel cohorts to AB Tasty for precise experiment targeting and import AB Tasty experiment data into Mixpanel for comprehensive behavior analysis. This seamless exchange enhances your ability to analyze, segment, and personalize user experiences.

## Permissions

To set up this integration, the following permissions are required:

### Mixpanel Permissions:

* Service Account Access: You will need a Mixpanel Service Account with permissions to read and manage cohorts.
* Project Token: Ensure you have access to the Mixpanel Project Token for the relevant project.

### AB Tasty Permissions:

Admin Access: You need admin-level permissions in AB Tasty to configure and enable integrations.

## Enable the Integration

### Mixpanel Setup

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select AB Tasty, and click Connect.
3. To set up the AB Tasty integration, you need to enter your account’s API Key. Copy and paste the API Key of your AB Tasty account. Click Continue.

### In AB Tasty

1. Access Integrations > Integration Hub.
2. Search for and select Mixpanel.
3. Click Setup connector.
4. Give a name to your connector so you can easily retrieve it.
5. Click Save and create connector.

## Export Cohorts from Mixpanel to AB Tasty

To export the cohorts to AB Tasty, follow the steps below:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the AB Tasty destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click the three-dot icon on the right side of the cohort.
    3. Click Export to > AB Tasty. Select either one-time sync or dynamic sync. Click Start Sync.
  </Tab>
</Tabs>

AB Tasty Documentation on cohorts exports from Mixpanel is [here](https://support.abtasty.com/hc/en-us/articles/7305491216924-Mixpanel)

* Mixpanel sends the cohorts every 15 minutes in case of recurring exports
* AB tasty pushes the abtasty\_visitor\_id to Mixpanel, and Mixpanel includes it in the cohort export. The abtasty\_visitor\_id is used to match the user.
* For the cohorts to be used in AB Tasty’s segment builder (once exported from Mixpanel), we need to match at least one user i.e. empty cohorts will not be displayed in the segment builder.

## AB Tasty Events in Mixpanel

Analyze your AB Tasty experiments in Mixpanel with a powerful, streamlined workflow. By creating two simple custom properties and configuring your project's Experiment Settings, you can access AB Tasty data in dropdowns, breakdowns, and experimentation reports. This one-time setup eliminates the need for complex, report-by-report data parsing and unlocks a more powerful and consistent way to measure the impact of your A/B tests.

### How AB Tasty Data Arrives

When the integration is active, AB Tasty sends a single event to Mixpanel named `"Event"` for users exposed to a test. This event contains one property, `"AB Tasty"`, which holds a concatenated string of the campaign and variation IDs. For example: `[12345]My Homepage Test[67890]Variation B`.

### Step 1: Create Campaign and Variation Custom Properties

Before configuring the Experiment Settings, you must first parse the campaign and variation names from the `"AB Tasty"` property into their own dedicated custom properties.

Navigate to **Lexicon** in your Mixpanel project and create the two custom properties below.

#### A. Campaign Custom Property

<Frame>
  ![Screenshot 2025-06-17 at 1 49 40 PM](https://github.com/user-attachments/assets/add85567-80d5-4a11-b05c-0934a5365b28)
</Frame>

This property uses a REGEX function to extract the campaign name.

1. **Create a new Custom Property.**
2. Name it. `AB Tasty Campaign Name` is recommended, but the name does not need to exactly match this format.
3. Use the following formula:

   ```text theme={"system"}
   REGEX_EXTRACT(properties["AB Tasty"], "^\\[\\d+\\](.*?)(?=\\[\\d+\\])", 1)
   ```
4. **Save** the property.

> **How it works:** This formula reads the `"AB Tasty"` property and extracts only the text that exists *between* the first and second ID brackets (e.g., `[12345]` and `[67890]`).

#### B. Variation Custom Property

<Frame>
  ![Screenshot 2025-06-17 at 1 49 16 PM](https://github.com/user-attachments/assets/fd48158a-a436-48bc-9d2b-f4cb9931f2e6)
</Frame>

This property uses a nested SPLIT function to isolate the variation name.

1. **Create another new Custom Property.**
2. Name it. `AB Tasty Variant Name` is recommended, but the name does not need to exactly match this format.
3. Use the following formula:

   ```text theme={"system"}
   SPLIT(SPLIT(properties["AB Tasty"], "[", 3), "]", 1)
   ```
4. **Save** the property.

> **How it works:** This formula first splits the full string by the `[` character to isolate the end of the string, and then splits that result by the `]` character to capture only the variation name.

### Step 2: Configure Project Experiment Settings

With your Custom Properties created, you can now tell Mixpanel how to recognize your AB Tasty experiments.

<Frame>
  ![image](https://github.com/user-attachments/assets/4384ed79-79d8-4035-8ffe-35550a0835e1)
</Frame>

1. Navigate to your **Project Settings**.
2. Scroll to the **Experiment Event Settings** section.
3. Define the mapping for your AB Tasty experiments:

   * **Experiment Event**: Select the `"Event"` event.
   * **Experiment Name**: Map this to your new custom property, `AB Tasty Campaign Name`.
   * **Variant Name**: Map this to your new custom property, `AB Tasty Variation Name`.
4. **Save** your settings.

### The Result: Powerful, Automated Analysis

Once saved, Mixpanel will automatically process all incoming AB Tasty data according to your settings. You can now analyze your experiments without any further configuration.

This provides several key advantages:

* No more ad-hoc filtering or complex formulas in your reports.
* Consistent, reliable analysis across all of your AB Tasty experiments.
* Unlock the full power of Mixpanel's Experimentation features, including significance testing and impact on multiple goals.


# Airship
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/airship



## Overview

The Airship integration with Mixpanel allows users to export Mixpanel cohorts into Airship. This updates the Mixpanel Tag Group in Airship, allowing you to target specific Mixpanel cohorts using Airship. Mixpanel cohorts can be exported to the Airship Tag Group once, or the cohort data can sync dynamically and update the Tag Group every 15 minutes.

## Permissions

You must be a Mixpanel project admin to enable the Airship integration.

If the setting below is enabled in Airship, you will see the error "Master secret required to set tags on Tag Group mixpanel" in Mixpanel. Work with Airship to disable this setting so Mixpanel can update the Airship tag group.

<Frame>
  <img alt="Airship 1 Image" />
</Frame>

## Enable the Integration

In order to integrate Airship with Mixpanel for anonymous mobile audience identification, you will first need to install both the [Airship SDK](https://docs.urbanairship.com/platform/) and Mixpanel SDK in your application. Once you have done so, follow these steps:

1. Navigate to **Data** in the nav bar, then select **Destinations**. Click **Add Destination**, then select Airship and enter the [Airship All Access Token and App Key](https://docs.airship.com/guides/messaging/user-guide/project/bearer-tokens/), which allows Mixpanel to send data to the correct Airship project.
2. Create a cohort in Mixpanel.
3. Create a Mixpanel [Tag Group within Airship](https://docs.urbanairship.com/guides/tag-groups-walkthrough/#tg-create-tag-group). **For this Integration, we require that you create a Tag Group Key called "mixpanel". Note that Tag Group Keys are case sensitive.**
4. Export the Cohort from Mixpanel, at which time Mixpanel will wait for a callback to ensure that the request to Airship was received.

   * A **one-time export** will add the new Airship tag to all users in the Mixpanel cohort at the time of the export. The new tag will be visible in Airship.
   * A **dynamic sync** will add or remove a tag for users in the cohort every 15 minutes until the sync is disconnected. This means that every 15 minutes, the tag in Airship will update to reflect the current status of the Mixpanel cohort.

## How does Mixpanel export data to Airship?

**For one-time exports:** Mixpanel will send a static export of users who currently qualify for the cohort. This is exported to Airship as a Tag Group that allows you to create an audience to target users. You will be able to name the Tag Group that appears in Airship. These names will only be added to the Tag Group with the Group Key called “mixpanel” (Group Keys are case sensitive).

*It is not recommended to use the same tag name for two static exports, as users who qualified at each time of export will be included in the tag within Airship.*

**For dynamically syncing exports:** Every 15 minutes, Mixpanel will initiate a sync between the Mixpanel cohort and the Airship tag. At the time of the sync, Mixpanel will add the tag for newly-qualified users, and remove the tag for users who have exited the cohort. Users can move into and out of the cohort depending on if they meet the cohort criteria. Note that these tags only apply to the “mixpanel” Tag Group Key, which must be created within Airship.

## How are users matched between Airship and Mixpanel?

> **Warning:** Projects using the [simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the \$user\_id in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.

Users are matched between Airship and Mixpanel using the [Airship channel id](https://docs.airship.com/guides/airship/user-guide/channels-intro/#channel-ids). This value must be set as a Mixpanel user property named `$ios_urban_airship_channel_id` for iOS users or `$android_urban_airship_channel_id` for Android users. These values must match with the Airship channel id.

The recommendation would be to insert code after the user authenticates that sends a `people.set` operation to the `$android_urban_airship_channel_id` and `$ios_urban_airship_channel_id` properties respectively as string values, so they are stored in the Mixpanel profile. This could be when they sign up (or just log in if they already had an account). By setting the property each time the user authenticates you would ensure users who have signed up previous to this code changes also have it.

> **Note:** SDK versions older than Android v5.9.6, Swift: v2.10.4, and Objective-C: v3.9.2 automatically created these properties. This has since been removed in favor of them being set according to your user's flow.

**Additionally**, exports will send all user profiles to match against [Airship's Named User system](https://docs.airship.com/guides/messaging/user-guide/audience/segmentation/named-users/), which handles cross-platform identification. If you would like to specify a value to match a Mixpanel user profile to a Named User, **you must add a user property, `$airship_named_user`**, which will be sent to attempt matching (note you must set this value, the Airship SDK will not automatically declare it).

Users without `$airship_named_user` user properties will instead have their distinct\_id sent to Airship's Named User system - this route is intended for implementations where the same identifier value is used for both distinct\_id (Mixpanel) and named\_user\_id (Airship). Note that for customers using identity merge, Mixpanel will send the [canonical distinct ID](https://help.mixpanel.com/hc/en-us/articles/360041039771-Getting-Started-with-Identity-Management#individual-users), which may change over time. To ensure a consistent identifier is sent to Airship's Named User system, add the `$airship_named_user` property to the user's profile.

## Sending Mixpanel Cohorts to Airship

To export cohorts to Airship, follow the steps below:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Airship destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and enter the Airship Tag under which the export should be saved. Configure the sync and click **Save**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select your cohort and click **Export to... > Airship**.

    <Frame>
      <img alt="Airship 2 Image" />
    </Frame>

    3. Enter the Airship Tag under which the export should be saved. Click **Save**.
  </Tab>
</Tabs>

<Frame>
  <img alt="Airship 3 Image" />
</Frame>

4. The tag will now be available for targeting within Airship.

<Frame>
  <img alt="Airship 4 Image" />
</Frame>

## FAQ

### Why does my Mixpanel Cohort display more users than in Airship?

In order for a user to be exported to Airship, the user must have the necessary property set on the user profile. These properties are `$ios_urban_airship_channel_id`, `$android_urban_channel_id`, or `$airship_named_user`.

### Is there a limitation to the number of profiles that can be exported to Airship?

15 million profiles is the maximum number of profiles that can be exported to Airship.

### Airship Events into Mixpanel & MTU Exemptions

You can export events from your Airship integration to Mixpanel to perform deeper analysis. For detailed instructions on how to do this, please refer to [Airship's integration documentation](https://docs.airship.com/partners/mixpanel/#set-up-a-mixpanel-rtds-integration-in-airship).

Events coming from Airship are marked with the property `$source` to denote the source product.

Mixpanel will exempt certain messaging outreach events from [MTU calculations](https://help.mixpanel.com/hc/en-us/articles/360001465686-Billing-for-Monthly-Tracked-Users#monthly-tracked-users-calculation), meaning you're free to send campaigns to dormant users without them counting towards MTU billing (only once a user engages with a message will they then be counted towards that tally).

The following events are exempt from MTU calculations:

* Airship Email Bounce
* Airship Email Delay
* Airship Email Delivery
* Airship In-App Message Display
* Airship Rich Delivery
* Airship Send
* Airship Send Rejected
* Airship Unsubscribe
* Airship SMS Delivered
* Airship Email Injection


# Appcues
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/appcues



## Overview

Export Mixpanel cohorts to Appcues to create custom segments that you can apply in your Appcues flows, surveys, and walkthroughs. Manage the Appcues integration from the Mixpanel Destinations page.

Appcues also supports an integration to send messaging interactions to Mixpanel - for more details, see [the Appcues Mixpanel integration](https://docs.appcues.com/article/447-integrations-list#Mixpanel).

## Permissions

You must be a Mixpanel project admin to enable the Appcues integration.

## Enable the Integration

Follow these steps to enable the integration with Appcues:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Appcues, and click **Connect**.

<Frame>
  <img alt="Appcues 2 Image" />
</Frame>

3. The connection uses one credential to authorize, API Key. Supply an **API token** generated from your **Appcues settings page** to establish the connection.
4. The Appcues integration will show a **Connected** tag in the UI once the connection establishes.

## Matching Users between Appcues and Mixpanel

Mixpanel only exports identified user profiles (users with at least 1 set profile properties) to match to Appcues - users without user profiles (i.e. anonymous users) will not export.

The integration requires that you use the same system of identifiers for both tools, meaning the value you pass to `mixpanel.identify("internal_user_id")` will have the same value as you pass to `appcues.identify("internal_user_id")`. Appcues will attempt to match users from inbound cohorts based on their Mixpanel distinct\_id.

## Export a Cohort

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Appcues destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click Export to > Appcues. Select either one-time sync or dynamic sync. Click **Start Sync**.

    <Frame>
      <img alt="Appcues 3 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Appcues a static export of users who currently qualify for the cohort. The cohort data will not be updated in Appcues after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and Appcues every two hours. The exported cohort will be updated every day to reflect the most recent list of users in a cohort.

## Ideal vs. Non-Recommended Use Cases

Because Dynamic syncs send cohorts at two-hour intervals, it is recommended to **avoid** using this integration for any tours requiring immediate identification and display (for example, onboarding guides that require user detection as soon as someone signs up). Appcues native targeting is still the preferred method in scenarios such as these.

More ideal use cases are instead around tours and surveys where the tour isn't tied to a real-time lifecycle moment (for example, getting easy in-product feedback after engaging with a particular feature, or directing a power user to a new product improvement for a feature they have a history of using).

## Select the Segment in Appcues

Once the export completes, you will see a Segment reflecting the set of users from your Mixpanel cohort in the Appcues Segment tab, under Custom Properties in the dropdown (e.g. "Volume Buyers"):

<Frame>
  <img alt="Appcues 4 Image" />
</Frame>

## Appcues events into Mixpanel

Appcues offers the ability to forward tour interaction events to Mixpanel. For more detail, [please refer to the Appcues integration guide](https://docs.appcues.com/article/447-integrations-list#Mixpanel).


# Apptimize
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/apptimize



## Overview

The Apptimize integration allows users to export Mixpanel cohorts into Apptimize groups, allowing you to target specific users using Apptimize.

Mixpanel cohorts can be exported to Apptimize one time, or sync and update every 15 minutes.

## Permissions

You must be a Mixpanel project admin to enable the Apptimize integration.

## Enable the Integration

Follow these steps to enable the integration with Apptimize:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Apptimize, and click **Connect**.

<Frame>
  <img alt="Apptimize 2 Image" />
</Frame>

3. You will need to provide an Apptimize Token (generated from the Apptimize dashboard) to authorize the connection. To generate an Apptimize token, go to the Tokens page on Apptimize Dashboard and click “New Token”. Give the token a memorable name and click Generate.

<Frame>
  <img alt="Apptimize 3 Image" />
</Frame>

4. Use the Apptimize token to authorize the Mixpanel integration.

## Matching Users between Apptimize and Mixpanel

> **Warning:** Projects using the [simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.

Mixpanel only exports identified user profiles (users with at least 1 set profile properties) to match to Apptimize - users without user profiles (i.e. anonymous users) will not export.

The exported users are properly mapped in Apptimize automatically by the integration through the setting of `$apptimize_user_id` user property. This property is set automatically when both the Apptimize and Mixpanel SDKs are installed on the client.

In addition, when our ingestion service detects calls setting this user property, Mixpanel will also auto-alias the value of `$apptimize_user_id` to the user's distinct\_id. This ensures that experiment data passed from Apptimize to Mixpanel still attributes to the correct user.

> **Note:** Mixpanel users can be associated with Apptimize users manually by setting the \$apptimize\_user\_id in Mixpanel with the Apptimize.getPartnerID method available in the Apptimize SDK. Do this if ThirdPartyImporting is disabled in Apptimize or when using the Mixpanel Swift SDK, which does not support ThirdPartyImporting.  It is important to note that the Apptimize.getParterID will return a modified variation of the customer user ID by prefixing "i\_" or "a\_" to represent if the ID is identified or anonymous, and will allow Apptimize to properly match users from Mixpanel cohorts.

## Export a Cohort

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Apptimize destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click Export to > Apptimize. Select either one-time sync or dynamic sync. Click Start Sync.
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and recurring syncs. When you generate a one-time export or recurring sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Apptimize a static export of users who currently qualify for the cohort. The cohort data will not be updated in Apptimize after a one-time export.

### Recurring Sync

In recurring sync, Mixpanel initiates sync between a cohort and Apptimize every 15 minutes. The exported cohort will be updated every fifteen minutes to reflect the most recent list of users in a cohort.

## Observe the Audience in Apptimize

Once the export completes, you will see your cohorts appear in your Apptimize Groups page.

<Frame>
  <img alt="Apptimize 4 Image" />
</Frame>


# Braze
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/braze



## Overview

The Mixpanel Braze integration exports Mixpanel Cohorts into [Braze](https://www.braze.com/). This allows you to send Braze campaign messages to targeted cohorts that are created in Mixpanel. You can also send your Braze events into Mixpanel to apply deeper analysis.

## Permissions

You must be a Mixpanel project admin to enable the Braze integration.

### Required Credentials

In order to set up the integration, you must use a Data Import Key and a Braze Instance URL to connect a Mixpanel instance with a Braze instance.

A Braze project stores the Data Import Key and Braze Instance URL. You can find these two values in from within Braze. [Use the Braze documentation to learn how to obtain the Key and URL](https://www.braze.com/docs/partners/data_and_infrastructure_agility/analytics/mixpanel_for_currents/).

## Set Up the Integration

Enter the Mixpanel project where the integration is to be performed, then:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, then select **Braze**. Click **Connect**.

<Note>
  If you set a User ID Property, it should be a Mixpanel user property that matches the Braze External ID. If you do not select one, Mixpanel will default to using the `$braze_external_id` property to match users between Braze and Mixpanel. See more about [matching users between Braze and Mixpanel](/docs/cohort-sync/integrations/braze#matching-mixpanel-and-braze-users).
</Note>

<Frame>
  <img alt="Braze 2 Image" />
</Frame>

If you've set up a Connection already, you have the option of reconnecting the existing Connection.

<Frame>
  <img alt="Braze 3 Image" />
</Frame>

You also have the option of adding a new Connection by clicking the dropdown on the left hand side of the row, and clicking "**+ Add Connection**".

<Frame>
  <img alt="Braze 4 Image" />
</Frame>

3. Enter the Data Import Key and select a Braze Instance. Note Braze hosts their application on [multiple clusters throughout the US and EU](https://www.braze.com/docs/partners/isv_partners/cohort_import/).

<Frame>
  <img alt="Braze 5 Image" />
</Frame>

4. Click **Continue** to complete the process.

## Export a Mixpanel Cohort to Braze

To export a Mixpanel cohort, you must create a cohort. To export a Mixpanel cohort to Braze:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Braze destination in the list and click on it. If you have multiple Connections, they will be differentiated by the Connection Name.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort to send to Braze and configure the sync (One-time export or Dynamic sync). Click **Begin Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.

    <Frame>
      <img alt="Braze 6 Image" />
    </Frame>

    2. Select the cohort to send to Braze. Select **Export to Braze**. If you have multiple Connections, they will be differentiated by the Connection Name in the parentheses after the Integration Name.

    <Frame>
      <img alt="Braze 7 Image" />
    </Frame>

    3. Select a One-time export or a Dynamic sync. Click Begin Sync.

    <Frame>
      <img alt="Braze 8 Image" />
    </Frame>
  </Tab>
</Tabs>

## Use the Mixpanel Cohort to Create a Segment in Braze

A new Braze segment can be built using a Mixpanel cohort after exporting a cohort from Mixpanel to Braze.

In order to build a Braze Segment after importing a cohort:

1. Select **Segments** tab under **Engagement**.

<Frame>
  <img alt="Braze 9 Image" />
</Frame>

2. Click **Create Segment**.

<Frame>
  <img alt="Braze 10 Image" />
</Frame>

3. After naming the Segment, click Select Filter from the dropdown.

<Frame>
  <img alt="Braze 11 Image" />
</Frame>

4. Select "Mixpanel Cohorts".

<Frame>
  <img alt="Braze 12 Image" />
</Frame>

5. Select the “includes” value from the dropdown. Click **Search for a value** from the dropdown.

<Frame>
  <img alt="Braze 13 Image" />
</Frame>

6. The exported Mixpanel cohort is visible in the dropdown. Select the cohort.

<Frame>
  <img alt="Braze 14 Image" />
</Frame>

7. Click Save.

## Matching Mixpanel and Braze Users

<Warning>
  **Warning:** Projects using the [Simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.
</Warning>

In order to match Mixpanel users to ones on Braze's end, the user in Mixpanel should have a profile property named \$braze\_external\_id with the value you have assigned in Braze to the same user as [external\_user\_id](https://www.braze.com/docs/developer_guide/platform_integration_guides/legacy_sdks/ios/analytics/setting_user_ids/#suggested-user-id-naming-convention).

The recommendation would be to insert code after the user authenticates that sends a `people.set` operation to the `$braze_external_id` property with the string value so it is stored in the Mixpanel profile. This could be when they sign up (or just log in if they already had an account). By setting the property each time the user authenticates you would ensure users who have signed up previous to this code changes also have it.

If you are planning to also enable sending engagement events from Braze to Mixpanel, and the Braze external\_user\_id differs from the user\_id you identify the user with in Mixpanel, you can also alias the Braze external\_user\_id to the distinct\_id you identify users with after they authenticate. Often times, you use the same user ID for both the external\_user\_id in Braze, and the ID you identify with in Mixpanel, so in that case, aliasing would not be needed.

<Note>
  SDK versions older than Android v5.9.6, Swift: v2.10.4, and Objective-C: v3.9.2 automatically created both the profile property and the alias mentioned above. This has since been deprecated due to possible ID management issues in some use cases, so on the SDK versions cited (or above), you should set the `$braze_external_id` profile property and alias when applicable.
</Note>

## Braze Events into Mixpanel & MTU exemptions

You can export events from your Braze integration to Mixpanel to perform deeper analysis. For detailed instructions on how to do this, please refer to [Braze’s Technology Partner’s documentation](https://www.braze.com/docs/partners/data_and_infrastructure_agility/analytics/mixpanel_for_currents/).

Events coming from Braze are marked with the property `$partner_id`.

Mixpanel will exempt certain messaging outreach events from MTU calculations, meaning you're free to send campaigns to dormant users without them counting towards MTU billing (only once a user engages with a message will they then be counted towards that tally).

The following events are exempt from MTU calculations:

* Canvas Entry
* Email Send
* Email Delivery
* Email Bounce
* Email Soft Bounce
* Email Mark As Spam
* Email Unsubscribe
* Push Notification Send
* Push Notification Bounce
* Webhook Send
* SMS Send
* SMS Delivery
* SMS Delivery Failure
* SMS Rejection
* SMS Send to Carrier

## Comparing Metrics

Braze can be configured to push events to Mixpanel on actions ([review full list of events on Braze's docs](https://www.braze.com/docs/partners/data_and_infrastructure_agility/analytics/mixpanel_for_currents/#supported-currents-events)). A consideration to have is that both platforms can present measurements in different ways (although it's based on the same underlying data).

For uniques specially, on the Mixpanel side, this is calculated based on the unique distinct\_id values (unique user IDs) that the events are related to. This can differ on Braze; as an example, unique email opens are measured on the unique number of users/devices that opened the message on a 7-day range (so a user opening the email twice, 2 weeks apart could be considered 2 uniques).

You can reference Braze's calculations [on their docs](https://www.braze.com/docs/user_guide/message_building_by_channel/email/reporting_and_analytics/analytics_glossary#:~:text=The%20total%20number%20of%20delivered%20emails%20that%20have%20been%20opened%20by%20a%20single%20user%20or%20machine%20at%20least%20once.%20This%20is%20tracked%20over%20a%207%20day%20period%20for%20Email) to understand the differences you can see in reporting.


# Chameleon
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/chameleon



## Overview

Export Mixpanel cohorts to Chameleon to create custom segments that you can apply in your Chameleon tours, surveys, and launchers. Manage the Chameleon integration from the Mixpanel Destinations page.

Chameleon also supports an integration to send messaging interactions to Mixpanel - for more details, see [Chameleon's Mixpanel integration](https://help.trychameleon.com/en/articles/1349054-mixpanel-integration-user-guide).

## Permissions

You must be a Mixpanel project admin to enable the Chameleon integration.

## Enable the Integration

Follow these steps to enable the integration with Chameleon:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Chameleon, and click **Connect**.

<Frame>
  <img alt="Chameleon 2 Image" />
</Frame>

3. The connection uses one credential to authorize, "API Key". Supply an API key generated from the [Mixpanel-specific integration page within your Chameleon dashboard](https://app.trychameleon.com/settings/integrations/mixpanel) to establish the connection.
4. The Chameleon integration will show a **Connected** tag in the UI once the connection establishes.

## Matching Users Between Chameleon and Mixpanel

Mixpanel only exports identified user profiles to match to Chameleon - users without user profile properties (i.e. anonymous users) will not export.

The integration requires that you use the same system of identifiers for both tools, meaning the value you pass to `mixpanel.identify("internal_user_id")` will have the same value as you pass to `chmln.identify("internal_user_id")`. Chameleon will attempt to match users from inbound cohorts based on their Mixpanel distinct\_id.

## Export a Cohort

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Chameleon destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click Export to > Chameleon. Select either one-time sync or dynamic sync. Click **Start Sync**.

    <Frame>
      <img alt="Chameleon 3 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Chameleon a static export of users who currently qualify for the cohort. The cohort data will not be updated in Chameleon after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and Chameleon every two hours. The exported cohort will be updated every day to reflect the most recent list of users in a cohort.

## Ideal vs. Non-Recommended Use Cases

Because Dynamic syncs send cohorts at two-hour intervals, it is recommended to **avoid** using this integration for any tours requiring immediate display and instead use Chameleon's native targeting (for example, onboarding guides that require user detection as soon as someone signs up).

More ideal use cases are instead around tours and surveys where the tour isn't tied to a real-time lifecycle moment (for example, getting easy in-product feedback after engaging with a particular feature, or directing a power user to a new product improvement for a feature they have a history of using).

## Select the Segment in Chameleon

Once the export completes, you will see a Segment reflecting the set of users from your Mixpanel cohort in the Chameleon Segment tab (via the builder), selecting for "Mixpanel Cohorts" as the Segment filter (e.g. "Users who haven't hit a Value Moment"):

<Frame>
  <img alt="Chameleon 4 Image" />
</Frame>

## Chameleon events in Mixpanel

Chameleon offers the ability to forward tour interaction events to Mixpanel. For more detail, [please refer to Chameleon's integration guide](https://help.trychameleon.com/en/articles/1349054-mixpanel-integration-user-guide).


# CleverTap
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/clevertap



## Overview

Export Mixpanel cohorts to CleverTap to create custom segments that you can apply in your CleverTap campaigns and journeys. Manage the CleverTap integration from the Mixpanel Destinations page.

CleverTap also supports an integration to send events data to Mixpanel - for more details, [see the CleverTap Mixpanel integration](https://docs.clevertap.com/docs/mixpanel-export).

## Permissions

You must be a Mixpanel project admin to enable the CleverTap integration.

## Enable the Integration

To enable the integration with CleverTap:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select CleverTap, and click **Connect**.

<Frame>
  <img alt="CleverTap 2 Image" />
</Frame>

3. Specify a **Connector Name** and enter the CleverTap **Project ID**, **Passcode**, and **Data center** details to authorize the connection.
4. You can optionally select the user properties to export by clicking on the ***Edit Columns*** and selecting the user properties you wish to be included in the export. The default user properties that are exported can be found [here](/docs/cohort-sync#limits).
5. The CleverTap integration will show a **Connected** tag in the UI once the connection establishes.

## Matching Users between CleverTap and Mixpanel

Mixpanel only exports identified user profiles to match to CleverTap - users without user profile properties (i.e. anonymous users) will not be exported.

It is recommended to set a `$CleverTap_user_id` user property with the ID that you use to identify users in Mixpanel. CleverTap will use this property as the first option to match user profiles in CleverTap and include them in the segments. For more information on how CleverTap matches exported cohorts from Mixpanel, refer to [CleverTap's User Identity Management](https://docs.clevertap.com/docs/mixpanel-integration#user-identity-management).

In addition, when our ingestion service detects calls setting this user property, Mixpanel will also auto-alias the value of `$CleverTap_user_id` to the user's distinct\_id. This ensures that messaging and experiment data passed from CleverTap to Mixpanel still attributes to the correct user.

## Export a Cohort

To export a Cohort to CleverTap:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the CleverTap destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click **Export to > CleverTap**. Select either one-time sync or dynamic sync. Click **Start Sync**.
  </Tab>
</Tabs>

<Frame>
  <img alt="CleverTap 3 Image" />
</Frame>

## Sync Types

This integration supports two types of exports: one-time export and recurring sync. When you generate a one-time export or recurring sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

## Select the Segment in CleverTap

Once the export completes, you will see a segment reflecting the set of users from your Mixpanel cohort in the CleverTap's Segments dashboard. The Type column under the Segments list page for the exported cohort is displayed as `Partner - Mixpanel`:

<Frame>
  <img alt="CleverTap 4 Image" />
</Frame>

You can also refer to CleverTap's [Mixpanel Import (Cohort)](https://docs.clevertap.com/docs/mixpanel-integration) documentation.

## CleverTap Events into Mixpanel & MTU exemptions

You can use events from your CleverTap integration to perform deeper analysis in Mixpanel.

Events coming from CleverTap are marked with the property `$source`.

Mixpanel will exempt certain messaging outreach events from MTU calculations, meaning you're free to send campaigns to dormant users without them counting towards MTU billing (only once a user engages with a message will they then be counted towards that tally).

The following CleverTap events are exempt from MTU calculations:

* Notification Sent
* Notification Viewed
* Notification Clicked
* Push Impressions
* Notification Replied
* Push Unregistered
* Control Group
* Channel Unsubscribed
* Reachable By
* Notification Delivered
* AB Experiment Rendered
* AB Experiment Stopped
* AB Experiment Rolled Out
* Geocluster Entered
* Geocluster Exited
* Reply Sent
* App Uninstalled
* Webhook Delivered
* State Transitioned
* UTM Visited


# Facebook Ads
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/facebook-ads



## Overview

Export Mixpanel cohorts to Facebook Ads to use targeted advertisements in Facebook. Manage the Facebook Ads integration from the Mixpanel Destinations page. The integration currently supports data from Mixpanel into Facebook Business.

> You must have a Facebook Business account connected to [Business Manager](https://audience.42matters.com/blog/how-to-connect-your-facebook-ad-account-to-business-manager-to-use-custom-audiences) to use this integration.

## Permissions

You must be a Mixpanel project admin to use the Facebook Ads data integration.

## Enable the Integration

Follow these steps to enable the integration with Facebook Ads:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, then select **Facebook Ads**.

<Frame>
  <img alt="Facebook 2 Image" />
</Frame>

3. Select your Facebook Ad Account ID and your connector name and also choose user property where you're storing device advertising ID (optional)

<Frame>
  <img alt="Facebook Connector Image" />
</Frame>

4. The Facebook Ads integration page will show a green export icon and details about the integration after it is connected. To disable the connector, select the **Facebook Ads** dropdown and click **Disconnect**.

## Export a Cohort

To export a cohort to Facebook Ads:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Facebook Ads destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three dot icon on the right side of the cohort.
    3. Click **Export to Facebook**. Select either a one-time sync or a dynamic sync. Click **Start Sync**.

    <Frame>
      <img alt="Facebook 3 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or a dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Facebook a static export of users who currently qualify for the cohort. The cohort data will not be updated in Facebook after a one-time export.

### Dynamic Sync

In a dynamic sync, Mixpanel initiates a sync between a cohort and Facebook every two hours. The exported cohort will be updated every two hours to reflect the most recent list of users in a cohort.

## Select the Cohort in Facebook Ads

You must log in to Facebook Business Manager to use the Mixpanel Cohort in Facebook Ads. Select the **Menu** in Facebook Business Manager top navigation.

Click on **Audiences**.

<Frame>
  <img alt="Facebook 4 Image" />
</Frame>

The Mixpanel Cohort is available in the Audience list. Cohorts are exported to Facebook Ads as `mixpanel_<Cohort Name>_<Cohort ID>`.

## Data Requirement

Meta uses *email addresses* as the primary identifier to match users in your cohort with users in their system. If an email address is not available, Meta may instead attempt to match using other identifiers such as a *phone number*, *first and last name*, or a *device advertising ID* (depending on your connection setup).

To use this integration, each user profile must include either an *email address* or a *device advertising ID*. In addition to the email (if present), your system will send the following user profile properties (if available): first name, last name, phone number, advertising ID, and distinct\_id. No other user properties will be exported.

If Meta is unable to match a cohort member with a user in their system, that member will be excluded from the resulting Meta audience. A lower count in the Meta audience compared to your cohort indicates that some users could not be matched.

## Troubleshooting Errors

Below are some common blocking errors (e.g. Error Message: Invalid OAuth 2.0 Access Token) that may occur when authorizing or using this connection:

#### Login Token Expired. Please disconnect and reconnect from the Destinations page.

[Facebook tokens expire after 60 days of inactivity](https://developers.facebook.com/docs/facebook-login/auth-vs-data/). Users will have to log in again to resume the cohort exports.

#### (#200) The current user can not update audience XXXXXXXXXXX

Verify the permissions for the user who created the sync, and then disconnect and reconnect from the Destinations page. Disconnecting and Reconnecting will resume your existing exports.

#### Error validating access token: The session has been invalidated because the user changed their password or Facebook has changed the session for security reasons.

Facebook sometimes invalidates the access token if they detect suspicious activity. Disconnect and reconnect the Facebook connection with a new token from the Destinations page to resume syncs.

#### Error validating access token: The user has not authorized application XXXXXXXXXX.

The user setting up the integration should be using a Facebook business account and have an admin role - verify these two pieces and then attempt reconnecting the integration to resume your existing exports.

#### To create or edit a Custom Audience made from a customer list, your admin needs to add this ad account to a business.

Please follow the directions here - [https://www.facebook.com/business/help/910137316041095?id=420299598837059](https://www.facebook.com/business/help/910137316041095?id=420299598837059)

#### To create or edit a saved audience with an uploaded customer list, please agree to the Custom Audience terms at [https://business.facebook.com/ads/manage/customaudiences/tos/?act=XXXXXXXXXXX](https://business.facebook.com/ads/manage/customaudiences/tos/?act=XXXXXXXXXXX).

We generally force a window to accept the terms and conditions for the users. In rare instances where that doesn't work you can go to the above URL by replacing **XXXXXXXXXXX with your FB account ID**. Accept the terms there and then disconnect + reconnect the integration.

#### Two factor authentication required. User have to enter a code from SMS or TOTP code generator to pass 2fac.

Please disable two factor authentication and re-establish the connection from the Destinations page.

#### (#2654) Customer List Audiences Are Not Available: Ad accounts owned by businesses new to Facebook Products can create customer file Custom Audiences after several weeks of following our policies.

Please contact Facebook support to get this feature enabled for you.


# Google Ads
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/google-ads



## Overview

Export Mixpanel cohorts to Google Ads to use targeted advertisements in Google Search. Manage the Google Ads integration from the Mixpanel Destinations page. The integration currently supports data from Mixpanel into a Google Ads account.

## Permissions

You must be a Mixpanel project admin to use the Google Ads data integration.

## Enable the Integration

Follow these steps to enable the integration with Google Ads:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Google Ads, and click **Sign In with Google**.

<Frame>
  <img alt="GoogleAds 2 Image" />
</Frame>

3. Enter your connector name, Google Customer ID and also choose user property where you’re storing device advertising ID (optional)

<Frame>
  <img alt="GoogleAds Connector Image" />
</Frame>

4. The Google Ads integration page shows a green export icon and details about the integration after it is connected.

## Export a Cohort

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Google Ads destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.

    <Frame>
      <img alt="GoogleAds 3 Image" />
    </Frame>

    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click **Export to Google Ads**. Select either one-time sync or dynamic sync. Click **Start Sync**.

    <Frame>
      <img alt="GoogleAds 4 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Google Ads a static export of users who currently qualify for the cohort. The cohort data will not be updated in Google Ads after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and Google Ads every two hours. The exported cohort will be updated every day to reflect the most recent list of users in a cohort.

## Select the Cohort in Google Ads

You must log in to Google Business Manager to use the Mixpanel Cohort in Google Ads. Select the **Menu** in Google Business Manager’s top navigation.

Click on **Tools & Settings** and launch Audience Manager.

<Frame>
  <img alt="GoogleAds 5 Image" />
</Frame>

The Mixpanel Cohort is available under Audience Manager. Cohorts are exported to Google Ads as `mixpanel*<Cohort Name>*<Cohort ID>`.

<Frame>
  <img alt="GoogleAds 6 Image" />
</Frame>

## Data Requirements

Google Ads matches users from your Mixpanel cohort to users in its system primarily using *email addresses*. If an email address is not available, Google Ads can instead attempt to match users using other identifiers — such as a *phone number*, *first and last name*, or a *device advertising ID*, depending on how you configure the connection.

To use this integration, your Mixpanel user profiles must include either an *email address* or a *device advertising ID*. Along with those identifiers, Mixpanel also sends the following user properties (if available): first name, last name, phone number, advertising ID, and distinct\_id. No other user properties are exported.

If Google Ads cannot match a cohort member with a user in its system, that member will be excluded from the Google Ads audience. A lower number of users in Google Audiences compared to your Mixpanel cohort means some users could not be matched.

## Troubleshooting Errors

Below are some common blocking errors that may occur when authorizing or using this connection:

**Advertiser needs to be on the allow-list to use remarketing lists created from advertiser uploaded data (e.g., Customer Match lists).**

Google has to whitelist customers to use this feature. [This Google support article](https://support.google.com/adspolicy/answer/6299717?hl=en) contains more information. Cohort exports will remain paused until it is enabled.

**No customer found for the provided customer id.**

Please [use a valid customer id](https://support.google.com/google-ads/answer/1704344?hl=en).

**The customer can't be used because it isn't enabled.**

Please make sure the user setting the integrations has standard or admin access in the Google Ads account.

**The user does not have permission to perform this action on the resource or call a method.**

Please make sure the user setting the integrations has standard or admin access in the Google Ads account.

**User doesn't have permission to access customer. Note: If you're accessing a client customer, the manager's customer id must be set in the 'login-customer-id' header. See [https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid)**

Please make sure the user setting the integrations has standard or admin access in the Google Ads account.

**User in the cookie is not a valid Ads user.**

Please make sure the user setting the integrations has standard or admin access in the Google Ads account.


# Insider
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/insider



## Overview

Export Mixpanel cohorts to Insider to create custom segments that you can apply in your Insider campaigns. Manage the Insider integration from the Mixpanel Destinations page.

## Permissions

You must be a Mixpanel project admin to enable the Insider integration.

## Enable the Integration

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Insider, and click **Connect**.

<Note>
  If you set a User ID Property, it should be a Mixpanel user property that matches the email or phone number set in Insider.
</Note>

<Frame>
  <img alt="insider 2 Image" />
</Frame>

3. The Insider integration will show a **Connected** tag in the UI once the connection succeeds.

## Matching Users between Insider and Mixpanel

Mixpanel only exports identified user profiles to match to Insider - users without user profile properties (i.e. anonymous users) will not export.

Insider will use either the user's email (set via the `$email` user property) or phone number (set via the `$phone` user property) to match the Mixpanel user profile to Insider. As a result, not all exported profiles may match if these values are missing or differ from the emails and phone numbers stored on Insider.

Note that exports are used solely for matching user identities between products - the integration will not send the full set of a user's profile properties to Insider, nor will it generate new users in Insider.

## Export a Cohort

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Insider destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click Export to > Insider. Select either one-time sync or dynamic sync. Click **Start Sync**.

    <Frame>
      <img alt="insider 3 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Insider a static export of users who currently qualify for the cohort. The cohort data will not be updated in Insider after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and Insider every 15 minutes. The exported cohort will be updated every 15 minutes to reflect the most recent list of users in a cohort.

## Select the Custom Segment in Insider

Once the export completes, you will see a custom segment reflecting the set of users from your Mixpanel cohort. (e.g. "7days-cart-abandoners")

<Frame>
  <img alt="insider 4 Image" />
</Frame>


# Iterable
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/iterable



## Overview

Export Mixpanel cohorts to Iterable to create user lists that you can target in your Iterable campaigns. Manage the Iterable integration from the Mixpanel Destinations page.

## Permissions

You must be a Mixpanel project admin to use the Iterable data integration.

## Enable the Integration

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Iterable, and click **Connect**.
3. The Iterable integration page will show a green export icon and details about the integration after it is connected.

If you select the US or EU Iterable data center, data will be sent to the corresponding Iterable project. Note: Every Iterable API key is associated with a specific Iterable project, which means that it's also associated with a specific data center. Further reading: [https://support.iterable.com/hc/en-us/articles/360043464871-API-Keys#api-keys-projects-and-data-centers](https://support.iterable.com/hc/en-us/articles/360043464871-API-Keys#api-keys-projects-and-data-centers)

To disable the connector, select the Iterable dropdown and click **Disconnect**.

## Export a Cohort

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Iterable destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click Export to > Iterable. Select either one-time sync or dynamic sync. Click **Start Sync**.

    <Frame>
      <img alt="iterable 3 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Iterable a static export of users who currently qualify for the cohort. The cohort data will not be updated in Iterable after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and Iterable every fifteen minutes. The exported cohort will be updated every fifteen minutes to reflect the most recent list of users in a cohort.

## Select the Cohort in Iterable

You must log in to Iterable to use the Mixpanel Cohorts to send campaigns.

The Mixpanel Cohort is available in the Audience list. Mixpanel exports cohort data as `mixpanel_<Cohort Name>_<Cohort ID>`.

<Frame>
  <img alt="iterable 4 Image" />
</Frame>

## Matching Users between Mixpanel and Iterable

> **Warning:** Projects using the [simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.

The best way to match users from Mixpanel to Iterable is to grab the value displayed as `userId` in Iterable and store it as a profile property for the user in Mixpanel under the name `$iterable_user_id`. This also prevents Iterable from overwriting the Iterable User ID with the Mixpanel Distinct ID upon cohort sync from Mixpanel. For context, the value you should store as `$iterable_user_id` in the Mixpanel profile would look like this in Iterable:

<Frame>
  <img alt="Iterable's user ID" />
</Frame>

Iterable uses an email address to match users from the cohort with users from their system. The integration will fail if an email address is not sent. In order to use this integration, you must set email as a user profile property.

## Iterable Events into Mixpanel and MTU Exemptions

Iterable offers the ability to send events from Iterable to Mixpanel to perform deeper analysis based on messaging data. For detailed instructions, please refer to [Iterable's integration documentation](https://support.iterable.com/hc/en-us/articles/208013936-System-Webhooks-).

Events coming from Iterable are marked with the property "\$source" to denote the source product.

Mixpanel will exempt certain messaging outreach events from MTU calculations, meaning you're free to send campaigns to dormant users without them counting towards MTU billing (only once a user engages with a message will they then be counted towards that tally).

The following events are exempt from MTU calculations:

* emailSend
* emailBounce
* emailComplaint
* emailSendSkip
* emailSubscribe
* emailUnSubscribe
* hostedUnsubscribeClick
* inAppSend
* inAppSendSkip
* pushBounce
* pushSend
* pushSendSkip
* smsBounce
* smsReceived
* smsSend
* smsSendSkip
* webPushSendSkip


# Kameleoon
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/kameleoon



## Overview

Export Mixpanel cohorts to Kameleoon to create custom segments that you can apply in your Kameleoon experiments. Manage the Kameleoon integration from the Mixpanel Destinations page.

Kameleoon also supports an integration to send experiment data to Mixpanel - for more details, see [the Kameleoon Mixpanel integration](https://help.kameleoon.com/en/setting-up-mixpanel/).

## Permissions

You must be a Mixpanel project admin to enable the Kameleoon integration.

## Enable the Integration

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Kameleoon, and click **Connect**.

<Frame>
  <img alt="Kameleoon 2 Image" />
</Frame>

3. The connection uses one credential to authorize, "API Key". Supply an **API token** generated from your Kameleoon settings page to establish the connection.
4. The Kameleoon integration will show a **Connected** tag in the UI once the connection establishes.

## Matching Users Between Kameleoon and Mixpanel

Mixpanel only exports identified user profiles to match to Kameleoon - users without user profile properties (i.e. anonymous users) will not export.

The integration requires that you use the same system of identifiers for both tools, meaning the value you pass to `mixpanel.identify("internal_user_id")` will have the same value as you pass to Kameleoon when identifying a "visitor". Kameleoon will attempt to match users from inbound cohorts based on their Mixpanel distinct\_id.

Additionally, if you're using Mixpanel's identity merge feature, you may want to provide a consistent identity value to deliver to Kameleoon (as Mixpanel's distinct\_id for a given user may change over time as the user's Canonical ID shifts). To provide a consistent user identifier to Kameleoon, **you may specify a user property**, `$kameleoon_mapping_id`, whose value is a string representing the user's consistent identifier (for example, an internal user ID). Mixpanel will also deliver this property to Kameleoon for user matching.

## Export a Cohort

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Kameleoon destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click Export to > Kameleoon. Select either one-time sync or dynamic sync. Click **Start Sync**.
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Kameleoon a static export of users who currently qualify for the cohort. The cohort data will not be updated in Kameleoon after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and Kameleoon every two hours. The exported cohort will be updated every day to reflect the most recent list of users in a cohort.

## Select the Segment in Kameleoon

Once the export completes, you will see a Segment reflecting the set of users from your Mixpanel cohort in Kameleoon's Segment editor, as custom data (e.g. "Song Sharers"):

<Frame>
  <img alt="Kameleoon 3 Image" />
</Frame>

## Kameleoon Data into Mixpanel

Kameleoon offers the ability to forward experiment data to Mixpanel. For more detail, please refer to [the Kameleoon integration guide](https://help.kameleoon.com/en/setting-up-mixpanel/).


# Leanplum
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/leanplum



## Overview

Export Mixpanel cohorts to Leanplum to create custom audiences that you can apply in your Leanplum campaigns. Manage the Leanplum integration from the Mixpanel Destinations page.

Leanplum also supports an integration to send messaging interactions to Mixpanel - for more details, see [Leanplum's Mixpanel integration](https://docs.leanplum.com/docs/mixpanel-feed).

## Permissions

You must be a Mixpanel project admin to enable the Leanplum integration.

## Enable the Integration

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Leanplum, and click **Connect**.

<Frame>
  <img alt="Leanplum 2 Image" />
</Frame>

3. The connection uses a Basic Authorization Username/Password system. You will need to provide two credentials to authorize the connection:

* Username: Leanplum App ID
* Password: Leanplum API Secret

You can find these values in your Leanplum settings page, and under the Mixpanel section in "Partner Integrations".

4. The Leanplum integration will show a **Connected** tag in the UI once the connection succeeds.

## Matching Users Between Leanplum and Mixpanel

> **Warning:** Projects using the [simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.

Mixpanel only exports identified user profiles to match to Leanplum - users without user profile properties (i.e. anonymous users) will not export.

If you use a different system of user identifiers for Mixpanel's distinct\_id as compared to Leanplum's user ID, the user's Mixpanel profile must contain a user property, `$leanplum_user_id`, whose value is a string representing that person's user ID in Leanplum. Use this joining key if your user identifiers in Mixpanel are different from the identifiers used in Leanplum (for example, if you identify Mixpanel users on internal user ID, but identify Leanplum users on device ID).

In addition, when our ingestion service detects calls setting this user property, Mixpanel will also auto-alias the value of `$leanplum_user_id` to the user's distinct\_id. This ensures that messaging data passed from Leanplum to Mixpanel still attributes to the correct user.

If you use the same system of user identifiers in both tools, meaning a user has the same ID string in both products, you do **not** have to declare `$leanplum_user_id`. The users' Mixpanel distinct\_id will still be sent in the cohort export, and Leanplum will attempt to match users on this value instead.

Note that exports are used solely for matching user identities between products - the integration will not send the full set of a user's profile properties to Leanplum.

## Export a Cohort

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Leanplum destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click Export to > Leanplum. Select either one-time sync or dynamic sync. Click Start Sync.

    <Frame>
      <img alt="Leanplum 3 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export. In case of dynamic sync, we compute a diff of users added and removed from the cohort's current state compared to the cohort state present on Leanplum and send the diff over to Leanplum to apply these changes.

### One-Time Export

In a one-time export, Mixpanel sends Leanplum a static export of users who currently qualify for the cohort. The cohort data will not be updated in Leanplum after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel exports the cohort to Leanplum every 15 minutes. The exported cohort will be updated every 15 minutes to reflect the most recent list of users in a cohort.

## Select the Audience in Leanplum

Once the export completes, you will see an Audience reflecting the set of users from your Mixpanel cohort. (e.g. "Recent Signups who haven't hit a Value Moment")

<Frame>
  <img alt="Leanplum 4 Image" />
</Frame>

## Leanplum events into Mixpanel & MTU exemptions

Leanplum offers the ability to forward campaign interaction events to Mixpanel. For more detail, [please refer to Leanplum's integration guide](https://docs.leanplum.com/docs/mixpanel-feed).

Events coming from Leanplum are marked with the property `$source` to denote the source product.

Mixpanel will exempt certain messaging outreach events from MTU calculations, meaning you're free to send campaigns to dormant users without them counting towards MTU billing (only once a user engages with a message will they then be counted towards that tally).

The following events are exempt from MTU calculations:

* (Leanplum) Campaign Enter
* (Leanplum) Push Notification Send
* (Leanplum) Push Notification Bounce
* (Leanplum) Email Send
* (Leanplum) Email Delivered
* (Leanplum) Email Bounce
* (Leanplum) Email Marked as spam
* (Leanplum) Email Unsubscribed
* (Leanplum) A/B test


# Mailchimp
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/mailchimp



## Overview

Export Mixpanel cohorts to Mailchimp to create custom audiences that you can apply in your Mailchimp campaigns. Manage the Mailchimp integration from the Mixpanel Destinations page.

## Permissions

You must be a Mixpanel project admin to enable the Mailchimp integration.

## Enable the Integration

The Mailchimp integration requires initial configuration through your Mailchimp account. Refer to [Mailchimp's documentation for information on authorizing the connection](https://mailchimp.com/help/connect-disconnect-mixpanel/).

Follow these steps to enable the integration with Mailchimp:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Mailchimp, and click **Connect**.

<Frame>
  <img alt="mailchimp 2 Image" />
</Frame>

You will need to provide an API key (referred to as an Authorization token in Mailchimp) to authorize the connection. Mailchimp will provide this token during the integration initialization flow.

3. The Mailchimp integration will show a **Connected** tag in the UI once the connection succeeds.

## Matching Users between Mailchimp and Mixpanel

> **Warning:** Projects using the [simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.

Mixpanel only exports identified user profiles to match to Mailchimp - users without user profile properties (i.e. anonymous users) will not export.

In order to match an exported Mixpanel user to Mailchimp, the user's Mixpanel profile must contain a user property, `$email`, whose value is a string representing that user's email address.

## Export a Cohort

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Mailchimp destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click **Export to > Mailchimp**. Select either one-time sync or dynamic sync. Click **Start Sync**.

    <Frame>
      <img alt="mailchimp 3 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Mailchimp a static export of users who currently qualify for the cohort. The cohort data will not be updated in Mailchimp after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and Mailchimp every 2 hours. The exported cohort will be updated every two hours to reflect the most recent list of users in a cohort.

## Observe the Audience in Mailchimp

Once the export completes, you will see updates in your Mailchimp dashboard reflecting your synced audience:

<Frame>
  <img alt="mailchimp 4 Image" />
</Frame>

## MTU exemptions

Events coming from Mailchimp are marked with the property "\$source" equal to "mailchimp".

Mixpanel will exempt certain messaging outreach events from MTU calculations, meaning you're free to send campaigns to dormant users without them counting towards MTU billing (only once a user engages with a message will they then be counted towards that tally).

The following events are exempt from MTU calculations:

* Mailchimp - Opened Campaign
* Mailchimp - Clicked Campaign Url
* Mailchimp - Sent To
* Mailchimp - Unsubscribed
* Mailchimp - Bounced


# Marketo
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/marketo



## Overview

The Marketo integration with Mixpanel is a turn-key integration that allows users to export Mixpanel cohorts into Marketo. The integration enables Marketo email campaigns to target users based on Mixpanel cohort data. The cohort export can happen once, or can be configured to dynamically update a Marketo Custom Field every two hours.

## Permissions

You must be a Mixpanel project admin to use the Marketo data integration.

## Enable the Integration

In order to setup your Mixpanel and Marketo Integration, you must be an Admin in both Marketo and your Mixpanel project. To set up the integration:

1. Input your[Marketo credentials](http://developers.marketo.com/rest-api/authentication/) (Client ID, Client Secret, Rest URL) in the Mixpanel integration setup flow. Remove "identity" from the url so its rest endpoint when setting up the integration looks like: [https://051-pvi-353.mktorest.com/](https://051-pvi-353.mktorest.com/)
2. Create a Mixpanel Custom Field in Marketo. **This Custom Field should be set as a boolean type**. Read the [Marketo Documentation](https://docs.marketo.com/display/public/DOCS/Create+a+Custom+Field+in+Marketo) for additional information on how to set up a Custom Field.
3. The new Custom Field will update to 'True', allowing you to target users based on the Mixpanel cohort criteria.

## Sending a Mixpanel Cohort to Marketo

To send a Mixpanel Cohort to Marketo:

1. Create a [Custom Field in Marketo](https://docs.marketo.com/display/public/DOCS/Create+a+Custom+Field+in+Marketo) for each cohort that you plan to export.
2. Export the cohort from Mixpanel:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1) Navigate to **Data** in the nav bar, then select **Destinations**.
    2) Find the Marketo destination in the list and click on it.
    3) Click the **Syncs** tab, then click **Add Cohort Sync**.
    4) Select the cohort you want to export and configure the sync.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select **Cohorts** to view all cohorts.

    <Frame>
      <img alt="Marketo 1 Image" />
    </Frame>

    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
  </Tab>
</Tabs>

3. Copy and paste the field name associated with the cohort you want to export into Marketo.
4. After exporting your cohort to Marketo, the custom field name for all matched users will be set to True.

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync.

### One-Time Exports

The Custom Field will automatically be updated to 'True', allowing you to target users based on this criteria.

### Dynamic Syncs

The Custom Field will be updated every two hours to reflect the status of the Mixpanel cohort. The Custom Field will be set to 'True' or 'False' to reflect the movement of any users in to or out of a Mixpanel cohort.

## FAQ

### Exporting the Same Cohort to Marketo

It is possible to export the same cohort to Marketo more than once, however each export will require a new custom field within Marketo. Mixpanel disallows exporting to the same custom field so that the custom field you have created in Marketo is up-to-date with only the latest export.

### Why is the cohort user count larger in Mixpanel than in Marketo?

In order to export a user to Marketo using Cohorts, the user must have the special user profile property \$email set on their user profile. If this property is not set on a user’s profile, they will not be exported to Marketo.

### How does Mixpanel handle users that exist within Mixpanel, but not in Marketo?

If the user within Mixpanel has the \$email user profile property, a new lead will be created in Marketo with the \$email user profile property value and the designated custom field will be set to True.

### Is there a limitation to the number of profiles that can be exported to Marketo?

The maximum cohort size exportable is 30 million profiles.

### Does Mixpanel export other profile properties to Marketo besides the user's email address?

No. At this time, Mixpanel will only export the \$email profile property.


# Moengage
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/moengage



## Overview

Export Mixpanel cohorts to MoEngage to create custom segments that you can apply in your MoEngage campaigns. Manage the MoEngage integration from the Mixpanel Destinations page.

# Permissions

You must be a Mixpanel project admin to enable the MoEngage integration.

## Enable the Integration

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select MoEngage, and click **Connect**.

<Note>
  If you set a User ID Property, it should be a Mixpanel user property that matches the MoEngage External ID. If you do not select one, Mixpanel will default to using the `$moengage_user_id` property to match users between MoEngage and Mixpanel. See more about [matching users between MoEngage and Mixpanel](/docs/cohort-sync/integrations/moengage#matching-users-between-moengage-and-mixpanel).
</Note>

<Frame>
  <img alt="Moengage 2 Image" />
</Frame>

3. The connection uses a Basic Authorization Username/Password system. You will need to provide two credentials to authorize the connection:

* Username: MoEngage APP ID
* Password: MoEngage API Key

You will additionally provide one credential to authorize the cohort exports:

* MOE-APPKEY: MoEngage APP ID

You can find these values in your MoEngage settings page - note that MoEngage App ID is used in both the Username and MOE-APPKEY fields.

<Frame>
  <img alt="Moengage 3 Image" />
</Frame>

4. The MoEngage integration will show a **Connected** tag in the UI once the connection succeeds.

## Matching Users between MoEngage and Mixpanel

<Warning>
  **Warning:** Projects using the [Simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.
</Warning>

Mixpanel only exports identified user profiles to match to MoEngage - users without user profile properties (i.e. anonymous users) will not export.

If the values you provide for users' distinct\_id differ from the values used for MoEngage's Unique ID, the user's Mixpanel profile must contain a user property, `$moengage_user_id`, whose value is a string representing that user's Unique ID in MoEngage. Exports will include this joining key to match the corresponding Unique ID in MoEngage.

In addition, when our ingestion service detects calls setting this user property, Mixpanel will also auto-alias the value of `$moengage_user_id` to the user's distinct\_id. This ensures that messaging data passed from MoEngage to Mixpanel still attributes to the correct user.

Note that exports are used solely for matching user identities between products - the integration will not send the full set of a user's profile properties to MoEngage, nor will it generate new user profiles in MoEngage.

## Export a Cohort

To export a cohort to MoEngage:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the MoEngage destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync. Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort and click **Export to MoEngage**.
    3. Click **Start Sync**.
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends MoEngage a static export of users who currently qualify for the cohort. The cohort data will not be updated in MoEngage after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and MoEngage every 15 minutes. The exported cohort will be updated every 15 minutes to reflect the most recent list of users in a cohort.

## Select the Custom Segment in MoEngage

Once the export completes, you will see a custom segment reflecting the set of users from your Mixpanel cohort (e.g. "Power Users"):

<Frame>
  <img alt="Moengage 6 Image" />
</Frame>

## MoEngage Events into Mixpanel & MTU exemptions

You can use events from your MoEngage integration to perform deeper analysis in Mixpanel.

Events coming from MoEngage are marked with the property `$source`.

Mixpanel will exempt certain messaging outreach events from MTU calculations, meaning you're free to send campaigns to dormant users without them counting towards MTU billing (only once a user engages with a message will they then be counted towards that tally).

The following MoEngage events are exempt from MTU calculations:

* Card Sent
* Card Delivered
* Connector Sent
* Email Sent
* Email Deferred
* Email Delivered
* Email Dropped
* Email Bounced
* Email Soft Bounced
* Notification Received Android
* Notification Sent iOS
* NOTIFICATION\_RECEIVED\_IOS\_MOE
* Notification Received Web
* SMS Sent
* SMS Delivered
* User Entered Flow
* User Exited Flow


# mParticle
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/mparticle



## Overview

This integration allows you to export Mixpanel Cohorts to [mParticle Feeds](https://docs.mparticle.com/guides/feeds/) to create [Audiences](https://docs.mparticle.com/guides/segmentation/audiences/overview/). This integration creates a user attribute in mParticle to represent cohort membership, which you can use to build or trigger [Audiences](https://docs.mparticle.com/guides/segmentation/audiences/overview/). By syncing your behavioral segments to mParticle, you can leverage Mixpanel’s deep analysis to power personalized experiences, targeted messaging, and audience suppression across the hundreds of downstream destinations supported by the mParticle CDP.

## Permissions

* **Mixpanel:** You must be a Mixpanel project admin to enable the mParticle integration.
* **mParticle:** You must have the necessary permissions in mParticle to create a Feed input and retrieve API credentials.

## Enable the Integration

This connection requires setup on both mParticle and Mixpanel.

### mParticle Setup

1. Log into your mParticle workspace.
2. Navigate to **Data Platform > Setup > Inputs**.
3. Select the **Feed** input type and search for **Mixpanel Cohorts**.

   <Frame>
     <img alt="mParticle 1 Image" />
   </Frame>

* Set Input Protection Level to Only Update Profiles to ensure only existing profiles can be updated and no new profiles will be created from cohort syncs.

4. Save and copy your **Webhook URL**.

   <Frame>
     <img alt="mParticle 2 Image" />
   </Frame>

### Mixpanel Setup

Mixpanel uses your mParticle API token to send data to the following endpoint: `https://inbound.mparticle.com/v1/pdf/mixpanelcohorts/{{customer_api_token}}`

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select **mParticle**, click **Connect**, and paste your **mParticle Webhook URL** into the box.
3. Click **Continue** to establish the connection.

   <Frame>
     <img alt="mParticle 5 Image" />
   </Frame>

***

## Export a Cohort

To export a Mixpanel cohort to mParticle:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the mParticle destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you wish to export.
    5. Select the sync type:

       * **One-Time Export:** A static snapshot of the cohort is sent immediately.
       * **Recurring (Dynamic) Sync:** Mixpanel will automatically update the audience in mParticle as users enter or exit the criteria.
    6. Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Find the cohort you wish to export, click the **three-dot overflow menu (...)**, and select **Export to... > mParticle**.
    3. Select the sync type:

       * **One-Time Export:** A static snapshot of the cohort is sent immediately.
       * **Recurring (Dynamic) Sync:** Mixpanel will automatically update the audience in mParticle as users enter or exit the criteria.
    4. Click **Start Sync**.

    <Frame>
      <img alt="mParticle 6 Image" />
    </Frame>
  </Tab>
</Tabs>

***

## Sync Types

### One-Time

In this sync, Mixpanel sends mParticle a static set of users who currently qualify for the cohort. The audience membership will not be updated in mParticle after this export.

### Dynamic (Recurring)

In a dynamic sync, Mixpanel initiates a sync every 15 minutes. Mixpanel sends "diffs" (adds and removes) to ensure that the user’s Audience membership in mParticle reflects their current state in Mixpanel.

***

## Setting \$mparticle\_user\_id in Mixpanel

If you find that Mixpanel Cohorts are not properly matching again mParticle Cohorts, this is most likely because the primary identifier in mParticle is not set in Mixpanel’s user profiles. This is easy to connect using one of the two below methods

### Set \$mparticle\_user\_id as a User Attribute via SDK (Recommended for Developers)

To ensure \$mparticle\_user\_id appears as a specific property on the user profile, you can manually set it as a user attribute in your app's code. Since mParticle forwards all user attributes to Mixpanel (if "Include User Attributes" is enabled), this is the most reliable method.

Web SDK Example:

```js theme={"system"}
const currentUser = mParticle.Identity.getCurrentUser();
if (currentUser) {
    const mpid = currentUser.getMPID();
    currentUser.setUserAttribute("$mparticle_user_id", mpid);
}
```

iOS (Swift) Example:

```swift theme={"system"}
if let currentUser = MParticle.sharedInstance().identity.currentUser {
    currentUser.setUserAttribute("$mparticle_user_id", value: currentUser.mpid.stringValue)
}
```

### Use mParticle Rules (No-Code)

If you cannot change your app's code, you can use mParticle Rules to automatically map the MPID to a user attribute before it is sent to Mixpanel.

Go to Data Plan > Rules in mParticle.

Create a new Rule for the Mixpanel Output.

Use the rule to copy the mpid from the batch level into the user\_attributes object as \$mparticle\_user\_id.

Logic: `batch.user_attributes['$mparticle_user_id'] = batch.mpid;`

Once the rule is active, every event sent to Mixpanel will include this attribute, and mParticle will update the Mixpanel People profile accordingly.

### Recommended Configuration Settings

For these connections methods to work as intended, ensure these toggles are active in your Mixpanel Connection Settings in mParticle:

Use Mixpanel People: Must be True (to enable user profiles). Include User Attributes: Must be True (to ensure the custom \$mparticle\_user\_id attribute is forwarded). Create Profile Only If Logged In: Set to True (typically we will only want profile + cohorts based on known/authenticated users)

***

## How the Sync Works

### Identity Mapping

To ensure users are correctly matched in mParticle, Mixpanel maps identifiers in the following order of priority:

1. `$mparticle_user_id`: If this property exists on the Mixpanel user profile, it will be used as the primary identifier.
2. `$distinct_id`: If `$mparticle_user_id` is not present, Mixpanel falls back to the standard `$distinct_id`.

### Data Format

Mixpanel sets a user attribute in mParticle to represent cohort membership. This allows you to build or trigger [Audiences](https://docs.mparticle.com/guides/segmentation/audiences/overview/) within mParticle based on these attributes.

When a user enters a cohort, Mixpanel sends an update to set the attribute to `true`:

```json theme={"system"}
{
  "user_attributes": {
    "<Cohort Name>": true
  }
}
```

When a user exits the cohort, Mixpanel updates the attribute to `false`:

```json theme={"system"}
{
  "user_attributes": {
    "<Cohort Name>": false
  }
}
```

***

## Verifying in mParticle

Once the export begins, you can verify the data flow in mParticle:

### Generic validation

1. Navigate to **Data Platform > Trends** (or Live Stream if you are using dev data).
2. Select your Mixpanel input feed in the inputs dropdown to see of user profile updates received from the mixpanel cohort sync.

   <Frame>
     <img alt="mParticle 3 Image" />
   </Frame>

### User specific validation (requires org setup and user permission for user profile lookup)

1. In your Mixpanel cohort grab the Mparticle User id
2. Go to mParticle > Customer 360 > User Profiles and search the user

   <Frame>
     <img alt="mParticle 4 Image" />
   </Frame>
3. Check that the user has a user attribute with the name of your cohort.

***

## Troubleshooting

### Discrepancies in User Count

The most common cause for mismatched user counts is missing identifiers. If a user in the Mixpanel cohort does not have an `$mparticle_user_id` or a valid `$distinct_id` that matches a record in mParticle, the sync will not be able to update that user.

To check for eligible users in Mixpanel:

1. Go to the **Users** report.
2. Filter for your cohort.
3. Add a filter to check if `$mparticle_user_id` is set. This shows the maximum number of users likely to match via the primary ID.

### Export is Paused

If your sync is marked as **Paused** in the Mixpanel Destinations page, hover over the status to see the error. This is usually caused by an invalid webhook url or a connection issue with the mParticle endpoint. You can typically resolve this by disconnecting and reconnecting the integration with a fresh API token.


# OneSignal
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/onesignal



## Overview

Export Mixpanel cohorts to OneSignal to create custom segments that you can apply in your OneSignal campaigns. Manage the OneSignal integration from the Mixpanel Destinations page.

OneSignal also supports an integration to send messaging interactions to Mixpanel - for more details, see [OneSignal's Mixpanel integration](https://documentation.onesignal.com/docs/mixpanel).

## Permissions

You must be a Mixpanel project admin to enable the OneSignal integration.

Additionally, you must have a paid OneSignal plan to use the integration. If you attempt to sync cohorts while on a free OneSignal plan, you will receive the following error: "App may not submit cohort updates from Mixpanel".

## Enable the Integration

Follow these steps to enable the integration with OneSignal:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select OneSignal, and click **Connect**.

<Note>
  If you set a User ID Property, it should be a Mixpanel user property that matches the OneSignal External ID. If you do not select one, Mixpanel will default to using the `$onesignal_user_id` property to match users between OneSignal and Mixpanel. See more about [matching users between OneSignal and Mixpanel](/docs/cohort-sync/integrations/onesignal#matching-users-between-onesignal-and-mixpanel).
</Note>

<Frame>
  <img alt="OneSignal 2 Image" />
</Frame>

3. You will need to provide two credentials to authorize the connection: **API Key and App ID**. You can find these values in your **OneSignal settings** page. The OneSignal integration will show a **Connected** tag in the UI once the connection succeeds.

## Matching Users between OneSignal and Mixpanel

<Warning>
  **Warning:** Projects using the [Simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the section below are primarily applicable to projects on the original ID merge system.
</Warning>

Mixpanel only exports identified user profiles to match to OneSignal - users without user profile properties (i.e., anonymous users) will not export.

To match an exported Mixpanel user to OneSignal, the user’s Mixpanel profile must contain a user property, `$onesignal_user_id`. The value of this property is a string representing that user’s External User ID in OneSignal. OneSignal recommends using External User ID, as it’s a cross-platform user identifier and allows for OneSignal’s email capabilities. In your implementation, reference your External User ID from OneSignal’s SDK and set the user property `$onesignal_user_id` on the user’s Mixpanel profile.

User profiles without this user property will **not** export to OneSignal - it is a requirement for user matching.

In addition, when our ingestion service detects calls setting this user property, Mixpanel will also auto-alias the value of `$onesignal_user_id` to the user's distinct\_id. This ensures that messaging data passed from OneSignal to Mixpanel continues to be attributed to the correct user.

## Export a Cohort

To export a cohort to OneSignal:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the OneSignal destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort and click **Export to OneSignal**.

    <Frame>
      <img alt="OneSignal 4 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends OneSignal a static export of users who currently qualify for the cohort. The cohort data will not be updated in OneSignal after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and OneSignal every fifteen minutes. The exported cohort will be updated every fifteen minutes to reflect the most recent list of users in a cohort.

## Select the Segment in OneSignal

Once the export completes, you will see a Segment reflecting the set of users from your Mixpanel cohort:

<Frame>
  <img alt="OneSignal 5 Image" />
</Frame>

## OneSignal Events into Mixpanel & MTU exemptions

OneSignal offers the ability to forward campaign interaction events to Mixpanel. For more detail, [please refer to OneSignal's integration guide](https://documentation.onesignal.com/docs/mixpanel).

Events coming from OneSignal are marked with the property `$source`.

Because OneSignal's event structure follows Mixpanel's naming convention for messaging events, it will have the same exemptions outlined in the MTU calculation guide for which events do not count towards MTU tallies. Message delivery events will not count towards a user being in MTU counts, while message engagement events will.

The following OneSignal events are exempt from MTU calculations:

* \$app\_open (App Opened from Push)
* \$campaign\_delivery (Message Sent)
* \$campaign\_received (Message Received)
* \$campaign\_open (Message Opened)


# Salesforce Marketing Cloud
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/salesforce-marketing-cloud



## Overview

This integration lets you export cohorts from Mixpanel to Salesforce Marketing Cloud (SFMC).

Once the one-time setup process is done, it's easy to sync cohorts on a recurring basis entirely from the Mixpanel UI.

## Permissions

You must be a Mixpanel project admin to enable the SFMC integration.

## Enable the Integration

This process will require setup on both SFMC and Mixpanel.

### SFMC Setup

1. Navigate to **Setup → Apps → Installed packages**. Then create a package with with a Scope that provides **read/write access to DataExtensions**. Keep track of the following information (highlighted above) -- it will be useful to connect Mixpanel to SFMC:

* **Client Id**
* **Client Secret**
* **Subdomain**

<Frame>
  <img alt="SFMC 1 Image" />
</Frame>

2. Navigate to **Audience Builder → Contact Builder → Data Extensions** to Create a New Data Extension.

<Frame>
  <img alt="SFMC 2 Image" />
</Frame>

3. Create a new **Data Extension** with a primary key of the name **SubscriberKey**. The key type for most use-cases will stay as **Text** and size of 250 characters unless you are selecting email or phone number as the id in which you can find corresponding data types. This field will contain ids that map to the unique user property in Mixpanel.

<Frame>
  <img alt="SFMC 3 Image" />
</Frame>

4. Note the **External Key** (underlined below) for setup on Mixpanel.

<Frame>
  <img alt="SFMC 4 Image" />
</Frame>

### Mixpanel Setup

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Salesforce Marketing Cloud, and click **Connect**. The following details are needed:

* **Data Extension External Key**
* An optional user property (distinct\_id will be used by default). This will sync to the SubscriberKey field
* **client\_id**, **client\_secret**, **subdomain**

<Frame>
  <img alt="SFMC 6 Image" />
</Frame>

3. The SFMC integration will show a **Connected** tag in the UI once the connection succeeds.

## Matching Users between SFMC and Mixpanel

You can select any user property to sync to SFMC as the subscriber key. Once the user ID is set you cannot change it later as this can cause corruption in the Data Extension. If you absolutely need to change this field, you should recreate the Data Extension.

User profiles without the above selected user property will **not** export to SFMC - it is a requirement for user matching.

## Export a Cohort

To export a cohort from Mixpanel to SFMC:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Salesforce Marketing Cloud destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.

    <Frame>
      <img alt="SFMC 7 Image" />
    </Frame>

    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click Export to > SFMC. Select either one-time sync or dynamic sync. Click **Start Sync**.

    <Frame>
      <img alt="SFMC 8 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync.

### One-Time Export

In a one-time export, Mixpanel sends SFMC a static export of users who currently qualify for the cohort. The cohort data will not be updated in SFMC after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and SFMC every 15 minutes. The exported cohort will be updated every 15 minutes to reflect the most recent list of users in a cohort.

## Data Extension in SFMC

The cohort data will be exported to the SFMC Data Extension that was set up above. New cohorts are added as property fields to the data extension.

<Frame>
  <img alt="SFMC 9 Image" />
</Frame>

Each record in the Data Extension is a user and its properties show the membership of this user in different cohorts.

<Frame>
  <img alt="SFMC 10 Image" />
</Frame>


# Segment
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/segment



## Overview

This integration allows you to export Cohorts of users from Mixpanel to Segment so that you can better target users across many downstream connections.

## Permissions

You must be a Mixpanel project admin to enable the Segment integration.

## Enable the Integration

This connection requires set up on both Segment and Mixpanel.

### Segment Setup

The connection requires a Segment Write Key. You can obtain this key via Segment's UI:

1. Log into your Segment workspace and click **Sources** under **Connections** in the menu bar on the left.
2. Click **Add Source** button on the right side above the sources table.
3. Search for **Mixpanel Cohorts**, select and hit next

<Frame>
  <img alt="Segment 1 Image" />
</Frame>

4. Create a Mixpanel Cohorts source.

<Frame>
  <img alt="Segment 2 Image" />
</Frame>

5. Copy the **Write Key** displayed there.

<Frame>
  <img alt="Segment 3 Image" />
</Frame>

### Mixpanel Setup

We will use the Write Key from Segment to enable the connection in Mixpanel.

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Segment, click **Connect**, and paste the **Write Key** that you generated in Segment.

<Note>
  If you set a User ID Property, it should be a Mixpanel user property that matches the Segment User ID.
</Note>

<Frame>
  <img alt="Segment 5 Image" />
</Frame>

3. Click **Continue** to complete the process.

## Export a Cohort

To export a Mixpanel cohort into Segment.

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Segment destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the overflow menu on cohort that you want to export and click Export to... → Segment.

    <Frame>
      <img alt="Segment 6 Image" />
    </Frame>

    3. Select either one-time sync or dynamic sync, Click **Start Sync**.
  </Tab>
</Tabs>

## Sync Types

There are two types of sync: one-time and dynamic. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time

In this sync, Mixpanel sends Segment the static set of users who currently qualify for the cohort. The cohort data will not be updated in Segment after a one-time export.

### Dynamic

In dynamic sync, Mixpanel initiates sync between a cohort and Segment every 15 minutes. The exported cohort will be updated every 15 minutes to reflect the most recent list of users in a cohort.

## Verifying in Segment

Once the export completes, you can open the debugger on the source you created in Segment above and you'll see "identify" calls flowing in for each user that has been added or removed from the cohort.

<Frame>
  <img alt="Segment 7 Image" />
</Frame>

Mixpanel sets a property on the user's profile in Segment indicating whether they are currently part of the cohort.

We send the following identify call to Segment when a user enters the cohort:

```json theme={"system"}
{
  "type": "identify",
  "traits": {
    "Mixpanel - <Cohort Name in Mixpanel>": true,
  },
  "userId": "user@email.com" // we use the distinct_id property here
}
```

We send the following when a user exits the cohort:

```json theme={"system"}
{
  "type": "identify",
  "traits": {
    "Mixpanel - <Cohort Name in Mixpanel>": false,
  },
  "userId": "user@email.com" // we use the distinct_id property here
}
```


# Taplytics
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/taplytics



## Overview

Export Mixpanel cohorts to Taplytics to create custom segments that you can apply in your Taplytics experiments, feature flags, and more. Manage the Taplytics integration from the Mixpanel Destinations page.

Taplytics also supports an integration to send experiment data to Mixpanel - for more details, [see the Taplytics Mixpanel integration](https://docs.taplytics.com/docs/guides-integrations-for-ios#mixpanel).

## Permissions

You must be a Mixpanel project admin to enable the Taplytics integration.

## Enable the Integration

To enable the integration with Taplytics:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Taplytics, and click **Connect**.

<Frame>
  <img alt="Taplytics 2 Image" />
</Frame>

3. The connection uses one credential to authorize, **API Key**. Supply an API token generated from your **Taplytics settings page** to establish the connection.
4. The Taplytics integration will show a **Connected** tag in the UI once the connection establishes.

## Matching Users between Taplytics and Mixpanel

Mixpanel only exports identified user profiles to match to Taplytics - users without user profile properties (i.e. anonymous users) will not export.

The integration requires that you use the same system of identifiers for both tools, meaning the value you pass to `mixpanel.identify("internal_user_id")` will have the same value as you pass to Taplytics when specifying `userId` to your Taplytics API calls. Taplytics will attempt to match users from inbound cohorts based on their Mixpanel distinct\_id.

## Export a Cohort

To export a Cohort to Taplytics:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Taplytics destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click **Export to > Taplytics**. Select either one-time sync or dynamic sync. Click **Start Sync**.
  </Tab>
</Tabs>

<Frame>
  <img alt="Taplytics 3 Image" />
</Frame>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Taplytics a static export of users who currently qualify for the cohort. The cohort data will not be updated in Taplytics after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and Taplytics every two hours. The exported cohort will be updated every day to reflect the most recent list of users in a cohort.

## Select the Segment in Taplytics

Once the export completes, you will see a Segment reflecting the set of users from your Mixpanel cohort in Taplytics's Segment editor, as custom data (e.g. "Beta Users"):

<Frame>
  <img alt="Taplytics 4 Image" />
</Frame>


# VWO
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/vwo



## Overview

Export Mixpanel cohorts to VWO to create custom segments that you can apply in your VWO experiments. Manage the VWO integration from the Mixpanel Destinations page.

VWO also supports an integration to send experiment data to Mixpanel - for more details, see [the VWO Mixpanel integration](https://help.vwo.com/hc/en-us/articles/900004226426).

## Permissions

You must be a Mixpanel project admin to enable the VWO integration.

## Enable the Integration

To enable the integration:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select VWO, and click **Connect**.

<Frame>
  <img alt="VWO 2 Image" />
</Frame>

3. The connection uses one credential to authorize, **API Key**. Supply an API token generated from your **VWO settings page** to establish the connection.
4. The VWO integration will show a **Connected** tag in the UI once the connection establishes.

## Matching Users between VWO and Mixpanel

> **Warning:** Projects using the [simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.

Mixpanel only exports identified user profiles with the user property `$vwo_user_id` to match to VWO - users without user profile properties (i.e. anonymous users) will not export. The value of this property should equal a matching User ID in VWO.

If you have the VWO SDK present in your application, it will automatically declare the `$vwo_user_id` property on users' Mixpanel profiles. If the VWO SDK is not on your application, you can declare the user properties either through Mixpanel's own SDKs or HTTP API. VWO will attempt to match users from inbound cohorts based on the value seen on `$vwo_user_id`.

In addition, when our ingestion service detects calls setting this user property, Mixpanel will also auto-alias the value of `$vwo_user_id` to the user's distinct\_id. This ensures that experiment data passed from VWO to Mixpanel still attributes to the correct user.

## Export a Cohort

To export a Cohort to VWO:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the VWO destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**. Do note: VWO has a 15MB export limit for profiles in the cohort.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click **Export to > VWO**. Select either one-time sync or dynamic sync. Click **Start Sync**. Do note: VWO has a 15MB export limit for profiles in the cohort.

    <Frame>
      <img alt="VWO 3 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends VWO a static export of users who currently qualify for the cohort. The cohort data will not be updated in VWO after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and VWO every two hours. The exported cohort will be updated every day to reflect the most recent list of users in a cohort.


# Webengage
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/webengage



## Overview

Export Mixpanel cohorts to WebEngage to create custom segments that you can apply in your WebEngage campaigns. Manage the WebEngage integration from the Mixpanel Destinations page.

## Permissions

You must be a Mixpanel project admin to enable the WebEngage integration.

## Enable the Integration

To enable the integration:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select WebEngage, and click **Connect**.
3. Enter the [WebEngage API Key](https://docs.webengage.com/docs/rest-api-getting-started#getting-your-credentials) from your WebEngage dashboard.

<Frame>
  <img alt="Webengage 2 Image" />
</Frame>

4. The WebEngage integration will show a **Connected** tag in the UI once the connection succeeds.

## Matching Users between WebEngage and Mixpanel

Mixpanel only exports identified user profiles to match to WebEngage - users without user profile properties (i.e. anonymous users) will not export.

The exported users are properly mapped in WebEngage's system only if the resolved distinct\_id in Mixpanel and the User ID in WebEngage have the same value. If no match is found, WebEngage will create new user profiles for the users exported from Mixpanel.

## Export a Cohort

To export a Mixpanel Cohort to WebEngage:

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the WebEngage destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click **Export to WebEngage**. Select either one-time sync or dynamic sync. Click **Start Sync**.

    <Frame>
      <img alt="Webengage 3 Image" />
    </Frame>
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends WebEngage a static export of users who currently qualify for the cohort. The cohort data will not be updated in WebEngage after the one-time export is complete.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and WebEngage every 30 minutes. The exported cohort will be updated every 30 minutes to reflect the most recent list of users in a cohort.

<Frame>
  <img alt="Webengage 4 Image" />
</Frame>


# Xtremepush
Source: https://docs.mixpanel.com/docs/cohort-sync/integrations/xtremepush



## Overview

The Xtremepush integration allows you to combine behavioral analytics with attribution and engagement data for targeted and relevant customer communication.

Export Mixpanel cohorts to Xtremepush, as a one-off or via automated, scheduled imports, to use as part of your segmented campaign sends. All cohorts are synced into Xtremepush as a matching list so they are simple to find afterwards.

Import Xtremepush Campaign engagement data to Mixpanel dashboards for richer understanding of your customers behavior across all channels.

## Permissions

You must be a Mixpanel project admin to enable the Xtremepush integration.

## Enable the Integration

To enable the integration:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select Xtremepush, and click **Connect**.
3. The Xtremepush integration will show a **Connected** tag in the UI once the connection succeeds.

## Matching Users between Xtremepush and Mixpanel

Mixpanel only exports identified user profiles to match to Xtremepush - users without user profile properties (i.e. anonymous users) will not export.

Xtremepush uses a given user's distinct\_id to match the Mixpanel user profile to Xtremepush. As a result, not all exported profiles may match if these values are missing or differ from the emails and phone numbers stored on Insider.

Note that exports are used solely for matching user identities between products - the integration will not send the full set of a user's profile properties to Xtremepush, nor will it generate new users.

## Export a Cohort

You can export a cohort to Xtremepush from the Cohorts report.

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Xtremepush destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to export and configure the sync (one-time or dynamic). Click **Start Sync**.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab to view all of your cohorts.
    2. Select the cohort that you want to export. Click on the three-dot icon on the right side of the cohort.
    3. Click **Export to Xtremepush**. Select either one-time sync or dynamic sync. Click **Start Sync**.
  </Tab>
</Tabs>

## Sync Types

This integration supports two types of exports: one-time export and dynamic sync. When you generate a one-time export or dynamic sync, it overwrites the previous export with an updated export that reflects users who qualify for the cohort at the time of export.

### One-Time Export

In a one-time export, Mixpanel sends Xtremepush a static export of users who currently qualify for the cohort. The cohort data will not be updated in Xtremepush after a one-time export.

### Dynamic Sync

In dynamic sync, Mixpanel initiates sync between a cohort and Xtremepush every two hours. The exported cohort will be updated every two hours to reflect the most recent list of users in a cohort.

## Select the Custom Segment in Xtremepush

Once the export completes, you will see a custom segment reflecting the set of users from your Mixpanel cohort (e.g. "7days-cart-abandoners"):

## Xtremepush Events into Mixpanel & MTU exemptions

You can use events from your Xtremepush integration to perform deeper analysis in Mixpanel.

Events coming from Xtremepush are marked with the property `$source`.

Mixpanel will exempt certain messaging outreach events from MTU calculations, meaning you're free to send campaigns to dormant users without them counting towards MTU billing (only once a user engages with a message will they then be counted towards that tally).

The following Xtremepush events are exempt from MTU calculations:

* xp.message.send.batch (EVENT\_MESSAGE\_SEND\_BATCH)
* xp.message.delivery (EVENT\_MESSAGE\_DELIVERY)
* xp.message.bounce (EVENT\_MESSAGE\_BOUNCE)
* xp.message.open (EVENT\_MESSAGE\_OPEN)
* xp.message.click (EVENT\_MESSAGE\_CLICK)
* xp.message.unsubscribe (EVENT\_MESSAGE\_UNSUBSCRIBE)
* xp.message.complaint (EVENT\_MESSAGE\_COMPLAINT)


# Syncing cohorts to a custom webhook
Source: https://docs.mixpanel.com/docs/cohort-sync/webhooks



Mixpanel lets you sync cohorts to a custom webhook URL that you provide through the Destinations page. After you establish a sync, Mixpanel sends the full cohort to the URL and then sends incremental updates that include users who enter or exit the cohort since the previous sync.

This capability allows you to export cohorts to destinations that do not have a [native Mixpanel integration](/docs/cohort-sync/integrations).

## Prerequisites

* A paid Mixpanel plan
* A Mixpanel project
* A webhook server. You can create a dummy webhook for testing purposes using [webhook.site](https://webhook.site/).
* The webhook server should send back events to Mixpanel to track actions like 'Message sent', etc. (This is optional, but customers who need this have to implement it themselves) Customers can follow the naming convention mentioned in this [document](/docs/admin/pricing-plans#mtu-calculation) to avoid certain events from being considered for MTU tallies.

## Setting up the webhook via our UI

To create a new Custom Webhook destination:

1. Navigate to **Data** in the nav bar, then select **Destinations**.
2. Click **Add Destination**, select **Webhook**, and click **Connect**.
3. Provide a name for the connection and the URL of your webhook server. Optionally, enable Basic Authentication for calls to the webhook URL.

<Frame>
  <img alt="image" />
</Frame>

From this point onward, you can sync any cohort to this connection.

### Initialize a Cohort Sync to the Webhook

<Tabs>
  <Tab title="From the Destinations page (recommended)">
    1. Navigate to **Data** in the nav bar, then select **Destinations**.
    2. Find the Webhook destination in the list and click on it.
    3. Click the **Syncs** tab, then click **Add Cohort Sync**.
    4. Select the cohort you want to sync and configure the sync.
  </Tab>

  <Tab title="From Lexicon">
    1. Navigate to **Lexicon**, then select the **Cohorts** tab.
    2. Click the three-dot menu next to the cohort you want to sync and select **Export to... > Webhook**.
    3. Choose a one-time export or a recurring sync, then click **Start Sync**.
  </Tab>
</Tabs>

### Exported Properties

Mixpanel will automatically include `email`, `mixpanel_distinct_id`, `first_name`, and `last_name` to identify the user. If you need to add extra properties, feel free to add them in the `Properties to Export` field, where we populate some pre-existing fields for you to choose.

## Webhook Format

Our webhook format has the following structure in the body of a `POST` request:

* **action**: The action defines the type of message we are sending. It will be one of:

  * `members`: All members of the cohort, sent the first time the cohort is being synced or to refresh the cohort if there are any intermediate errors. When you get this message, replace the users you have in the cohort with the copy provided by us.
  * `add_members`: A diff consisting of users who have entered the cohort since the last sync.
  * `remove_members`: A diff consisting of users who have exited the cohort since the last sync.
* **parameters**

  * **mixpanel\_project\_id**: the ID for the Mixpanel project that produced this cohort.
  * **mixpanel\_cohort\_id**: unique identifier of the cohort.
  * **mixpanel\_cohort\_name**: The cohort name, editable via the Mixpanel UI.
  * **mixpanel\_cohort\_description**: The cohort description, editable via the Mixpanel UI.
  * **mixpanel\_session\_id**: An identifier for this export. Mixpanel sends large cohorts over multiple messages; mixpanel\_session\_id uniquely identifies a set of requests that correspond to the same export.
  * **page\_info**: An object containing “total\_pages”, i.e., the number of total messages for the given session ID, and “page\_count”, the index of which page this message is (e.g., message 6 of 10, in the example below). You may use this value to know if/when you’ve collected the full set of messages for an export.
  * **members**: The list of users being added or removed from the cohort. We include `email`, `mixpanel_distinct_id`, `first_name`, and `last_name` to help identify the user. You may [specify additional properties](/docs/cohort-sync/webhooks#exported-properties) during setup.

You can download the Swagger spec [here](https://mxpnl.notion.site/Cohort-Webhook-Yaml-17d35e8ca78245fdbfa0aa4fcbb56596).

```json theme={"system"}
{
  "action": "members",
  "parameters": {
    "mixpanel_project_id": "{mixpanel_project_id}",
    "mixpanel_cohort_name": "{mixpanel_cohort_name}",
    "mixpanel_cohort_id": "{mixpanel_cohort_id}",
    "mixpanel_cohort_description": "description",
    "mixpanel_session_id": "mixpanel_session_id",
    "page_info": {
      "total_pages": 10,
      "page_count": 6
    },
    "members": [
      {
        "email": "string",
        "mixpanel_distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "phone_number": "xxx-xxx-xxxxx"
      },
      {
        "email": "string",
        "mixpanel_distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "phone_number": "xxx-xxx-xxxxx"
      }
    ]
  }
}
```

## Expected Response Format

We expect a JSON response of the following shape.

* **action**: Must match the action we sent.
* **status**: Must be either `success` or `failure`.
* **error**: Only expected on failure.

  * **message**: details about the error.
  * **code**: an HTTP status code.

```json theme={"system"}
{
  "action": "add_members",
  "status": "success", // or failure
  "error": {
    "message": "some error message; this will be displayed in our UI",
    "code": 400 // an HTTP status code
  }
}
```

## Sync

Cohorts are synced once every 30 minutes. The batch size is set to 1000 users per call to `add_members` or `remove_members`.

### Full Sync

Full syncs are only performed when:

* We sync the cohort for the first time.
* We store the snapshot of the cohort state for the last successful sync for 3 days. If your webhook server is down (returns a 429 or 5XX error) for more than 3 days, the snapshot expires, and we do a full sync.

Subsequent syncs include only differences in membership since the previous successful sync in order to preserve bandwidth, through a [diffing](/docs/cohort-sync/webhooks#diffing) mechanism.

### Diffing

Every time we perform a successful sync to your webhook, we store a snapshot of the cohort as of that time. This snapshot is valid for 3 days. Subsequent syncs use the last successful snapshot of the cohort to compute the number of users added and removed (the diff). We send this diff to your webhook via the `add_members` and `remove_members` calls.

### Example Webhook Sync Scenario

Consider A, B, C, D, E, and F as users. The sync interval is 30 minutes. T represents the time when the sync is created in our UI.

`add_members(...)` indicates a call to the webhook to add members. `remove_members(...)` indicates a call to remove members.

* **T**: `add_members(A, B, C, D)` | `remove_members()`
* **T+10mins**: B, D leave the cohort
* **T+20mins**: E, F join the cohort
* **T+30mins**: `add_members(E, F)` | `remove_members(B, D)`
* \<...No cohort changes...>
* **T+1h**: `add_members()` | `remove_members()` calls are made to the customer webhook

### Failed Syncs

We pause syncs when your server returns a non-transient error (400, 401, 403, 404). Please use the appropriate HTTP status code to indicate a non-transient error; this helps avoid added load. We record failed syncs in our UI and display the error message returned in the response from your webhook server (see the `error.message` field in the sample response above).

A notification email is sent to all users who have set up cohort syncs when the syncs pause due to an error.

We retry syncs 5 times over 60 secs with exponential backoff in response to 5xx and 429 status codes. After this point, we will wait until the next scheduled sync to retry.

#### Diffs After Failed Syncs

When a sync fails, we do not update the cohort snapshot. The next sync performed will recompute the diff based on the last successful snapshot (until 3 days have passed, at which point we will attempt to sync the full cohort). This ensures that the state of the cohort will converge to what Mixpanel has.

## FAQ

**Does page\_count in the requests start from 0 or 1?**

The page\_count starts from 1.

**Are users within the cohort re-synced when webhook calls fail or there is an internal failure?**

Even though we just sync a diff of users for each cohort, there can be failures that occur mid-sync. In a case like this, we don't have a mechanism to keep track of users that were already synced for a cohort when the failure occurs in between the sync process, so we start the sync from the top again. This can cause issues like users being synced again.

**What can go wrong for custom webhooks when users are synced again after failure scenarios?**

For example, if these users are set up for some action upon arrival, this failure and recovery could trigger a duplicate action for the same user.

This can be fixed on the custom webhook server-side by keeping track of users who have already been targeted with the action. This way, during failure and recovery scenarios of cohort syncs, duplicate actions for the same users can be avoided.

**How are actions tracked in Mixpanel?**

The actions are not automatically tracked in Mixpanel as they occur on the customer-side webhook server. Customers have to explicitly track events back to Mixpanel in order to use them on the Mixpanel platform.

**How can I edit a webhook's URL after creating it?**

It's not possible at this moment to edit a webhook's URL; the only available action via UI is to disconnect it.

**How can I delete/remove a webhook from the Destinations page?**

It's not possible at this moment to delete or remove a webhook from your project's Destinations page; the only available action via UI is to disconnect it.


# Community
Source: https://docs.mixpanel.com/docs/community



<CardGroup>
  <Card title="Slack Community" href="https://community.mixpanel.com/" />

  <Card title="Guidelines" href="/docs/community/guidelines" />
</CardGroup>


# Guidelines
Source: https://docs.mixpanel.com/docs/community/guidelines



You can join our Slack Community [here](https://www.mixpanel.com/community-slack)!

## General guidelines

Mixpanel, Inc. (“Mixpanel”) provides the Mixpanel Community (“the Community”) to you as a place to share new product ideas, ask questions, plan your analytics strategy, find technical solutions, and learn how to use Mixpanel. While we want this to be a transparent community with free-flowing discussion, we do have some guidelines.

1. ID yourself. When creating an account, please edit your profile to include your company, title, and a photo (if you can). Try to use your Mixpanel @business address so the Community can better identify you.
2. Become a power user. Have the answer to someone’s question? Jump in and share your knowledge. There is no stigma in being a “know-it-all” here. In fact, we encourage it!
3. One you, one account. Please create only one account per person. Don’t misrepresent yourself (e.g., lie about your identity, affiliations, or age). Don’t pretend to be someone that you’re not, or intentionally give misleading or false information.
4. Keep it clean. Cursing, harassment, threatening language, violent content, nudity, and sexually explicit obscene material or the like are not permitted in the Community.
5. No spam. We have zero tolerance for it. Posted content should be related to sharing knowledge about Mixpanel. Don’t post irrelevant content.
6. No selling. If it is relevant to the conversation, you are free to share information about products and services that you love. However, do not use the Community to prospect or link out to your website for commercial or promotional purposes or for political campaigning.
7. Ownership/Confidentiality. Do not post content that you do not have the right to publish. Additionally, do not post information that is confidential or that may be considered “Customer Content” under Mixpanel’s Terms of Use or separate Master Services Agreement.
8. Privacy. Do not post other people's personal information, such as phone numbers, private email addresses, physical addresses, credit card numbers, Social Security/National Identity numbers, or passwords. Your use of the Community is subject to Mixpanel’s Privacy Statement.
9. No bullying, harassment, or trolling. We do not tolerate bullying, harassment, or trolling. This means any habitual badgering, or intimidation targeted at a specific person or group of people or trying to get a rise out of someone for the sake of it.
10. No hate speech. Don’t post any content that demeans, defames, or promotes discrimination on the basis of race, ethnicity, national origin, religion, sexual identity or orientation, gender identity or expression, disability, or veteran status.

## What happens if someone breaks the rules?

While Mixpanel does not regularly review posted content, if you violate these guidelines, Mixpanel may take whatever action Mixpanel determines, in its sole discretion, is appropriate in response, including, but not limited to: removing the offending content, suspending your account, terminating your account, or even notifying law enforcement. If your account is terminated for violating these Community Terms of Use, you may not use the Community again. Please take these guidelines seriously and honor them in the spirit in which they are intended. We’ll do our best to enforce them consistently and fairly, and ultimately we’ll try to do what we think is best in each situation. To report inappropriate behavior or content, please write to [community@mixpanel.com](mailto:community@mixpanel.com).

## Copyright Infringement

If you believe that work belonging to you has been copied onto the Community without your permission, please review Mixpanel’s DMCA Copyright Policy and notify us at [legal@mixpanel.com](mailto:legal@mixpanel.com).

## Legal Notices

By posting content to the Community, you grant Mixpanel any license necessary, including any sublicense rights, to use, reproduce, modify, adapt, publish, translate, create derivative works from, distribute, and display such content in connection with the Community or Mixpanel’s legitimate business purposes.

The majority of the content in the Community is user-generated. Such third-party content is the sole responsibility of the person originating the content. The Community does not control and is not responsible for this third-party material. Mixpanel and its suppliers will not be liable or responsible in any way for any content on the Community, including, but not limited to, any accuracy, reliability, usefulness, or errors or omissions in any content, nor will they be liable for any losses or damages of any kind, including indirect, incidental, special, consequential or exemplary damages.

For the avoidance of doubt, use and provisioning of Mixpanel’s services are subject to separate terms, such as Mixpanel’s Terms of Use. In case of a discrepancy between these Community Terms of Use and those separate terms, the separate terms will prevail, provided, for clarity, that content posted to the Community does not constitute generally available documentation provided by Mixpanel.

As of Sept 12th, 2023, Mixpanel is piloting the use of a chatbot powered by [kapa.ai](https://kapa.ai) in the Mixpanel Slack Community. [kapa.ai](https://kapa.ai)'s chatbot generates responses to your questions automatically by leveraging [OpenAI LLC's](https://openai.com/) generative AI model, trained using Mixpanel's Docs. Your questions and answers to the @kapa.ai will be processed by [Kapa.ai](https://kapa.ai) and [Open.ai](https://openai.com/).


# Data Governance
Source: https://docs.mixpanel.com/docs/data-governance



Mixpanel has an extensive suite of data monitoring and management tools, take a look below:

<CardGroup>
  <Card title="Lexicon - Data Dictionary" href="/docs/data-governance/lexicon" />

  <Card title="Data Views & Classification" href="/docs/data-governance/data-views-and-classification" />

  <Card title="Data Standards" href="/docs/data-governance/data-standards" />

  <Card title="Event Approval" href="/docs/data-governance/event-approval" />

  <Card title="Data Volume Monitoring" href="/docs/data-governance/data-volume-monitoring" />

  <Card title="Data Clean-Up" href="/docs/data-governance/data-clean-up" />
</CardGroup>


# AI-Powered Data Governance
Source: https://docs.mixpanel.com/docs/data-governance/ai-powered-data-governance



Mixpanel uses AI to help you keep your project clean and well-governed with less manual effort. Instead of hunting through Lexicon by hand, these capabilities proactively surface issues in your data and let you resolve them in bulk.

<Info>
  AI-Powered Data Governance is available to organizations on an **Enterprise** plan that have Mixpanel's AI features (Mixpanel Agent) enabled in your organization settings. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Info>

## Merge suggestions

Over time, the same concept often ends up tracked under several names — `Add to Cart`, `add_to_cart`, and `addToCart`, or `from_date` and `from-date`. These duplicates clutter Lexicon, split your data across reports, and make analysis harder.

Merge suggestions automatically discover these potential duplicates in your project for you, so you don't have to hunt for them by hand. Mixpanel groups near-duplicate **events** and **event properties** together and suggests a single canonical name for each group, so you can clean them up in bulk instead of merging one pair at a time.

<Info>
  Merge suggestions cover events and event properties only — user (profile) properties cannot be merged at this time.
</Info>

To review and apply merge suggestions:

1. Open [Lexicon](/docs/data-governance/lexicon) and click **Tidy Up**, then **Reduce clutter**.

   <img alt="Tidy Up entry point in Lexicon" />

2. The **Merge Duplicate Events and Properties** window opens, listing the suggested groups of duplicates in two sections — Events and Event Properties.

   <img alt="Merge suggestions modal listing duplicate events and properties" />

3. Review the suggestions. **Every group is selected by default.** Each group shows the near-duplicate names it found and the canonical name they'll merge into. To change the canonical name or drop a name from a group, edit the group before submitting.

4. Uncheck any group you don't want to merge, or use **Select all** / **Deselect all** to adjust the whole list at once.

5. Click **Merge Duplicates** to submit.

<Warning>
  Submitting is a single batch action: **selected groups are merged, and every unselected group is dismissed** so it won't be suggested again. If you want to keep a suggestion for later, leave the window without submitting rather than deselecting it.
</Warning>

Merging behaves exactly like a [manual Lexicon merge](/docs/data-governance/lexicon#merging-data) — the underlying raw data is unaffected, and a merge can be undone from Lexicon. As with any merge, update any reports or custom events that referenced the old names afterward, and note that [Autocapture](/docs/tracking-methods/autocapture) events cannot be merged. Merging requires the same permission as a manual merge.


# Data Clean-Up
Source: https://docs.mixpanel.com/docs/data-governance/data-clean-up



## Types of data clean-up

Usually, data "clean-up" comes in two primary forms:

1. Cleaning up data mess that accumulates naturally over time
2. Deleting problematic data stemming from acute issues (e.g. implementation bugs, bot traffic, PII)

In this page, we'll help you address both forms of data clean-up

## 1. Cleaning up data when it naturally gets messy

Even if you start with strong data governance and best practices about how to structure your data, data can get messy over time (e.g. as your product expands or is updated, or as new data governance owners move on).

In this section, we will look at tips and tricks on how to clean up messy data when it gets out of hand.

### Automatically find duplicates with merge suggestions

If you're on an Enterprise plan with AI features enabled, Mixpanel can automatically discover duplicate events and event properties for you and merge them in bulk. See [AI-Powered Data Governance → Merge suggestions](/docs/data-governance/ai-powered-data-governance#merge-suggestions).

### Leverage Lexicon for a quick spot check

#### Blocking events that are not queried

[Lexicon](/docs/data-governance/lexicon) is our data dictionary in Mixpanel, and is where project owners and admins can add / manage descriptions for all events and properties to organize your data.

* Order by volume descending. Are your users querying events with large volume? If not, you might want to think about blocking these events. Blocking events means that they will no longer be ingested in Mixpanel. This is especially helpful for apps, since you don’t need to release new app versions and wait for users to download the latest versions for the code change to take effect (we still recommend that you clean up the code on the backend though!).
* Sometimes, customers may still want these large volume events because they rely on them downstream (via data pipelines). But if you’re not querying the events in Mixpanel itself, you shouldn’t send it in - if you’re on the [events plan](/docs/pricing#monthly-events-calculation), this increases your utilization; also, this clutters up the UI for users who don’t need to see it there. You could hide the event in the UI in Lexicon, but our recommended approach is to not send this data into Mixpanel at all.
* If you’re leveraging our SDKs and want to continue doing so for ease of leveraging our ID management and default properties, an alternative is to route events from [Mixpanel’s SDKs via a proxy in your own domain](/docs/tracking-methods/sdks/javascript). This way, you get to push the events required for backend analyses directly into your warehouse, and send only the events users query in our UI to Mixpanel

#### Cleaning up display names and adding descriptions for events

It’s always helpful to add descriptions to your events so users know where they are triggered. If you’re an owner or admin, you can add the descriptions directly on the UI itself. You could also export the data into a CSV, update the description there, then import it back into Lexicon if it’s easier to clean up that way. If you leverage Segment, mParticle, or Avo.app, you can use that to import your event names and descriptions that way too.

If you use Figma to identify your events, some customers add their links to the event descriptions as well.

#### Adding tags to events

<Frame>
  <iframe />
</Frame>

### Using custom events to combine or filter events

<Frame>
  <iframe />
</Frame>

### Cleaning up user profiles

If you want to clean up old user profile properties that are no longer being used, you can use our [Engage API](/reference/profile-delete-property) to remove these old user properties. We also provide a ‘people\_unset’ method in the Mixpanel-utils Library [here](https://github.com/mixpanel/mixpanel-utils#unset-properties).

## 2. Deleting problematic data

Data Deletion allows you to delete noisy or sensitive data from your Mixpanel project, helping you maintain the integrity of your analytics project, and preserve a clear view of user behavior.

You might find this useful if you:

* accidentally send Personal Identifiable Information (PII) in a property
* have implementation issues leading to duplicated data
* experience bot traffic issues that clutter an important event

In addition to permanently deleting the chosen data from our servers, we will immediately hide the data in your project so your users don’t accidentally view or analyze incorrect/sensitive data.

Unlike [**Hiding Events**](https://mixpanel.com/blog/now-you-can-hide-events-and-properties/) or [**Data Views**](/docs/data-governance/data-views-and-classification), Data Deletion affects your entire project, and can allow you to remove a subset of problematic events from an otherwise useful event.

### Is data deletion right for my problem?

Data Deletion is a severe action with permanent consequences. Thus, we recommend it only in a few scenarios:

| Scenario                                                                                                                               | Recommendation                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Bot attack sent spam events I don’t want to consider in my analysis                                                                    | Yes, use Data Deletion with targeted event property filters to delete spam event data.                                                                                                                                                                             |
| Due to an implementation issue, duplicate events were ingested                                                                         | Yes, use Data Deletion with targeted event property filters to delete duplicate event data.                                                                                                                                                                        |
| Due to an implementation issue, events were sent with wrong timestamp                                                                  | Yes, use Data Deletion with targeted event property filters to delete affected data, and then re-upload with corrected timestamps. Please refer to our 'Reminders with ETL Approach' section on this page as you proceed                                           |
| We have sensitive data that we accidentally ingested that we legally cannot have and need to urgently delete                           | Yes, use Data Deletion with targeted event property filters to delete events with sensitive data. You can then re-upload data without sensitive PII data included. Please refer to our 'Reminders with ETL Approach' section on this page as you proceed           |
| I no longer want an event/ property entirely, as it’s no longer relevant to my team                                                    | No, we recommend you actually use [Dropping and Hiding Data](/docs/data-governance/lexicon#dropping-and-hiding-data) instead, as these will hide the events from your team, without using up your limited Data Deletion requests.                                  |
| I don’t need to legally delete some events with sensitive data, but I don’t want some of my users to be able to see the sensitive data | No, we recommend you use [Mark Properties as Classified](/docs/data-governance/data-views-and-classification#mark-properties-as-classified-data) to remove the data from the analysis experience for certain user types, while keeping accessible for other users. |
| I want to delete data associated with a specific distinct ID                                                                           | No, we recommend you use our [Distinct ID Deletion API](/reference/create-deletion), as Data Deletion does not support Distinct ID as a filtering criteria                                                                                                         |

### Who can use Data Deletion?

You can use the Data Deletion tool in these scenarios:

* Your Mixpanel role is Owner or Admin
* Your data does not extend beyond the past 180 days (event time, not ingestion time)
* Your event volumes are below 5 billion events per month, any month over the trailing 3 months
* Your project has not had more than 10 deletes over the past calendar month

### How to use

<Warning>
  Data Deletion is irreversible. Exercise caution when using this feature.
</Warning>

<Frame>
  <img alt="image" />
</Frame>

Once you've identified the problematic data, and confirmed you want to delete:

1. Navigate to the **Lexicon > Data Governance > Data Deletion**
2. Click ‘Request an Event Deletion’
3. Select which event you want to delete
4. Select time range (event time cannot be more than 180 days in the past)
5. Add any Event property filters if needed
6. Validate in the preview that the right data is being deleted
7. Submit deletion request

Data Deletion will be **permanent and irreversible** in 7 days after submitting. Until that time, you may undo the action. Ensure that you carefully review and confirm your selections before proceeding.

During this intermediate 7 day period, we will automatically hide the data in your Deletion request from your users, so they don’t accidentally analyze incorrect or sensitive data.

### Undoing data deletion

You may undo Data Deletion requests **for only 7 days after submitting**, after which deletions become permanent. To do so, take the following steps:

<Frame>
  <img alt="image" />
</Frame>

1. Navigate to the **Lexicon > Data Governance > Data Deletion**
2. Locate the Deletion request you wish to undo in the table
3. Click ‘Undo’ button in the Deletion Data column

<Warning>
  While the deletion becomes permanent after 7 days, the process to fully clean the data from the storage can take up to 30 days total. During this time, said data will not appear in reports, or formatted API queries, but might appear in raw exports while it's being fully removed
</Warning>

### Reminders with ETL approach

* For projects created prior to 1 Jan 2023 offset your timestamps

  * If your project was created prior to 1 Jan 2023, you cannot just clean the data you don't want and re-import it. Your data is stored in project time, so you need to adjust the offset before importing
* Don’t forget to regenerate \$insert\_id’s when you ETL

  * When you submit a deletion request, we hide your data immediately from your project to reduce any privacy concerns. We call this “soft deletion”, an interim phase before our “hard deletion” kicks in (where your data is permanently deleted from our servers) so that you can review the impact of your changes and undo when necessary. If you re-import data while the data is soft deleted **with the same \$insert\_id**, our deduplication systems may keep the old (deleted) event and toss the new event. Since this data is soft-deleted, your re-import won’t reflect the data as imported. Thus, when the ETL is done, you should regenerate the \$insert\_id value if possible, to avoid this possible collision

### Frequently asked questions

***How does Data Deletion impact billing?***

Billing behavior for successfully deleted events depends on your plan:

* Legacy event timestamp billing — Deleted events are excluded from the current month's usage calculation.
* Ingestion timestamp billing — Deleted events are still counted toward your usage for the month.

***Do you support property deletion?***

Not as of now. If you have events with properties you want to delete, you should do an Extract, Transform, Load approach. The goal would be to run a raw export on the event and then delete the bad imported data. Once this data has been transformed, re-import the data into the project. Then, call this event something slightly different and then hide the original one

Please refer to 'Reminders with ETL Approach' section as you proceed, and submit feedback (accessible in-app with our help menu) if this is a blocker for you and your team

## 3. Drop Filters

Drop Filters let you stop unwanted events from being ingested and stored into Mixpanel going forward. Where [Data Deletion](#2-deleting-problematic-data) addresses *past* problematic data, Drop Filters address it *proactively* — events matching your filter rules are dropped at ingestion and never stored, never queried, and never counted.

You might find this useful if you:

* Have **unwanted events** (e.g. test or staging events) leaking into your production project
* Are dealing with **noisy events** that clutter your project without adding analytical value
* Have **malformed or deprecated events** you no longer intend to send

<Note>
  Drop Filters only affect events going forward. To remove data already in your project, use [Data Deletion](#2-deleting-problematic-data).
</Note>

### Who can use Drop Filters?

* Only Owners have permission to create drop filters and drop data.

### Supported filter criteria

A Drop Filter targets a specific event, narrowed by one or more property values. Every filter must include:

* **Event name** — the event you want to filter (required)
* **Event property** — at least one property on that event to filter by (required)
* **Property values** — one or more values for that property (required)

You can combine multiple criteria within a single filter to target precisely the events you want to drop.

Only events matching the event name *and* the specified property values will be dropped. Filtering by event name alone is not supported with drop filters. To drop a full event by event name with no property filters, go to Lexicon and add a Dropped tag to the event.

### How to use

<Warning>
  Dropped events are not stored and cannot be recovered. Review your filter carefully before saving. Filters are active within 10 minutes after creation and while drop filters can be deleted, the data dropped while they were active cannot be recovered unless sent to Mixpanel again.
</Warning>

<Frame>
  <img alt="image" />
</Frame>

1. Navigate to **Lexicon > Data Governance > Data Drop And Deletion**
2. Click **Create Drop Filter**
3. Select the event you want to drop
4. Add property + value conditions to narrow the filter
5. Save the filter

<Frame>
  <img alt="image" />
</Frame>

Once saved, the filter takes effect on all newly ingested events. Existing data in your project is unaffected.

### Editing or removing a Drop Filter

To stop dropping events, locate the filter in **Lexicon > Data Governance > Data Drop And Deletion** and delete it. Events sent after that point will be ingested normally.

<Frame>
  <img alt="image" />
</Frame>

<Warning>
  A project can currently contain up to 15 Drop Filters.
</Warning>

### Dropping a full event

To drop an entire event, locate the event in Lexicon under the **Events** tab. Select the event and under ***Status*** toggle on ***Blocked***. Fully dropped events have a status of ***Blocked*** on lexicon while events dropped with drop filters have a status of ***Filtered***

### Frequently asked questions

***How do Drop Filters impact billing?***

Dropped events are not ingested, so they do not count toward your event volume usage.

***Can I recover events that were dropped?***

No. Dropped events are discarded at ingestion and cannot be recovered. If you need historical analysis on these events, disable the filter first and re-send the data.

### Other resources

* [Event Approval](/docs/data-governance/event-approval)
* [Recovering from a hot shard](/docs/debugging/distinct-id-limits)


# Data Standards
Source: https://docs.mixpanel.com/docs/data-governance/data-standards

Keep Your Data Clean and Consistent

<Note>
  Customers on an Enterprise plan can access the Data Standards feature. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

Data Standards is a Data Governance feature that helps organizations enforce naming and metadata standards on events ingested into Mixpanel. This helps improve event consistency, easy navigation, and user trust in using data for analysis.

This feature evaluates your event metadata against predefined standards and assigns a "Compliancy" status to each event. This status is visible in Lexicon, helping admins and analysts quickly identify and correct non-compliant events.

## Enabling Data Standards

To define data standards, organizations can navigate to the Data Standards tab in Lexicon. There, they can configure rules such as:

| Rule                   | Description                                                                        |
| ---------------------- | ---------------------------------------------------------------------------------- |
| **Naming conventions** | Events must follow a required syntax (e.g., snake\_case, camelCase).               |
| **Descriptions**       | All events must include a description.                                             |
| **Ownership**          | Events must have an assigned owner.                                                |
| **Rich media uploads** | Events should have relevant media assets uploaded (like Figma or app screenshots). |

## Viewing Compliancy Status in Lexicon

For every event in your project, Mixpanel will automatically evaluate against your defined data standards. The compliancy status is displayed in Lexicon, allowing Data Governors to:

* Identify compliant and non-compliant events at a glance.
* Filter / sort events based on their compliancy status.
* Take corrective actions by updating metadata directly within Lexicon.

## Additional Notes

* The feature will check the standard against the Display Name if set. If no Display Name is set, it will check against the tracked event name
* Only Project Admins or Owners can define data standards.
* This feature is only available on Enterprise plans.
* We will soon be adding automated actions to be applied when Data Standards are violated. Please reach out to your Account Manager if you're interested in getting early access to these tools.


# Data Views & Classification
Source: https://docs.mixpanel.com/docs/data-governance/data-views-and-classification

Filter team access to your data within a project

<Note>
  Users on a Growth plan or above can access the Data View and Data Classification features. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Data Views Overview

Data Views allow you to manage data access for a group of users within a single Mixpanel project. [Project Owners and Admins](/docs/orgs-and-projects/roles-and-permissions#permissions) can create and edit Data Views and determine access for privacy and productivity purposes.

### Use Cases

**Teams or Functional Areas**

You have a Mixpanel project that contains all of your data. Engineering, Marketing, Support, and various product teams all use Mixpanel on a regular basis. Each team can have a Data View filtering for relevant data.

**Separate Customer Data from Internal User Data**

Create a Data View for customer data by excluding data tracked by your internal users/employees. Create another Data View for just your internal users. By doing this, you no longer have to remember to add cohorts or filters each time you create a Board, Report, or Cohort.

**Regions or Geo-Based Teams**

For a global organization with multiple offices, regional teams might need access to data from only their region. E.g. The marketing team in the Asia region would like to target only Asian customers and should not have access to US customers' data.

**Verified Data Only**

Teams that want to closely manage events that are included in all their analysis can either include or exclude the specific events in the Data View definition.

**Specific Platform/App Version**

Engineering or Product teams working on a specific version can use Data Views to target specific versions of the app or platform version(s) to be included in the analysis.

### Create Data View

To create a new Data View, navigate to **Project Settings** then click on **+ Create Data View** in the top right of the Data Views settings. Add a name and description to your Data View and click **Save**. The name of the Data View cannot be longer than 255 characters.

<Frame>
  <img alt="Create Data View" />
</Frame>

Click on your new Data View to see an overview of Data View details, review or update filters, and manage access at the individual or team level.

### Manage Data View

Navigate to Project Settings, and select at the left-hand menu  Data Views.

<Frame>
  <img alt="Project Settings" />
</Frame>

<Frame>
  <img alt="Manage Data View Project Settings" />
</Frame>

#### Default Data View

All projects have a global Data View called “All Project Data.” This Data View has no data filters and gives users access to all the data in a project. The global Data View in a project is equivalent to a Mixpanel project without Data Views.

The “All Project Data” Data View starts as the default Data View of a project for any new users added to the project. You can decide which Data View you want to set as default by checking the box next to the Workspace name and selecting **Set Default**.

<Frame>
  <img alt="Manage Data View Project Settings" />
</Frame>

### Manage Visibility and Editing Controls

The **Overview** tab displays details about the Data View including the name, description, editing controls, visibility, creator name, date created, and URL to access the Data View. The Overview is accessible to all Admins and Owners in the project.

Select **Restricted** under Editing Controls to prevent other Admins from editing the Data View settings and filters. Select **Unrestricted** to allow Admins to edit the Data View settings and filters.

Select **Public** under Visibility to allow project members to discover your Data View in the Data View Library. All project members can also self join a Data View that is public. Select **Private** to prevent project members from seeing your Data View in the Library and self joining. Project members who are added to a private Data View will be able to see it.

After the Editing Controls and Visibility are set upon Data View creation, they can be changed by only the Data View creator or a Project Owner.

<Frame>
  <img alt="Data Views Overview" />
</Frame>

#### Manage Data View Filters

Filters determine what data is accessible within a Data View.

<Frame>
  <img alt="Data Views Filters" />
</Frame>

You can apply multiple event, event property, and user profile property filters to a Data View.

#### Add Users or Teams

Click **+ Add User** to add individual project members to your Data View. The modal shows only users that are part of your project.

You can remove users from your Data View by selecting the box next to their name and clicking Remove to the left above the user list.

Click on the **Teams** tab to add or remove teams from a Data View. Add a team to a Data View to indicate that any project member in the team should have access to a Data View.

If you set up your Identity Provider to connect to Mixpanel with Single Sign-On, you can define which project members are assigned to which teams. If you set up certain teams with access to specific projects and Data Views, you can streamline your member onboarding to a Mixpanel project. This helps control who has access to what data at scale.

### Data View Library

Click on the name of your project in the upper-right corner, and then on "Data View Library". The Data View Library allows you to see the Data Views you have joined, to create new Data Views, and to join other public Data Views. Private Data Views that you have not been invited to will not show up here.

<Frame>
  <img alt="Data View Library Nav" />
</Frame>

<Frame>
  <img alt="Data View Library" />
</Frame>

### Experience Data Views as a User

You can see the name of the Data View that you are currently in on the upper-left corner next to the project name. A message banner will also notify you when you enter a Data View if the Data View has a filter.

### Saved Content in Data Views

The saved content you create in Mixpanel is not contained to the Data View in which it was created. For example, you can view a Report you made in one Data View in any of the other Data Views you have access to. The results of a report or Board will change depending on the Data View you have selected.

### Data Views Limits

The following are limitations to be aware of when using Data Views:

* JQL features are only available in ‘All Project Data’ Data View.
* Any Mixpanel APIs that use Project Token or Secret (e.g. Export API), work at a project level and are not the Data View level. That said, any APIs that use OAuth (e.g. Query API) work at the Data View level.
* Lexicon shows events and properties filtered based upon the Data View you have selected. However if you edit an event or property in Lexicon in one Data View, the changes will persist across the project. All Data Views will be impacted.
* Applying any User Profile Property filter will remove the ability to analyze by all Group Identifiers except User

## Data Classification

**Mark Properties as Classified Data**

Marking properties as classified limits which users can view them. Navigate to the event properties and user profile properties tabs in Lexicon to mark a property as classified.

> You must have an active **Enterprise** plan with Mixpanel to access this feature.

When you mark a property as classified, users or teams with the checked Can View checkbox checked can see the classified property in reports. You can see the Can View checkbox in Project Settings for individual users and in Organization Settings for teams. Only Project Owners and Admins can mark a property as classified.

Select a property or group of properties and click **Mark Classified**.

<Frame>
  <img alt="Mark Classified" />
</Frame>

A pop-up will confirm that you want to mark the selected property or properties as classified.

<Frame>
  <img alt="Mark Classified Warning" />
</Frame>

When you mark a property as classified, the Status column will indicate that the property is classified alongside its visibility state (visible or hidden). If the Status column shows only the visibility state, then the property is not marked as classified.

### Manage Classified Data Viewing Permissions for Individual Users

Go to your Project Settings, and then to the tab "Project Users" in order to manage which users can access the events and properties marked as classified.

In the **Current Users** table, the Classified Data column indicates which users have permission to view classified data. Click the Can View check box in a user’s row to update their classified data viewing permission.

<Frame>
  <img alt="Mark Classified Viewing Perms" />
</Frame>

### Manage Classified Data Viewing Permissions for Teams

Navigate to Organization Settings from the gear icon at the top-right corner of the navigation bar. Go to the Users & Teams tab and click on the team for which you wish to manage permissions. You can manage the team’s access to Classified Data for each of the projects to which they have access.

<Frame>
  <img alt="Manage Classified Data Viewing for Teams" />
</Frame>

### Analysis Experience for Users that Cannot View Properties Marked as Classified Data

Users that cannot view properties marked as Classified Data can see which specific properties are marked as classified in Lexicon. Users that cannot view properties marked as Classified Data cannot use such properties as filters or breakdowns.

**Boards**

If a report contains any event or property marked as classified when a user without the "Can View" option tries to open it, will see the next warning

<Frame>
  <img alt="Sensitive Data Warning" />
</Frame>

Users that cannot view classified data can click on a Board card to access the full report and determine what properties are preventing them from viewing a report.

**Analysis Reports (Insights, Funnels, Flows, and Retention)**

Classified properties won't be visibly different when building a report, but if used by a user without the "Can View" option enabled, the next warning will be displayed:

<Frame>
  <img alt="Analysis Reports Warning" />
</Frame>


# Data Volume Monitoring
Source: https://docs.mixpanel.com/docs/data-governance/data-volume-monitoring

Get notified about drastic changes in event volume

<Note>
  Customers on an Enterprise can access the Data Volume Monitoring feature. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

Data Volume Monitoring is a Data Governance feature for organizations that want to monitor for implementation issues with events being sent to their Mixpanel project. The feature is a project-level setting for Enterprise accounts that watches for sudden, drastic changes in event volume and notifies admins so they can take corrective action.

### Enabling Data Volume Monitoring

For New Enterprise Customers (starting December 2025 onwards): Data Volume Monitoring is automatically enabled by default on all new enterprise projects. You can configure the notification settings or disable the feature following the instructions below.

To configure Data Volume Monitoring, navigate to the Lexicon page, go to the left-hand menu under Data Governance, and click the Data Volume Monitoring section.

When enabling this setting, input email addresses or aliases to be notified when a spike or drop is detected. This will be gated to project admin and owner email addresses. Admins can also set up a Slack channel to be notified when a spike or drop is detected.

Notifications are sent once per day. If multiple spikes or drops are found for a project within one day, we will batch the notifications so you will get at most 2 per day per project.

Only Project Admins or Owners can enable this setting, and it's only available on Enterprise plans.

<Frame>
  <img alt="data-volume-monitoring-settings" />
</Frame>

### Notes

* Data Volume Monitoring begins as soon as it is enabled, but it may take 24 hours to run for the first time
* We will check once a day as long as Data Volume Monitoring is enabled
* By default, we inspect event volume for the previous day (a 1-day "look-back"), but you can select a 2-day "look-back" to compensate for ingestion delay
* We use up to 24 months of event volume history to determine an "expected" range
* We analyze up to 1,000 of most-active events which have volume of 100+ for at least half of the last month
* Volume needs to be at least 50% higher or lower than the expected range for a change in volume to generate a notification


# Event Approval
Source: https://docs.mixpanel.com/docs/data-governance/event-approval

Review unexpected events before they are visible

<Note>
  Customers on an Enterprise can access the Event Approval feature. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

Event Approval is a Data Governance feature for organizations that want visibility and control over all new events sent to their Mixpanel project. The feature is a project-level setting that hides new events by default and notifies admins when those new events come in, so they can then mark them as visible for everyone to see.

### Enabling Event Approval

To enable Event Approval, navigate to Lexicon, scroll to Event Approval under the Data Governance section, and click the Event Approval toggle.

When enabling this setting, input email addresses or aliases to be notified when a new event is ingested. Admins can also set up a Slack channel to be notified when a new event is ingested.

You can also enable new property detection, which will notify the same email addresses or Slack channels about new properties detected on new and existing events.

Notifications are sent once per day. If multiple events are implemented in a project within one day, the notification will batch all these events.

Only Project Admins or Owners can enable this setting, and it's only available on Enterprise plans.

<Frame>
  <img alt="event-approval-settings" />
</Frame>

### Lexicon Workflow

When an admin receives a notification that new events have been ingested, they can click the "View New Events" button, which will take them to a Lexicon view of hidden events. New events will have a "Pending" status and be sorted to the top of the list.

From there, an admin can take actions such as marking the event as visible, adding a description, or a tag.

Events will be given a status of "Pending" as long as the following criteria are met:

* It hasn’t been modified
* It is hidden
* It was created within the last 30 days

If new property detection is enabled, notifications will also include a "View New Properties" button, which will take them to a Lexicon view of new properties.  Properties will have a "Pending" status as long as the following criteria are met:

* It was created within the last 30 days

### Additional Notes

* Please note that all [custom properties](/docs/features/custom-properties) will **not** be marked as "Pending"
* Event Approval is not available for projects with > 3000 hidden events and will be auto-disabled if projects exceed this limit


# Lexicon
Source: https://docs.mixpanel.com/docs/data-governance/lexicon

Describe your events and data using a dictionary

## Overview

<Frame>
  <iframe />
</Frame>

Lexicon is a data dictionary that stores descriptions of events and their properties. Project owners and admins can add/manage descriptions for all events and properties and organize data for clarity and discoverability. Event and property definitions help your entire team understand what your data means, so everyone stays on the same page.

To open Lexicon, select the **Data** tab on the left-hand navigation menu, and then select **Lexicon**.

When you open Lexicon, you'll see two sections:

Tracked Data

1. Events
2. Event Properties
3. Profile Properties

Computed Data

1. Cohorts
2. Custom Events
3. Lookup Tables
4. Formulas
5. Behaviors

### Events

Events are actions a user performs in your application or website.

<Frame>
  <img alt="Lexicon Events" />
</Frame>

This table contains descriptions for each field in the “Events” view.

| Field          | Description                                                                                                                                                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Event Name     | The database name of the event. Status Icons indicate whether the event is hidden or visible in the Mixpanel project                                                                                                      |
| Display Name   | The event name that displays in the Mixpanel interface.                                                                                                                                                                   |
| Description    | The information that describes the event, such as what triggers it or what properties are sent with it.                                                                                                                   |
| 30-Day Volume  | The total number of events that users fired in the last 30 days.                                                                                                                                                          |
| 30-Day Queries | The total number of UI queries that project members executed in the last 30 days. Includes queries from selecting events in reports, viewing reports, and queries in "Users" and "Events" tabs. Excludes dashboard views. |
| Last Queried   | The user that last used this event in the Mixpanel UI.                                                                                                                                                                    |
| First Queried  | The user that first used this event in the Mixpanel UI.                                                                                                                                                                   |
| Owners         | The user(s) that are points-of-contact for this event.                                                                                                                                                                    |
| Status         | Whether this event is Pending, Visible, Hidden, Blocked, or Merged.                                                                                                                                                       |

### Event Properties

Event properties describe details about events, such as distinct\_id or browser.

This table contains descriptions for each field in the “Event Properties” view.

| Field                | Description                                                                                                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                 | The database name of the property.                                                                                                                                                                                        |
| Display Name         | The property name that displays in the Mixpanel interface.                                                                                                                                                                |
| Description          | The information that describes the property, such as what events it is sent with.                                                                                                                                         |
| Example Value        | What is an example value of this property.                                                                                                                                                                                |
| Events With Property | The total number of events that contain this property in the last 30 days.                                                                                                                                                |
| Queries              | The total number of UI queries that project members executed in the last 30 days. Includes queries from selecting events in reports, viewing reports, and queries in "Users" and "Events" tabs. Excludes dashboard views. |
| Status               | Indicates whether the property is visible or hidden from the Mixpanel interface. Also indicates if the property is blocked, merged, or marked as sensitive.                                                               |

Lexicon contains property definitions for the default properties that Mixpanel’s client-side libraries automatically send with each event across web and mobile platforms.

<Frame>
  <img alt="Lexicon Event Properties" />
</Frame>

### Profile Properties

Profile properties describe details about your users, such as username or email address.

This table contains descriptions for each field in the “Profile Properties” view.

| Field               | Description                                                                                                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                | The database name of the property.                                                                                                                                                                                        |
| Display Name        | The property name that displays in the Mixpanel interface.                                                                                                                                                                |
| Description         | The information that describes the property, such as what events it is sent with.                                                                                                                                         |
| Example Value       | What is an example value of this property.                                                                                                                                                                                |
| Status              | Indicates whether the property is visible or hidden from the Mixpanel interface. Also indicates if the property is blocked, merged, or marked as sensitive.                                                               |
| Users With Property | The total number of profiles that contain this property.                                                                                                                                                                  |
| Queries             | The total number of UI queries that project members executed in the last 30 days. Includes queries from selecting events in reports, viewing reports, and queries in "Users" and "Events" tabs. Excludes dashboard views. |

If you have Group Analytics enabled, you will see a dropdown on the Profile Properties tab that will let you select any Group Types that you may have configured. The default selection will be "User Profiles" which correspond to User properties.

<Frame>
  <img alt="Lexicon Profile Properties" />
</Frame>

### Cohorts

[Cohorts](/docs/users/cohorts) are groups of users that share a certain set of properties or who perform a similar sequence of events. You can create cohorts based on user properties, events, and other criteria to analyze user behavior and engagement.

### Custom Events

[Custom Events](/docs/features/custom-events) are events and properties you combine into one event to use in Mixpanel reports. The fields for custom events are “Name”, “Description”, "Definition", "30 Day Queries", "Last Queried" and “Created” (defined above).

### Lookup Tables

[Lookup Tables](/docs/data-structure/lookup-tables) in your project are listed in your Lexicon. Click into a Lookup Table definition to export the underlying CSV, replace the Lookup Table with a new CSV, and see which properties are linked.

### Formulas and Behaviors

Saved [Formulas](/docs/reports/insights#formulas) and [Funnels/Retention Behaviors](/docs/features/saved-metrics-and-behaviors) in your project are also documented in your Lexicon. Review here to get an overview of existing definitions in your project that you can quickly leverage in your own analysis.

## Renaming Properties

After you ingest raw data into a project, you cannot rename it. However, you can change the display names of events, event properties, and user profile properties to control how they appear in the UI. The system dynamically renders these display names on the front end and does not modify the underlying data in the project’s data store or affect how the data appears in exports.

## Filtering Events, Custom Events, and Properties

Lexicon provides several options for you to filter your events, custom events, event properties, and profile properties.

You can filter by visible or hidden events, blocked events, merged events, tags, your defined events, autotracked events, and default Mixpanel events. These filtering options help you arrive at the most useful data to analyze your performance.

<Frame>
  <img alt="Lexicon Filtering" />
</Frame>

## Viewing Query Volumes for Events and Properties

In each view, you can see the total UI and API queries in the last 30 days for any of these data types and sort by them.

This data lets you easily discover the parts of your implementation that are most valuable and the parts that are not being used. You can use this information to determine which events and properties you should block.

<Frame>
  <img alt="Lexicon Query Volumes" />
</Frame>

## Blocking Data

<Note>
  Only project owners may block and unblock data from the Lexicon. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

In Lexicon, you can intercept and block incoming events or properties. Mixpanel won't store any **new data** for the event or property you select to block. **Warning: You cannot recover event data after you block it.**

When an event is blocked, all events of that type that have previously been ingested (before blocking it) will still show in the interface. Only project owners can block events and properties. **Note: It takes a few hours for Mixpanel to process the blocked event.**

Sample use cases for blocking events and properties are:

**Sensitive data:** If you accidentally send sensitive data, such as passwords or credit card information, you can block the event or property with that data and prevent it from being stored in Mixpanel servers.

**Cost and Time Efficiency:** Being able to block events and properties that are no longer useful directly from Lexicon is easier and more efficient than having to implement changes to your code base.

**Better Organization:** Events and properties that are no longer useful can cause a cluttered Mixpanel project. Blocking unnecessary events and properties optimizes your code for a clean and streamlined project implementation.

**Blocking Events**

<Info>
  Previously, Block was called "Drop" in Lexicon. Events that formerly showed a "Dropped" status now show a "Blocked" status.
</Info>

By blocking an event, you can intercept and block incoming events. Mixpanel will not store any new data for the event you select to block.

To block an event in Lexicon:

1. Select an event to block. The Block icon appears.

<Frame>
  <img alt="Lexicon Block Events" />
</Frame>

2. Click Block. A “Confirm blocking your event(s)” warning indicates you cannot recover the data associated with the event.

<Frame>
  <img alt="Lexicon Block Events Warning" />
</Frame>

3. Click Block. The status of the event indicates **Blocked**.

**Unblocking Events**

You can unblock events and properties when you decide you need them again.

To unblock an event:

1. Select a blocked event. The “Status” column indicates if an event is blocked.

<Frame>
  <img alt="Lexicon Unblock Events" />
</Frame>

2. Click **Unblock**. The “Status” column no longer contains “Blocked”.

**Blocking Properties**

By blocking a property, you can intercept and block an incoming property. Mixpanel won’t store any new data for the property you select to block.

To block a property in Lexicon:

1. Select a property to block. The Block icon appears.

<Frame>
  <img alt="Lexicon Block Properties" />
</Frame>

2. Click **Block**. A warning indicates that you cannot recover the data that you choose to block. Click Block to confirm. The status of the property will indicate Blocked.

**Unblocking Properties**

1. Select a blocked property. The “Status” column indicates if a property is blocked.

<Frame>
  <img alt="Lexicon Unblock Properties" />
</Frame>

2. Click **Unblock**. The “Status” column no longer contains “Blocked”.

## Hiding Data

<Note>
  You must have an admin or owner project role to hide and unhide data from the Lexicon. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

In Lexicon, you can hide any events or properties. Unlike [blocking data](/docs/data-governance/lexicon#blocking-data), hiding data does not affect data ingestion; any events/properties that are hidden will continue to be ingested in your project and count toward your data allowance.

A hidden entity will not be indexed in your event/properties menu in the query builder. Any [inactive events and properties](/docs/tracking-best-practices/debugging#inactive-events-and-properties) will also be hidden.

Hidden events will be excluded from your query results. For example, it will not be included in "All Events" and won't appear as an intermediate step in your [Flows report](/docs/reports/flows).

Hiding data is useful for preventing not-so-commonly used entities from cluttering your events/properties menu, or to prevent certain events from being considered in your reports.

If you wish to use a hidden entity in your report, you may manually select the entity by searching in the events/properties menu and then clicking "Show Hidden Events/Properties" to reveal the hidden entity.

**Hiding Events and Properties**

To hide an event or property:

1. Select one or more visible events, event properties, or profile properties. The “Hide” icon appears. You can check the “Status” field to determine whether an event or property is visible or hidden.

<Frame>
  <img alt="Lexicon Hide Events" />
</Frame>

2. Select **Hide**. A message appears to allow you to confirm hiding the event(s). After you select **Hide**, the event or property status changes to “Hidden”.

<Frame>
  <img alt="Lexicon Hide Events Warning" />
</Frame>

Another option for hiding an event, property, or property value is to let it inactivate until it is hidden in report dropdown menus. Mixpanel’s report dropdown menus hide events that have not been fired within the last 30 days. Event properties and property values that have not been sent to your project in 28 days are hidden from dropdown menus.

**Show Events and Properties**

To show an event or property:

1. Select one or more hidden events, event properties, or profile properties. The “Unhide” icon appears. You can check the “Status” field to determine whether an event or property is visible or hidden.
2. Select **Unhide**. After you select **Unhide**, the event or property status changes to “Visible”.

<Frame>
  <img alt="Lexicon Show Events and Properties" />
</Frame>

## Merging Data

<Note>
  In Lexicon, only project owners can merge events and event properties. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

Let's suppose your iOS app sends an event named “Purchase”, and your Android app sends an event named “purchase item”. Even though both events have the same function, you have to individually select them every time you build a report.

By merging “Purchase” and “purchase item” into a single event named “Purchase”, you would no longer need to query each event separately since Mixpanel would recognize both “Purchase” and “purchase item” as a unique event.

Being able to merge events can help streamline your implementation, reduce your costs by eliminating redundant events being sent to Mixpanel, and simplify report analysis because you’re only using optimal events and properties. Do note however that user profile properties cannot be merged at this time.

<Note>
  [Autocapture](/docs/tracking-methods/autocapture) events cannot be merged. These events are displayed using preset labels such as “\[Auto] Page View” and “\[Auto] Element Click”.
</Note>

**Merging Events**

To merge events:

1. Select the events to merge. The “Merge” icon appears.
2. Click Merge. The “Merge Events” window appears. It shows the events you selected and explains that merging the selected events combines them into a single event, which does not affect the raw data.

<Frame>
  <img alt="Lexicon Merge Events" />
</Frame>

3. In the “MERGE SELECTED EVENTS INTO…” section, specify which event Mixpanel should consider as the new unique event.
4. Click **Merge**. The merged event appears and the “Status” column indicates “Merged”.

**Unmerge Events**

To unmerge events:

1. Select the merged event to unmerge. The “Unmerge” icon appears.

<Frame>
  <img alt="Lexicon Unmerge Events" />
</Frame>

2. Click Unmerge. The merged event appears as the original two distinct events.

**Merging Properties**

To merge properties:

1. Select the properties to merge. The “Merge” icon appears.
2. Click Merge. The “Merge Properties” window appears. It shows the properties you selected and explains that merging the selected properties combines them into a single property, which does not affect the raw data.

<Frame>
  <img alt="Lexicon Merge Events" />
</Frame>

3. In the “MERGE SELECTED PROPERTIES INTO…” section, specify which property Mixpanel should recognize as the newly merged property name.
4. Click **Merge**. The merged property appears and the “Status” column indicates “Merged”.

**Unmerge Properties**

To unmerge properties:

1. Select the merged property to unmerge. The “Unmerge” icon appears.

<Frame>
  <img alt="Lexicon Unmerge Events" />
</Frame>

2. Click Unmerge. The merged property appears as the original two distinct properties.

## Verify Data

<Note>
  Customers on an Enterprise can access the Verified Data feature. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Verified Data in Mixpanel allows designated project owners and admins to add Verified badges to certain Events, Behaviors, Formulas, Custom Events, and Cohorts. This signals to other users within your project that this data has been vetted and can be confidently used for analysis and reporting.

By providing a clear distinction between vetted and non-vetted data, it becomes easier for teams to adopt Mixpanel, knowing they are using the right events.

**How it Works**

1. Navigate to Lexicon
2. Go to any event, behavior, formula, custom event, or cohort
3. In the top right corner, click the Verify button
4. Now, whenever end users are creating reports, or browsing data in Lexicon, they will see a Verified icon next to this data item.

<Frame>
  <img alt="verifyButton" />
</Frame>

## Session Replay in Event Metadata

Event metadata across Query Builder, Lexicon, and Event pages now automatically includes relevant Session Replays when available.

**How it works:** When viewing event details, Session Replays that captured the specific event will appear in the metadata panel. This applies to:

* Individual event inspection in Query Builder
* Event definitions in Lexicon
* Event detail views on dedicated Event pages

**Requirements:** This feature is available to accounts with Session Replay enabled. No additional configuration is needed—relevant replays will automatically appear when present.

**What you'll see:** Session Replay thumbnails and links will display alongside standard event properties. Click any replay to view the full session context surrounding that event.

This enhancement provides immediate visual context for event analysis without requiring manual correlation between Events and Session Replay data.

For Session Replay setup and configuration, see our [Session Replay documentation](/docs/session-replay).

## Export and Import Lexicon Data

Mixpanel supports exporting and importing Lexicon data dictionaries. Project owners, admins, and analysts can click **Export** in Lexicon to receive a CSV file via email that contains the events and properties, and/or user profile properties data from a project.

<Frame>
  <img alt="Lexicon Export" />
</Frame>

In the Export panel, you can select:

* Events & Properties and/or
* User Profile Properties

The requester will receive an email with a link to download a single CSV file. This link remains active for 14 days. Each CSV file can contain up to 5,000 events, 2,000 properties per event, and 2,000 user profile properties.

The numbers in the CSV export may not match exactly with the numbers in the Mixpanel UI. This is because the numbers in the Lexicon UI only include queries made from the Mixpanel UI, whereas the numbers in the CSV export include queries made from the Mixpanel public API in addition to the queries made from the UI.

### CSV Import

Project owners and admins can export a CSV of their Lexicon changes, make changes, and import that CSV back into Lexicon.

When you export your Lexicon Data into a CSV file, you can make modifications, add events and/or properties, and import them into Lexicon.

To import CSV files, they must be in the exported CSV format, otherwise the file will be rejected:

<Frame>
  <img alt="Lexicon CSV Import Format" />
</Frame>

Once you've made your modifications, you can directly import the CSV file into Lexicon:

* Select your CSV file
* Review Events, Event Properties, and/or User Profile Properties
* Import into Lexicon

Event and property descriptions and metadata (hidden, blocked, sensitive, etc) that are already in Lexicon will be overwritten by descriptions and metadata for matching event and property names. By default, any event and property descriptions for events that are not imported will remain unchanged unless you check the option to overwrite your entire data dictionary during import.

### Segment Import

When importing a data dictionary from Segment Protocols using the Segment Config API, you will be asked for your Segment Token and Segment Workspace. You can find your Segment Token by going to your Segment dashboard: Settings > Access Management > Tokens

You can use an existing Token, or create a new token with a Token Role of Workspace Owner.

For the Segment Workplace value, we recommend using the Slug name located in the Segment dashboard: Settings > General Settings.

Once you have your Segment Token & Workspace, head over to Lexicon and select Import from Segment.

* Enter your Token & Workspace
* Select the Plan you want to import from Segment
* Review the Events and Profile Properties that will be imported
* Import your Segment Plan into Lexicon

### Avo.app Import

To import your data dictionary from Avo.app, you will need to enable an integration with Mixpanel. The following information would be necessary to complete this integration from Avo.app:

* Mixpanel Project ID (`https://mixpanel.com/project/[Mixpanel Project ID]/...`)
* Mixpanel Service Account Username & Secret (Owner or Admin role required) To publish your Avo data dictionary to Lexicon, click the "Publish to Lexicon" button in the integration interface.

Click [here](https://www.avo.app/docs/publishing/integrations) for more information on integrating Avo.app with Lexicon.

### mParticle Import

When importing a data dictionary from mParticle, navigate to your Data Plan and select Download Plan Version from the upper right menu.

* Click Import on the top right-hand side of Lexicon
* Select mParticle
* Select the downloaded JSON file from mParticle Data Plans
* Review Events, Event Properties, and User Profile Properties to be imported.
* Import data into Lexicon

## Lexicon Schemas API

Mixpanel provides a suite of API endpoints for you to Retrieve, Create, and Delete your data dictionary in Lexicon. To use these APIs, check out our [API reference docs](/reference/lexicon-schemas-api).

### Lexicon UI vs Lexicon Schemas API

The payload returned from the Lexicon Schemas API is most likely not an exact match of the Lexicon as seen in your project's UI. This is because the Lexicon Schemas are a subset of the data that appears in Lexicon UI.

The Lexicon UI contains entities that were sent to your project within the last 30 days or have an associated Lexicon Schema.

A Lexicon Schema is created when one of the following takes place:

1. When a schema is created through the Lexicon Schema API
2. When a new entity is imported to your Lexicon via CSV import
3. When metadata about an entity is added via the UI (such as adding description, hiding/showing, adding tags, etc.)

When using the Lexicon Schema API to export, only entities that have a Schema are exported. Entities that are seen in your Lexicon UI that were sent within the last 30 days without a Schema will not be reflected in the Lexicon Schema payload.

To export all of your entities from the Lexicon, please use the [CSV export method](/docs/data-governance/lexicon#export-and-import-lexicon-data), which will export everything as seen in the UI, which includes recently sent entities and all entities with a Schema.

## Lexicon Event Details

Mixpanel provides a variety of tools to make it easier for teams to better understand what specific events mean.

| Field         | Description                                                                                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name          | The database name of the event.                                                                                                                                            |
| Display Name  | The event name that displays in the Mixpanel interface.                                                                                                                    |
| Description   | The information that describes the event, such as what triggers it or what properties are sent with it.                                                                    |
| Status        | The event is either hidden or visible in the Mixpanel project.                                                                                                             |
| Tags          | Allows your team to categorize events by different themes.                                                                                                                 |
| Platforms     | Allows your team to categorize which platforms this event is fired in.                                                                                                     |
| Owners        | Allows your team to assign a point-of-contact to events in case team members have follow-up questions about an event. (Only available on the Enterprise Plan)              |
| First Tracked | The earliest date a given event was tracked, within the past two years. If the event was first tracked more than two years ago, that earlier date won't be reflected here. |
| Image         | Allows your team to upload a JPG, PNG, or GIF that helps to describe the event. This will show up throughout the platform wherever the event appears.                      |


# Warehouse Sync Monitoring (Beta)
Source: https://docs.mixpanel.com/docs/data-governance/warehouse-sync-monitoring



## Overview

Mixpanel provides comprehensive monitoring for your warehouse syncs to help you maintain data quality and control costs. When you create a warehouse sync, you're automatically subscribed to Sync Health notifications, ensuring you stay informed about the status of your data pipelines.

<Note>
  Warehouse sync monitoring is currently available for Enterprise customers only. It supports BigQuery, Snowflake, and Redshift warehouses and must be enabled by Mixpanel Support. Please reach out to [support@mixpanel.com](mailto:support@mixpanel.com) with the project ID numbers you wish to enable Warehouse Sync Monitoring for.
</Note>

## Sync Health Notifications

Sync Health notifications alert you to potential issues with your warehouse syncs. These notifications are automatically enabled for all warehouse connections and are sent to project owners and admins by default. You can add additional email addresses and Slack channels to receive alerts.

The following sync issues trigger notifications:

**Sync Failed**: Alerts you when a sync fails to complete successfully, helping you quickly identify and resolve connection or data issues.

These notifications help you maintain data pipeline reliability without changing the status of your syncs. Your syncs will continue to retry according to their configured schedule.

## Data Volume Alerts

Data volume alerts help you monitor unusual increases in your warehouse sync data and prevent unexpected billing charges. You can configure two types of thresholds:

**Notify and Sync**: When data volume exceeds this threshold, Mixpanel sends a notification but continues to sync the data. This allows you to monitor volume changes while maintaining data completeness.

**Notify and Pause**: When data volume exceeds this higher threshold, Mixpanel sends a notification and pauses the sync for up to 14 days. This gives you time to investigate the volume increase and decide whether to proceed.

Data volume increases can occur when:

* New columns are added to your warehouse tables
* Historical data is backfilled
* Table schemas are modified in ways that trigger updates across many rows
* Your data processing pipeline generates more events than usual

Volume thresholds are calculated based on the rolling 30-day average of billable events for each sync. You can customize these thresholds in your warehouse sync settings to match your organization's needs and risk tolerance.

## Managing Notifications

To configure your notification preferences:

1. Navigate to **Data > Lexicon**
2. Select **Volume Monitoring** under **Data Governance**
3. Toggle **Enable monitoring for data warehouse syncs**
4. Configure your email recipients
5. Set your data volume thresholds

<Note>
  Sync Health notifications are built into warehouse monitoring and cannot be disabled independently.
</Note>


# Data Pipelines Overview
Source: https://docs.mixpanel.com/docs/data-pipelines



<Warning>
  If you already did setup older version of pipelines via the API and want to manage it, go to docs [here](/docs/data-pipelines/old-pipelines).
</Warning>

<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Data Pipelines is a feature that continuously exports data from your Mixpanel project to a Cloud Storage bucket or Data Warehouse of your choice. This feature is ideal for those who wish to perform SQL analysis on Mixpanel data within their own environment.

Setting up Data Pipelines involves two main steps:

1. Configuring your destination to accept data writes from Mixpanel.
2. Creating data pipelines through the **Destinations** page in the UI.

We offer a 30-day free trial of the Data Pipelines add-on. For details on activation, refer to the [FAQ](#how-does-the-free-trial-work).

## Step 1: Configuring Your Destination

The configuration process varies depending on the type of destination you choose: Cloud Storage or Data Warehouse.

### Cloud Storage

JSON pipelines export data as JSON files to a cloud storage bucket, providing a straightforward method for data handling.

For specific configuration instructions, see our guides for each storage destination:

* [AWS S3](/docs/data-pipelines/integrations/aws-s3)
* [Google Cloud Storage](/docs/data-pipelines/integrations/gcp-gcs)
* [Azure Blob Storage](/docs/data-pipelines/integrations/azure-blob-storage)

Data is exported to the following structured paths in your bucket:

* Events: `<BUCKET_NAME>/<MIXPANEL_PROJECT_ID>/mp_master_event/<YEAR>/<MONTH>/<DAY>/`
* User profiles: `<BUCKET_NAME>/<MIXPANEL_PROJECT_ID>/mp_people_data/`
* Identity mappings: `<BUCKET_NAME>/<MIXPANEL_PROJECT_ID>/mp_identity_mappings_data/`

### Data Warehouse

JSON Pipelines also facilitate data export into tables, creating schemas that are inferred from your event data.

For detailed setup guides per destination, see:

* [BigQuery](/docs/data-pipelines/integrations/bigquery)
* [Databricks](/docs/data-pipelines/integrations/databricks)
* [Redshift Spectrum](/docs/data-pipelines/integrations/redshift-spectrum)
* [Snowflake](/docs/data-pipelines/integrations/snowflake)

## Step 2: Creating the Pipeline

<Note>
  To create and manage a Data Pipeline, you must have an admin or owner project role. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

After configuring your destination to accept data exported from Mixpanel, we must initiate the pipeline from the Mixpanel UI.

After configuring your destination, initiate the data export in the **Destinations** page on your Mixpanel project -> **Create Pipeline** -> fill in the necessary configurations. You can choose different data sources, including events, people and identity, and other advanced options. See [Data Pipelines](/docs/data-pipelines/json-pipelines) for more details.

<Steps>
  <Step title="Click the settings button and select Destinations">
    <Frame>
      <img alt="create_pipeline1" />
    </Frame>
  </Step>

  <Step title="Select the provider of your warehouse destination, and click &#x22;+ Create Pipeline&#x22;">
    <Frame>
      <img alt="create_pipeline2" />
    </Frame>
  </Step>

  <Step title="Provide the details of your destination to create the pipeline">
    <Frame>
      <img alt="create_pipeline3" />
    </Frame>
  </Step>
</Steps>

## FAQ

### Managing Existing Pipelines

To delete, pause, or unpause a JSON pipeline:

1. Go to the **Destinations** page
2. Find the pipeline you want to manage
3. Click the **3-dot** menu on the right side of the pipeline
4. Select **Delete Pipeline**, **Pause Pipeline**, or **Unpause Pipeline** as needed

Note: JSON pipelines can only be managed through the UI, not via the data pipelines API.

### Backfilling Historical Data

You can schedule an initial backfill when creating a pipeline. This ensures that historical data is also exported to the data warehouse. Note that the `from_date` value must be within 6 months in the past.

The completion time for a backfill depends on the number of days and the amount of data in the project. Larger backfills can take up to multiple weeks.

### Viewing Pipeline Configuration

To check a pipeline's configuration:

1. Go to the **Destinations** page
2. Either:

   * Click on the pipeline name to view the configuration at the top of the page, or
   * Click the **3-dot** menu and select **View Configuration**

### Why does the number of events in Mixpanel not match the number of exported events to my destination?

Discrepancies between the event counts in Mixpanel and those exported to your destination can occur for several reasons:

* **Data Sync**: If [Events Data Sync](/docs/data-pipelines/json-pipelines#events-data-sync) is not enabled or is unsupported for your pipeline, this could prevent some data from being exported.
* **Data Delay**: Late-arriving data may take up to one day to sync from Mixpanel to your destination, leading to temporary discrepancies.
* **Hidden Events**: Mixpanel exports all events, including those hidden in the Mixpanel UI via Lexicon. To reconcile differences in counts, check if the events in your destination include those hidden in the Mixpanel UI.
* **Timezone Differences**: Data is exported to your warehouse in UTC, whereas data displayed in Mixpanel is in your project's timezone.

### What timezone is the data exported in?

The data is exported in UTC timezone. You’ll need to convert it to your project’s timezone when running queries in your warehouse. Please refer to [this page](/docs/data-pipelines/common-sql-queries) for some common SQL queries.

### How can I count events exported by Mixpanel in the warehouse?

Counting events can be slightly different for each warehouse, since we use different partitioning methods. Here are examples for [BigQuery](/docs/data-pipelines/integrations/bigquery#get-the-number-of-events-each-day) and [Snowflake](/docs/data-pipelines/integrations/snowflake#get-the-number-of-events-each-day).

### How does the free trial work?

Mixpanel offers a 30-day free trial of the Data Pipelines, allowing you to create one pipeline per data source for each project.

**Trial limitations**:

* Exports are scheduled daily only.
* Data synchronization feature is not available.
* Only one pipeline can be created per data source per project.
* Backfilled data is limited to one day before the creation date of the pipeline.

### Why can’t I delete my trial pipeline?

You can’t delete a trial pipeline in Mixpanel — this is intentional. Each project is limited to one trial pipeline per data source, and keeping it prevents deleting/recreating trials to bypass limits. It also serves as a record that the trial has been used. Even after you upgrade to a paid Data Pipelines package, the trial pipeline remains visible and cannot be removed. This is a policy decision to preserve the integrity of the trial program, not a technical constraint.

### What is Active Pipeline Limit

Each project can have two recurring pipelines and one date-ranged backfill pipeline active. Multiple pipelines cannot write to the same destination or for the same date range in a destination. Recurring pipelines must have different frequencies.

To maintain optimal performance across our services, we limit the number of concurrently running pipeline steps to one per project. This approach ensures that each job, including those involving substantial backfills, waits its turn, preventing any single project from monopolizing resources and thus promoting fair scheduling among all customers.

### Is it possible to specify when pipeline exports run?

No. Hourly pipelines are targeted to run 30 minutes past the hour to be exported, and daily pipelines are targeted to run 30 minutes past the day to be exported (e.g., 00:30 AM) in the project’s timezone. For example, a project in the Pacific timezone with a daily events pipeline will start the export for data from 5/22 on 5/23 00:30 AM PT.

Please note that the [24-hour SLA](/docs/data-pipelines#what-is-the-service-level-agreement) applies.

### What is the Service Level Agreement?

Our Service Level Agreement (SLA) stipulates a latency policy for exported events of up to 24 hours end-to-end, with an additional 24-hour allowance for late-arriving data.

**Note**: Mixpanel classifies late data as any data point or user profile update that reaches Mixpanel servers more than two hours after the end of the export window. Late-arriving event data is exported only for pipelines that have **sync** enabled.

For hourly pipelines, data that arrives on time is expected to be exported within 24 hours from the moment it is ingested by Mixpanel. For daily pipelines, this 24-hour period begins at the start of the next calendar day based on project time (e.g., data ingested on January 1st is scheduled to be exported from the start of January 2nd midnight to the end of the day on January 3rd).

Data arriving late is handled during a daily sync process the following day after ingestion, provided sync is enabled. For instance, if data for January 1st arrives on January 3rd, it would be exported in the sync run on January 4th.

### What should I set for the Account Name and Storage Integration when creating a Snowflake pipeline?

The Account Name should be set to your unique account identifier, e.g., "example1234.us-west-2", while the Storage Integration should be set to the name of the storage integration you created in Snowflake Eg. "MIXPANEL\_EXPORT\_STORAGE\_INTEGRATION".

### What happens to late-arriving data?

For [incremental JSON pipelines](/docs/data-pipelines/json-pipelines#incremental-pipelines), late-arriving data will be exported as it's ingested. However, that is not the case for Raw and Schematized pipelines without [sync](/docs/data-pipelines/json-pipelines#events-data-sync) enabled — manual intervention will be needed to export late-arriving data into your data warehouse.

### Can I change the destination of an existing pipeline?

No, you cannot. If you need to change the destination, you would need to create a new pipeline.


# Common SQL Queries
Source: https://docs.mixpanel.com/docs/data-pipelines/common-sql-queries



### Total daily count with deduplication logic and timezone adjustment

Events exported via pipelines (i.e. raw exports) can contain duplicates. Deduplication should be performed using 4 event properties: `event_name`, `time`, `distinct_id`, and `insert_id` (docs [here](/reference/event-deduplication)). This is an example of a total daily count, converted to a specific timezone and deduplicated.

```sql theme={"system"}
SELECT
  DATE(time, 'America/Los_Angeles') AS event_date,
  COUNT(DISTINCT CONCAT(event_name, time, distinct_id, insert_id)) AS event_count,
FROM
  `<your dataset>.mp_master_event`
WHERE
  DATE(time, 'America/Los_Angeles') >= '2025-08-01'
  AND DATE(time, 'America/Los_Angeles') < '2025-09-16'
GROUP BY
  1
ORDER BY
  1 ASC
```

### Unique user count with user ID resolution

Raw events may contain the original `distinct_id` associated with the user at the time of the event instead of the final canonical `distinct_id` for the user after authentication. The `mp_identity_mappings_data_view` contains mappings of the original `distinct_id`s to the resolved ones (i.e. canonical `distinct_id`s). You can use this mapping to make sure that the unique users calculations account for ID management and therefore more accurate.

```sql theme={"system"}
SELECT
  DATE(time, 'America/Los_Angeles') AS event_date,
  COUNT(DISTINCT resolved_user_id) AS unique_users
FROM (
  SELECT
    time,
    IFNULL(id_mappings.resolved_distinct_id, events.distinct_id) AS resolved_user_id
  FROM
    `<your dataset>.mp_master_event` AS events
  LEFT JOIN
    `<your dataset>.mp_identity_mappings_data_view` AS id_mappings
  ON
    events.distinct_id = id_mappings.distinct_id
  WHERE
    DATE(time, 'America/Los_Angeles') >= '2025-08-01'
    AND DATE(time, 'America/Los_Angeles') < '2025-09-16' )
GROUP BY
  1
ORDER BY
  1 ASC
```

### Top 20 events by volume

```sql theme={"system"}
SELECT
  event_name,
  COUNT(*) AS event_count
FROM
  `<your dataset>.mp_master_event`
WHERE
  DATE(time, 'America/Los_Angeles') >= '2025-08-01'
  AND DATE(time, 'America/Los_Angeles') < '2025-09-16'
GROUP BY
  1
ORDER BY
  2 DESC
LIMIT
  20
```

### Querying duplicate events

Raw exported events can contain duplicates. You can use these 4 event properties to identify duplicates: `event_name`, `time`, `distinct_id`, and `insert_id` (docs [here](/reference/event-deduplication)). This is an example of a query you can use to identify duplicate events in your raw data.

```sql theme={"system"}
SELECT
 *,
 COUNT(*) OVER (PARTITION BY event_name, time, distinct_id, insert_id ) AS dup_group_size
FROM
 `<your dataset>.mp_master_event`
WHERE
 DATE(time, 'America/Los_Angeles') >= '2025-08-01'
 AND DATE(time, 'America/Los_Angeles') < '2025-09-16'
QUALIFY
 dup_group_size > 1
ORDER BY
 DATE(time, 'America/Los_Angeles'),
 event_name,
 time
```


# Data Pipeline Integrations
Source: https://docs.mixpanel.com/docs/data-pipelines/integrations

Export your Mixpanel data to a data warehouse

<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

These integrations allow you to send your Mixpanel data into a data warehouse.

## Featured Integrations

<CardGroup>
  <Card title="AWS S3" href="/docs/data-pipelines/integrations/aws-s3" />

  <Card title="Azure Blob Storage" href="/docs/data-pipelines/integrations/azure-blob-storage" />

  <Card title="BigQuery" href="/docs/data-pipelines/integrations/bigquery" />

  <Card title="Databricks" href="/docs/data-pipelines/integrations/databricks" />

  <Card title="Google Cloud Storage" href="/docs/data-pipelines/integrations/gcp-gcs" />

  <Card title="Redshift Spectrum" href="/docs/data-pipelines/integrations/redshift-spectrum" />

  <Card title="Snowflake" href="/docs/data-pipelines/integrations/snowflake" />
</CardGroup>


# AWS S3
Source: https://docs.mixpanel.com/docs/data-pipelines/integrations/aws-s3



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Mixpanel allows you to export events and people data into AWS S3 through [Json Pipelines](/docs/data-pipelines)

## Setting S3 Permissions

Before detailing the steps necessary to configure permissions, it's important to note that you need to create your AWS S3 bucket.

Mixpanel supports various configurations to securely manage your data on AWS S3. For resource access, Mixpanel utilizes AWS cross-account roles. This section details the necessary permissions Mixpanel requires based on your S3 bucket configuration.

### Step 1: Create Data Modification Policy

To export data from Mixpanel to AWS S3, assign the following data modification permissions. Use the following policy, replacing `<BUCKET_NAME>` with the name of your bucket:

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MixpanelS3AccessStatement",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:ListBucket",
        "s3:DeleteObject"
      ],
      "Resource": ["arn:aws:s3:::<BUCKET_NAME>", "arn:aws:s3:::<BUCKET_NAME>/*"]
    }
  ]
}
```

### Step 2: Server-Side Encryption (optional)

Mixpanel ensures data transfer to your S3 bucket over a TLS encrypted connection. To secure your data at rest in S3, enable [Server-Side Encryption (SSE)](https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html), which offers two options: **Encryption with Amazon S3-Managed Keys (SSE-S3)** and **Encryption with AWS KMS-Managed Keys (SSE-KMS)**

#### Encryption with Amazon S3-Managed Keys (SSE-S3)

This option encrypts your data at rest using the AES-256 algorithm, with keys managed by S3. To enable this, select `AES` from the **Encryption** dropdown menu when creating pipelines.

#### Encryption with AWS KMS-Managed Keys (SSE-KMS)

For encryption with AWS KMS, you have the option to use either the default `aws/s3` key or your own custom keys.

* Using the Default Key

  Simply select `KMS` from the **Encryption** dropdown menu and leave the `KMS Key ID` field empty when creating your pipeline.
* Using Custom Key

  1. Select `KMS` from the **Encryption** dropdown menu and enter your custom key's ARN in the `KMS Key ID` field.
  2. Create an IAM policy allowing Mixpanel to use your KMS key, as shown in the JSON snippet below. Replace `<KEY_ARN>` with your key's ARN:

     ```json theme={"system"}
     {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Sid": "MixpanelKmsStatement",
           "Effect": "Allow",
           "Action": [
             "kms:Decrypt",
             "kms:Encrypt",
             "kms:GenerateDataKey",
             "kms:ReEncryptTo",
             "kms:GenerateDataKeyWithoutPlaintext",
             "kms:DescribeKey",
             "kms:ReEncryptFrom"
           ],
           "Resource": "<KEY_ARN>"
         }
       ]
     }
     ```

### Step 3: Create Access Role

After establishing the necessary policies, create a cross-account IAM Role to attach policies you've created:

* Go to the **IAM** service on the AWS console.
* Select **Roles** in the sidebar and click **Create role**.
* On the trusted entity page, choose **AWS Account**, then click **Another AWS account**, and enter `485438090326` for the **Account ID** and click **Next**.
* On the permissions page, locate and attach the policies you created in previous steps (data modification and, if applicable, KMS).
* On the review page, provide a name and description for this role and click **Create role**.

To ensure secure operations, limit the trust relationship to the Mixpanel export user:

* Return to the **IAM** service, select **Roles**, and locate the role you just created.
* In the **Trust relationships** tab, click **Edit trust policy**.
* Update the trust relationship with the following JSON, replacing `<MIXPANEL_PROJECT_TOKEN>` with your Mixpanel project token.

  ```json theme={"system"}
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::485438090326:user/mixpanel-export"
        },
        "Action": "sts:AssumeRole",
        "Condition": {
          "StringEquals": {
            "sts:ExternalId": "<MIXPANEL_PROJECT_TOKEN>"
          }
        }
      }
    ]
  }
  ```
* Click **Update policy** and save.

This setup utilizes an external ID to prevent [the confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html), enhancing the security of cross-account access as Mixpanel interacts with AWS using your project token.

### Step 4: Provide Mixpanel with S3 Details

Refer to [Step 2: Creating the Pipeline](/docs/data-pipelines/#step-2-creating-the-pipeline) to create data pipeline via UI. It is essential to provide specific details to ensure that Mixpanel can accurately direct the data exports to your S3 bucket:

* **Bucket**: Specify the S3 bucket where Mixpanel data should be exported.
* **Region**: Indicate the AWS region where your S3 bucket is located.
* **Role**: Provide the AWS Role ARN that Mixpanel should assume when writing to your S3, e.g., `arn:aws:iam:::role/example-s3-role`.
* **Encryption (optional)**: Specify the type of at-rest encryption used by the S3 bucket.
* **KMS Key ID (optional)**: If using KMS encryption, you can provide the custom key ID that you wish to use.

<Note>
  If you'll query this data through Glue or Redshift Spectrum and your account uses AWS Lake Formation, see [Setting Glue Permissions](/docs/data-pipelines/integrations/redshift-spectrum#setting-glue-permissions) for the additional Lake Formation grants you'll need.
</Note>

## Supported AWS Regions

`US-EAST-1, US-EAST-2, US-WEST-1, US-WEST-2, AP-NORTHEAST-1, AP-NORTHEAST-2, AP-NORTHEAST-3, AP-SOUTHEAST-1, AP-SOUTHEAST-2, AP-SOUTH-1, CA-CENTRAL-1, CN-NORTH-1, CN-NORTHWEST-1, EU-CENTRAL-1, EU-NORTH-1, EU-WEST-1, EU-WEST-2, EU-WEST-3, SA-EAST-1, ME-SOUTH-1`


# Azure Blob Storage
Source: https://docs.mixpanel.com/docs/data-pipelines/integrations/azure-blob-storage



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Mixpanel allows you to export events and people data directly into an Azure Blob Storage instance through [Json Pipelines](/docs/data-pipelines).

## Setting Blob Storage Permissions

To enable Mixpanel to write data to your Azure Blob Storage, specific permissions need to be set up because Azure authentication mechanisms do not support cross-account access. You will need to provide Mixpanel with Azure credentials linked to your Blob Storage container.

### Step 1: Create a Service Principal

Start by creating a ***Service Principal*** in your Azure Active Directory. This can be done using the Azure CLI with the following command (with `"redacted"` output). This command generates credentials in JSON format. Ensure you securely handle the output as it contains sensitive information.

```shell theme={"system"}
$ az ad sp create-for-rbac --sdk-auth
{
  "clientId": "redacted",
  "clientSecret": "redacted",
  "subscriptionId": "redacted",
  "tenantId": "redacted",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  "activeDirectoryGraphResourceId": "https://graph.windows.net/",
  "sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
  "galleryEndpointUrl": "https://gallery.azure.com/",
  "managementEndpointUrl": "https://management.core.windows.net/"
}
```

### Step 2: Assign Role to Service Principal

Next, navigate to the Blob Storage container you wish to use, and assign the `"Storage Blob Data Contributor"` role to the newly created Service Principal.

### Step 3: Provide Mixpanel with Access Details

Refer to [Step 2: Creating the Pipeline](/docs/data-pipelines/#step-2-creating-the-pipeline) to create data pipeline via UI. You need to provide specific details to enable authentication and data export to Azure Blob Storage. For authentication, supply the `Client Id`, `Client Secret`, and `Tenant Id`. These credentials are crucial for Mixpanel to operate as the Service Principal and ensure secure authentication without exposing broader Azure resources.

Additionally, to define the export destination, you must provide the `Storage Account` and `Container Name`. These details identify the exact location within Azure where your data will be exported.


# BigQuery
Source: https://docs.mixpanel.com/docs/data-pipelines/integrations/bigquery



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

This guide describes how Mixpanel exports your data into a customer-managed [Google BigQuery](https://cloud.google.com/bigquery/) dataset.

## Design

<Frame>
  <img alt="image" />
</Frame>

For events data, we create a single table called `mp_master_event` and store all external properties inside the `properties` column in JSON type. Users can extract properties using JSON functions. See [Query Data](#query-data) for more details.

For user profiles and identity mappings, we create new tables `mp_people_data_*` and `mp_identity_mappings_data_*` with a random suffix every time and then update views `mp_people_data_view` and `mp_identity_mappings_data_view` accordingly to use the latest table. Always use the views instead of the actual tables, as we do not immediately delete old tables, and you may end up using outdated data.

Export logs are maintained in the `mp_nessie_export_log` table within BigQuery. This table provides detailed information such as export times, date ranges (from date & to date), and the number of rows exported. This data allows for effective monitoring and auditing of the data export processes.

> **Important:** Please do not modify the schema of tables generated by Mixpanel. Altering the table schema can cause the pipeline to fail to export due to schema mismatches.

## Setting BigQuery Permissions

Please follow these steps to share permissions with Mixpanel and create json pipelines.

### Step 1: Create a Dataset

Create a dataset in your BigQuery to store the Mixpanel data.

<Frame>
  <img alt="image" />
</Frame>

### Step 2: Grant Permissions to Mixpanel

> **Note:** If your organization uses [domain restriction constraint](https://cloud.google.com/resource-manager/docs/organization-policy/restricting-domains) you will have to update the policy to allow Mixpanel domain `mixpanel.com` and Google Workspace customer ID: `C00m5wrjz`.

Mixpanel requires two permissions to manage the dataset:

**BigQuery Job User**

* Navigate to **IAM & Admin** in your Google Cloud Console.
* Click **+ ADD** to add principals
* Add new principal `export-upload@mixpanel-prod-1.iam.gserviceaccount.com` and set the role as `BigQuery Job User`
* Click the **Save** button.

<Frame>
  <img alt="image" />
</Frame>

**BigQuery Data Owner**

* Go to **BigQuery** in your Google Cloud Console.
* Open the dataset intended for Mixpanel exports.
* Click on **Sharing** and **Permissions** in the drop down.
* In the Data Permissions window, click on **Add Principal**
* Add new principal `export-upload@mixpanel-prod-1.iam.gserviceaccount.com` and set the role as `BigQuery Data Owner`, and save.

<Frame>
  <img alt="image" />
</Frame>

### Step 3: Provide Necessary Details for Pipeline Creation

Refer to [Step 2: Creating the Pipeline](/docs/data-pipelines/#step-2-creating-the-pipeline) to create data pipeline via UI. You need to provide specific details to enable authentication and data export to BigQuery.

* **GCP project ID**: The project ID where BigQuery dataset is present
* **Dataset name**: Dataset created on the GCP project to which Mixpanel needs to export data
* **GCP region**: The region used for BigQuery

## Partitioning

Data in the events table `mp_master_event` is partitioned based on the [`_PARTITIONTIME` pseudo column](https://cloud.google.com/bigquery/docs/querying-partitioned-tables#ingestion-time_partitioned_table_pseudo_columns) and in the project timezone.

Note: `TIMEPARTITIONING` should not be updated on the table. It will cause your export jobs to fail. Create a new table/view from this table for custom partitioning.

## Query Data

This section provides examples of how to query data exported to BigQuery. Refer to [BigQuery docs](https://cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_value) for more details about using JSON functions to query properties.

### Get the Number of Events Each Day

To verify the completeness of the export process, use the following SQL query to count events per day:

```sql theme={"system"}
SELECT
  _PARTITIONTIME AS pt,
  COUNT(*)
FROM
  `<your gcp project>.<your dataset>.mp_master_event`
WHERE
  DATE(_PARTITIONTIME) <= "2024-05-31"
  AND DATE(_PARTITIONTIME) >= "2024-05-01"
GROUP BY
  pt
```

### Query identity mappings

When querying the identity mappings table, prioritize using the `resolved_distinct_id` over the non-resolved `distinct_id` whenever it is available. If a `resolved_distinct_id` is not available, you should revert to using the `distinct_id` from the existing people or events table.

Below is an example query that utilizes the identity mappings table. This query counts the number of events for each unique user in San Francisco within a specific date range.

```sql theme={"system"}
SELECT
  CASE
    WHEN mappings.resolved_distinct_id IS NOT NULL THEN mappings.resolved_distinct_id
    WHEN mappings.resolved_distinct_id IS NULL THEN events.distinct_id
END
  AS resolved_distinct_id,
  COUNT(*) AS count
FROM
  `<your gcp project>.<your dataset>.mp_master_event` events
INNER JOIN
  `<your gcp project>.<your dataset>.mp_identity_mappings_data_view` mappings
ON
  events.distinct_id = mappings.distinct_id
  AND JSON_VALUE(properties,'$."$city"') = "San Francisco"
  AND DATE(events._PARTITIONTIME) <= "2024-05-31"
  AND DATE(events._PARTITIONTIME) >= "2024-05-01"
GROUP BY
  resolved_distinct_id
LIMIT
  100
```

This query demonstrates how to effectively use conditional logic and JSON functions within BigQuery to analyze user behavior based on geographic location. Additional filters on event properties can be added to refine the analysis, allowing for more detailed insights into specific user actions or behaviors.

## Supported GCP Regions for BigQuery

`US, US_CENTRAL_1, US_EAST_1, US_WEST_1, US_WEST_2, US_EAST_4, NORTH_AMERICA_NORTHEAST_1, SOUTH_AMERICA_EAST_1, EU, EUROPE_NORTH_1, EUROPE_WEST_2, EUROPE_WEST_3, EUROPE_WEST_4, EUROPE_WEST_6, ASIA_SOUTH_1, ASIA_EAST_1, ASIA_EAST_2, ASIA_NORTHEAST_1, ASIA_NORTHEAST_2, ASIA_NORTHEAST_3, ASIA_SOUTHEAST_1, ASIA_SOUTHEAST_2, AUSTRALIA_SOUTHEAST_1`

### VPC Service Controls

IP allowlists are [not supported](https://docs.cloud.google.com/vpc-service-controls/docs/use-access-levels#limitations_of_using_access_levels_with) for BigQuery because Mixpanel's infrastructure runs on GCP, and inter-project communication in Google Cloud routes through internal Google IPs rather than public IPs. Instead, configure an ingress rule to allow access based on other attributes such as the project or service account. The Mixpanel project is `745258754925` for US, `848893383328` for EU, and `1054291822741` for IN. The service account is `export-upload@mixpanel-prod-1.iam.gserviceaccount.com`.


# Databricks
Source: https://docs.mixpanel.com/docs/data-pipelines/integrations/databricks



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Export your Mixpanel data to Databricks using Unity Catalog Managed Volumes. This integration supports all Databricks clouds (AWS, GCP, and Azure).

## Design

Mixpanel exports data to the customer's Databricks workspace using Unity Catalog Managed Volumes. We first load the data into a single-column (VARIANT type) raw data table, then create a view to expose all properties as typed columns.

### Supported Features

* **Cross-cloud Support**: Works with Databricks on AWS, GCP, or Azure
* **Date Clustering**: Raw tables use liquid clustering on `event_date` for efficient date-based queries
* **Static IP Addresses**: Supports IP allowlisting for secure connections

### IP Allowlist

Mixpanel Data Pipelines supports static IP addresses for Databricks connections when IP restrictions are configured on your Databricks workspace. If you are using network policies to restrict access to your instance, you might need to add the following IP addresses to the allowed list:

**US**

```text theme={"system"}
34.31.112.201
35.184.21.33
35.225.176.74
```

**EU**

```text theme={"system"}
34.147.68.192
35.204.164.122
35.204.177.251
```

**IN**

```text theme={"system"}
34.47.224.29
34.93.42.83
35.244.19.238
```

## Prerequisites

Before setting up the integration, ensure you have:

* A Databricks workspace with Unity Catalog enabled
* A SQL Warehouse (Serverless recommended for best performance and cost)
* Admin permissions in your Databricks workspace to create Service Principals

## Set Export Permissions

### Step 1: Create a Service Principal (or use existing one)

A Service Principal is a Databricks identity that Mixpanel will use to access your workspace.

1. In your Databricks workspace, navigate to **Settings** → **Identity and access** → **Service principals**
2. Click **Add service principal**
3. Click **Add new**
4. Note the **Application ID** - you'll need this later

### Step 2: Generate OAuth Secret

1. Click on the Service Principal you just created
2. Navigate to the **Secrets** tab
3. Click **Generate secret** and enter lifetime (730 days recommended)
4. Copy the **Secret value** immediately - it won't be shown again
5. Store it securely - you'll need it for Mixpanel configuration

### Step 3: Create new Catalog (or use existing ones) and Schema

<Note>
  Creating a new catalog requires the `CREATE CATALOG` privilege, which is a metastore-level permission. Contact your **metastore admin** or **account admin** to grant this privilege.
</Note>

<Note>
  If you are using an existing shared catalog, contact the **catalog owner** or a **metastore admin** to grant the following privileges:

  ```sql theme={"system"}
  GRANT USE CATALOG ON CATALOG <catalog> TO `<user>`;
  GRANT CREATE SCHEMA ON CATALOG <catalog> TO `<user>`;
  GRANT MANAGE ON CATALOG <catalog> TO `<user>`;
  ```
</Note>

Create a dedicated catalog and schema for Mixpanel data. You can run SQL under SQL Editor or Catalog Explorer.

```sql theme={"system"}
-- Create Catalog
CREATE CATALOG IF NOT EXISTS mixpanel_export;

-- Create schema
CREATE SCHEMA IF NOT EXISTS mixpanel_export.json_pipelines;
```

### Step 4: Grant Permissions to Service Principal

Grant the Service Principal required permissions to operate within the catalog.

```sql theme={"system"}
GRANT USE CATALOG ON CATALOG mixpanel_export
  TO `<service-principal-application-id>`;

GRANT USE SCHEMA ON SCHEMA mixpanel_export.json_pipelines
  TO `<service-principal-application-id>`;

GRANT CREATE TABLE ON SCHEMA mixpanel_export.json_pipelines
  TO `<service-principal-application-id>`;

GRANT CREATE VOLUME ON SCHEMA mixpanel_export.json_pipelines
  TO `<service-principal-application-id>`;
```

**For Metastore Privilege Version 1.1+**, additionally grant "CREATE VIEW" on schema:

* **Version 1.0**: privilege `CREATE TABLE` covers both tables and views
* **Version 1.1+**: Separate `CREATE VIEW` privilege required

```sql theme={"system"}
-- Check your metastore privilege version by PrivilegeModelVersion
DESCRIBE METASTORE;

GRANT CREATE VIEW ON SCHEMA mixpanel_export.json_pipelines
  TO `<service-principal-application-id>`;
```

#### Why These Permissions?

* `USE CATALOG`: Required to access the catalog
* `USE SCHEMA`: Required to access objects in the schema
* `CREATE TABLE`: Create raw tables to store event data
* `CREATE VOLUME`: Create temporary volumes for uploading files
* `CREATE VIEW`: Create views with typed columns (metastore v1.1+ only)

**Note**: The Service Principal automatically becomes the **owner** of all objects it creates (tables, views, volumes), which grants it full permissions (SELECT, MODIFY, READ FILES, WRITE FILES, etc.) on those objects. No additional grants needed.

### Step 5: Grant SQL Warehouse Access

The Service Principal needs permission to use the SQL Warehouse to execute queries.

1. In your Databricks workspace, navigate to **SQL Warehouses**
2. Click on your SQL Warehouse (or create one if needed)
3. Go to the **Permissions** tab
4. Click **Add** or **Grant permissions**
5. Search for your Service Principal by Application ID (from Step 1)
6. Select permission level: **Can use** (minimum required)
7. Click **Save**

**Why this is needed**: SQL Warehouses have their own access control separate from data permissions. Even with all catalog/schema/table permissions, the Service Principal cannot execute queries without warehouse access.

### Step 6: Get SQL Warehouse Connection Details

1. In the same SQL Warehouse, go to the **Connection details** tab
2. Note the following values:

   * **Server hostname**: e.g., `abc123.cloud.databricks.com`
   * **HTTP Path**: e.g., `/sql/1.0/warehouses/xyz789`

**Recommendation**: Use a Serverless SQL Warehouse for:

* Fast startup (\~3 seconds)
* Auto-scaling
* Pay-per-use pricing
* No idle cluster costs

### Step 7: Configure Mixpanel Integration

Refer to [Step 2: Creating the Pipeline](/docs/data-pipelines/#step-2-creating-the-pipeline) to create data pipeline via UI. You'll need to provide:

* **Server Hostname** (from Step 6)
* **HTTP Path** (from Step 6)
* **Catalog** (from Step 3, e.g., `mixpanel_export`)
* **Schema** (from Step 3, e.g., `json_pipelines`)
* **Service Principal ID** (Application ID from Step 1)
* **Service Principal Secret** (from Step 2)

## Clustering

Raw tables are clustered by the `event_date` column, which is computed in your project's timezone during data load. This clustering significantly improves query performance when filtering by date.

## Data Schema

Mixpanel creates a raw table and a view with typed columns:

**Raw Table Columns** (`mp_master_event_raw`):

* `DATA` (VARIANT) - Contains the complete event JSON
* `event_date` (DATE) - Computed from event time in your project's timezone

**View Columns** (`mp_master_event`):

* `user_id` (STRING)
* `time` (TIMESTAMP)
* `properties` (VARIANT) - All event properties as semi-structured data
* `insert_id` (STRING)
* `event_name` (STRING)
* `distinct_id` (STRING)
* `device_id` (STRING)
* `event_date` (DATE)

## Queries

<Note>
  Remember to grant necessary permissions to any user who wants to query the table

  ```sql theme={"system"}
  GRANT USE CATALOG ON CATALOG mixpanel_export TO `<user>`;
  GRANT USE SCHEMA ON SCHEMA mixpanel_export.json_pipelines TO `<user>`;
  GRANT SELECT ON SCHEMA mixpanel_export.json_pipelines TO `<user>`;
  ```
</Note>

Databricks supports a VARIANT type that can store semi-structured JSON data. Use the `::` syntax to extract and cast properties from VARIANT columns.

### Basic event query

```sql theme={"system"}
SELECT count(*)
FROM mixpanel_export.json_pipelines.mp_master_event
WHERE event_name = 'sign up';
```

### Query nested properties

```sql theme={"system"}
SELECT
    event_name,
    time,
    distinct_id,
    properties:button_name::STRING AS button_name,
    properties:product:category::STRING AS product_category,
    properties:price::DOUBLE AS price
FROM mixpanel_export.json_pipelines.mp_master_event
WHERE event_name = 'Purchase'
  AND properties:product:category::STRING = 'Electronics';
```

### Getting the number of events per day

```sql theme={"system"}
SELECT
    event_date,
    count(*) as event_count
FROM mixpanel_export.json_pipelines.mp_master_event
WHERE event_date >= '2024-01-01' AND event_date <= '2024-01-31'
GROUP BY event_date
ORDER BY event_date;
```

### Efficient date filtering

Use the `event_date` column for best performance:

```sql theme={"system"}
SELECT
    event_name,
    time,
    distinct_id,
    properties:button_name::STRING AS button_name
FROM mixpanel_export.json_pipelines.mp_master_event
WHERE event_date BETWEEN '2024-01-01' AND '2024-01-31'
  AND event_name = 'Purchase'
ORDER BY time DESC;
```

## Costs

* **Delta tables**: Billed by your cloud provider (AWS S3, GCP GCS, or Azure ADLS) via Databricks
* **Managed volumes**: Temporary storage cleaned up after each export
* **Compute**: SQL Warehouse usage during COPY INTO operations


# Google Cloud Storage
Source: https://docs.mixpanel.com/docs/data-pipelines/integrations/gcp-gcs



Mixpanel supports exporting events and people data directly to Google Cloud Storage (GCS) via [Json Pipelines](/docs/data-pipelines).

## Setting GCS Permissions

To facilitate data export to Google Cloud Storage, proper permissions need to be configured to allow Mixpanel access to your GCS bucket.

### Step 1: Assign Roles to Service Account on Bucket

You must grant the `Storage Object Admin` role to the service account `export-upload@mixpanel-prod-1.iam.gserviceaccount.com` for the bucket you are creating or intend to reuse. This role allows Mixpanel to manage storage objects on your behalf.

To assign this role:

* Navigate to the **Cloud Storage** in your Google Cloud Console and select the GCS bucket you have created or plan to reuse
* Click on the **PERMISSIONS** tab and select **GRANT ACCESS**
* In the new principals field, add `export-upload@mixpanel-prod-1.iam.gserviceaccount.com` and then select `Storage Object Admin` from the role dropdown menu
* Confirm the assignment by clicking the **SAVE** button.

This process ensures that the specified service account has the necessary permissions to efficiently manage and handle the data exported to your GCS bucket.

### Step 2: Provide Mixpanel with GCS Details

Refer to [Step 2: Creating the Pipeline](/docs/data-pipelines/#step-2-creating-the-pipeline) to create data pipeline via UI. You need to provide the following details to ensure Mixpanel can accurately direct the data exports to your GCS:

* Bucket: The GCS bucket to export Mixpanel data to
* Region: The GCS region for the bucket

## Supported GCS Regions

`NORTHAMERICA-NORTHEAST1, US-CENTRAL1, US-EAST1, US-EAST4, US-WEST1, US-WEST2, SOUTHAMERICA-EAST1, EUROPE-NORTH1, EUROPE-WEST1, EUROPE-WEST2, EUROPE-WEST3, EUROPE-WEST4, EUROPE-WEST6, ASIA-EAST1, ASIA-EAST2, ASIA-NORTHEAST1, ASIA-NORTHEAST2, ASIA-NORTHEAST3, ASIA-SOUTH1, ASIA-SOUTHEAST1, AUSTRALIA-SOUTHEAST1`


# AWS Redshift Spectrum
Source: https://docs.mixpanel.com/docs/data-pipelines/integrations/redshift-spectrum



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Mixpanel's JSON pipelines enable direct export of your Mixpanel data into an S3 bucket, facilitating the use of Redshift Spectrum for querying.

## Design

<Frame>
  <img alt="image" />
</Frame>

Mixpanel exports data to your S3 bucket and simultaneously updates the necessary schema in the AWS Glue Data Catalog. This allows seamless integration with [Redshift Spectrum](https://docs.aws.amazon.com/redshift/latest/dg/c-getting-started-using-spectrum.html) for querying your data.

## Setting S3 Permissions

See [Setting S3 Permissions](/docs/data-pipelines/integrations/aws-s3#setting-s3-permissions)

## Setting Glue Permissions

[AWS Glue](https://aws.amazon.com/glue/) provides a robust data catalog service that facilitates seamless access to S3 data across various AWS services.

Mixpanel writes and updates schemas in your Glue instance, ensuring that new data becomes quickly available. This section details configuring Glue permissions to manage the exported data in S3.

### Step 1: Create Glue Database

* Navigate to the **AWS Glue** service on the AWS console. Make sure you are in the same region as your S3 exported data.
* Click **Databases** in the sidebar, then **Add database**.
* Name your database and click **Create database**.

<Frame>
  <img alt="image" />
</Frame>

### Step 2: Create Data Modification Policy

Mixpanel partitions the Glue table by default if it has the proper AWS permissions. The partition key type and name are `string` and `mp_date` respectively and the partition values are dates in the **UTC timezone** e.g. `2024-05-01`. To enable partitioning in Glue, the policy must include partition-related permissions.

To enable Mixpanel to manage partitions (e.g., `mp_date`) and schemas in Glue, you need to grant specific AWS permissions:

* Go to the **IAM** service on the AWS console.
* Click **Policies** in the sidebar and then **Create policy**.
* Under the **JSON** tab, input the following policy to manage tables and partitions:

  ```json theme={"system"}
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "MixpanelGlueAccessStatement",
        "Effect": "Allow",
        "Action": [
          "glue:GetDatabase",
          "glue:CreateTable",
          "glue:GetTable",
          "glue:GetTables",
          "glue:GetTableVersions",
          "glue:UpdateTable",
          "glue:DeleteTable",
          "glue:GetPartition",
          "glue:CreatePartition",
          "glue:DeletePartition",
          "glue:UpdatePartition",
          "glue:BatchCreatePartition",
          "glue:GetPartitions",
          "glue:BatchDeletePartition",
          "glue:BatchGetPartition"
        ],
        "Resource": "*"
      }
    ]
  }
  ```
* Click **Next** and name the policy and **Create policy**.

Note that AWS does not support granular resources when granting Glue access. So you will have to use \* (asterisk) in the Resources field until AWS can support more granular resources.

### Step 3: Create Access Role

* Go to the **IAM** service on the AWS console.
* Select **Roles** in the sidebar and click **Create role**.
* On the trusted entity page, choose **AWS Account**, then click **Another AWS account**, and enter `485438090326` for the **Account ID**.
* On the permissions page, locate and attach the policies you created in Step 2.
* On the review page, provide a name and description for this role and click **Create role**.

To ensure secure operations, limit the trust relationship to the Mixpanel export user:

* Return to the **IAM** service, select **Roles**, and locate the role you just created.
* In the **Trust relationships** tab, click **Edit trust policy**.
* Update the trust relationship with the following JSON and click **Update policy**.

  ```json theme={"system"}
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::485438090326:user/mixpanel-export"
        },
        "Action": "sts:AssumeRole",
        "Condition": {}
      }
    ]
  }
  ```

<Warning>
  If your Glue Data Catalog is governed by [AWS Lake Formation](https://docs.aws.amazon.com/lake-formation/latest/dg/what-is-lake-formation.html), the IAM permissions above are not sufficient on their own. Lake Formation enforces its own permission layer, so you'll also need to grant the Mixpanel Glue role permissions inside Lake Formation: `CREATE_TABLE` on the Glue **database**, plus a **Data location** permission on your registered S3 export path. Grant these at the database and data-location level, not only on the table.
</Warning>

## Setting Redshift Spectrum Permissions

This section outlines the necessary steps for configuring permissions to allow Mixpanel to create external schemas in Redshift Spectrum.

### Step 1: Create Policy

Create a policy in IAM with the necessary permissions to enable Mixpanel to interact with Redshift Spectrum, Glue Data Catalog, and S3. Replace `<BUCKET_NAME>` with your actual S3 bucket name:

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MixpanelRedshiftAccessStatement",
      "Effect": "Allow",
      "Action": [
        "redshift-data:GetStatementResult",
        "redshift-data:DescribeStatement",
        "redshift-data:BatchExecuteStatement",
        "redshift-data:ExecuteStatement",
        "redshift-serverless:GetCredentials",
        "redshift-serverless:GetWorkgroup",
        "redshift:GetClusterCredentialsWithIAM",
        "redshift:GetClusterCredentials"
      ],
      "Resource": "*"
    },
    {
      "Sid": "MixpanelGlueAccessStatement",
      "Effect": "Allow",
      "Action": [
        "glue:GetDatabase",
        "glue:GetDatabases",
        "glue:GetTable",
        "glue:GetTables",
        "glue:GetPartition",
        "glue:GetPartitions"
      ],
      "Resource": "*"
    },
    {
      "Sid": "MixpanelS3AccessStatement",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket", "s3:PutObject", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::<BUCKET_NAME>", "arn:aws:s3:::<BUCKET_NAME>/*"]
    }
  ]
}
```

### Step 2: Create Access Role

* Go to the **IAM** service on the AWS console.
* Select **Roles** in the sidebar and click **Create role**.
* On the trusted entity page, choose **AWS Account**, then click **Another AWS account**, and enter `485438090326` for the **Account ID**.
* On the permissions page, locate and attach the policies you created in Step 1.
* On the review page, provide a name and description for this role and click **Create role**.

To ensure secure operations, limit the trust relationship to the Mixpanel export user:

* Return to the **IAM** service, select **Roles**, and locate the role you just created.
* In the **Trust relationships** tab, click **Edit trust policy**.
* Update the trust relationship with the following JSON and click **Update policy**.

  ```json theme={"system"}
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::485438090326:user/mixpanel-export",
          "Service": "redshift.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
      }
    ]
  }
  ```

### Step 3: Associate Access Role to Redshift

Once you've established the IAM role that enables Mixpanel to access both the external Data Catalog and Amazon S3, it's essential to link this role with your Amazon Redshift Serverless instance.

Use the steps below, and refer to [IAM in Redshift Serverless](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless-iam.html) for additional details:

* Go to **Amazon Redshift** service on the AWS console
* Select Redshift Serverless and access the Namespace configuration for an existing workgroup
* Under **Security and encryption** tab, click **Manage IAM roles**
* Use the **Manage IAM roles** dropdown to select **Associate IAM roles** and then attach the role you created in Step 2.

### Step 4: Create Redshift Database

Create a new Redshift database or utilize an existing one. Here is how to create a new Redshift database:

<Frame>
  <img alt="image" />
</Frame>

<Frame>
  <img alt="image" />
</Frame>

### Step 5: Grant Privilege to Database User

To enable Mixpanel's external schema creation for pipeline operations, grant the `CREATE` privilege to the federated database user associated with the IAM role. AWS recommends using [federated identity](https://docs.aws.amazon.com/redshift/latest/mgmt/authorization-fas-spectrum.html) for Redshift resource management, leveraging your organization's identity system (e.g., AWS IAM) for authentication and authorization.

> **Important:** Do not manually create `IAMR:xxx` users via SQL commands. Redshift automatically generates a corresponding database user with the `IAMR:` prefix upon the first connection using the IAM role.

Follow these steps to grant the `CREATE` privilege:

* Go to the **CloudShell** service on the AWS console and assume the IAM role. Replace `<role-arn>` with the full ARN of the role you created in Step 2.

  ```bash theme={"system"}
  aws sts assume-role --role-arn <role-arn> --role-session-name MixpanelSession
  ```
* If you get an **"AccessDenied"** error, your current AWS CLI role can't assume the Mixpanel role. To fix this, edit the Mixpanel role's trust policy to allow your current role to assume it. If you're using SSO, add this to the trust policy, replacing `<your account id>` with your AWS account ID:

  ```json theme={"system"}
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::485438090326:user/mixpanel-export",
          "Service": "redshift.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
      },
      {
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::<your account id>:root"
        },
        "Action": "sts:AssumeRole"
      }
    ]
  }
  ```
* Configure AWS CLI with the temporary credentials.

  ```bash theme={"system"}
  aws configure set aws_access_key_id "<YOUR_ACCESS_KEY_ID>"
  aws configure set aws_secret_access_key "<YOUR_SECRET_ACCESS_KEY>"
  aws configure set aws_session_token "<YOUR_SESSION_TOKEN>"
  ```
* Run this command in your terminal, replacing the placeholders with your actual values, and trigger the db user `IAMR:<mixpanel-role-name>` creation in Redshift.

  ```bash theme={"system"}
  aws redshift-data execute-statement \
  --workgroup-name <your-workgroup-arn> \
  --database <your-database-name> \
  --sql "SELECT 1;"
  ```
* Grant `CREATE` privilege. Click **Query data** in the Amazon Redshift console to open **Query Editor v2**. Connect using appropriate credentials and run the following SQL commands, replacing `<your-database-name>` and `<mixpanel-role-name>` with your actual values:

  ```sql theme={"system"}
  -- Check if the IAMR user has been created
  SELECT * FROM pg_user WHERE usename LIKE 'IAMR:<mixpanel-role-name>';

  -- If you see your IAMR user in the results, proceed with the following commands
  GRANT CREATE ON DATABASE "<your-database-name>" TO "IAMR:<mixpanel-role-name>";

  -- Should return true if the privilege was successfully granted
  SELECT HAS_DATABASE_PRIVILEGE('IAMR:<mixpanel-role-name>', '<your-database-name>', 'CREATE');
  ```

## Provide Necessary Details for Pipeline Creation

Refer to [Step 2: Creating the Pipeline](/docs/data-pipelines/#step-2-creating-the-pipeline) to create data pipeline via UI. It is essential to provide specific details to Mixpanel:

**S3**

* **Bucket**: S3 bucket where Mixpanel data should be exported.
* **Region**: AWS region where your S3 bucket is located.
* **Role**: AWS Role ARN that Mixpanel should assume when writing to your S3, e.g., `arn:aws:iam:::role/example-s3-role`.
* **Encryption (optional)**: Specify the type of at-rest encryption used by the S3 bucket.
* **KMS Key ID (optional)**: If using KMS encryption, you can provide the custom key ID that you wish to use.

**Glue**

* **Database**: Glue database to which the schema needs to be exported.
* **Region**: AWS region where your Glue Database is created.
* **Role**: AWS Role ARN that needs to be assumed for updating glue, e.g., `arn:aws:iam:::role/example-glue-role`.

**Redshift**

* **Workgroup Arn**: Workgroup ARN for Redshift Serverless.
* **Database**: Redshift database where the external schema is created.
* **Region**: AWS region where your Redshift is located.
* **Role**: AWS Role ARN that Mixpanel should assume when creating schema to your database, e.g., `arn:aws:iam:::role/example-redshift-role`.

## Queries

To query data in external schema created by Mixpanel, you need to ask admin to grant schema **USAGE** privilege to the federated database user.

```sql theme={"system"}
GRANT USAGE ON SCHEMA "mp_json_export" TO "IAM:<your user name>";
```

Once the pipelines are successfully executed and you have necessary privilege, you can begin querying nested JSON data within the `properties` column in Redshift through the **Query Editor**. Here's an enhanced example query that retrieves the `distinct_id` of users from San Francisco:

```sql theme={"system"}
SET json_serialization_enable TO true;
SELECT
    distinct_id
FROM
    "your-database"."mp_json_export"."mp_master_event"
WHERE
    json_extract_path_text(properties, '$city') = 'San Francisco'
LIMIT 10;
```

For more detailed guidance on querying nested JSON data and using JSON functions in Redshift, you can review the official documentation on [querying nested data](https://docs.aws.amazon.com/redshift/latest/dg/serializing-complex-JSON.html) and [JSON functions](https://docs.aws.amazon.com/redshift/latest/dg/JSON_EXTRACT_PATH_TEXT.html).

## Supported AWS Regions

`US-EAST-1, US-EAST-2, US-WEST-1, US-WEST-2, AP-SOUTH-1, AP-NORTHEAST-1, AP-NORTHEAST-2, API-NORTHEAST-3, AP-SOUTHEAST-1, AP-SOUTHEAST-2, CA-CENTRAL-1, CN-NORTH-1, CN-NORTHWEST-1, EU-CENTRAL-1, EU-WEST-1, EU-WEST-2, EU-WEST-3, EU-NORTH-1, SA-EAST-1, ME-SOUTH-1`


# Snowflake
Source: https://docs.mixpanel.com/docs/data-pipelines/integrations/snowflake



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

This guide describes how Mixpanel data is exported into a Snowflake dataset. Create a pipeline to export your Mixpanel data into Snowflake. Once an export job is scheduled, Mixpanel exports data to Snowflake on a recurring basis.

## Design

Mixpanel exports data to your database. We first load the data into a single-column raw (VARIANT type) data table. Then, we create a view to expose all properties as columns.

### IP Restrictions

Mixpanel Data Pipelines supports static IP addresses for Snowflake connections when IP restrictions are configured on your Snowflake instance. If you are using [Snowflake Network policy](https://docs.snowflake.com/en/user-guide/network-policies) to restrict access to your instance, you might need to add the following IP addresses to the allowed list:

**US**

```jsx theme={"system"}
34.31.112.201
35.184.21.33
35.225.176.74
```

**EU**

```jsx theme={"system"}
34.147.68.192
35.204.164.122
35.204.177.251
```

**IN**

```jsx theme={"system"}
34.47.224.29
34.93.42.83
35.244.19.238
```

## Set Export Permissions

### Step 1: Create a Role and Grant Permissions

Create a role (`MIXPANEL_EXPORT_ROLE` as an example) and grant access on your database, schema, warehouse to the role. Replace `<database name>`, `<schema name>`, `<warehouse name>` with actual names.

```sql theme={"system"}
CREATE ROLE MIXPANEL_EXPORT_ROLE;
GRANT ALL ON DATABASE <database name> TO ROLE MIXPANEL_EXPORT_ROLE;
GRANT ALL ON SCHEMA <database name>.<schema name> TO ROLE MIXPANEL_EXPORT_ROLE;
GRANT USAGE ON WAREHOUSE <warehouse name> TO ROLE MIXPANEL_EXPORT_ROLE;
GRANT OPERATE ON WAREHOUSE <warehouse name> TO ROLE MIXPANEL_EXPORT_ROLE;
GRANT MONITOR ON WAREHOUSE <warehouse name> TO ROLE MIXPANEL_EXPORT_ROLE;
```

### Step 2: Create a Storage Integration

Mixpanel stages exported data in a GCS bucket (`gcs://mixpanel-export-pipelines-<project-id>`) before loading it into your warehouse. This bucket is created and managed by Mixpanel — you do *not* need to create it yourself. To allow Mixpanel to load data from this bucket into your Snowflake warehouse, create a GCS storage integration and grant it to the role. Replace `<project-id>` with your Mixpanel project ID.

```sql theme={"system"}
CREATE STORAGE INTEGRATION MIXPANEL_EXPORT_STORAGE_INTEGRATION
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ("gcs://mixpanel-export-pipelines-<project-id>");
GRANT USAGE ON INTEGRATION MIXPANEL_EXPORT_STORAGE_INTEGRATION TO MIXPANEL_EXPORT_ROLE;
```

### Step 3: Authenticate the User

Refer to [Step 2: Creating the Pipeline](/docs/data-pipelines/#step-2-creating-the-pipeline) to create a data pipeline via the UI.

We provide two different authentication methods: password and key-pair. In the example, create a user with either a password or public key and then grant the role to the user. You can find the public key in the Snowflake pipeline creation UI. If you already have a user, change the fields and grant the role.

password authentication

```sql theme={"system"}
CREATE USER MIXPANEL_EXPORT_USER PASSWORD='<password you provided>' DEFAULT_ROLE=MIXPANEL_EXPORT_ROLE;

ALTER USER MIXPANEL_EXPORT_USER SET PASSWORD='<password you provided>';
GRANT ROLE MIXPANEL_EXPORT_ROLE TO USER MIXPANEL_EXPORT_USER;
```

key-pair based authentication

```sql theme={"system"}
CREATE USER MIXPANEL_EXPORT_USER RSA_PUBLIC_KEY='<mixpanel generated key>' DEFAULT_ROLE=MIXPANEL_EXPORT_ROLE;

ALTER USER MIXPANEL_EXPORT_USER SET RSA_PUBLIC_KEY='<mixpanel generated key>';
GRANT ROLE MIXPANEL_EXPORT_ROLE TO USER MIXPANEL_EXPORT_USER;
```

## Partitioning

The data in the raw tables is clustered based on the `time` column in the project's timezone. To be exact, we use `CLUSTER BY (TO_DATE(CONVERT_TIMEZONE('UTC','<TIMEZONE>', TO_TIMESTAMP(DATA:time::NUMBER)))` where `TIMEZONE` is the Mixpanel project's timezone.

## Queries

A query is a request for data results. You can perform actions on the data, such as combine data from different tables; add, change, or delete table data; and perform calculations.

Snowflake supports an Object type that can store JSON objects and arrays. Mixpanel exposes array and object top-level properties as Object columns in the view.

Here is an example of how you can query the raw table when using one table for all the events. `DB_NAME` and `SCHEMA_NAME` should be replaced by your Snowflake database and schema name.

```sql theme={"system"}
SELECT count(*)
FROM <DB_NAME>.<DB_NAME>.MP_MASTER_EVENT_RAW
WHERE DATA:event_name::string = 'sign up';
```

Here is an example of how you can query the view when using one table for all the events:

```sql theme={"system"}
SELECT count(*)
FROM <DB_NAME>.<DB_NAME>.MP_MASTER_EVENT
WHERE event_name = 'sign up';
```

### Getting the number of events in each day

You will need this if you suspect the export process is not exporting all the events you want. As the time column in the tables is in UTC timezone, you first need to convert that to your Mixpanel project timezone, and then, get the number of events for each day. The following query will do that for you.

```sql theme={"system"}
SELECT
  TO_DATE(CONVERT_TIMEZONE('UTC','<PROJECT_TIMEZONE>', time)) as ttime,
  count(*)
FROM <DB_NAME>.<DB_NAME>.MP_MASTER_EVENT
WHERE ttime>=TO_DATE('2021-12-03') AND ttime<=TO_DATE('2024-09-01')
GROUP BY ttime
ORDER BY ttime;
```

This example returns the number of events in each day in your project timezone. `PROJECT_TIMEZONE`, `DB_NAME` and `SCHEMA_NAME` should be replaced by your Mixpanel project timezone and your snowflake database and schema name.

### Querying the identity mapping table

When using the ID mappings table, you should use the **resolved** `distinct_id` in place of the non-resolved `distinct_id` whenever present. If there is no **resolved** `distinct_id`, you can then use the `distinct_id` from the existing people or events table.

Below is an example SQL query that references the ID mapping table to count the number of events in a specific date range for each unique user in San Francisco.

```sql theme={"system"}
SELECT
  COALESCE(mappings.resolved_distinct_id, events.distinct_id) AS resolved_distinct_id,
  COUNT(*) AS count
FROM
  <DB_NAME>.<SCHEMA_NAME>.MP_MASTER_EVENT events
FULL OUTER JOIN
  <DB_NAME>.<SCHEMA_NAME>.MP_IDENTITY_MAPPINGS_DATA mappings
ON
  events.distinct_id = mappings.distinct_id
  AND events.properties:"$city"::STRING = 'San Francisco'
  AND TO_DATE(CONVERT_TIMEZONE('UTC','<PROJECT_TIMEZONE>', events.time)) >= TO_DATE('2020-04-01')
  AND TO_DATE(CONVERT_TIMEZONE('UTC','<PROJECT_TIMEZONE>', events.time)) <= TO_DATE('2024-09-01')
GROUP BY
  COALESCE(mappings.resolved_distinct_id, events.distinct_id)
LIMIT
  100;
```


# JSON Pipelines
Source: https://docs.mixpanel.com/docs/data-pipelines/json-pipelines



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

JSON Pipeline is designed to export your Mixpanel data to supported data warehouses or object storage solutions. We maintain all properties in a high-level JSON format under the `properties` key for both events and user profile data.

This documentation is intended for users with intermediate or advanced knowledge of databases and familiarity with Amazon Web Services, Google Cloud Platform, or Snowflake technology.

## Create JSON Pipelines

Follow the instructions here in the [Overview](/docs/data-pipelines).

## Destination and Date Range Restrictions

To prevent data duplication and conflicts, the system enforces the following rule: **you cannot create multiple event pipelines that export to the same destination with overlapping date ranges**.

For example, if you already have a pipeline exporting to BigQuery dataset "my\_dataset" for dates January 1-31, you cannot create another pipeline exporting to the same dataset with dates January 15 - February 15, as the January 15-31 period would overlap.

This constraint ensures data integrity and prevents duplicate exports to the same destination tables or storage locations.

## Data Sources Output

Json pipelines support three different data sources: events, people, and identity.

We aggregate all events and user profiles properties under the `properties` key to facilitate easier querying of every row with conditions. In addition to consolidating all event and user profiles properties under the `properties` key, we export several common properties across all records. This standardization facilitates simpler and more consistent querying conditions. Below are examples of the output structure in **BigQuery**

The following are examples of the output in **BigQuery** for each data source pipeline. Note that different warehouses may have different corresponding types, but the names will be the same.

### Events

| name         | Type      | description                                                             |
| :----------- | :-------- | :---------------------------------------------------------------------- |
| device\_id   | STRING    | Unique ID used to track a device while the user remains anonymous       |
| distinct\_id | STRING    | Unique ID for the user who triggered the event                          |
| event\_name  | STRING    | Name of the event                                                       |
| insert\_id   | STRING    | Unique ID used to deduplicate events that are sent multiple times       |
| properties   | JSON      | JSON object containing all the properties associated with the event     |
| time         | TIMESTAMP | Timestamp marking when the event occurred                               |
| user\_id     | STRING    | Unique ID used to track a user across different devices when identified |

### User Profiles

| name         | Type   | description                                |
| :----------- | :----- | :----------------------------------------- |
| distinct\_id | STRING | Unique ID for the user                     |
| properties   | JSON   | JSON object containing all user properties |

### Identity Mappings

| name                   | Type   | description                                    |
| :--------------------- | :----- | :--------------------------------------------- |
| distinct\_id           | STRING | Unique ID for the user who triggered the event |
| resolved\_distinct\_id | STRING | Unique ID of the user after merging            |

## Events Data Sync

Events Data Sync is enabled by default when creating JSON pipelines to ensure data consistency. This feature automatically detects data changes as soon as they are ingested and appends new files for new/late data to your storage/warehouses, helping keep the data fresh and minimizing missing data points.

Event data can fall out of sync between Mixpanel's datastore and the export destination due to several causes:

* Late data can arrive multiple days later due to a mobile client being offline.
* The import API can add data to previous days.
* Delete requests related to GDPR can cause deletion of events and event properties.

**Important limitations**: Data sync does not guarantee syncing GDPR Data Deletions. It is recommended to implement a strategy to remove all records of GDPR Deleted Users in your data warehouse.

## Backfill Historical Events

You can schedule an initial backfill when creating events pipeline to ensure that historical data is also exported to the destination.

Use the `from_date` parameter to specify the date from which you want to export historical data. Note that the `from_date` must be no more than 6 months in the past.

The completion time for a backfill depends on the number of days and the volume of data in the project. Larger backfills can take several weeks.

## Export Frequency

Mixpanel supports hourly and daily exports, with daily being the default.

## People Data Support

User profiles are exported to a single table or directory named `mp_people_data`. Since user profiles are mutable, the data in the table is replaced with the latest user profiles each time an export occurs, based on the chosen schedule (daily or hourly).

## User Identity Resolution

Exports from projects with [ID merge enabled](/docs/tracking-methods/id-management/identifying-users#how-do-i-switch-between-the-simplified-and-original-api) will need to use the identity mapping table to replicate the user counts seen in UI reporting. Mixpanel resolves multiple identifiers for an individual into one identifier for reporting unique user counts. Learn more about how Mixpanel resolves IDs [here](/docs/tracking-methods/id-management/identifying-users#example-user-flows).

Pipelines export event data as they appear when Mixpanel ingests them. Data sent before an alias event carries the original user identifier, not the resolved one. Use the identity mappings table to accurately count unique users. This will allow you to recreate the identity cluster that Mixpanel creates.

Note: Use the `resolved_distinct_id` from the identity mappings table instead of the non-resolved `distinct_id` when available. If there is no resolved `distinct_id`, use the `distinct_id` from the existing people or events table.

Examples of querying the identity mapping table are available for [BigQuery](/docs/data-pipelines/integrations/bigquery#query-identity-mappings) and [Snowflake](/docs/data-pipelines/integrations/snowflake#query-identity-mappings).

## Incremental Pipelines

As of 10 September 2025, all JSON pipelines in all regions (US/EU/IN) have been migrated to our improved incremental pipeline export system. Schematized pipelines will be migrated to this same export system soon.

**What is affected?**

* **Events pipelines with sync enabled only**: This improvement only affects event pipelines that have sync enabled. People and identity mapping pipelines remain unchanged.

**Benefits**

* **Elimination of data sync delays**: No more waiting for daily sync processes to detect and fix data discrepancies.
* **Complete data export**: All events are exported without the risk of missing late-arriving data. Late-arriving events are automatically exported regardless of how late they arrive, eliminating the previous 10-day sync window restriction.

**Changes you may notice**

* **Event count display**: The event count shown per task in the UI now represents the total events processed per batch rather than events exported per day or per hour. Since each batch can span multiple days, this number may appear different from before.
* **Backfill process**: When a new pipeline is created, it will complete the full historical backfill first before starting regular processing. For example, if you create a pipeline on January 15th at 11 AM with a backfill from January 1st, the system will first export all events that arrived in Mixpanel before around January 15th 11 AM as the initial backfill, then begin processing any new events that arrive after around January 15th 11 AM, regardless of which date those events are for. Existing pipelines will have the last 10 days backfilled as part of the migration and then the new incremental behavior will start.
* **Storage location file structure changes**: Previous behavior of sync would replace files for a day when the day was re-synced. No sync means Mixpanel will no longer coalesce files for days when sync runs so files are no longer updated/removed. Incremental pipelines will instead add a new file with events seen in each day for each run of the pipeline meaning more small files are expected.
* **Pipelines logs reset**: Once your pipeline is migrated, the logging available in the UI will be reset so past jobs log lines will no longer be available. Only the new incremental jobs will be visible going forward.
* **Predicable deletion behavior**:  In rare cases, the sync functionality meant that Mixpanel could re-sync days for which data was deleted, allowing the pipeline to also remove that data from your data warehouse. Sync keeping your warehouse in line with deletions was not guaranteed behavior however. The removal of sync means this unreliable behavior has been removed and as such, warehouse data owners are responsible for the deletion of all data on the warehouse side.
* **More pre-shuffled distinct IDs in data**: The faster export and removal of late syncs for data can lead to more events exported with their original `distinct_id` as opposed to the resolved identifier seen in Mixpanel after we’ve shuffled the data. These discrepancies are expected in pipelines on both the old and new behavior, and can be resolved using the ID mappings table exported from identity pipelines outlined in [our docs here](/docs/data-pipelines/json-pipelines#user-identity-resolution).

## FAQs

### Why is sync not available for People and Identity pipelines?

The sync feature is designed for events to keep the exported data up-to-date with changes that occur in Mixpanel (e.g. late-arriving data). For People and Identity pipelines, the data is re-exported in full in each export for profiles and identity mappings, which means that it's always up-to-date and does not require the sync feature. For that reason, you would not be able to enable sync for People and Identity pipelines — there is simply no use for it.

### How are GDPR deletions handled?

GDPR deletions do not automatically cascade deletions to data warehouses via pipelines. When a user is deleted from Mixpanel via the GDPR deletion API, this deletion is reflected in Mixpanel’s own storage, but the deletion does not propagate to data that has already been exported to data warehouses via pipelines.

To keep your synced warehouse data GDPR compliant, you will need to implement a process to delete the corresponding user and event data from your warehouse when a GDPR deletion occurs in Mixpanel.

### Can I configure my pipeline to export data into a subfolder or prefix within my bucket?

No, Mixpanel’s JSON pipeline configuration does not currently support custom subfolders or prefixes. Data is exported into predefined structured paths that are automatically generated by Mixpanel.

For example, event data is exported to the following path: `<BUCKET_NAME>/<PROJECT_ID>/mp_master_event/<YEAR>/<MONTH>/<DAY>/`

This structure is created by Mixpanel and cannot be customized at the moment.

### Can I export only a subset of events or properties with JSON pipelines?

No, all events and properties are exported as they are ingested into Mixpanel. It’s not possible to filter for events and properties to include or exclude in your data pipeline exports. However, it is possible to whitelist events to export and filter by properties if you’re using our older pipelines created via API (Raw and Schematized).

### Why isn’t my hourly pipeline running exactly every hour?

With incremental pipelines, the next export iteration begins after the previous one completes rather than on a fixed schedule. This ensures we export all data completely without the risk of cutting off late-arriving events. While your pipeline is configured for “hourly” export, the actual run time will vary based on how long each iteration takes to process.

## Change Log

<Accordion title="2025-09-29: Sync Enabled by Default for JSON Pipelines">
  Removed sync toggle from JSON pipeline creation UI. All new JSON pipelines now have incremental sync enabled by default to ensure data consistency without requiring manual configuration.

  **Impact**: New JSON pipelines automatically include sync functionality - no longer optional through UI toggle.
</Accordion>

<Accordion title="2025-08-14: Incremental Export Deployed for US Pipelines">
  We have deployed the Incremental Export Improvement for newly created pipelines with US data residency.

  The rollout of these updates to existing pipelines in US residency is scheduled for the near future. Your pipeline will automatically transition to the new system when ready. Your data quality and completeness remain the same; only the processing method has improved.
</Accordion>

<Accordion title="2025-06-26: Introducing Incremental Export for Event Pipelines">
  We're rolling out an improved pipeline system to improve the efficiency and reliability of your data exports. We're deploying these improvements for newly created pipelines in our EU and IN data residency. New pipelines in projects with US residency and migrating existing pipelines in all regions will follow after. Your pipeline will automatically transition to the new system when ready. Your data quality and completeness remain the same - only the processing method has improved.
</Accordion>


# Data Pipelines
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines



## Overview

<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

<Warning>
  This version of managing pipelines via API is Deprecated going forward. For the customers who earlier used these APIs to create and manage can continue using it. Otherwise, go to the Integrations page in Mixpanel to create and manage pipelines via UI and go to [docs](/docs/data-pipelines) for more info.
</Warning>

Data Pipelines continuously exports the events in your Mixpanel project to a cloud storage bucket or data warehouse of your choice. It's useful if you want to analyze Mixpanel events using SQL in your own environment.

Using Data Pipelines requires 2 steps:

1. Configuring your destination to allow Mixpanel to write to it.
2. Telling Mixpanel to start exporting your data to that destination using the Pipelines API.

We offer a 30-day free trial of the Data Pipelines add-on. See the [FAQ](#free-trial) for how to enable it.

## Step 1: Configuring your destination

Configuration depends on the type of Pipeline you want to set up.

### Raw

Raw Pipelines export events as JSON to a cloud storage bucket. This is the simplest approach.

See our configuration guides for each raw destination:

* [Amazon Web Services](/docs/data-pipelines/old-pipelines/integrations/raw-aws-pipeline)
* [Google Cloud Storage](/docs/data-pipelines/old-pipelines/integrations/raw-gcs-pipeline)
* [Azure Blob Storage](/docs/data-pipelines/old-pipelines/integrations/raw-azure-pipeline)

Upon successful creation of a pipeline, events will be exported to the following locations:

* Hourly: `<BUCKET_NAME>/<PATH_PREFIX>/<MIXPANEL_PROJECT_ID>/<YEAR>/<MONTH>/<DAY>/<HOUR>`
* Daily: `<BUCKET_NAME>/<PATH_PREFIX>/<MIXPANEL_PROJECT_ID>/<YEAR>/<MONTH>/<DAY>/full_day`

An empty `complete` file will be written in the finished hour or day prefix to indicate that the export is complete. The absence of this file means there is an ongoing export for that hour or day.

### Schematized

Schematized Pipelines export events into tables with schemas generated by Mixpanel, inferred from your event history. There are two types of schemas, which you can configure:

* Monoschema: A single table for all events in which you have the event name as the column and one column per property.
* Multischema: One table per event name with the properties of that event as columns.

See our configuration guides for each schematized destination:

* [BigQuery](/docs/data-pipelines/old-pipelines/integrations/schematized-bigquery-pipeline)
* [Snowflake](/docs/data-pipelines/old-pipelines/integrations/schematized-snowflake-pipeline)
* [Amazon Web Services](/docs/data-pipelines/old-pipelines/integrations/schematized-aws-pipeline)
* [Google Cloud Storage](/docs/data-pipelines/old-pipelines/integrations/schematized-gcs-pipeline)
* [Azure Blob Storage](/docs/data-pipelines/old-pipelines/integrations/schematized-azure-pipeline)

The [Schematized Pipeline reference](/docs/data-pipelines/old-pipelines/schematized-export-pipeline) goes into the details of schematization and the output format.

## Step 2: Creating the Pipeline

Once you’ve configured your destination, you need to tell Mixpanel to start exporting to that destination.

You can do this with our [Create Pipeline API](/reference/create-warehouse-pipeline). You can create the Pipeline directly from our developer docs UI.

<Note>
  Note that the Service Account must have an Admin or Owner role in order to authenticate the request.
</Note>

Limits:

* For event export pipelines (`data_source: events`) in each Mixpanel project, we support at most two recurring pipelines (`to_date` is empty) and one non-recurring pipeline (has a `to_date` that is the ending date of the export window).
* Note that `from_date` must also be no more than 6 months from the date the pipeline is created.

## FAQ

**1. Why are some events or properties not exported to the destination?**

This normally happens when you have thousands of unique event names or property names, which is usually an implementation mistake (eg: including a UUID in the event or property name). This causes the export process to exceed table or column limits in the destination. Mixpanel itself imposes a limit of 10K unique properties in your schema after transformation rules have been applied. Any projects exceeding this limit will have their pipelines paused until the issue can be remediated. If you notice an error in your pipelines around exceeding this limitation, please try to identify a regex selector that selects some properties you would like to filter out of your schema and reach out to our support team for assistance.

**2. Why does the number of events in Mixpanel not match the number of exported events to my destination?**

This can happen for a few reasons:

* [Data Sync](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#data-sync) is not enabled or not supported for your pipeline.
* Data Delay: It can take up to 1 day for late arriving data to be synced from Mixpanel to your destination.
* Hidden Events: Mixpanel exports all events to your destination, even ones that are hidden in the UI via Lexicon. We recommend checking whether the count in your destination is mostly due to events that have been hidden in the Mixpanel UI.

**3. What timezone is used for my event exports?**

The timestamp for exported events from your pipeline will be in the UTC timezone. For projects created before 1 Jan 2023, the raw event timestamps are transformed from Project Timezone to UTC. For projects after 1 Jan 2023, raw event data is stored in UTC. Learn more about [managing timezones here](/docs/orgs-and-projects/managing-projects#manage-timezones-for-projects).

**4. How can I count events exported by Mixpanel in the warehouse?**

Counting events can be slightly different for each warehouse, since we use different partitioning methods. Here are examples for [BigQuery](/docs/data-pipelines/old-pipelines/integrations/schematized-bigquery-pipeline#getting-the-number-of-events-in-each-day) and [Snowflake](/docs/data-pipelines/old-pipelines/integrations/schematized-snowflake-pipeline#getting-the-number-of-events-in-each-day).

## Free Trial

Mixpanel offers a 30-day trial version of the Data Pipelines. The trial allows for one data export pipeline per project to be created. Simply pass `trial=true` to our API to create a trial pipeline.

Trial limitations:

* Export scheduling is daily only.
* Data sync is unavailable.
* You can only create one pipeline per project.
* Backfilled data will only include one day prior to the creation date.
* Pipelines will, by default, include both event and user data (not available for raw pipelines).
* The pipeline cannot filter by event name.
* The “Create Pipeline” parameters will default to the values highlighted to list in the [parameters table](/reference/create-warehouse-pipeline#create-warehouse-pipeline).


# Data Pipeline Integrations
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines/integrations



<Note>
  This page highlights integrations that send Mixpanel data to data warehouses. Learn more about [integrations that import data from other destinations into Mixpanel](/docs/tracking-methods/integrations) and [integrations that export cohorts for audience targeting](/docs/cohort-sync/integrations).
</Note>

These integrations allow you to send your [raw data](/docs/data-pipelines#raw) and [schematized data](/docs/data-pipelines#schematized) to your cloud storage bucket or data warehouse. You may review our complete integrations directory [here](https://mixpanel.com/partners/integrations). If you don't see what you're looking for [reach out to us](https://mixpanel.com/get-support).

## Raw Pipelines

<CardGroup>
  <Card title="Raw AWS Pipeline" href="/docs/data-pipelines/old-pipelines/integrations/raw-aws-pipeline" />

  <Card title="Raw Azure Pipeline" href="/docs/data-pipelines/old-pipelines/integrations/raw-azure-pipeline" />

  <Card title="Raw GCS Pipeline" href="/docs/data-pipelines/old-pipelines/integrations/raw-gcs-pipeline" />
</CardGroup>

## Schematized Pipelines

<CardGroup>
  <Card title="Schematized AWS Pipeline" href="/docs/data-pipelines/old-pipelines/integrations/schematized-aws-pipeline" />

  <Card title="Schematized Azure Pipeline" href="/docs/data-pipelines/old-pipelines/integrations/schematized-azure-pipeline" />

  <Card title="Schematized BigQuery Pipeline" href="/docs/data-pipelines/old-pipelines/integrations/schematized-bigquery-pipeline" />

  <Card title="Schematized GCS Pipeline" href="/docs/data-pipelines/old-pipelines/integrations/schematized-gcs-pipeline" />

  <Card title="Schematized Snowflake Pipeline" href="/docs/data-pipelines/old-pipelines/integrations/schematized-snowflake-pipeline" />
</CardGroup>


# Raw AWS Pipeline
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines/integrations/raw-aws-pipeline



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

To set up a raw export pipeline to an S3 bucket from Mixpanel, you must configure S3 to receive the exported data, then [create a pipeline](/reference/create-warehouse-pipeline) to export the data.

The following document summarizes the steps to edit S3 bucket permissions so that it accepts the Mixpanel export. Consult [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/gsg/GetStartedWithS3.html) for any AWS specific tasks, such as creating an [S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) and editing [permissions](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html).

To prepare S3 for the incoming data you must:

1. Create an S3 bucket.
2. Give Mixpanel the required permissions to write to the bucket.

## S3 Bucket Permissions

Mixpanel supports a wide range of configurations to secure and manage your data on S3. To access resources, the pipeline uses AWS cross-account roles.

This section highlights the permissions you must give Mixpanel depending on the configuration of the target S3 bucket.

## Data Modification Policy

All exports from Mixpanel to AWS require that you create a new data modification policy, or add the following permissions to an existing data modification policy.

Replacing `<BUCKET_NAME>` and `<SID>` with your bucket name and chosen sid before inserting this JSON:

```json JSON Example with Variables theme={"system"}
{
    "Version": "VERSION",
    "Statement": [
        {
            "Sid": "<SID>",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::<BUCKET-NAME>",
                "arn:aws:s3:::<BUCKET-NAME>/*"
            ]
        }
    ]
}
```

## Server-Side Encryption

Mixpanel always sends data to your S3 bucket on a TLS encrypted connection. To secure your data at rest on S3, you can enable [Server-Side Encryption (SSE)](https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html).

There are two options when using SSE: Encryption with Amazon S3-Managed Keys (SSE-S3) and Encryption with AWS KMS-Managed Keys (SSE-KMS)

### Encryption with Amazon S3-Managed Keys (SSE-S3)

This setting on your bucket encrypts data at rest using the AES-256 algorithm that uses keys managed by S3.

If you are using this type of SSE, you only need to configure your pipeline by passing the `s3_encryption=aes` parameter when calling the Mixpanel Data Warehouse Export API. See [AWS S3 and Glue Parameters](/reference/create-warehouse-pipeline).

### Encryption with AWS KMS-Managed Keys (SSE-KMS)

For S3 buckets, you can pick a default key named `aws/s3`. If you opt to use the default key you need to configure your pipeline by passing `s3_encryption=kms`  and `s3_kms_key_id=<aws managed default CMK>`  when calling the Mixpanel Data Warehouse Export API or you can choose to use your own custom keys for encrypting the contents of your bucket

In either case you will need to allow Mixpanel to use the key to encrypt the data properly as it is written to your bucket.

To achieve this, create an IAM policy that gives permission to Mixpanel to use the KMS key. Use the following JSON snippet and replace `<KEY_ARN>` and `<SID>` with your custom key's (or aws managed default CMK's) ARN and chosen sid:

```json JSON Example with Variables theme={"system"}
{
    "Version": "VALUE",
    "Statement": [
        {
            "Sid": "<SID>",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:Encrypt",
                "kms:GenerateDataKey",
                "kms:ReEncryptTo",
                "kms:GenerateDataKeyWithoutPlaintext",
                "kms:DescribeKey",
                "kms:ReEncryptFrom"
            ],
            "Resource": "<KEY-ARN>"
        }
    ]
}
```

You must configure your pipeline by passing `s3_encryption=kms` and `s3_kms_key_id=<KEY_ARN>` when calling the Mixpanel Data Warehouse Export API.

## S3 Access Role

After creating the policies in the sections above, you must create a cross account IAM Role to assign the policies to the role.

* Go to the \_AWS IAM \_service on the console.
* Click **Roles** in the sidebar.
* Click **Create Role**.
* Select \*\*Other AWS Accounts \*\*on the trust policy page and enter "485438090326" for the account ID.
* In the *Permissions* page, find and select the policies you created above.
* In the \_Review \_page, enter a name and description for the role and click **Save**.

Next, limit the trust relationship to the Mixpanel export user to ensure only Mixpanel has the ability to assume this specific role.

* Navigate to the *AWS IAM* service in the console.
* Click **Roles** in the sidebar.
* Find and click the role you just created.
* Navigate to the *Trust Relationships* tab.
* Click **Edit trust relationship**.
* Replace the contents with the following JSON:

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::485438090326:user/mixpanel-export"
      },
      "Action": "sts:AssumeRole",
      "Condition": {}
    }
  ]
}
```

## Using AWS External ID

Amazon introduced the use of external id for cross-account access because of [the confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). As Mixpanel uses cross account access to export data, you can make use of this feature to make the data transfer more secure.

Mixpanel uses your project token as external ID when talking to AWS. In order to enable this, you simply need to edit the trust relationship you created as part of the previous step and add a condition to check the passed external id is in fact your Mixpanel project token. So, the final JSON for your trust relationship would be:

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::485438090326:user/mixpanel-export"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<MIXPANEL_PROJECT_TOKEN>"
        }
      }
    }
  ]
}
```

## Use The Data Pipelines API

After permissions have been granted, use the [Data Pipelines API](/reference/create-warehouse-pipeline) to create the pipeline. Here is an example request:

```sh cURL Example with Values theme={"system"}
curl https://data.mixpanel.com/api/2.0/nessie/pipeline/create \
-u API_SECRET: \
-d type="s3-raw" \
-d from_date="2019-08-10" \
-d s3_bucket="example-s3-export" \
-d s3_region="us-west-2" \
-d s3_prefix="test" \
-d s3_role="arn:aws:iam::<account-id>:role/example-s3-role" \
-d s3_encryption="aes" \
```


# Raw Azure Pipeline
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines/integrations/raw-azure-pipeline



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

To set up a raw export pipeline to Azure Blob Storage from Mixpanel, you must first give Mixpanel permission to write to Azure. Next you can [create a pipeline](/reference/create-warehouse-pipeline) to export the data. Mixpanel then uploads the data to Azure Blob Storage on a recurring basis.

The following document summarizes the steps to configure Azure permissions so that it accepts the Mixpanel export, and provides an example request to create the pipeline.

## Edit Mixpanel Permission

Since the Azure authentication mechanisms do not allow for cross-account access, you must provide  Azure credentials to use with their Blob storage container.

To achieve this, Mixpanel uses Service Principals created in your Azure Active Directory deployment. To create a Service Principal,  use the Azure command line tool and run the following command (with redacted output):

```shell theme={"system"}
$ az ad sp create-for-rbac --sdk-auth          
{
  "clientId": "redacted",
  "clientSecret": "redacted",
  "subscriptionId": "redacted",
  "tenantId": "redacted",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  "activeDirectoryGraphResourceId": "https://graph.windows.net/",
  "sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
  "galleryEndpointUrl": "https://gallery.azure.com/",
  "managementEndpointUrl": "https://management.core.windows.net/"
}
```

If the above step is successful, go to the Azure. Navigate to a blob storage container of your choice and assign the “Storage Blob Data Contributor” to the Service Principal from above.

Mixpanel needs the clientId, clientSecret, and tenantId to access the blob container as the Service Principal. You must provide the blob account name, container name, and (optional) path prefix you want to choose for the export.

You can share the Service Principal’s credentials over the TLS encrypted API at the time that you create your Mixpanel to Azure pipeline.

## Use the Data Pipelines API

After permissions have been granted, use the [Data Pipelines API](/reference/create-warehouse-pipeline) to create the pipeline. Here is an example request:

```sh cURL theme={"system"}
curl https://data.mixpanel.com/api/2.0/nessie/pipeline/create \
-u API-SECRET: \
--data type="azure-raw" \
--data from_date="2021-02-02" \
--data storage_account="test-storage-account" \
--data container_name="test-container-name" \
--data client_id="test-client-id" \
--data client_secret="test-secret" \
--data tenant_id="test-tenant-id"
```


# Raw GCS Pipeline
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines/integrations/raw-gcs-pipeline



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

To set up a raw export pipeline to Google Cloud Storage (GCS) from Mixpanel, you must configure GCS to receive the exported data, then [create a pipeline](/reference/create-warehouse-pipeline) to export the data.

The following document summarizes the steps to edit GCS permissions so that it accepts the Mixpanel export, and provides an example request to create the pipeline.

## Configure GCS to Accept Mixpanel Data

Create a destination bucket, or use an existing one.

`export-upload@mixpanel-prod-1.iam.gserviceaccount.com` needs to be given a "Storage Object Admin" role on the bucket you are creating or intending to reuse for this purpose.

## Use the Data Pipelines API

After permissions have been granted, use the [Data Pipelines API](/reference/create-warehouse-pipeline) to create the pipeline. Here is an example request:

```sh cURL theme={"system"}
curl https://data.mixpanel.com/api/2.0/nessie/pipeline/create \
-u API_SECRET: \
-d type="gcs-raw" \
-d from_date="2019-08-10" \
-d gcs_bucket="example-gcs-export" \
-d gcs_prefix="dwe" \
-d gcs_region="us-east-2"
```


# Schematized AWS Pipeline
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines/integrations/schematized-aws-pipeline



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Mixpanel's [Schematized Export Pipeline](/docs/data-pipelines/old-pipelines/schematized-export-pipeline) lets you export your Mixpanel data directly into an S3 bucket, allowing the use of Glue to query it. To set up the Mixpanel AWS pipeline, you must configure AWS to receive the exported data, then [create a pipeline](/reference/create-warehouse-pipeline) to export the data.

## Design

<Frame>
  <img alt="image" />
</Frame>

Mixpanel applies [transformation rules](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#transformation-rules) to make the data compatible with data warehouses and then transfers the transformed data to your S3 bucket. You can then choose to use a Glue crawler to create the schema out of the transformed data or let Mixpanel to directly create the schema in your glue database. Having the data and the glue schema in place, you can use SQL with multiple AWS products, including [Amazon Athena](https://aws.amazon.com/athena/) and [Redshift Spectrum](https://docs.aws.amazon.com/redshift/latest/dg/c-getting-started-using-spectrum.html), to query the imported data.

We recommend the use of [Spectrum](https://docs.aws.amazon.com/redshift/latest/dg/c-getting-started-using-spectrum.html) and [Glue](https://aws.amazon.com/glue/) to query the imported data.

> **Important:** Please do not modify the schema of glue tables generated by Mixpanel. Altering the table schema can cause the pipeline to fail to export due to schema mismatches.

## Exporting Mixpanel Data to Redshift Spectrum

The following summarizes the steps to export Mixpanel data to an S3 bucket. Consult [AWS documentation](https://docs.aws.amazon.com/AmazonS3/latest/gsg/GetStartedWithS3.html) for AWS specific tasks, such as creating an [S3 bucket](http://google.com) and [permissions](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html).

To prepare S3 for the incoming data:

1. Create a S3 bucket.
2. Give Mixpanel the required permissions to write to the bucket.
3. Configure Glue as shown below.

### S3 Bucket Permissions

Mixpanel supports a wide range of configurations to secure and manage your data on S3. To access resources, the pipeline uses AWS cross-account roles.

This section highlights the permissions you must give Mixpanel depending on the configuration of the target S3 bucket.

### Data Modification Policy

All exports from Mixpanel to AWS require that you create a new data modification policy, or add the following permissions to an existing data modification policy.

Replacing `<BUCKET_NAME>` with your bucket name before inserting this JSON:

```json theme={"system"}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SomeSidYouChoose",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:ListBucket",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::<BUCKET_NAME>",
                "arn:aws:s3:::<BUCKET_NAME>/*"
            ]
        }
    ]
}
```

#### Server-Side Encryption

Mixpanel always sends data to your S3 bucket on a TLS encrypted connection. To secure your data at rest on S3, you can enable [Server-Side Encryption (SSE)](https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html).

There are two options when using SSE: Encryption with Amazon S3-Managed Keys (SSE-S3) and Encryption with AWS KMS-Managed Keys (SSE-KMS)

##### Encryption with Amazon S3-Managed Keys (SSE-S3)

This setting on your bucket encrypts data at rest using the AES-256 algorithm that uses keys managed by S3.

If you are using this type of SSE, you only need to configure your pipeline by passing the `s3_encryption=aes`  parameter  when calling the Mixpanel Data Pipelines API. See [AWS S3 and Glue Parameters](/reference/create-warehouse-pipeline).

##### Encryption with AWS KMS-Managed Keys (SSE-KMS)

You have a choice of keys if you use the Key Management Service (KMS).

For S3 buckets, you can pick a default key named `aws/s3`. If you opt to use the default key you don’t need any further configuration on AWS, and only need to configure your pipeline by passing `s3_encryption=kms` when calling the Mixpanel Data Pipelines API.

If you choose to use your own custom keys for encrypting the contents of your bucket, you will need to allow Mixpanel to use the key to encrypt the data properly as it is written to your bucket.

To achieve this, create an IAM policy that gives permission to Mixpanel to use the KMS key. Use the following JSON snippet and replace `<KEY_ARN>` with your custom key’s ARN:

```json theme={"system"}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SomeSidYouChooseAgain",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:Encrypt",
                "kms:GenerateDataKey",
                "kms:ReEncryptTo",
                "kms:GenerateDataKeyWithoutPlaintext",
                "kms:DescribeKey",
                "kms:ReEncryptFrom"
            ],
            "Resource": "<KEY_ARN>"
        }
    ]
}
```

You must configure your pipeline by passing `s3_encryption=kms` and `s3_kms_key_id=<KEY_ARN>` when calling the Mixpanel Data Pipelines API.

#### S3 Access Role

After creating the policies in the sections above, you must create a cross account IAM Role to assign the policies to the role.

* Go to the \*AWS IAM \*service on the console.
* Click **Roles** in the sidebar.
* Click **Create Role**.
* Select \*\*Other AWS Accounts \*\*on the trust policy page and enter "485438090326" for the account ID.
* In the *Permissions* page, find and select the policies you created above.
* In the \*Review \*page, enter a name and description for the role and click **Create Role**.

Next, limit the trust relationship to the Mixpanel export user to ensure only Mixpanel has the ability to assume this specific role.

* Navigate to the *AWS IAM* service in the console.
* Click **Roles** in the sidebar.
* Find and click the role you just created.
* Navigate to the *Trust Relationships* tab.
* Click **Edit trust relationship**.
* Replace the contents with the following JSON:

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::485438090326:user/mixpanel-export"
      },
      "Action": "sts:AssumeRole",
      "Condition": {}
    }
  ]
}
```

#### Using AWS External ID

Amazon introduced the use of external id for cross-account access because of [the confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). As Mixpanel uses cross account access to export data, you can make use of this feature to make the data transfer more secure.

Mixpanel uses your project token as external ID when talking to AWS. In order to enable this, you simply need to edit the trust relationship you created as part of the previous step and add a condition to check the passed external id is in fact your Mixpanel project token. So, the final JSON for your trust relationship would be:

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::485438090326:user/mixpanel-export"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<MIXPANEL_PROJECT_TOKEN>"
        }
      }
    }
  ]
}
```

#### Glue Configurations

[Glue](https://aws.amazon.com/glue/) offers a data catalog service that will facilitate access to the S3 data from other services on your AWS account.

This section describes how to connect Glue to the exported data in S3. You can select either of the  following options:

* Configure Glue for Mixpanel direct export (recommended)
* Configure Glue to use crawlers.

Note: If you use Athena with Glue and want to enable partitioning, you must choose **parquet** as the data\_format for your pipeline

##### Configuring Glue for Mixpanel Direct Export

Mixpanel can write and update a schema in your Glue instance as soon as new data is available. To get more information about the table schemas, please see [Schema](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#schema). To set this up:

1. Create a Glue database.

* In the AWS console, go to "Glue". (Make sure you are in the same region as your S3 exported data).
* Click **Databases** in the sidebar.
* Click **Add Database**.
* Enter a database name and click **Create**.

<Frame>
  <img alt="image" />
</Frame>

2. Create an IAM policy.

* Go to the "AWS IAM" service on the console.
* Click **Policies** in the sidebar.
* Click **Create Policy** on the top of the screen.
* In the new screen, click the \*\*JSON \*\* tab.
* Paste the following policy:

```json theme={"system"}
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "MixpanelGlueAccessStatement",
            "Effect": "Allow",
            "Action": [
                "glue:GetDatabase",
                "glue:CreateTable",
                "glue:GetTables",
                "glue:GetTableVersions",
                "glue:UpdateTable",
                "glue:DeleteTable",
                "glue:GetTable"
            ],
            "Resource": "*"
        }
    ]
}
```

* Click **Review Policy** and give the policy a name in the next screen.
* Click \*\*Create Policy \*\*to save.

Note: AWS does not support granular resources when granting Glue access. So you will have to use \* (asterisk) in the Resources field until AWS can support more granular resources.

3. Create an IAM Role and assign the Policy you created in Step 2.

* Go to the "AWS IAM" service on the console.
* Click **Roles** in the sidebar.
* Click **Create Role**.
* Select **Other AWS Accounts** on the trust policy page and enter "485438090326" for the account ID.
* In the "Permissions" page, find and select the policy you created in Step 2.
* In the Review page, enter a name and description for the role and click **Create Role**.

4. Limit the trust relationship to the Mixpanel export user.

* Navigate to the "AWS IAM" service in the console.
* Click **Roles** in the sidebar.
* Find and click the role you created in Step 3.
* Navigate to the "Trust Relationships" tab.
* Click **Edit trust relationship**.
* Replace the contents with the following JSON:

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::485438090326:user/mixpanel-export"
      },
      "Action": "sts:AssumeRole",
      "Condition": {}
    }
  ]
}
```

* Save the contents.

<Frame>
  <img alt="image" />
</Frame>

<Warning>
  If your Glue Data Catalog is governed by [AWS Lake Formation](https://docs.aws.amazon.com/lake-formation/latest/dg/what-is-lake-formation.html), the IAM permissions above are not sufficient on their own. Lake Formation enforces its own permission layer, so you'll also need to grant the Mixpanel Glue role permissions inside Lake Formation: `CREATE_TABLE` on the Glue **database**, plus a **Data location** permission on your registered S3 export path. Grant these at the database and data-location level, not only on the table.
</Warning>

##### Configuring Table Partitions in Glue

Mixpanel partitions the Glue table by default if it has the proper AWS permissions. The partition key type and name are `string` and `mp_date` respectively and the partition values are dates in the project timezone e.g. `2021-02-03`. To enable partitioning in Glue, the Glue Data Modification Policy must include the following actions:

```text theme={"system"}
"glue:GetPartition",
"glue:CreatePartition",
"glue:DeletePartition",
"glue:UpdatePartition",
"glue:BatchCreatePartition",
"glue:GetPartitions",
"glue:BatchDeletePartition",
"glue:BatchGetPartition"
```

##### Configuring Glue to Use Crawlers

You can configure Glue to crawl the S3 bucket with Mixpanel data. Glue crawlers are convenient because they automatically extract the schema from the data files and update the Glue schema.

This convenience, however, can also pose issues, such as:

* The run time of the crawlers could be out of sync with Mixpanel’s export schedule. As a result, it can prevent you from using your data as soon as new properties are available.
* The time column is interpreted as an integer. As a result, it is more difficult to perform timestamp operations.
* When using the one table per event schema option, Glue crawlers can merge data from multiple events in one table based on similarity.

To avoid these issues, Mixpanel can write and update a schema in your Glue instance as soon as new data is available. Follow [these instructions](/docs/data-pipelines/old-pipelines/integrations/schematized-aws-pipeline#configuring-glue-for-mixpanel-direct-export) to enable Mixpanel to write your data catalog to AWS Glue.

To use crawlers, you must point the crawler to the top level folder with your Mixpanel project ID.

For more details to configure Glue to use crawlers, see [Cataloging Tables with a Crawler](https://docs.aws.amazon.com/glue/latest/dg/add-crawler.html).

#### Setting up Redshift

When the data catalog and table definitions are available in Glue through either of the aforementioned means, you can connect your Redshift cluster to the catalog and query it from Redshift. [AWS documentation](https://docs.aws.amazon.com/redshift/latest/dg/c-using-spectrum.html) walks through the process in detail.

The following is an overview of the process. To properly configure Redshift:

1. Create an IAM role with read access to Glue and the S3 bucket containing your Mixpanel data.
2. Assign that role to your Redshift cluster.
3. After you insert your role and the database name in the following SQL query, run it as cluster admin:

```sql theme={"system"}
CREATE EXTERNAL SCHEMA mixpanel FROM DATA CATALOG 
DATABASE '<YOUR_GLUE_DATABASE_NAME>' -- defined when you configured Glue
IAM_ROLE '<YOUR_ROLE_ARN>' -- this is the ARN for the role with access to Glue+S3
CREATE EXTERNAL DATABASE IF NOT EXISTS;
```

You only need to connect Redshift to Glue once. As the Mixpanel pipeline exports more data to your bucket and Glue catalog, you will automatically have access to all the new data and schema changes.

You can also join data stored in Redshift with Mixpanel data available in S3 through the external schema.

## Queries

You can query data with a single table schema or with a multiple table schema in Redshift Spectrum. To get more information about the table schemas, please see [Schema](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#schema).

To query a single table schema, use this snippet.

```sql theme={"system"}
SELECT count(*)
FROM mixpanel.mp_master_event
WHERE mp_event_name = “<CLEANED_EVENT_NAME>”
```

To query a multiple table schema, use this snippet.

```sql theme={"system"}
SELECT count(*)
FROM mixpanel.mp_master_event
WHERE mp_event_name = “<CLEANED_EVENT_NAME>”
```

`CLEANED_EVENT_NAME` is the transformed event name based on [transformation rules](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#transformation-rules).

#### Nested and Repeated Fields

[Redshift Spectrum](https://docs.aws.amazon.com/redshift/latest/dg/c-using-spectrum.html) does not support nested and repeated fields.

Mixpanel exports array and object properties as a string. You can use built in functions to convert the string to JSON at query time.


# Schematized Azure Pipeline
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines/integrations/schematized-azure-pipeline



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Mixpanel’s Azure Blob Export is one type of [Schematized Export Pipeline](/docs/data-pipelines/old-pipelines/schematized-export-pipeline) that exports Mixpanel events and people data and imports them into an Azure Blob storage instance.

Azure Export enables the use of SQL to query your event data, either for expressing new types of queries or for joining against other data already present in your data environment.

## Integration Set Up

In order to export data to Azure Blob Storage, you must first give Mixpanel permission to write to Azure. Next you can [create a pipeline](/reference/create-warehouse-pipeline) to export the data. Mixpanel then uploads the data to Azure Blob Storage on a recurring basis. The data is a slightly transformed version of the raw data stored in Mixpanel. Please see [transformation rules](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#transformation-rules) to understand how the data is transformed.

## Edit Mixpanel Permission

Since the Azure authentication mechanisms do not allow for cross-account access, you must provide  Azure credentials to use with their Blob storage container.

To achieve this, Mixpanel uses Service Principals created in your Azure Active Directory deployment. To create a Service Principal,  use the Azure command line tool and run the following command (with redacted output):

```shell theme={"system"}
$ az ad sp create-for-rbac --sdk-auth          
{
  "clientId": "redacted",
  "clientSecret": "redacted",
  "subscriptionId": "redacted",
  "tenantId": "redacted",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  "activeDirectoryGraphResourceId": "https://graph.windows.net/",
  "sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
  "galleryEndpointUrl": "https://gallery.azure.com/",
  "managementEndpointUrl": "https://management.core.windows.net/"
}
```

If the above step is successful, go to the Azure. Navigate to a blob storage container of your choice and assign the “Storage Blob Data Contributor” to the Service Principal from above.

Mixpanel needs the `clientId`, `clientSecret`, and `tenantId` to access the blob container as the Service Principal. You must provide the blob account name, container name, and (optional) path prefix you want to choose for the export.

You can share the Service Principal’s credentials over the TLS encrypted API at the time that you create your Mixpanel to Azure pipeline.


# Schematized BigQuery Pipeline
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines/integrations/schematized-bigquery-pipeline



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

This guide describes how Mixpanel exports your data to a [Google BigQuery](https://cloud.google.com/bigquery/) dataset.

## Design

<Warning>
  Mixpanel exports data into customer-managed BigQuery. Mixpanel-hosted BigQuery is no longer supported for new pipelines.
</Warning>

<Frame>
  <img alt="image" />
</Frame>

As part of the export pipeline, a new dataset `mixpanel_nessie_day_partitioned_<PROJECT_ID>` will be created if the customer chose to export into Mixpanel managed BigQuery or a dataset should be created with appropriate permissions on customer-managed BigQuery and provide us with a name. We also apply [transformation rules](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#transformation-rules) to make the data compatible with data warehouses.

For user profile and identity mappings tables, we create a new table with a random suffix every time and then will update the `mp_people` and `mp_identity_mappings` views accordingly to use the latest table. You should always use the views and should refrain from using the actual tables as we don't delete the old tables immediately and you may be using an old table.

> **Important:** Please do not modify the schema of bigquery tables generated by Mixpanel. Altering the table schema can cause the pipeline to fail to export due to schema mismatches.

## Partitioning

The data in the tables is partitioned based on [`_PARTITIONTIME` pseudo column](https://cloud.google.com/bigquery/docs/querying-partitioned-tables#ingestion-time_partitioned_table_pseudo_columns) and in project timezone.

Note: TIMEPARTITIONING shouldn't be updated on the table. It will fail your export jobs. Create a new table/view from this table for custom partitioning.

## Queries

You can query data with a single table schema or with a multiple table schema in BigQuery. To get more information about the table schemas, please see [Schema](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#schema).

To query a single table schema, use this snippet.

```sql theme={"system"}
SELECT count(*)
FROM mixpanel_nessie_day_partitioned_<PROJECT_ID>.mp_master_event
WHERE mp_event_name = “<CLEANED_EVENT_NAME>”
```

To query a multiple table schema, use this snippet.

```sql theme={"system"}
SELECT count(*)
FROM mixpanel_nessie_day_partitioned_<PROJECT_ID>.<CLEANED_EVENT_NAME>
```

`CLEANED_EVENT_NAME` is the transformed event name based on [transformation rules](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#transformation-rules).

#### Getting the number of events in each day

You will need this if you suspect the export process is not exporting all the events you want. As the tables are partitions using  [`_PARTITIONTIME` pseudo column](https://cloud.google.com/bigquery/docs/querying-partitioned-tables#ingestion-time_partitioned_table_pseudo_columns) and in project timezone, you can use to following query to get the number of events per day in an easy and fast way:

```sql theme={"system"}
SELECT
  _PARTITIONTIME AS pt,
  COUNT(*)
FROM
  `mixpanel_nessie_day_partitioned_<PROJECT_ID>.mp_master_event`
WHERE
  DATE(_PARTITIONTIME) <= "2021-12-03"
  AND DATE(_PARTITIONTIME) >= "2021-12-01"
GROUP BY
  pt
```

This example returns the number of events in each day in project timezone for a monoschema export pipeline and an example date range. You can adjust the query for multischema by putting the right table name in the query.

#### Querying the identity mapping table

When using the ID mappings table, you should use the **resolved** `distinct_id` in place of the non-resolved `distinct_id` whenever present. If there is no resolved `distinct_id`, you can then use the `distinct_id` from the existing people or events table.

Below is an example SQL query that references the ID mapping table to count number of events in a specific date range for each unique user in San Francisco :

```sql theme={"system"}
SELECT
 CASE
     WHEN m.resolved_distinct_id IS NOT NULL THEN m.resolved_distinct_id
     WHEN m.resolved_distinct_id IS NULL THEN e.distinct_id
 END as resolved_distinct_id,
COUNT(*) AS count
FROM mixpanel_nessie_day_partitioned_<PROJECT_ID>.mp_master_event e FULL OUTER JOIN mixpanel_nessie_day_partitioned_<PROJECT_ID>.mp_identity_mappings_data_view m
ON e.distinct_id = m.distinct_id
AND mp_city="San Francisco"
AND DATE(e._PARTITIONTIME) <= "2021-12-03"
AND DATE(e._PARTITIONTIME) >= "2021-12-01"
GROUP BY resolved_distinct_id
LIMIT 100
```

Counting number of times a user has done a specific behavior is also possible by adding more filters on event properties. You can adjust the query for multischema by putting the right table name in the query.

## Exporting into Customer managed BigQuery (Recommended)

We recommend exporting Mixpanel data into customer-managed BigQuery, for this the customer needs to follow these steps.

1. Create a dataset in their BigQuery

   <Frame>
     <img alt="image" />
   </Frame>
2. Give Mixpanel the necessary permissions to export into this dataset.

   > **Note:** If your organization uses [domain restriction constraint](https://cloud.google.com/resource-manager/docs/organization-policy/restricting-domains) you will have to update the policy to allow Mixpanel domain `mixpanel.com` and Google Workspace customer ID: `C00m5wrjz`.

   We need two permissions to manage the dataset.

   **BigQuery Job User**

   * Go to **IAM \&Admin** in your Google Cloud Console.
   * Click **+ ADD** to add principals
   * Add new principal "[export-upload@mixpanel-prod-1.iam.gserviceaccount.com](mailto:export-upload@mixpanel-prod-1.iam.gserviceaccount.com)" and set role as "BigQuery Job User", and save.

     <Frame>
       <img alt="image" />
     </Frame>

   **BigQuery Data Owner**

   * Go to **BigQuery** in your Google cloud Console.
   * Open the dataset you want mixpanel to export to.
   * Click on **sharing** and **permissions** in the drop down.
   * In the Data Permissions window click on **Add Principal**
   * Add new principal "[export-upload@mixpanel-prod-1.iam.gserviceaccount.com](mailto:export-upload@mixpanel-prod-1.iam.gserviceaccount.com)" and set role as "BigQuery Data Owner", and save.

     <Frame>
       <img alt="image" />
     </Frame>
3. You need to pass this dataset and gcp project id as params when you [create your pipeline](/reference/create-warehouse-pipeline)


# Schematized GCS Pipeline
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines/integrations/schematized-gcs-pipeline



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

The Google Cloud Storage schema pipeline exports [transformed data](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#transformation-rules) to a GCS bucket. This can be useful in case you want to export Mixpanel data into your own BigQuery instance.

To set up a schematized export pipeline to Google Cloud Storage (GCS) from Mixpanel, you must configure GCS to receive the exported data, then [create a pipeline](/reference/create-warehouse-pipeline) to export the data.

The following document summarizes the steps to edit GCS permissions so that it accepts the Mixpanel export, and provides an example request to create the pipeline.

## Configure GCS to Accept Mixpanel Data

Create a destination bucket, or use an existing one.

`export-upload@mixpanel-prod-1.iam.gserviceaccount.com` needs to be given a "Storage Object Admin" role on the bucket you are creating or intending to reuse for this purpose.

## Use the Data Pipelines API

After permissions have been granted, use the [Data Pipelines API](/reference/create-warehouse-pipeline) to create the pipeline. Here is an example request:

```sh cURL Example with Values theme={"system"}
curl https://data.mixpanel.com/api/2.0/nessie/pipeline/create \
-u API_SECRET: \
-d type="gcs-schema" \
-d from_date="2019-08-10" \
-d gcs_bucket="example-gcs-export" \
-d gcs_prefix="dwe" \
-d schema_type="multischema" \
-d gcs_region="us-east-2"
```


# Schematized Snowflake Pipeline
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines/integrations/schematized-snowflake-pipeline



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

This guide describes how Mixpanel data is exported into a [Snowflake](https://docs.snowflake.net/manuals/user-guide-getting-started.html) dataset. [Create a pipeline](/reference/create-warehouse-pipeline) to export your Mixpanel data into Snowflake. Once an export job is scheduled, Mixpanel exports data to Snowflake on a recurring basis.

## Design

<Warning>
  Mixpanel exports data into customer-managed Snowflake. Mixpanel-hosted Snowflake (Data Sharing) is no longer supported for new pipelines. Only password-based authentication is supported via the API; key-pair authentication is not available.
</Warning>

Mixpanel stages exported data in a GCS bucket before loading it into your Snowflake warehouse. You need to set up a role, storage integration, and user in your Snowflake account before creating a pipeline.

## Set Export Permissions

### Step 1: Create a Role and Grant Permissions

Create a role (`MIXPANEL_EXPORT_ROLE` as an example) and grant access on your database, schema, warehouse to the role. Replace `<database name>`, `<schema name>`, `<warehouse name>` with actual names.

```sql theme={"system"}
CREATE ROLE MIXPANEL_EXPORT_ROLE;
GRANT ALL ON DATABASE <database name> TO ROLE MIXPANEL_EXPORT_ROLE;
GRANT ALL ON SCHEMA <database name>.<schema name> TO ROLE MIXPANEL_EXPORT_ROLE;
GRANT USAGE ON WAREHOUSE <warehouse name> TO ROLE MIXPANEL_EXPORT_ROLE;
GRANT OPERATE ON WAREHOUSE <warehouse name> TO ROLE MIXPANEL_EXPORT_ROLE;
GRANT MONITOR ON WAREHOUSE <warehouse name> TO ROLE MIXPANEL_EXPORT_ROLE;
```

### Step 2: Create a Storage Integration

Mixpanel stages exported data in a GCS bucket (`gcs://mixpanel-export-pipelines-<project-id>`) before loading it into your warehouse. This bucket is created and managed by Mixpanel - you do *not* need to create it yourself. To allow Mixpanel to load data from this bucket into your Snowflake warehouse, create a GCS storage integration and grant it to the role. Replace `<project-id>` with your Mixpanel project ID.

```sql theme={"system"}
CREATE STORAGE INTEGRATION MIXPANEL_EXPORT_STORAGE_INTEGRATION
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'GCS'
  ENABLED = TRUE
  STORAGE_ALLOWED_LOCATIONS = ("gcs://mixpanel-export-pipelines-<project-id>");
GRANT USAGE ON INTEGRATION MIXPANEL_EXPORT_STORAGE_INTEGRATION TO MIXPANEL_EXPORT_ROLE;
```

### Step 3: Authenticate the User

Create a user with a password and grant the role to the user. If you already have a user, change the fields and grant the role.

```sql theme={"system"}
CREATE USER MIXPANEL_EXPORT_USER PASSWORD='<password you provided>' DEFAULT_ROLE=MIXPANEL_EXPORT_ROLE;

ALTER USER MIXPANEL_EXPORT_USER SET PASSWORD='<password you provided>';
GRANT ROLE MIXPANEL_EXPORT_ROLE TO USER MIXPANEL_EXPORT_USER;
```

For Snowflake export, we first load the data into a single-column raw (VARIANT type) data table. This data will be a [transformed version](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#section-transformation-rules) of the raw data stored in Mixpanel. Then, we create a view to expose all properties as columns. The view name is the cleaned version of the event name and the raw table name is always the view name suffixed with `_raw`. For example, for `signup` event, you will have a `signup_raw` table and a `signup` view. Please see [Schema](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#schema) for general information about the schemas in Schematized Export Pipelines.

## Partitioning

The data in the raw tables is clustered based on `time` column but in project's timezone. To be exact, we use `CLUSTER BY (TO_DATE(CONVERT_TIMEZONE('UTC','<TIMEZONE>', TO_TIMESTAMP(DATA:time::NUMBER)))` where `TIMEZONE` is the Mixpanel project's timezone.

## Queries

Mixpanel recommends you place all events into a single table to make querying easier. To get more information about the table schemas, please see [Schema](/docs/data-pipelines/old-pipelines/schematized-export-pipeline#schema).

A query is a request for data results. You can perform actions on the data, such as combine data from different tables; add, change, or delete table data; and perform calculations.

Snowflake supports a VARIANT type that can store JSON objects and arrays. Mixpanel exposes array and object top-level properties as VARIANT columns in the view.

Here is an example of how you can query the raw table when using one table for all the events:

```sql theme={"system"}
SELECT count(*)
FROM mixpanel.mp_master_event_raw
WHERE data:mp_event_name::string = “Signup”;
```

Here is an example of how you can query the view when using one table for all the events:

```sql theme={"system"}
SELECT count(*)
FROM mixpanel.mp_master_event
WHERE mp_event_name = “Signup”;
```

Here is an example of how you can query the raw table when using multiple tables for the events:

```sql theme={"system"}
SELECT count(*)
FROM mixpanel.signup_raw
WHERE data:distinct_id::string = “1”;
```

Here is an example of how you can query the view when using multiple tables for the events:

```sql theme={"system"}
SELECT count(*)
FROM mixpanel.signup
WHERE distinct_id = “1”;
```

### Getting the number of events in each day

You will need this if you suspect the export process is not exporting all the events you want. As time column in the tables is in UTC timezone, you first need to convert that to your Mixpanel project timezone, and then, get the number of events for each day. The following query will do that for you.

```sql theme={"system"}
SELECT TO_DATE(CONVERT_TIMEZONE('UTC','<PROJECT_TIMEZONE>', time)) as ttime, count(*) 
FROM "<DB_NAME>"."PUBLIC"."MP_MASTER_EVENT"
WHERE ttime>=TO_DATE('2021-12-03') AND ttime<=TO_DATE('2021-12-07')
GROUP BY ttime
```

This example returns the number of events in each day in project timezone for a monoschema export pipeline and an example date range. `PROJECT_TIMEZONE` and `DB_NAME` should be replaced by your Mixpanel project timezone and your snowflake database name. You can adjust the query for multi-schema by putting the right table name in the query.

### Querying the identity mapping table

When using the ID mappings table, you should use the **resolved** `distinct_id` in place of the non-resolved `distinct_id` whenever present. If there is no resolved `distinct_id`, you can then use the `distinct_id` from the existing people or events table.

Below is an example SQL query that references the ID mapping table to count number of events in a specific date range for each unique user in San Francisco

```sql theme={"system"}
SELECT
 CASE
     WHEN m.resolved_distinct_id IS NOT NULL THEN m.resolved_distinct_id
     WHEN m.resolved_distinct_id IS NULL THEN e.distinct_id
 END as resolved_distinct_id,
COUNT(*) AS count
FROM "<DB_NAME>"."PUBLIC"."MP_MASTER_EVENT" e FULL OUTER JOIN "<DB_NAME>"."PUBLIC"."MP_IDENTITY_MAPPINGS_DATA" m
ON e.distinct_id = m.distinct_id
AND mp_city="San Francisco"
AND TO_DATE(CONVERT_TIMEZONE('UTC','<PROJECT_TIMEZONE>', e.time)) >= TO_DATE("2020-04-01")
AND TO_DATE(CONVERT_TIMEZONE('UTC','<PROJECT_TIMEZONE>', e.time)) <= TO_DATE("2020-04-03")
GROUP BY resolved_distinct_id
LIMIT 100
```

Counting number of times a user has done a specific behavior is also possible by adding more filters on event properties. You can adjust the query for multi-schema by putting the right table name in the query.


# Schematized Export Pipeline
Source: https://docs.mixpanel.com/docs/data-pipelines/old-pipelines/schematized-export-pipeline



<Note>
  Customers on an Enterprise or Growth plan can access Data Pipeline as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Schematized Export Pipeline is designed to export your Mixpanel data into supported data warehouses or object storage solutions. We first transform the events and user profile data in Mixpanel to be ready to be loaded into the supported data warehouses using [transformation rules](#transformation-rules). For object storage solutions, we only add the mapping of original property names to the column names to the bucket. For data warehouses, we add the schema and time-based partitions to the tables to make the queries easier to write and more efficient.

This documentation targets users with intermediate or advanced knowledge of databases and knowledge of Amazon Web Services, Google Cloud Platform, or Snowflake technology.

## Mixpanel Schematized Export Pipeline Overview

You must first configure your destination to accept the data before you can export data from Mixpanel to that destination.

For additional information on configuring the Mixpanel export for different destinations, see:

* [BigQuery](/docs/data-pipelines/old-pipelines/integrations/schematized-bigquery-pipeline)
* [Snowflake](/docs/data-pipelines/old-pipelines/integrations/schematized-snowflake-pipeline)
* [Amazon Web Services](/docs/data-pipelines/old-pipelines/integrations/schematized-aws-pipeline)
* [Google Cloud Storage](/docs/data-pipelines/old-pipelines/integrations/schematized-gcs-pipeline)
* [Azure Blob Storage](/docs/data-pipelines/old-pipelines/integrations/schematized-azure-pipeline)

After configuring the destination, you can [create a pipeline](/reference/create-warehouse-pipeline) to export the data.

After configuring the destination and creating a pipeline with the API, you can begin to query Mixpanel data from the destination warehouse or storage bucket. This opens up the use of SQL use from within Google Bigquery, Snowflake, and Amazon Redshift Spectrum.

## Data Sources

Mixpanel can export both events and user data. Mixpanel supports hourly and daily exports (daily is the default).

The event data that is exported using the schematized export pipeline is the same data exported from the [Raw Data Export API](/reference/raw-event-export#raw-event-export).

The user data that is exported using the schematized export pipeline is the same data exported from the [Query API Engage Endpoint](/reference/engage-query#engage-query).

In order to ensure a performant service for all customers, certain steps of the pipelines are limited to 1 pipeline per project running at a time. For example, a project with multiple jobs would have one wait for the other to complete certain steps before proceeding. In this way, something like a large backfill for one customer does not take priority over other customers, and keeps scheduling more fair.

In addition, customers are limited to 1 date-range based pipeline creation per 24 hours. A date-range based pipeline is one that has a `from_date` and `to_date` that are both in the past, and uses `events` as the data type.

#### Backfilling Historical Data

You can schedule an initial backfill when creating a pipeline. This ensures that historical data is also exported to the data warehouse.

Use the `from_date` parameter to specify the date you want to use to export historical data. Note that the `from_date` must be no more than 6 months in the past.

The completion time for a backfill depends on the number of days and the amount of data in the project. Larger backfills can take up to multiple weeks.

## User Data Support

User data is exported to a single table named `mp_people_data` (user data is accessible as a view of `mp_people_data` in BigQuery).

Since user profiles are mutable, the data in the table is replaced every time an export happens based on the schedule (daily or hourly) with the latest user profiles.

## User Identity Resolution

Exports from projects with [ID merge enabled](/docs/tracking-methods/id-management#identity-merge-apis) will need to use the identity mapping table to replicate the user counts seen in UI reporting. When ID merge is enabled, Mixpanel assigns multiple identifiers to an individual. Mixpanel resolves these into one identifier, and uses that for reporting unique user counts. Read more about how Mixpanel resolves IDs [here](/docs/tracking-methods/id-management/identifying-users-simplified#example-user-flows).

Pipelines export event data as they appear when Mixpanel ingests them. This means exported event data before sending alias event has the original user identifier, **not** the resolved identifier. Use the identity mappings table to accurately count unique users. This will allow you to recreate the identity cluster that Mixpanel creates.

Mixpanel automatically exports the ID mapping table when you create a people export pipeline from a project with ID merge enabled.

Note: When using the ID mappings table, you should use the **resolved** `distinct_id` in place of the non-resolved `distinct_id` whenever present. If there is no resolved `distinct_id`, you can then use the `distinct_id` from the existing people or events table. }

Examples of how to do this are available for [BigQuery](/docs/data-pipelines/old-pipelines/integrations/schematized-bigquery-pipeline#querying-the-identity-mapping-table) and [Snowflake](/docs/data-pipelines/old-pipelines/integrations/schematized-snowflake-pipeline#querying-the-identity-mapping-table).

## Service Level Agreement

The policy for latency on exported events is 24 hours end to end, plus an additional 24 hours for late-arriving data.

**Note**: Mixpanel defines late data as any data point or user profile update that reaches Mixpanel servers later than two hours after the end of the export window. Late-arriving event data is only exported for pipelines with sync enabled.

For hourly pipelines, data that arrived on time would be exported in up to 24 hours from the time that Mixpanel ingests the data. For daily pipelines, the 24 hours would be counted from the start of the next calendar day in project time (ex: data ingested on Jan 1st is scheduled to be imported starting Jan 2nd at midnight and before midnight on Jan 3rd).

Data that arrived late is exported during a sync process daily (if sync is enabled), the next day after the data is ingested. As an example, data for Jan 1st that arrived on Jan 3rd (a couple of days late) would be exported/synced in the sync run from Jan 4th.

## Data Sync

Event data stored in Mixpanel’s datastore and event data in the data warehouse can fall out of sync.

The discrepancy can be attributed to several different causes:

* Late data can arrive multiple days later due to a mobile client being offline.
* The import API can add data to previous days.
* Delete requests related to GDPR can cause deletion of events and event properties.

Mixpanel is able to detect any changes in your data with the granularity of a day and replaces the old data with the latest version both in object storage and data warehouse, if applicable.

Data sync helps keep the data fresh and minimizes missing data points.

Do Note: Data sync does not fully guarantee syncing GDPR Data Deletions and will only sync data for days up to 10 days in the past. It is recommended to implement a strategy to remove all records of GDPR Deleted Users in your data warehouse. Additionally, we start checking for late arriving data 24 hours after the data for a day is exported. It may take more than 2 days for the data in the destination to be in sync with the data in Mixpanel.

## Transformation Rules

Some characters are not legal for table or column names, or when collisions can occur in the dataset. Mixpanel cleans, or transforms, the data to account for this. This section provides the rules on how Mixpanel cleans data.

#### Table and Column Names

Mixpanel applies these rules for table and column names:

* Special characters and whitespaces are replaced with `_`(underscore).
* Letters are converted to lowercase.
* Maximum name length is 128 characters (The name is truncated after 128 characters.)
* Properties that start with a `$` (dollar sign) have a prefix of `mp_`.
* Properties that conflict with reserved keywords are prefixed with `res_`.
* When there are multiple types for the same property name, we append suffix `_<type>` (e.g., `_string`, \`\_number) to the column names to differentiate them.

#### Naming Conflicts

There are several naming transformations that happen as a result of character conflicts.

Capitalized letters are converted to lower case. Any duplicate strings has a numeric value appended to them to differentiate.

For example if values “XY” and “Xy” are sent in:

* Both are transformed to “xy”.
* If “Xy” is sent in after "XY", it becomes “xy\_1”.
* Any subsequent “xy” values inherit incremental numeric values (i.e. xy\_2, xy\_3, etc.).

#### Type Conflicts

Mixpanel transforms values to resolve type conflicts.

If a property value is passed with a particular data type and is passed subsequently with a different data type, then the new data type appends to the property name.

For example, if “X” appears with type INT first, then subsequently appears as type STRING (or VARCHAR), then the property name will be transformed to "x\_string" with a data type of string.

#### New Properties

New properties that were not present in previous imports will append to the old rows with a `NULL` value.

## Property Mappings

Because of the transformation rules, sometimes it can be hard to know the mappings between original and transformed event and property names. In case you are exporting the schematized data to an object storage or you are exporting to a data warehouse but providing your own intermediate object storage, we export these mappings to `<BUCKET_NAME>/<PATH_PREFIX>/<MIXPANEL_PROJECT_ID>/schema/` under `events.json`, `people.json` and `identities.json`.

## Schema

This section describes how Schematized Export Pipeline creates the schema for the exported data. Event data and user data are loaded into separate tables. User profile data is loaded into one table, whereas events can be loaded into either a single table for each event or one table for all events.

#### Common Properties

Regardless of whether you're using a single table or multiple tables, the following properties will be always present in the schema:

| name         | type   | description                                         |
| :----------- | :----- | :-------------------------------------------------- |
| time         | int    | The timestamp representing when the event occurred. |
| distinct\_id | string | The unique ID of the user who triggered the event.  |

For a single table schema, you will also have an extra property for event name:

| name            | type   | description           |
| :-------------- | :----- | :-------------------- |
| mp\_event\_name | string | the name of the event |

Please note that the types in the above tables are generic. The exact type can be different based on your export destination.

#### Limits

The schema for each table cannot exceed 9500 unique properties. If a tables schema reaches this limit all new properties added to the schema will be included in a JSON like property called `mp_properties`.

| name           | type             | pipeline destination |
| :------------- | :--------------- | :------------------- |
| mp\_properties | json             | BigQuery             |
| mp\_properties | object           | Snowflake            |
| mp\_properties | json-like string | AWS Glue             |
| mp\_properties | json-like string | GCS                  |
| mp\_properties | json-like string | Azure                |

#### Using One Table for All Events

In this schema, all your Mixpanel data exists in a single table. Mixpanel recommends a single table schema because it makes querying simpler.

If you select the single table schema, the export pipeline creates a \*mp\_master\_event \*table. The table has one column per unique property name across all events in the history of the dataset.

Suppose you have an event with a `purchase_amount` property and one with a `referrer` property, the table will have a *purchase\_amount* column and a *referrer* column. Events that don’t have a property contain a NULL value in that column.

For examples of one table for all events, see [One Table for All Events](#one-table-for-all-events).

#### Using One Table for Each Event

Each Mixpanel event exists in a single table. This schema is a useful workaround for limitations in the number of columns that are allowed in a S3 table.

If you select the multi-table option, Mixpanel creates one table per unique event name. Each table is named for the event. For example, if you have an event called `signup` there will be a table named *signup*.

Each table for each event has one column per unique property name across all events in the history of the dataset.

For an example of one table for each event, see [One Table for Each Event](#one-table-for-each-event).

<Note>
  One table for each event is not available during the trial period.
</Note>

#### Table Example

Here is an example dataset to view different schema options in either one table for all events or one table for each event.

```json theme={"system"}
{
       “event”: “Signup”,
       “properties”: {
       “plan”: “free”,
       “browser”: “chrome”,
       “distinct_id”: 1,
       “time”: 123
       }
}
{
       “event”: “Purchase”,
       “properties”: {
       “product_id”: “123”,
       “browser”: “chrome”,
       “distinct_id”: 1,
       “time”: 124
       }
}
{
       “event”: “Signup”,
       “properties”: {
       “plan”: “paid”,
       “browser”: “firefox”,
       “ab_test”: 1,
       “distinct_id”: 2,
       “time”: 125
}
```

##### One Table for All Events

Single table: *mixpanel\_events*

| mp\_event\_name | time | distinct\_id | plan   | browser   | product\_id | ab\_test |
| :-------------- | :--- | :----------- | :----- | :-------- | :---------- | :------- |
| “Signup”        | 123  | 1            | "free" | "chrome"  | NULL        | NULL     |
| “Purchase”      | 124  | 1            | NULL   | "chrome"  | 123         | NULL     |
| “Signup”        | 125  | 2            | "paid" | "firefox" | NULL        | 1        |

##### One Table for Each Event

Two tables: *signup \_and \_purchase*

Table: *signup*

| time | distinct\_id | plan   | browser   | ab\_test |
| :--- | :----------- | :----- | :-------- | :------- |
| 123  | 1            | "free" | "chrome"  | NULL     |
| 125  | 2            | "paid" | "firefox" | 1        |

Table: *purchase*

| time | distinct\_id | browser  | product\_id |
| :--- | :----------- | :------- | :---------- |
| 124  | 1            | "chrome" | 123         |


# Data Structure
Source: https://docs.mixpanel.com/docs/data-structure



<CardGroup>
  <Card title="All about our Data Model" href="/docs/data-structure/concepts" />

  <Card title="Events & Properties" href="/docs/data-structure/events-and-properties" />

  <Card title="User Profiles" href="/docs/data-structure/user-profiles" />

  <Card title="Group Analytics" href="/docs/data-structure/group-analytics" />

  <Card title="Lookup Tables" href="/docs/data-structure/lookup-tables" />

  <Card title="Property Reference" href="/docs/data-structure/property-reference" />
</CardGroup>


# Data Model
Source: https://docs.mixpanel.com/docs/data-structure/concepts

How Mixpanel data is organized

## Overview

Mixpanel data is stored and isolated within a [project](/docs/orgs-and-projects/managing-projects). At this time, you cannot query data across multiple projects. Mixpanel supports a few different categories of data that can be used for analysis: events, user profiles, group profiles, and lookup tables. In data warehouse parlance, events make up the fact table while user profiles, group profiles, and lookup tables are dimension tables.

<Frame>
  <img alt="Data Model Overview" />
</Frame>

| Types              | Description                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Events**         | Events describe actions that take place within your product. An event contains properties that describe the action. Events can also be joined with user profiles, group profiles, and lookup tables to enrich the data. <br /><br /> [Learn more about event properties](/docs/data-structure/events-and-properties)                                                                                       |
| **User Profiles**  | A user profile is a key/value store that holds state about a user. User profiles are joined to events on `event.distinct_id = user_profile.distinct_id`. <br /><br /> [Learn more about profile properties](/docs/data-structure/user-profiles)                                                                                                                                                            |
| **Group Profiles** | A group profile is a key/value store that holds state about members of your group. Group profiles are joined to Events on your chosen *group key*. For example, if you create a new group key for `company_id` your events will be joined on `event.company_id = group_profile.company_id`. <br /><br /> [Learn more about group analytics](/docs/data-structure/group-analytics)                          |
| **Lookup Tables**  | A lookup table is a key/value store that holds state about an entity. Lookup tables are joined to events (and other profiles) on your chosen join key. For example, if you create a lookup table for "Songs" and specify the join key as `song_id`, your events will be joined on `event.song_id = lookup_table.song_id`. <br /><br />[Learn more about lookup tables](/docs/data-structure/lookup-tables) |

### Event Property vs User Profile Property

An event property is a detail about an event.  Event properties are incredibly important, as they provide the necessary context about events to ensure valuable analytics. Properties also facilitate the dissection of data, allowing for more detailed insight into event-driven data. Once tracked, events and their properties are immutable, meaning they cannot be changed.

Profile Properties give you detail about a certain user overall. In other words, Profile Properties describe your users as they exist in this moment. A user profile property could be a static value, such as a first name, or be something more likely to change, like the date of last login or the number of songs a user has played.

For example, while an Event Property or Super Property tells you whether a user had a paid or free account over time when a user did specific actions, a Profile Property would simply show you currently if they are paid or free.

## Example

Imagine you work on a music streaming product and you want to answer questions like:

* What are the most popular songs and artists this week?
* What is the distribution of number of songs played per week by user?
* Which experiment performed better in an A/B test to drive a higher conversion rate from Free to Premium accounts?

You want to analyze uniques by both users *and* accounts so you create a group key for `account_id`. You also want to augment your events with details about songs being played so you create a "Songs" lookup table and specify the join key as `song_id`. Your data model will look like this:

<Frame>
  <img alt="Data Model Example" />
</Frame>

Your Mixpanel data is made up of **events** and **profiles**, each of which is comprised of **properties**.  Events are data points in a time-series database. Profiles are key-value stores.

## Anatomy of an Event

The following event represents the fact that user `john.doe@gmail.com` played the song\_id of `0wwPcA6wtMf6HUMpIRdeP7` on Tuesday, September 29, at 2020 8:42:11 PM GMT on a machine with IP 203.0.113.9.

```json theme={"system"}
{
  // The name of your event
  "event": "Played Song", 

   // A dictionary of properties to hold metadata about your event
  "properties": { 

    // The Mixpanel token associated with your project. You can find your Mixpanel token
    // in the project settings dialog in the Mixpanel app. Events without a valid token
    // will be ignored.
    "token": "6972694d809c7390676a138834f8c890",

    // The time an event occurred. If present, the value should be a Unix timestamp
    // (milliseconds since UTC epoch). If this property is not included in your request,
    // Mixpanel will use the time the event arrives at the server. If you're using our mobile SDKs,
    // it will be set automatically for you.
    "time": 1601412131000,

    // An IP address string (e.g. "127.0.0.1") associated with the event. This is
    // used for adding geolocation data to events, and should only be required if
    // you are making requests from your backend. If IP is absent (and ip=1 is not
    // provided as a URL parameter), Mixpanel will ignore the IP address of the request.
    "ip": "203.0.113.9",

    // A unique identifier for the event. Mixpanel uses this to deduplicate events in the case
    // of retries or network failures. Events with the same (event, time, distinct_id, $insert_id)
    // are considered duplicates. 
    // We recommend generating UUIDs for $insert_ids. Our SDKs do this automatically.
    "$insert_id": "5d958f87-542d-4c10-9422-0ed75893dc81",

    // The value of distinct_id will be treated as a string, and used to uniquely 
    // identify a user associated with your event. If you provide a distinct_id property
    // with your events, you can track a given user through funnels and distinguish 
    // unique users for retention analyses. You should always send the same distinct_id
    // when an event is triggered by the same user.
    "distinct_id": "john.doe@gmail.com",

    // You can also specify any arbitrary properties you want to track as metadata
    // about the event
    "app_version": "1.1.34.694.gac68a2b3",
    "song_id": "0wwPcA6wtMf6HUMpIRdeP7"
}
```

## User Profiles, Group Profiles & Lookup Tables

All three are key/value stores that augment your event data with additional metadata about entities. The differences are whether the join key is customizable and whether events are copied and indexed by the join key.

[**User profiles**](/docs/data-structure/user-profiles) are joined to events via `distinct_id` which is the default indexing for Events.

[**Group profiles**](/docs/data-structure/group-analytics) are joined to events via an event property you specify as a group key. Once you create a new group key, we will add an additional index for your events on that property. This allows you to do funnels or retention by that property instead of by `distinct_id`.

[**Lookup tables**](/docs/data-structure/lookup-tables) are joined to events and user profiles using the join key that you specify. Unlike group profiles, your events are *not* indexed by the join key. You can use lookup table properties to do filtering, breakdowns, etc but you can't do things like funnels analysis using the join key for uniques. Note: Currently, group profile properties cannot be lookup table keys.

| Profile Type   | Can Specify Join Key | Can Use Join Key For Uniques Analysis | Can Be Referenced From Other Profiles |
| -------------- | -------------------- | ------------------------------------- | ------------------------------------- |
| User Profiles  | ❌                    | ✅                                     | ❌                                     |
| Group Profiles | ✅                    | ✅                                     | ❌                                     |
| Lookup Tables  | ✅                    | ❌                                     | ✅                                     |


# Events
Source: https://docs.mixpanel.com/docs/data-structure/events-and-properties

Capture behaviors and actions

## Overview

Events are the core of [Mixpanel's Data Model](/guides/strategic-playbooks/onboarding-playbook/plan/tracking-strategy#the-mixpanel-data-model). All events should have an **Event Name**, a **Timestamp** of when that event has occurred, and a [**Distinct ID**](/docs/tracking-methods/id-management#distinct-id) (Mixpanel's identifier for a user) to tie all events belonging to the same user. Events can optionally have a set of properties, which describes the event in more detail.

* If you're familiar with databases, events are like tables and properties are like columns.
* If you're familiar with Google Analytics, events are like hits and properties are like dimensions.

<Note>
  **Note:** There are a few use cases, such as tracking [Ad Spend](/docs/tracking-methods/integrations/ad-spend), in which the event should not be tied to specific users; as such, these events should be sent without a Distinct ID, but this is the exception.
</Note>

For more information about events refer to the documentation on [The Mixpanel Data Model](/guides/strategic-playbooks/onboarding-playbook/plan/tracking-strategy#the-mixpanel-data-model).

## Examples

* A `Page Viewed` event might have a property called `Page URL`, which is set to the URL of the page that was viewed.
* A `Signed Up` event might have a property called `Signup Type`, which indicates whether the signup was `organic` vs `referral`.
* A `Song Played` event might have a property called `Song Name`, which is set to the name of the song that was played.
* An `Order Completed` event might have a property called `Items`, which is a list of objects, each of which contains details about an item, like its name, category, and price.

## Use Cases

You can filter, breakdown, and aggregate your events by their properties to answer more questions:

* Which pages do users look at before they visit the pricing page?
* How many sign-ups did I get that were organic vs referral?
* Which song name is most popular among my users?
* How many orders contain shoes? What is the sum total price that users paid for shoes in the last month?

## Best Practices

### Keep Events as Actions

We recommend striking the right balance when defining your events. Events should neither be too broad nor too specific, and should be defined at the level of how you plan to analyze the user's action or behavior. Also keep in mind to use event properties to provide context or details about an event, instead of creating different events to capture similar actions.

**For example:**

* If your goal is to analyze at high-level how users traverse through different pages: instead of tracking multiple events `Home Page Viewed` and `Pricing Page Viewed`, track a `Page Viewed` event with a `Page Name` property set to **"/home"** or **"/pricing"**. See [Tracking Page Views](/docs/tracking-methods/sdks/javascript#tracking-page-views) in our Javascript SDK documentation on how to instrument this.
* If your goal is to track users adding items to a shopping cart: instead of tracking multiple events `Add Shirt to Cart`, `Add Hoodie to Cart`, and `Add Socks to Cart`, track a `Add to Cart` event with a `Item` property set to **"Shirt"**, or **"Hoodie"**, or **"Socks"**.
* If your goal is to track 1 button on a specific screen: instead of tracking multiple events `Blue Button Clicked` and `Checkout Button Clicked`, track a `Button Clicked` event with a `Color` property set to **"Blue"** and `Button Name` set to **"Checkout"**.
* If your goal is to track different buttons from different user journeys: instead of tracking 1 event `Button Clicked` with `Button Name` property set to **"Play"**, or **"Profile"**, or **"X"**, track them as different events `Song Played` and `Profile Updated` and `Logout` with specific properties for each event to provide richer context.

### Use a Naming Convention for Events and Properties

<Warning>
  Mixpanel strings are case-sensitive; `sign_up_completed` and `Sign_Up_Completed` are considered two separate events.
</Warning>

We recommend having a consistent naming convention for your events and properties:

* Generally, adopting snake\_case for your event and property names tend to be more robust, especially if you plan to export your Mixpanel data to downstream processes such as data warehouses.
* Use the **(Object) (Verb)** format for event names. Like `song_played` or `page_viewed`.
* Mixpanel [Lexicon](/docs/data-governance/lexicon) provides a means for you to change an event's or property's display name on the UI (if needed, to make it more user-friendly).

### Avoid Creating Events or Property Names Dynamically

For example, don't create an event name like `Purchase (11-01-2019)`. Instead, create an event called `Purchase` and have some property (eg: `Return Date`) set to the dynamic value **"11-01-2019"**.

> **Tip:** Learn more best practices around defining your events and properties under our tutorials for [Creating a Tracking Plan](/guides/strategic-playbooks/onboarding-playbook/plan/tracking-strategy#tracking-plan-methodology).

### Super Properties

It's very common to have certain event properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event - for example, the user's age, gender, source, or initial referrer.

To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are stored in a browser cookie, and will persist between visits to your site. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference/properties).

Learn more about registering super properties [here](/docs/tracking-methods/sdks/javascript#setting-super-properties).

## FAQ

### What types of data can I send as properties?

Mixpanel accepts arbitrary JSON as properties, including strings, numbers, booleans, lists, and objects. See our [Property Reference doc](/docs/data-structure/property-reference/data-type) or our [API docs](/reference/import-events) for more details.

### What are the limits of events and properties?

We don't have a limit on the total number of events you can send to Mixpanel, but it will factor into your [pricing](https://mixpanel.com/pricing).

We have a soft limit of 5000 distinct event names. If you send more event names, we'll still ingest them, but those event names will not be indexed and will not appear in our autocomplete menus.

Each event can have up to 255 properties. Event property names/values can be at most 255 characters in length (longer names are truncated). Event property values are limited based on data type, refer to these limits under [Supported Data Types](/docs/data-structure/property-reference/data-type).

<Callout icon="lightbulb">
  **Note**: while events can have up to 255 properties and batches of events can have up to 2000 events per ingestion batch, some libraries might default to sending the data through the GET protocol which would have a much lower size limit since the information is appended to the URL. If you are hitting the limits on the size of the request, first verify if the method being used is GET and can be switched to POST.
</Callout>


# Group Analytics
Source: https://docs.mixpanel.com/docs/data-structure/group-analytics

Group users together as an aggregated unit of measurement

<Note>
  Customers on an Enterprise or Growth plan can access Group Analytics as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

Mixpanel Group Analytics allows behavioral data analysis at a customized group level (such as account, device—or any other way you want to assess your business).

Historically, Mixpanel grouped events by a single identifier called the distinct\_id. This ultimately grouped events by the individual user. Group Analytics allows you to establish an event property other than the distinct\_id, such as company ID, account ID, project ID, or billing ID, as an identifier by which to analyze your data.

<Frame>
  <iframe />
</Frame>

### Data Modeling

Mixpanel Group Analysis allows you to select alternative unique identifiers in reports.

By default, Mixpanel counts unique users by distinct\_id. Group Analytics allows you to uniquely count events by an alternative identifier, such as company ID, invite ID, or another value shared by a group of individuals with different distinct\_ids. Below you will see an example of an event coming into a project that has `company_id` and `team_id` set up as separate group keys. You will see how, starting with a single event being ingested (on the left), by switching the identifier you're analyzing on, the event can be read with said identifier as the user key to do the analysis on:

<Frame>
  <img alt="" />
</Frame>

This allows behavioral analysis from a business or group level, as opposed to an individual level. You can answer questions such as:

* Which companies are engaging the most with a product?
* In instances where there are more than one user per account, such as a video streaming service, how are events triggered at an account level?
* What groups convert through a funnel to a goal event (as opposed to what individual users convert)?

### Group Profiles

Much like a [user profile](/docs/data-structure/user-profiles), Group Profiles are a collection of properties and event history specific to a group.

Group Profiles have an activity feed that shows the events performed by users in a group. Only the events attributed to the group with a defined group key will appear in the group's activity feed.

The Group Profile also displays the properties unique to that group - here's an [example](https://mixpanel.com/project/3187769/view/3699049/app/profile#distinct_id=company_id_8889\&data_group_id=-1405123841946871899) of it:

<Frame>
  <img alt="image" />
</Frame>

To access a group profile:

1. Navigate to the Users page from the menu.
2. Click on the group identifier you want to analyze on.

<Frame>
  <img alt="/group_analytics_navigation.png" />
</Frame>

3. Groups profiles will populate the Users report.

### Change the Group Identifier in a Report

By default, Metrics aggregates at the user-level. To change the identifier used for aggregation in a metric:

1. Go to a report
2. Click the “Users” dropdown within the Metric
3. Select a Group. The report will now display results grouped by the newly selected group identifier.

<Frame>
  <img alt="" />
</Frame>

When your [Insights report](/docs/reports/insights) includes multiple Metrics, you can individually toggle the identifier for each one.

For example, you can create an Insights report that shows Signups by unique Users and by unique Companies.

<Frame>
  <img alt="" />
</Frame>

Similarly, you can build a report that displays Conversion Rates per User and per Company.

<Frame>
  <img alt="" />
</Frame>

### B2B Company Analytics

Company Analytics is a feature within Group Analytics tailored to B2B SaaS Companies.  Here we focus on the idea that users ‘belong’ to a company, and that company behavior is dependent on user behavioral activity. For instance, if you have 2 accounts, each worth \$50M but with 5 and 20 users respectively, the account with 20 users is considered more healthy and likely to renew compared to the other account.

Company Analytics enables you to understand such account health and activation metrics, which are derived from the underlying user activity.

To use these features, you must [designate the group key as a company key when setting up the group](/docs/data-structure/group-analytics#setup-b2b-company-key).

#### Company Profiles

The Company Profiles page gives you a holistic view into your company health, which includes key metrics and company profile properties (i.e, company attributes).

Company Health Metrics on the page include KPIs on usage (DAU, WAU, MAU, new users), users’ engagement level (activity per user, life cycle of user), and their retention (Day 1, Week 1, and Month 1).

You can view the definition of each metric by clicking on the metric card, which will open the underlying Mixpanel report.

To access this page, click on Users/ Companies → Company Profile.

Note: This is only available if you have [set up a B2B Company Key](/docs/data-structure/group-analytics#setup-b2b-company-key), an option available in the Group Analytics package.

<Frame>
  <img alt="image" />
</Frame>

#### Activation Metrics

SaaS companies often have use cases that require them to segment companies based on the number of users and the quality of users.

For example, a question you may have is 'What is the number of trial accounts that have more than two active users?'. The hypothesis is that these accounts will convert faster.

We have a computed property in both breakdown and filter, called the **“Number of users who did…”**, available in the Group Analytics add-on, which enables you to answer these types of questions as it allows you to break down account activity by the number of active users.

<Frame>
  <img alt="image" />
</Frame>

When using **“Number of users who did…”** as a breakdown, we show you how many downloads came from different types of account health. For example, 605 downloads came from accounts with zero active users. \~1.5 downloads in the last 30 days came from accounts with two active users. Where an “active user” is defined by both the activity (e.g., event as such document created) and frequency of the activity (e.g., performing the event ≥1 time).

In a line chart, we look for activity per interval.

For example, in the below daily chart, we’re looking for activity qualification per day (i.e., an active user is one who has created at least one document on that day). The chart below shows that on Aug 19th, 35 accounts downloaded a document. Of the 35 accounts, 32 had one active user, 2 had two active users, and 1 had twenty-eight active users. Since most downloads originated from accounts with only one active user, we can conclude there is no correlation between account document downloaded activity and account health.

<Frame>
  <img alt="image" />
</Frame>


# Group Analytics FAQ
Source: https://docs.mixpanel.com/docs/data-structure/group-analytics/group-analytics-faq



## Limits

The limits below ensure group analytics works correctly in Mixpanel:

* 1M group profiles per group key (e.g. company\_id)
* 1M events per day per group identifier (e.g. company\_id = "Mixpanel") - see [Hot Shard Limits](/docs/tracking-best-practices/hot-shard-limits)
* Group properties have similar [limits as User properties](/docs/data-structure/user-profiles#what-are-the-limits-of-user-properties)
* This add-on supports up to 3 group keys. Enterprise Plans can increase this to 6 for an additional fee.

## Events Missing from Groups

The group key property must be present as an event property on an event in order to attribute them to a group profile.

Having the group key present as a user profile property does not automatically attribute the events by that user to the group.

Mixpanel does not backfill historical data to groups before the group key was implemented. This means that Mixpanel is only able to attribute group data from the date that the group key was set up in your Project Settings. Historical events that contain the group key as an event property sent prior to the implementation of the group key in Project Settings will not be attributed to a group.

## Group Analysis in Reports

Group properties are supported when analyzing by users, but user properties are not supported when analyzing by groups.

## Exporting Group Profiles via API

Use the [Engage API endpoint](/reference/engage-query) to export Group Profiles by adding `data_group_id` in the `data` param of the request.

```sh theme={"system"}
curl --request POST \
  --url https://eu.mixpanel.com/api/2.0/engage \
  --header 'Authorization: Basic <redacted>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'filter_by_cohort={"id": <cohort_id_here>}' \
  --data data_group_id=<data_group_id_here>
```

The `<data_group_id>` for the respective group key's profile can be found under Group Keys within Project Settings:

<Frame>
  <img alt="image" />
</Frame>

Alternatively, the `<data_group_id>` can also be seen as part of the URL of the [Group Profile](/docs/data-structure/group-analytics#group-profiles) page:

`https://mixpanel.com/project/<project_id>/view/<workspace_id>/app/profile#distinct_id=<distinct_id>&data_group_id=<data_group_id>`

Here's an actual [example](https://mixpanel.com/project/3187769/view/3699049/app/profile#distinct_id=company_id_8889\&data_group_id=-1405123841946871899) with `data_group_id` = `-1405123841946871899`:

<Frame>
  <img alt="image" />
</Frame>

## How is B2B Company Analytics different than Group Analytics?

Company Analytics is an advanced offering ‘within’ group analytics.

Group Analytics focuses on the concept of there being multiple entities on which analysis can be done ‘independently’ (eg. user ID, restaurant ID, driver ID, company ID, etc.)

Company Analytics is specific to B2B Companies where you are likely to have a user ID and company ID. Here we focus on the idea that users ‘belong’ to a company, and that company behavior is ‘dependant’ on user behavioral activity. For instance, in SaaS companies, the health of an account is determined by how active the users of that account are.

## What are the unique features of B2B Company Analytics?

There are two features unique to B2B Company Analytics being set up, which aren’t available with the generic group analytics setup.

* Company Profiles - this is an advanced version of group profiles that shows you the health of a company
* Company Activation filters & breakdowns


# Group Analytics Implementation Guide
Source: https://docs.mixpanel.com/docs/data-structure/group-analytics/group-analytics-implementation



<Note>
  Customers on an Enterprise or Growth plan can access Group Analytics as an [add-on package](https://mixpanel.com/pricing/). See our pricing page for more details.
</Note>

## Setup

### Group Keys in Project Settings

Group keys are project-specific, and must be set up before data is sent. To administer group keys, navigate to your Project Settings. Click **+Add Group Key** under the *Group Keys* section.

1. Navigate to your Project Settings (requires project owner or admin permissions)
2. Click **+Add Group Key** under the *Group Keys* section
3. Fill in the details on the group key (the exact name as data will be ingested) and the display name that will appear in Mixpanel

<Frame>
  <img alt="image" />
</Frame>

Once you hit save, a new row will appear in the Group Keys section with a new group ID (an ID autogenerated on our end, required for queries). The setup process takes a few minutes, so recently ingested data just after the group key is created might not be associated to a group during this time.

### Setup B2B Company Key

1. Choose which group key will be used as the B2B Company Key. This is the key for which [Company Profiles (B2B Company Analytics)](../group-analytics#company-profiles) will be generated.
2. Specify the property that should be referenced as the Company name (identifier) throughout the Mixpanel interface.

<Note>
  You can change which group key should be used as the Company Key. To change, first unset the current group key set as Company Key in the project settings, and then set a new group key as the Company Key.
</Note>

## Tracking events for a Group

By default, event data is tracked at a user level, and the association of that event to a group (or multiple groups) depends on: 1) the group key already being defined in project settings **AND** 2) that the event has the group key(s) in it with its associated values.

To better illustrate the process with an example, if you have an anonymous user triggering an event, authenticating, and then triggering other events, you may have a timeline like the picture below:

<Frame>
  <img alt="image" />
</Frame>

While the pre and post authentication events are tied to the user [via ID merge](../../tracking-methods/id-management), only events ingested with the group key in it (in this case `company_id`) would be associated with the group. In this timeline, the journey of the user starts with the initial `page_view` event, but the journey of the group starts with the `login` event.

The group key(s) and their value should be present in every event you want associated with the group (much like the ID of a user). In our client-side libraries that support a form of local storage, we have convenience functions that allow you to store the group key(s) and values in the device so every event has that information (after it's registered and before the user logs out).

<CodeGroup>
  ```javascript Javascript (Web) theme={"system"}
  mixpanel.track("page_view"); // event while anonymous
  mixpanel.identify("existing_user");
  mixpanel.add_group("company_id","company 1");
  mixpanel.track("login"); //event after authentication and part of the group "company 1"
  ```

  ```kotlin Kotlin (Android) theme={"system"}
  mixpanel.track('page_view'); // event while anonymous
  mixpanel.identify("existing_user");
  mixpanel.setGroup('company_id', 'company 1');
  mixpanel.track('login'); //event after authentication and part of the group "company 1"
  ```

  ```swift Swift (iOS) theme={"system"}
  Mixpanel.mainInstance().track(event: "page_view") // event while anonymous
  Mixpanel.mainInstance().identify(distinctId: "existing_user")
  Mixpanel.mainInstance().setGroup(groupKey: "company_id", groupID: ["company 1"])
  Mixpanel.mainInstance().track(event: "login") //event after authentication and part of the group "company 1"
  ```
</CodeGroup>

Note this is just a convenience function; for server-side libraries, or if there's no access to local storage, you can send the group key and value in every event tracked. Below you will see the same flow using python.

```python theme={"system"}
mp.track('$device:anoymous_id', 'page_view',{'$device_id':'anoymous_id'})
mp.track('existing_user', 'login',{'$device_id':'anoymous_id', '$user_id': 'existing_user', 'company_id': ['company 1']})
mp.track('existing_user', 'page_view',{'$user_id': 'existing_user', 'company_id': ['company 1']})
```

### Attributing Events to Multiple Groups

An event can be attributed to multiple groups. The convenience functions cited above define the group key as a list of strings, so calling it with a value adds to an existing list in local storage, but when tracking manually, you can send a list of strings with each group the event should be associated to.

```javascript Javascript theme={"system"}
mixpanel.track("Some Event", { company_id: ["company 1", "company 2", "company 3"] });
```

<Note>
  Up to 300 group keys may be assigned to an event. Any additional groups beyond that number are ignored.
</Note>

## Updating Group Profiles

To create or update a [group profile](../group-analytics#group-profiles), similarly to user profile operations, at least one (1) profile property must be set. A set operation for a group profile that does not exist would create said profile, while it would update an existing profile.

```python theme={"system"}
mp.group_set('company_id', 'company 1', {
    'Company Type': 'Analytics',
    'Company name': 'Mixpanel'
})
```

### Upload Group Profiles Using the Users Report

It is possible to create Group Profiles by CSV upload as an alternative to the Groups API. [Follow the instructions here to learn how to upload Group Profiles using the Users report](/docs/data-structure/user-profiles#importing-from-csv).

## SDK references for Groups

To view the setup guides for implementing Groups using the Groups API, follow the instructions connected to the SDK you are using, cataloged [here](/docs/tracking-methods/sdks).

* [HTTP](/reference/group-set-property)
* [Javascript SDK](/docs/tracking-methods/sdks/javascript#group-analytics)
* [iOS-Swift SDK](/docs/tracking-methods/sdks/swift#group-analytics)
* [iOS-Objective-C SDK](/docs/tracking-methods/sdks/ios#group-analytics)
* [Android SDK](/docs/tracking-methods/sdks/android#group-analytics)
* [Java SDK](/docs/tracking-methods/sdks/java#group-analytics)
* [Python SDK](/docs/tracking-methods/sdks/python#group-analytics)
* [React Native SDK](/docs/tracking-methods/sdks/react-native#group-analytics)
* [Ruby SDK](/docs/tracking-methods/sdks/ruby#group-analytics)

## Add Group Key to User's Profile

Adding `<group_key>: <group_id>` to user profiles connects user profiles to group profiles. This allows you to view user group profile properties when analyzing by Users in reports; for example, when creating user cohorts based on group profile properties.

This relationship is one-way, meaning that you cannot use user profile properties when analyzing by a Group in reports.

Because a user can be part of multiple groups within a group key, set the value of the user property as a list of string values, i.e., `"company_id": ["1", "2"]`


# Lookup Tables
Source: https://docs.mixpanel.com/docs/data-structure/lookup-tables

Enrich ingested data using a CSV

This guide covers Lookup Tables and how to use them effectively. Lookup Tables are optional; if you're new to Mixpanel, we recommend starting with our guide on [Events and Properties](/docs/data-structure/events-and-properties).

## Overview

Lookup Tables let you enrich your Mixpanel properties ([event properties](/docs/data-structure/events-and-properties) or [user profile properties](/docs/data-structure/user-profiles)) with additional attributes or metadata about these properties. This is done by uploading a CSV containing a join key column and additional property columns, then mapping a Mixpanel property the join key.

* If you have a database background, lookup tables are like dimension tables or join tables.
* If you have an Excel / Google Sheets background, Lookup Tables are like VLOOKUP.

Let's say you're building a media product, and you track a `Song Played` event, which contains a `song_id` property.

| event\_name | time                | user\_id | song\_id |
| ----------- | ------------------- | -------- | -------- |
| Song Played | 2023-05-18T09:00:00 | user123  | c994bb   |
| Song Played | 2023-05-18T10:15:00 | user456  | d8d949   |
| Song Played | 2023-05-18T11:30:00 | user789  | a43fb8   |

You want to filter and breakdown this event by other attributes of the song, like `artist` and `genre`, which are not tracked as properties. Lookup Tables let you upload a CSV of data about songs like the table below and map it to the `song_id` property:

| song\_id | artist      | genre    | is\_platinum | name          | release\_date       |
| -------- | ----------- | -------- | ------------ | ------------- | ------------------- |
| c994bb   | Drake       | Pop      | True         | Hotline Bling | 2015-10-18T22:00:00 |
| d8d949   | Gipsy Kings | Flamenco | False        | Bamboleo      | 1987-07-12T05:00:00 |
| a43fb8   | Daft Punk   | House    | False        | Aerodynamic   | 2001-03-12T07:30:00 |

Then, whenever you use an event with the `song_id` property, you'll have access to all these other properties of the song as well. Under the hood, Mixpanel joins the two tables like so:

| event\_name | time                | user\_id | song\_id | Artist      | Genre    | is\_platinum | Name          | Release\_date       |
| ----------- | ------------------- | -------- | -------- | ----------- | -------- | ------------ | ------------- | ------------------- |
| Song Played | 2023-05-18T09:00:00 | user123  | c994bb   | Drake       | Pop      | True         | Hotline Bling | 2015-10-18T22:00:00 |
| Song Played | 2023-05-18T10:15:00 | user456  | d8d949   | Gipsy Kings | Flamenco | False        | Bamboleo      | 1987-07-12T05:00:00 |
| Song Played | 2023-05-18T11:30:00 | user789  | a43fb8   | Daft Punk   | House    | False        | Aerodynamic   | 2001-03-12T07:30:00 |

The benefit is that you don't need to change your tracking code at all. You can upload this Lookup Table after the fact and it automatically joins onto all prior events or user profiles with the mapped property.

We also provide an [API](/reference/replace-lookup-table) and [Warehouse Connectors](/docs/tracking-methods/data-warehouse#lookup-tables) to keep Lookup Tables synced on a recurring basis.

## Use Cases

**Media**

One possible use case for Lookup Tables is to load metadata about your content (songs, podcasts, articles) into Mixpanel. If you track some content identifier (eg: song\_id, podcast\_id, article\_id) as a property on your events, you can then upload a Lookup Table with other properties of that content, like name, category, author, or creation date. You can then use any of those properties on any events that have the ID properties.

**E-Commerce**

If you sell products online, you can load your product catalog into Mixpanel as a Lookup Table. As long as you track a product\_id or sku\_id property on your events, you'll be able to enrich those events with other properties about those products, like their name, category, and price.

**B2B**

If you have a B2B product, you likely have some key entities that are specific to your product. For example, Github has repositories, Figma has design components, Slack has channels. If they track repository\_id, component\_id, or channel\_id as properties on their events, they can use Lookup Tables to enrich those events with information about those repositories, components, and channels.

In general, it is still best to have metadata that don't change over time, and you analyze often, to be tracked as event or user properties. Do refer to the FAQ section on [When shouldn't I use Lookup Tables?](/docs/data-structure/lookup-tables#when-shouldnt-i-use-lookup-tables)

## Create a Lookup Table

A Lookup Table CSV must contain at least 2 columns; a join key column and one or more Lookup Table property columns.

The first row is the header and will serve as names for the Lookup Table properties for each column. Header names must be unique.

The CSV must be valid according to [RFC4180](https://datatracker.ietf.org/doc/html/rfc4180). See our [API reference](/reference/replace-lookup-table) for more specific details about how we parse CSVs.

**Example**

```csv theme={"system"}
song_id,artist,genre,is_platinum,name,release_date
c994bb,Drake,Pop,True,Hotline Bling,2015-10-18T22:00:00Z
d8d949,Gipsy Kings,Flamenco,False,Bamboleo,1987-07-12T05:00:00Z
a43fb8,Daft Punk,House,False,Aerodynamic,2001-03-12T07:30:00Z
```

### Join Key Column

The first column is reserved for the join key used to map to the property you choose. Each value in this column must be unique with no duplicates with no falsy values.

The first row column header is unimportant since it is reserved for the join key and can be any text as long as it is unique to all other column headers in the CSV.

Using the existing example from above, "song\_id" is the Mixpanel property being used to map additional properties, so we set the first column of the Lookup Table CSV using the column header "song\_id" (could be any other string) then add the song\_id values "c994bb", "d8d949", and "a43fb8" in each row.

### Lookup Table Property Column

<Note>
  Lookup Tables property values do not support [Objects and List of Objects](/docs/data-structure/property-reference/data-type#list-property-support) data types.
</Note>

Any additional columns to the right of the first join key column are Lookup Table property columns that contains the additional attributes or metadata that you wish to enrich your data with.

The column headers in the first row will serve as names for the Lookup Table properties for each column. This is the name value that will appear in Mixpanel when you query for your Lookup Table properties. Header names must be unique.

Under each column, add the Lookup Table property values, corresponding to the join key value of each row.

Using the existing example from above, we add the "artist", "genre", "is\_platinum", "name", and "release\_date" Lookup Property names as column headers to the right of the first join key column. Then we add values for each Lookup Table property for each join key.

## Upload a Lookup Table

<Note>
  Free plan users can upload and map a Lookup Table to an existing property locally from within a report. Growth and Enterprise plan users can also create globally persistent mappings to a Lookup Table via the Lexicon. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

### Globally using Lexicon

Lookup Tables that are uploaded globally via the Lexicon can be accessed by other project users when they build reports.

<Steps>
  <Step title="Upload your Lookup Table CSV">
    Navigate to **Lexicon**, select **Lookup Tables** from the left-hand sidebar, then click **"Import Lookup Table"** to upload a CSV file or manage existing Lookup Tables.

    <Frame>
      <img alt="image" />
    </Frame>
  </Step>

  <Step title="Map the Lookup Table to an event or user profile property">
    Once you have uploaded the CSV file for the Lookup Table, map it to an event or user profile property, which is the ID (e.g. song\_id) that the Lookup Table join key will map to. Mixpanel will assume the first column of the CSV is the ID and will join it with that property.

    <Frame>
      <img alt="image" />
    </Frame>
  </Step>
</Steps>

#### Multiple Mappings

A single Mixpanel property can only be mapped to one Lookup Table at a time in the Lexicon. For example, if you have a "first\_location" property and it is already mapped to a "City" Lookup Table, it cannot be simultaneously mapped to a "Country" Lookup Table.

If you need to map multiple Lookup Tables to a single Mixpanel property for your use case, we recommend one of the two approaches below:

1. [Locally map your Lookup Table to the property within the report](/docs/data-structure/lookup-tables#locally-within-a-report). This option allows you to have multiple local Lookup Tables across different reports, where their context and usage are only relevant to these reports.
2. Create multiple [Custom Properties](/docs/features/custom-properties) that contain the property you want to map to without any functions, then map the different Lookup Tables to each custom property in Lexicon. Since the output of these Custom Properties without functions would be identical to the property itself, the mapping will also be identical and globally accessible via the Custom Properties.

Multiple Mixpanel properties can map to the same Lookup Table. For example, if you have a "first\_location" property and a "last\_location" property, they can both be mapped to the same "City" Lookup Table.

### Locally within a Report

You can also upload Lookup Tables straight from your reports. Lookup Tables uploaded directly in reports create a local mapping that can only be used while you are in the report. This mapping is not global, and can't be used in other reports.

This feature can be useful if you need to have the Lookup Table mapping only for a specific report or if you wish to override an existing globally mapped lookup table for a property within a report.

<Steps>
  <Step title="Click the &#x22;...&#x22; button next to the breakdown property from your report and choose &#x22;Map Lookup Table&#x22;">
    This breakdown property will be used as the ID that the Lookup Table join key will map to.

    <Frame>
      <img alt="image" />
    </Frame>
  </Step>

  <Step title="Select a Lookup Table to map to the breakdown property">
    Alternatively, you may upload a new Lookup Table CSV for use locally in the report.

    <Frame>
      <img alt="image" />
    </Frame>
  </Step>
</Steps>

Lookup Tables can be replaced with a fresh copy, either via our UI, [API](/reference/replace-lookup-table), or [Warehouse Connectors](/docs/tracking-methods/data-warehouse#lookup-tables).

## Use a Lookup Table

Once a Lookup Table is mapped, you can access if by clicking on the mapped property and it will expand the columns from the Lookup Table as if they are nested properties. Lookup Table property names are derived from the header (1st row) in the CSV; these labels cannot be renamed (i.e. using a Lexicon Display Name) within the Mixpanel UI.

<Frame>
  <img alt="image" />
</Frame>

These Lookup Table properties can be used like any normal property in reports as filters or breakdowns or even in [custom properties](/docs/features/custom-properties).

<Frame>
  <img alt="image" />
</Frame>

## Limits

* Lookup Tables have a limit of **100MB** per CSV file or roughly 1M rows.
* You can use multiple lookup tables in your projects, but the total count of rows has to be less than **5 million rows** across all uploaded CSVs.
* Lookup Tables does not support Objects or List of Objects [data types](/docs/data-structure/property-reference/data-type).

## FAQ

### When should I use Lookup Tables?

A good use case for Lookup Tables are for mapping metadata that changes over time, since lookup tables can be replaced via the Mixpanel UI or programatically via [API](/reference/replace-lookup-table) or [Warehouse Connectors](/docs/tracking-methods/data-warehouse#lookup-tables), and changes are retroactive. A currency exchange rate table mapped to `Order Currency` property which can be used to convert `Order Amount`; or a region territory grouping table mapped to `Country` are good examples.

### When shouldn't I use Lookup Tables?

We don't recommend using Lookup Tables for anything with very high cardinality IDs. For properties with high cardinal IDs, we recommend that you track the metadata as event properties.

* Don't use Lookup Tables when the ID is a User ID. Instead use [User Profiles](/docs/data-structure/user-profiles). Mixpanel is more optimized for User Profiles, so they don't have any scale limits and support more opinionated workflows in our product (like clicking into a report and seeing the list of User Profiles).
* Don't use Lookup Tables as a way to mutate events. For example, it might be tempting to have an Orders lookup table, with 1 row per Order that a customer makes. Then, you can update the Orders table whenever an order is mutated (eg: when you issue a refund). This approach will quickly run into the 100MB scale limit and will make it difficult to do the analysis you need. Instead, we recommend modeling state changes as events, which doesn't have scale limits and preserves the history of state changes. Track an `Order Completed` event and an `Order Refunded` or `Order Modified` event. You can then use our funnels report to answer questions like: "what % of orders were refunded?"

### Who has access?

All users will be able to upload and map a Lookup Table to an existing property [locally from within a report](/docs/data-structure/lookup-tables#locally-within-a-report). Only users with "Admin" or "Owner" roles will be able to [make the mapping persistent in Lexicon globally](/docs/data-structure/lookup-tables#globally-using-lexicon) for other users in the project to use.

Project Owners can delete any Lookup Table in a project while Admins can only delete their own. Consumers and Analysts cannot delete lookup tables even if they own them.

Customers on the Free plan will be able to locally map a property to a Lookup Table, but not have the option of persisting the mapping.

### Where can I find the "id" of the lookup table for API's Path Params?

When replacing a lookup table using the [API](/reference/replace-lookup-table), you would need to pass the lookup table's ID as part of the URL in the API call. This `id` can be found in Lexicon under the Lookup Table's Details. See below screenshot as example:

<Frame>
  <img alt="image" />
</Frame>

### Can I map it to the \$distinct\_id property?

Mapping a Lookup Table to the `$distinct_id` property is not supported. To create a user property for a profile, upload it as a user property directly.


# Property Reference
Source: https://docs.mixpanel.com/docs/data-structure/property-reference



Take a look at any of these pages for more information about Mixpanel's properties.

<CardGroup>
  <Card title="Types of Properties" href="/docs/data-structure/property-reference/properties" />

  <Card title="Supported Data Types" href="/docs/data-structure/property-reference/data-type" />

  <Card title="Default Properties" href="/docs/data-structure/property-reference/default-properties" />

  <Card title="Reserved Properties" href="/docs/data-structure/property-reference/reserved-properties" />
</CardGroup>


# Supported Properties Data Type
Source: https://docs.mixpanel.com/docs/data-structure/property-reference/data-type



## Overview

Mixpanel supports five data types for properties: String, Numeric, Boolean, Date and List. By choosing the most suitable data type for your properties, you're able to apply a set of operators that are most relevant to your properties in Mixpanel reports, giving you richer insights into your data.

### String

* Alphanumeric value e.g. Plan Type = "Free", Artist Name = "Bruno Mars".
* String properties have a limit of 255 bytes.
* Different [character encodings](https://en.wikipedia.org/wiki/Character_encoding) require different number of bytes to represent a single character.
* Mixpanel will treat any property value that does not match any other data type as a String.

### Numeric

* Numeric (integer or decimal) value e.g. Cost = 15.00, Quantity = 5.
* You can apply operators such as sum, median and percentile on numeric properties.

### Boolean

* Mixpanel treats properties as boolean if the value is either the JSON constant `true` or `false`; e.g. Favorite = true, Bookmarked = false.
* On Mixpanel, you can typecast any non-boolean property to boolean.
* "false", 0, null, undefined, empty string and `not set` will be typecasted to boolean `false`.
* "true" and any set value that is not 0 or empty string will be typecasted to boolean `true`.

### Date

* An ISO formatted date `YYYY-MM-DDTHH:MM:SS` in UTC e.g. Last Purchase = "2022-10-30T13:30:25", Last Login = "2022-10-29". Note that all timestamps need to be sent in UTC timezone in an ISO format.
* Mixpanel treats unix timestamps as Numeric property, however, you can typecast it to Date data type.
* Timestamps are ingested with [millisecond precision](/changelogs/2022-11-07-millisecond), but exported with second precision.
* You can break down your results by the "Time" event property and breakdown by Hour, Day, Week, Month, Quarter, Year, Hour of Day, or Day of Week.

<Frame>
  <img alt="/breakdown_by_date.gif" />
</Frame>

### List

* A list of values as a JSON array e.g. Favorite Genres = `["Folk","Alternative"]` or Favorite Numbers = `[1,5,10.0]`
* Limits of a List property: Event Property = 8KB, User Profile Property = 256KB
* Each item in a list would be further limited by their data type's limits; example: a list of strings would be limited by 255 bytes per string. Also refer to [List of Objects](/docs/data-structure/property-reference/data-type#list-of-objects-property-support) covered below.
* Mixpanel lists are not ordered (i.e. position of values in a list are not significant in Mixpanel reports) and are useful for grouping or analyzing similar values across events. Read more details on [List Property Support](/docs/data-structure/property-reference/data-type#list-property-support) in reports.
* Note: Editing of list properties is not supported directly within the Mixpanel UI. To modify list properties, you must use the [Mixpanel API](/reference/profile-set) or one of our SDKs.

### Object

<Note>
  Mixpanel supports object in a limited capacity. We recommend using the five non-object data types for most use cases as they are fully supported in the UI.
</Note>

* Arbitrarily-nested groups of JSON key-value pairs e.g. Experiments = `{"Exp Onboarding":"Quick","Exp Checkout":"Without Coupon"}`
* Limits of a Object property: Event Property = 8KB, User Profile Property = 256KB, max 255 keys per nested object with a max nesting depth of 3
* Mainly supported in core reports (i.e. Insights, Funnels, Flows, Retention, Users / Cohorts, Events) as filters and breakdowns. Property Names (ie keys) within an object are not supported in Lexicon.

### List of Objects

* A JSON array of 1 level JSON objects with each object having similar sets of key-value pairs e.g. Cart = `[{"Brand":"Puma","Category":"Jacket","Price":30}, {"Brand":"Adidas","Category":"Hats","Price":15}]`
* Limits of a List of Objects: Event Property = 8KB, User Profile Property = 256KB, max 255 keys and no nesting; average list size = 50 objects
* Mainly supported in core reports (i.e. Insights, Funnels, Flows, Retention, Users / Cohorts, Events) as filters and breakdowns. Property Names (ie keys) within an object are not supported in Lexicon.

## List Property Support

List is an iterable data type, which makes them inherently different from non-iterable data types (ie: strings, numbers, time). This section highlights a few scenarios on how list properties behave within Mixpanel. The examples used here are from the Insights report, but the principles of how filter and breakdowns work with list properties remain the same across reports.

### Sample Scenario

Let's assume an e-commerce platform has these 3 events:

* Event 1: *PurchaseCompleted*

  * *List of ProductIDs* = `["P1", "P2", "P4"]`
* Event 2: *PurchaseCompleted*

  * *List of ProductIDs* = `["P2", "P3", "P4"]`
* Event 3: *PurchaseCompleted*

  * *List of ProductIDs* = `["P3", "P4"]`

Now let's assume that *"List of ProductIDs"* is mapped to a [lookup table](/docs/data-structure/lookup-tables) called *Products* which looks like this:

| ProductID | Category            | Price |
| --------- | ------------------- | ----- |
| P1        | Clothing - pants    | 100   |
| P2        | Clothing - shirt    | 54    |
| P3        | Shoes               | 109   |
| P4        | Electronics - music | 199   |

### List Breakdown

* Breakdown a list property

  * **Question:** TOTAL of *PurchaseCompleted* broken down by *"List of ProductIDs"*
  * **Answer:**

    | List of ProductIDs | Total |
    | ------------------ | ----- |
    | P1                 | 1     |
    | P2                 | 2     |
    | P3                 | 2     |
    | P4                 | 3     |
  * **What's going on here?** When breaking down, each of the list's contents is evaluated as a single item. So for example, P2 is present in Event 1 and Event 2, so the TOTAL (of the *PurchaseCompleted* event) where "P2" is present is 2.
* Breakdown by [lookup profile property](/docs/data-structure/lookup-tables) that's joined to a list property

  * **Question:** TOTAL of *PurchaseCompleted* broken down by *"List of ProductIDs"* → *Category*
  * **Answer:**

    | List of ProductIDs  | Total |
    | ------------------- | ----- |
    | Clothing - pants    | 1     |
    | Clothing - shirt    | 2     |
    | Shoes               | 2     |
    | Electronics - music | 3     |
  * **What's going on here?** When breaking down, each of the list's contents is evaluated as a single item after being mapped to the lookup table. So for example, P2 is present in Event 1 and Event 2, and P2 mapped to the lookup table which gets us *Category* = "Clothing - shirt", so the TOTAL (of *PurchaseCompleted* events) where "Clothing - shirt" is present is 2. The thing to note here is that the results are identical to when *PurchaseCompleted* was broken down by *"List of ProductDs"*, except the *ProductIDs* are replaced by *Category*.
* Breakdown by lookup profile property that's joined to a list property AND by the list property itself

  * **Question:** TOTAL of *PurchaseCompleted* broken down by *"List of ProductIDs"* → *Category* AND *"List of ProductIDs"* (2 breakdowns applied)
  * **Answer:**

    | List of ProductIDs.Category | List of ProductIDs | Total |
    | --------------------------- | ------------------ | ----- |
    | Clothing - pants            | P1                 | 1     |
    |                             | P2                 | 1     |
    |                             | P4                 | 1     |
    | Clothing - shirt            | P1                 | 1     |
    |                             | P2                 | 2     |
    |                             | P3                 | 1     |
    |                             | P4                 | 2     |
    | Shoes                       | P2                 | 1     |
    |                             | P3                 | 2     |
    |                             | P4                 | 2     |
    | Electronics - music         | P1                 | 1     |
    |                             | P2                 | 2     |
    |                             | P3                 | 2     |
    |                             | P4                 | 3     |
  * **What's going on here?** For each breakdown value, Mixpanel recomputes the list breakdown. So for example, TOTAL (*PurchaseCompleted*) with "*List of ProductIDs*" → *Category* = "Shoes" should get us Event 2 and Event 3:When these 2 events are broken down by *"List of ProductIDs"*, we get these results for "Shoes"(*ProductID* = "P3"):

    * Event 2: *PurchaseCompleted*

      * *List of ProductIDs* = `["P2", "P3", "P4"]`
    * Event 3: PurchaseCompleted

      * *List of ProductIDs* = `["P3", "P4"]`
    * P2: 1
    * P3: 2
    * P4: 2

### List Filter

When filtering using a list property, you may additionally configure whether all items in the list must match your expression and whether to return all items from a list in your analysis.

1. **Any in List:** If any item in your list matches your filter criteria, the event will be included.

   **Example:**

   * Products: \["a","b","c","d"]
   * Filter criteria: "Products" = "a", Any in List
   * Result: The event is included since at least 1 item in the Products list property is "a".
2. **All in List:** If every item in your list matches your filter criteria, the event will be included.

   **Example:**

   * Products: \["a","b","c","d"]
   * Filter criteria: "Products" = "a", All in List
   * Result: The event is not included because not all items in the Products list property is "a"
3. **Include Matching Items:** If the event matches your filter criteria and the list property is included as a breakdown, return only the matching items from the list in the results.

   **Example:**

   * Products: \["a","b","c","d"]
   * Filter criteria: "Products" = "a", Any in List, Include Matching Items
   * Result: The event is included since at least 1 item in the Products list property is "a". In the resulting report, only "a" appears as a breakdown segment.
4. **Include All Items:** If the event matches your filter criteria and the list property is included as a breakdown, return all items from the list in the results.

   **Example:**

   * Products: \["a","b","c","d"]
   * Filter criteria: "Products" = "a", Any in List, Include All Items
   * Result: The event is included since at least 1 item in the Products list property is "a". In the resulting report, "a", "b", "c", and "d" appears as a breakdown segment.

**Additional Examples:**

* Filter by any element of a list property

  * **Question:** TOTAL of *PurchaseCompleted* filtered by

    | "List of ProductIDs" | Any | = (equals) | "P1" |
    | -------------------- | --- | ---------- | ---- |
  * **Answer:** *PurchaseCompleted - TOTAL*: 1
  * **What's going on here?** The "Any" operator filters down events when the filtered value matches ANY item in the list property. So in this example, the only event in which "List of ProductIDs" has "P1" present even once is Event 1, so the total event count for this filter is 1.
* Filter by all elements of a list property

  * **Question**: TOTAL of *PurchaseCompleted* filtered by

    | "List of ProductIDs" | All | = (equals) | "P1" |
    | -------------------- | --- | ---------- | ---- |
  * **Answer:** *PurchaseCompleted - TOTAL*: 0
  * **What's going on here?** The "All" operator filters down events when the filtered value matches ALL of the items in the list property. So in this example, there is no event in which "List of ProductIDs" has all the elements equal to "P1", so the total event count for this filter is 0.
* Filter by list property and broken down by list property

  * **Question:** TOTAL of PurchaseCompleted filtered byBroken down by "List of ProductIDs"

    | "List of ProductIDs" | Any | = (equals) | "P1" |
    | -------------------- | --- | ---------- | ---- |
  * **Answer:**

    | List of ProductIDs | Total |
    | ------------------ | ----- |
    | P1                 | 1     |
    | P2                 | 1     |
    | P4                 | 1     |
  * **What is going on here?** There is only 1 event that contains "P1" (Event 1, *"List of ProductIDs"* = \["P1", "P2", "P4"]), so when that one event is broken down by *"List of ProductIDs"*, Mixpanel evaluates each list item individually, thereby getting us:

    * P1: 1 (1 event)
    * P2: 1 (1 event)
    * P4: 1 (1 event)
* Filter by lookup profile property that is joined to a list property and then broken down by list property

  * **Question:** TOTAL of *PurchaseCompleted* filtered byBroken down by "List of ProductIDs"

    | "List of ProductIDs" → Category | Any | = (equals) | "Shoes" |
    | ------------------------------- | --- | ---------- | ------- |
  * **Answer:**

    | List of ProductIDs | Total |
    | ------------------ | ----- |
    | P2                 | 1     |
    | P3                 | 2     |
    | P4                 | 2     |
  * **What is going on here?** There are 2 events that contain where the *Category* mapping for at least one of the *ProductIDs* in "*List of ProductIDs*" is equal to "Shoes" (i.e. *ProductID* = P3).When these two events are broken down by *"List of ProductIDs"*, Mixpanel evaluates each list item individually, thereby getting us:

    * Event 2: PurchaseCompleted

      * List of ProductIDs = \["P2", "P3", "P4"]
    * Event 3: PurchaseCompleted

      * List of ProductIDs = \["P3", "P4"]
    * P2: 1 (1 event)
    * P3: 2(2 events)
    * P4: 2 (2 events)
* Filter by lookup profile property that is joined to a list property (with multiple matching values) and then broken down by list property

  * **Question**: TOTAL of *PurchaseCompleted* filtered byBroken down by "List of ProductIDs"

    | "List of ProductIDs" → Category | Any | ∋ (contains) | "Clothing" |
    | ------------------------------- | --- | ------------ | ---------- |
  * **Answer:**

    | List of ProductIDs | Total |
    | ------------------ | ----- |
    | P1                 | 1     |
    | P2                 | 2     |
    | P3                 | 1     |
    | P4                 | 2     |
  * **What is going on here?** This filter can be read as "for any of the items in *'List of ProductIDs'* , the lookup property *Category* contains the string 'Clothing'". This operation is filtering down to all the events that contain the *Category* mapping for the *ProductID* contains EITHER "Clothing - pants" or "Clothing - shirt", and that gives us 2 events:

    * Event 1: PurchaseCompleted

      * List of ProductIDs \["P1","P2","P4"]
    * Event 2: PurchaseCompleted

      * List of ProductIDs \["P2","P3","P4"]
  * Therefore, when those two events are broken down by "List of ProductIDs", Mixpanel evaluates each item of the list individually and we end up getting:

    * P1: 1
    * P2: 2
    * P3: 1
    * P4: 2
* Filter by lookup profile property that is joined to a list property (numeric filter) and then broken down by list property

  * **Question**: TOTAL of *PurchaseCompleted* filtered byBroken down by *"List of ProductIDs"*

    | "List of ProductIDs" → Price (number) | Any | \< (less than) | 100 |
    | ------------------------------------- | --- | -------------- | --- |
  * **Answer:**

    | List of ProductIDs | Total |
    | ------------------ | ----- |
    | P1                 | 1     |
    | P2                 | 2     |
    | P3                 | 1     |
    | P4                 | 2     |
  * **What is going on here?** The filter can be read as "for any item in *'List of ProductIDs',* the lookup property *Price* is less than 100" and it only matches 1 product, and that is P2. Therefore, what this operation is doing is filtering down to all the events that contain P2 as ANY of the values in "List of ProductDs", and that gives us 2 events:Therefore, when those two events are broken down by *"List of ProductIDs"*, Mixpanel evaluates each item of the list individually and we end up getting:

    * Event 1: *PurchaseCompleted*

      * *List of ProductIDs* = \["P1", "P2", "P4"]
    * Event 2: PurchaseCompleted

      * *List of ProductIDs* = \["P2", "P3", "P4"]
    * P1: 1
    * P2: 2
    * P3: 1
    * P4: 2

## List of Objects Property Support

List of objects is a List property where all items contained are Objects. List of objects are generally useful when tracking a list of complex things. Some examples:

* items in a cart
* search results
* images in a slideshow

In each case, the object will have multiple properties, such as "price" and "brand" for items in a cart.

```json theme={"system"}
"event": "Product Added",
"properties": {
    "cart": [
        {
            "brand": "Puma",
            "category": "Jacket",
            "price": 30
        },
        {
            "brand": "Adidas",
            "category": "Hats",
            "price": 15
        }
    ]
}
```

### Breakdown and Filter

List of objects can be used like other properties in Mixpanel. Upon selecting a list of objects property, you will be prompted to select another property common to the objects in the list. Usage in measurements, filters, and breakdowns follows the same behavior as other [list properties](/docs/data-structure/property-reference/data-type#list-property-support).

### Property Computation

We provide a few convenient property computation after a list of objects property is selected. This does a computation on the property, and works similarly to [custom properties](/docs/features/custom-properties).

<Frame>
  <img alt="list computed properties" />
</Frame>

#### Size

The size, or length of the list as a numeric property.

#### Sum

Prompts a selection of a numeric property contained within the objects of the list. This will give the total for the whole list for that property.

#### Distinct Count

Prompts a selection of a property contained within the objects of the list. This will give the number of unique values for that property in the list.

## Falsy Values

### Undefined and Null

**Undefined**

Undefined values are seen when one or more of the events being measured in a query do not contain the property used for breakdown. For example, building a report using Page View events broken down by a campaign ID property would Page Views with a set campaign ID property by their value, and group events without a set Campaign ID property to undefined. Undefined values are parsed as `(not set)` in the UI.

There are several reasons why you might see "undefined" values throughout Mixpanel reports when segmenting:

* \*\*\*The specific property you are segmenting by is not always sent along with the event you are analyzing. \*\*\*For example, let’s say you are segmenting the event “App Open” by the property “Account type” If there are instances where App Open fires without the Account type property getting sent with it, these will be categorized as “undefined” when you segment by Account type. Another common example is UTM parameters - “undefined” represents users who fired an event without any UTM in the URL that brought the user to your site.
* When segmenting an event by a User Profile property, ***you’ll see “undefined” if there are User Profile profiles that do not contain that property or if the event was triggered by a user without a User Profile at all.*** For example, let’s say you’re segmenting the event “Song Play” by the User Profile property “Favorite Genre.” If there are profiles that have triggered Song Play but don’t have the Favorite Genre property, that value will be “undefined.” Triggers of Song Play by users without a User Profile will also show up under “undefined.”
* ***For geolocation data (City, Region, Country), the user’s IP could not be mapped to a location, or their IP was not included with the request.*** For JavaScript implementations, City, Region, and Country are [default properties](/docs/data-structure/property-reference/default-properties). However, if the IP address of the user is not in Mixpanel’s geolocation database and can’t be mapped to a city, region, or country, they will be “undefined” in reports. For server-side implementations, City, Region, and Country can be “undefined” if the IP address is not included with the request. [Read more about how Mixpanel maps IP to location.](/docs/tracking-best-practices/geolocation)

**Null**

[Null values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null) represents the intentional absence of any object value. Unlike undefined values, null values are usually explicitly defined as a value of a property. Null values are parsed as `(not set)` in the UI, but will appear as `<null>` or `null` when looking at raw data.

#### Remove “undefined” & "null" values from reports

If you do not want to see “undefined” or "null" values in your report, you can remove them by:

1. Unchecking the “undefined/null” box in the visualization legend.
2. Looking only at instances where the property in question “is set" - this will exclude values where you see "undefined" or "null":

<Frame>
  <img alt="image" />
</Frame>

3. Directly exclude undefined or null values from an Insights visualization by hitting the exclude action:

<Frame>
  <img alt="image" />
</Frame>

### Empty String

Empty string refers to a string with a length of zeros, meaning there are no characters or symbols. This happens when a property is sent with a value of `""`. Empty string are parsed as `(empty string)` in the UI.


# Default Properties
Source: https://docs.mixpanel.com/docs/data-structure/property-reference/default-properties

Automatically collected properties

Mixpanel's [Data Ingestion APIs](/reference/ingestion-api) and [Client-Side SDKs](/docs/tracking-methods/choosing-the-right-method#client-side-tracking) automatically collect certain properties on every event or user profile. Do also note that some Customer Data Platforms (CDPs) that integrate with Mixpanel may also map their own properties to Mixpanel default properties. This document describes what those properties mean.

## Ingestion APIs

Mixpanel’s ingestion APIs can collect user geolocation data (City, Region, Country) as properties if IP address is present. Our client-side SDKs by default pull the user’s IP address when sending data to our ingestion APIs. The IP address is then cross-referenced against a local copy of MaxMind’s ([third-party IP geolocator](https://www.maxmind.com/en/home)) GeoIP database to estimate geolocation data. Mixpanel does not store the IP address and is discarded once geolocation data is derived.

To disable capturing of geolocation properties (i.e. City, Region, Country) refer to the respective SDKs or API documentation. For a quick reference, refer to examples on [disabling geolocation on client-side SDKs](/docs/privacy/protecting-user-data#disabling-geolocation) and [server-side best practice on tracking geolocation](/docs/best-practices/server-side-best-practices#tracking-geolocation-server-side). Note that there is currently no means to selectively disable one or two of the three geolocation properties.

### Event Properties

| **Raw Name**             | **Display Name**     | **Description**                                                                                                                                                                                                                                                             |
| ------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \$city                   | City                 | The city of the event sender parsed from the IP property or the Latitude and Longitude properties.                                                                                                                                                                          |
| \$region                 | Region               | The region (state or province) of the event sender parsed from the IP property or the Latitude and Longitude properties.                                                                                                                                                    |
| mp\_country\_code        | Country              | The country of the event sender parsed from the IP property or the Latitude and Longitude properties. The value is stored as a 2-letter country code in the raw data and parsed into the country name in the UI.                                                            |
| \$mp\_api\_endpoint      | API Endpoint         | Mixpanel property to record the API endpoint the data was sent to: <br /> **api.mixpanel.com** - default ingestion <br /> **api-eu.mixpanel.com** - EU data ingestion <br /> **api-in.mixpanel.com** - India data ingestion <br /> **api-js.mixpanel.com** - Javascript SDK |
| \$import                 | Import               | Internal Mixpanel property set to `true` to indicate that events were sent through [/import API](/reference/import-events).                                                                                                                                                 |
| \$mp\_api\_timestamp\_ms | API Timestamp        | UTC timestamp in milliseconds when the event was received by our API.                                                                                                                                                                                                       |
| mp\_processing\_time\_ms | Time Processed (UTC) | UTC timestamp in milliseconds when the event was processed by Mixpanel servers.                                                                                                                                                                                             |
| \$mp\_event\_size        | Event Size           | The size, in bytes, of the event ingested before transformation.                                                                                                                                                                                                            |

### User Properties

Do note that Mixpanel's default user properties are only updated when you send or update at least one property yourself (via [\$set](/reference/profile-set) or [\$set\_once](/reference/profile-set-property-once) operations). Please, refer to this article to [understand how to send or update profile properties](/docs/data-structure/user-profiles).

| **Raw Name**    | **Display Name** | **Description**                                                                                                                                                                                                                                                                                    |
| --------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \$city          | City             | The city of the user parsed from the IP property or the Latitude and Longitude properties.                                                                                                                                                                                                         |
| \$region        | Region           | The region (state or province) of the user parsed from the IP property or the Latitude and Longitude properties.                                                                                                                                                                                   |
| \$country\_code | Country Code     | The country of the user parsed from the IP property or the Latitude and Longitude properties. The value is stored as a 2-letter country code in the raw data and parsed into the country name in the UI.                                                                                           |
| \$geo\_source   | Geo Source       | Set to "reverse\_geocoding" if profile geolocation properties (Country Code, Region, and City) were determined through [Latitude and Longitude](/docs/best-practices/server-side-best-practices#tracking-geolocation-latitude-and-longitude).                                                      |
| \$timezone      | Timezone         | Timezone of the user parsed from the IP property or the Latitude and Longitude properties.                                                                                                                                                                                                         |
| \$last\_seen    | Updated at       | The last time a user profile property was set or updated **(this should not be set manually)**. Passing `$ignore_time` as `true`, typically for server-side updates, will skip updating the \$last\_seen property. See example [here](/docs/tracking-methods/sdks/php#setting-profile-properties). |

## Client-side SDKs

Note that the following SDKs wrap around our other SDKs; and as such, would also inherit the appropriate default properties from these wrapped SDKs indicated in the tables below:

* [React Native](/docs/tracking-methods/sdks/react-native) wraps around Android and Swift SDK; `mp_lib` will be set to `react-native` with `$lib_version` set as React Native's library version.
* [Flutter](/docs/tracking-methods/sdks/flutter) wraps around Javascript, Android, and Swift SDK; `mp_lib` will be set to `flutter` with `$lib_version` set as the Flutter's library version.

### Event Properties

| **Raw Name**                   | **Display Name**         | **Description** <br /> *Scroll right to see more columns -->*                                                                                                                                                                                                                                             | [**Javascript**](/docs/tracking-methods/sdks/javascript) | [**Android**](/docs/tracking-methods/sdks/android) | **iOS [Objective-C](/docs/tracking-methods/sdks/ios) / [Swift](/docs/tracking-methods/sdks/swift)** | [**Unity**](/docs/tracking-methods/sdks/unity) |
| ------------------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------: | :------------------------------------------------: | :-------------------------------------------------------------------------------------------------: | :--------------------------------------------: |
| \$device\_id                   | Device ID                | Autogenerated ID that is local to the device. Calling reset() regenerates this value. More details [here](/docs/tracking-methods/id-management/identifying-users-simplified).                                                                                                                             |                             ✅                            |                          ✅                         |                                                  ✅                                                  |                        ❌                       |
| \$user\_id                     | User ID                  | The identified ID of the user. Calling identify() sets this. More details [here](/docs/tracking-methods/id-management/identifying-users-simplified).                                                                                                                                                      |                             ✅                            |                          ✅                         |                                                  ✅                                                  |                        ❌                       |
| \$insert\_id                   | Insert ID                | A unique identifier for the event, used to deduplicate events that are accidentally sent multiple times. More details [here](/reference/import-events#propertiesinsert_id).                                                                                                                               |                             ✅                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |
| mp\_lib                        | Mixpanel Library         | The Mixpanel library that sent the event.                                                                                                                                                                                                                                                                 |                           `web`                          |                      `android`                     |                                          `iphone` / `swift`                                         |                     `unity`                    |
| \$lib\_version                 | Library Version          | Mixpanel library version.                                                                                                                                                                                                                                                                                 |                             ✅                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |
| mp\_sent\_by\_lib\_version     | Sent By Library Version  | Mixpanel library version used to send data (not necessarily the same as the version which enqueued the data).                                                                                                                                                                                             |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$os                           | Operating System         | OS of the event sender.                                                                                                                                                                                                                                                                                   |                             ✅                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |
| \$os\_version                  | OS Version               | The current version of operating system on the device.                                                                                                                                                                                                                                                    |                             ❌                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |
| \$browser                      | Browser                  | Name of the browser.                                                                                                                                                                                                                                                                                      |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$browser\_version             | Browser Version          | Version of the browser.                                                                                                                                                                                                                                                                                   |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$app\_build\_number           | App Build Number         | General build of the app.                                                                                                                                                                                                                                                                                 |                             ❌                            |                          ✅                         |                                                  ✅                                                  |                        ❌                       |
| \$app\_version\_string         | App Version              | Current app version.                                                                                                                                                                                                                                                                                      |                             ❌                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |
| \$device                       | Device                   | Name of the event sender’s device, if they’re on mobile web.                                                                                                                                                                                                                                              |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ✅                       |
| \$screen\_height               | Screen Height            | The height of the device screen in pixels / points (iOS).                                                                                                                                                                                                                                                 |                             ✅                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |
| \$screen\_width                | Screen Width             | The width of the device screen in pixels / points (iOS).                                                                                                                                                                                                                                                  |                             ✅                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |
| \$screen\_dpi                  | Screen DPI               | Pixel density of the device screen.                                                                                                                                                                                                                                                                       |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ✅                       |
| \$current\_url                 | Current URL              | The URL of the page on which the event was tracked.                                                                                                                                                                                                                                                       |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$initial\_referrer            | Initial Referrer         | Referring URL when the user first arrived on your site. Defaults to "\$direct" if the user is not referred.                                                                                                                                                                                               |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$initial\_referring\_domain   | Initial Referring Domain | Referring domain at first arrival. Defaults to "\$direct" if the user is not referred.                                                                                                                                                                                                                    |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$referrer                     | Referrer                 | Referring URL including your own domain. Might not be present if document.referrer does not return a value. As opposed to \$initial\_referrer and \$initial\_referring\_domain, this property will be omitted if the user lands directly or the referring website adds the rel="noreferrer" parameter.    |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$referring\_domain            | Referring Domain         | Referring domain including your own domain. Might not be present if document.referrer does not return a value. As opposed to \$initial\_referrer and \$initial\_referring\_domain, this property will be omitted if the user lands directly or the referring website adds the rel="noreferrer" parameter. |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$search\_engine               | Search Engine            | The search engine that the customer used when they arrived at your domain.                                                                                                                                                                                                                                |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| mp\_keyword                    | Search Keyword           | Search keywords detected on the referrer from a search engine to your domain. This property is only collected when search keywords are included in a URL.                                                                                                                                                 |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| utm\_source, utm\_medium, etc. | UTM Parameters           | UTM tags derived from the URL a customer clicked to arrive at your domain. Each UTM will be collected under its own property. More details [here](/docs/tracking-methods/sdks/javascript#tracking-utm-parameters).                                                                                        |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$manufacturer                 | Manufacturer             | Device manufacturer.                                                                                                                                                                                                                                                                                      |                             ❌                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |
| \$brand                        | Brand                    | Device brand.                                                                                                                                                                                                                                                                                             |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ❌                       |
| \$model                        | Model                    | The model of the device.                                                                                                                                                                                                                                                                                  |                             ❌                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |
| \$watch\_model                 | Watch Model              | The model of the iOS watch.                                                                                                                                                                                                                                                                               |                             ❌                            |                          ❌                         |                                                  ✅                                                  |                        ❌                       |
| \$carrier                      | Carrier                  | Wireless carrier of the device owner.                                                                                                                                                                                                                                                                     |                             ❌                            |                          ✅                         |                                                  ✅                                                  |                        ❌                       |
| \$radio                        | Radio                    | Current [cellular network communication standard](https://www.objc.io/issues/5-ios7/iOS7-hidden-gems-and-workarounds/#know-your-radio)(opens in a new tab) (3G, 4G, LTE, etc).                                                                                                                            |                             ❌                            |                          ❌                         |                                                  ✅                                                  |                        ✅                       |
| \$wifi                         | Wifi                     | Set to true if the user’s device has an active, available Wifi connection, false if not.                                                                                                                                                                                                                  |                             ❌                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |
| \$bluetooth\_enabled           | Bluetooth                | Set to true if Bluetooth is enabled, false if not.                                                                                                                                                                                                                                                        |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ❌                       |
| \$bluetooth\_version           | Bluetooth Version        | Set to "none", "ble", or "classic".                                                                                                                                                                                                                                                                       |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ❌                       |
| \$has\_nfc                     | Has NFC                  | The device supports Near Field Communication(NFC). Set to true if the device hardware supports NFC, false if not.                                                                                                                                                                                         |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ❌                       |
| \$has\_telephone               | Has Telephone            | Set to true if this device has telephone functionality, false if not.                                                                                                                                                                                                                                     |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ❌                       |
| \$google\_play\_services       | Google Play Services     | Verifies that Google Play services is installed and enabled on this device, and that the version installed on this device is no older than the one required by this client.                                                                                                                               |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ❌                       |
| \$duration                     | Duration                 | A property that is appended to an event to capture the elapsed time (in seconds) between a `time_event` and a `track` call. See [time\_event](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneltime_event) in Javascript SDK for example.       |                             ✅                            |                          ✅                         |                                                  ✅                                                  |                        ✅                       |

### User Properties

Do note that Mixpanel's default user properties are only updated when you send or update at least one property yourself (via [\$set](/reference/profile-set) or [\$set\_once](/reference/profile-set-property-once) operations). Please, refer to this article to [understand how to send or update profile properties](/docs/data-structure/user-profiles).

| **Raw Name**                                     | **Display Name**         | **Description**  <br /> *Scroll right to see more columns -->*                                                                                                                                                                     | [**Javascript**](/docs/tracking-methods/sdks/javascript) | [**Android**](/docs/tracking-methods/sdks/android) | **iOS [Objective-C](/docs/tracking-methods/sdks/ios) / [Swift](/docs/tracking-methods/sdks/swift)** | [**Unity**](/docs/tracking-methods/sdks/unity) |
| ------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------: | :------------------------------------------------: | :-------------------------------------------------------------------------------------------------: | :--------------------------------------------: |
| \$lib\_version                                   | Library Version          | Last used Mixpanel library version (also applies to React Native and Flutter wrapper SDKs).                                                                                                                                        |                             ❌                            |                          ❌                         |                                                  ❌                                                  |                        ✅                       |
| \$android\_lib\_version                          | Android Lib Version      | Last used Mixpanel Android / Unity library version.                                                                                                                                                                                |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ✅                       |
| \$ios\_lib\_version                              | iOS Lib Version          | Last used Mixpanel iOS / Unity library version.                                                                                                                                                                                    |                             ❌                            |                          ❌                         |                                                  ✅                                                  |                        ✅                       |
| \$swift\_lib\_version                            | Swift Lib Version        | Last used Mixpanel Swift library version.                                                                                                                                                                                          |                             ❌                            |                          ❌                         |                                                  ✅                                                  |                        ❌                       |
| \$os                                             | Operating System         | Last OS of the event sender.                                                                                                                                                                                                       |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ✅                       |
| \$android\_os                                    | Android OS               | Set when Android operating system was used.                                                                                                                                                                                        |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ✅                       |
| \$android\_os\_version                           | Android OS Version       | Last version of Android on the device.                                                                                                                                                                                             |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ✅                       |
| \$ios\_version                                   | iOS Version              | Last version of iOS on the device.                                                                                                                                                                                                 |                             ❌                            |                          ❌                         |                                                  ✅                                                  |                        ✅                       |
| \$browser                                        | Browser                  | Name of the browser.                                                                                                                                                                                                               |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$browser\_version                               | Browser Version          | Version of the browser.                                                                                                                                                                                                            |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$android\_app\_version                          | Android App Version      | Current Android app version ([versionName](https://developer.android.com/studio/publish/versioning)).                                                                                                                              |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ✅                       |
| \$android\_app\_version\_code                    | Android App Version Code | Current Android app version code ([versionCode](https://developer.android.com/studio/publish/versioning)).                                                                                                                         |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ❌                       |
| \$ios\_app\_release                              | iOS App Release          | The release or version number of the iOS app ([CFBundleShortVersionString](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleshortversionstring)).                                       |                             ❌                            |                          ❌                         |                                                  ✅                                                  |                        ✅                       |
| \$ios\_app\_version                              | iOS App Version          | The version of the build that identifies an iteration of the iOS app ([CFBundleVersion](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleversion)).                                     |                             ❌                            |                          ❌                         |                                                  ✅                                                  |                        ❌                       |
| \$initial\_referrer                              | Initial Referrer         | Referring URL when the user first arrived on your site. Defaults to "\$direct" if the user is not referred.                                                                                                                        |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$initial\_referring\_domain                     | Initial Referring Domain | Referring domain at first arrival. Defaults to "\$direct" if the user is not referred.                                                                                                                                             |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| initial\_utm\_source, initial\_utm\_medium, etc. | Initial UTM Parameters   | UTM tags seen for the first time from the URL a customer clicked to arrive at your domain. Each UTM will be collected under its own property. More details [here](/docs/tracking-methods/sdks/javascript#tracking-utm-parameters). |                             ✅                            |                          ❌                         |                                                  ❌                                                  |                        ❌                       |
| \$android\_manufacturer                          | Android Manufacturer     | Android device manufacturer.                                                                                                                                                                                                       |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ❌                       |
| \$android\_brand                                 | Android Brand            | Android device brand.                                                                                                                                                                                                              |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ❌                       |
| \$android\_model                                 | Android Model            | The model of the Android device.                                                                                                                                                                                                   |                             ❌                            |                          ✅                         |                                                  ❌                                                  |                        ✅                       |
| \$ios\_device\_model                             | iOS Device Model         | The model of the iOS device.                                                                                                                                                                                                       |                             ❌                            |                          ❌                         |                                                  ✅                                                  |                        ✅                       |


# Types of Properties in Mixpanel
Source: https://docs.mixpanel.com/docs/data-structure/property-reference/properties



## Overview

Properties are attributes that help you define the specifics of an **Event**, a **User**, or a **Group**.

Mixpanel has many Properties defined in its Data Model.

| **Property Type**                                                                  | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Event Properties](/docs/data-structure/events-and-properties)                     | Event Properties describes the events that are tracked within your product.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [Super Properties](/docs/tracking-methods/sdks/javascript#super-properties)        | Super Properties are a logical term for global Event Properties that, after registration, are saved into the end user's device, and appended to every event from that device until persistence is cleared. This logical term is mostly applicable to our client-side libraries.                                                                                                                                                                                                                             |
| [User Profile Properties](/docs/data-structure/user-profiles)                      | User Profile Properties describe your users (they typically store current demographic information). User profiles are joined to events based on [Distinct ID](/docs/tracking-methods/id-management/identifying-users-simplified#what-is-distinct-id).                                                                                                                                                                                                                                                       |
| [Group Profile Properties](/docs/data-structure/group-analytics#group-profiles)    | Group Profile Properties describe group level information (similar to User Profiles Properties at user level). With Mixpanel’s [Group Analytics](/docs/data-structure/advanced/group-analytics), multiple users can be grouped and behavioral data analyzed at a customized group level (such as company, account). Group profiles are joined to events on your chosen [Group Key](/docs/data-structure/advanced/group-analytics#group-keys-tracked-as-event-properties).                                   |
| [Lookup Tables](/docs/data-structure/lookup-tables)                                | Lookup Tables allow you to dynamically extend additional properties mapped to an existing Event or User Property. For example, if you create a lookup table for "Songs" (that contains additional properties like `hash_tags`, `top_10`, `all_time_favorite`) and map it to an event property `song_id`; you can use these additional properties when doing filtering or breakdowns for events that has `song_id` as an event property.                                                                     |
| [Default Properties](/docs/data-structure/property-reference/default-properties)   | Default Properties (for Events and User Profiles) are collected and populated with values automatically in Mixpanel. This can happen upon data ingestion or when using certain Mixpanel client-side SDKs. Typically, they have a dollar sign (\$) or “mp\_” as prefix to distinguish them from normal properties.                                                                                                                                                                                           |
| [Reserved Properties](/docs/data-structure/property-reference/reserved-properties) | Mixpanel reserves certain property names (for [Events](/docs/data-structure/events-and-properties#reserved-event-properties) and [User Profiles](/docs/data-structure/user-profiles#reserved-user-properties)) for special use cases, and these may or may not be automatically populated with values. The purpose of such Reserved Properties are for processing (ie event time stamping) or for specific system features (eg: cohort exports). Examples: `time`, `$email`, `$phone`, `$name`, `$created`. |


# Reserved Properties
Source: https://docs.mixpanel.com/docs/data-structure/property-reference/reserved-properties

Properties used for system features

Mixpanel reserves certain property names for special processing or for specific system features. These properties, when populated, will affect the way Mixpanel processes your data.

## Reserved Profile Properties

> **Note:** Also refer to the list of Mixpanel [Default Properties](/docs/data-structure/property-reference/default-properties) indicated in our documentation.

| **Raw Name**                                      | **Display Name**                          | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| \$distinct\_id                                    | Distinct ID                               | Mixpanel's internal unique identifier for a profile. See [Identifying Users](/docs/tracking-methods/id-management/identifying-users) and [Group Profiles](/docs/data-structure/advanced/group-analytics#group-profiles)                                                                                                                                                                                                                                                        |
| \$name, <br /> \$first\_name, <br /> \$last\_name | Name, <br /> First Name, <br /> Last Name | The user's / group's general name, as well as, first and last names. These are primarily useful because they are used, if available, in various Mixpanel UI / reports. For user [Cohort Syncs](/docs/cohort-sync), only `$first_name` and `$last_name` is exported.                                                                                                                                                                                                            |
| \$email                                           | Email                                     | The user's / group's email address. You must set this property if you want to send emails to users via partners receiving cohorts from our [Cohort Syncs](/docs/cohort-sync).                                                                                                                                                                                                                                                                                                  |
| \$phone                                           | Phone                                     | The user's / group's phone number. You must set this property if you want to send SMS to users via partners receiving cohorts from our [Cohort Syncs](/docs/cohort-sync). Note that a '+' needs to precede international phone numbers. If the user does not import a phone number with the '+' sign in front, the country code will be prefixed to the front of the number based on the \$country\_code default property, resulting in a phone number with two country codes. |
| \$avatar                                          | Avatar URL                                | Set this property to a URL resource of a gif, jpg, jpeg, or png to update the profile picture in a profile. This property will override a profile picture pulled from [Gravatar](https://gravatar.com/).                                                                                                                                                                                                                                                                       |
| \$created                                         | Created                                   | The time that the profile was created. Note that this is not auto-populated.                                                                                                                                                                                                                                                                                                                                                                                                   |
| \$mp\_first\_event\_time                          | First Seen                                | Mixpanel calculated property that represents the time of the user's (or group's) very first event in Mixpanel. This can be used to filter/segment reports by users (or groups) who were "new" in a particular timeframe.                                                                                                                                                                                                                                                       |

## Reserved Event Properties

> **Note:** Also refer to the list of Mixpanel [Default Properties](/docs/data-structure/property-reference/default-properties) indicated in our documentation.

| **Raw Name**                     | **Display Name**              | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token                            | -                             | The project's token when sending data via [/track API](/reference/track-event). Not visible via Mixpanel UI reports.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ip                               | -                             | The `ip` event property is the value to be used for [geo-location parsing](/docs/tracking-best-practices/geolocation) (i.e. `$city`, `$region`, and `mp_country_code`) if `ip` as param to the [/track endpoint](/reference/track-event) has **not been** set to 1. Our client-side libraries, by default, will set the `ip` param to 1 so geo location is parsed from the incoming request, but this can be disabled or, if you're implementing from the [server-side](/docs/best-practices/server-side-best-practices#tracking-geolocation-server-side), you can include the `ip` event property so it's parsed from it instead of the IP of the incoming request. The `ip` event property is not stored in Mixpanel. |
| \$bucket / bucket                | -                             | A reserved property that is hidden from the Mixpanel interface, and will cause other events to not appear in the interface. Do not name any property bucket or \$bucket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| \$distinct\_id / distinct\_id    | Distinct ID                   | Mixpanel's internal unique identifier for a user. See [Identifying Users](/docs/tracking-methods/id-management/identifying-users).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| \$device\_id                     | Device ID                     | In [Simplified ID Merge](/docs/tracking-methods/id-management/identifying-users#example-user-flows): unique identifier used to track a device while the user is in anonymous state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| \$user\_id                       | User ID                       | In [Simplified ID Merge](/docs/tracking-methods/id-management/identifying-users#example-user-flows): unique identifier used to track a user across devices when user is in identified state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| \$event\_name                    | Event Name                    | Name of the tracked event used in the Mixpanel UI.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| \$time / time                    | Time or Date                  | A unix time epoch that is used to determine the time of an event. If no time property is provided, we will use the time when the event arrives at our servers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| \$insert\_id                     | Insert ID                     | A unique identifier for the event, used to deduplicate events that are accidentally sent multiple times. More details [here](/reference/import-events#propertiesinsert_id).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| \$identified\_id                 | Identified ID                 | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the identifier passed into the [`$identify`](/reference/create-identity) event.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| \$ignore                         | n/a                           | When this property is present on an event, the ingestion API silently drops it, preventing it from entering your dataset. This is helpful for [filtering out unwanted traffic](/docs/tracking-best-practices/bot-traffic).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| \$anon\_id                       | Anonymous ID                  | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the anonymous ID passed into the [`$identify`](/reference/create-identity) event.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| alias                            | Alias                         | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the alias passed into the [`$create_alias`](/reference/identity-create-alias) event.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| \$distinct\_ids                  | Distinct Ids                  | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the distinct IDs passed into the [`$merge`](/reference/identity-merge) event.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| \$distinct\_id\_before\_identity | Distinct ID Before Identity   | Internal Mixpanel property to track an event's original \$distinct\_id before it was updated due to identity merging. Used in [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge) and [Simplified ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#understanding-simplified-id-merge).                                                                                                                                                                                                                                                                                                                         |
| \$is\_reshuffled                 | Is Reshuffled                 | Internal Mixpanel property to denote an event was reshuffled (sets to true if original \$distinct\_id was updated) due to identity merging. Used in [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge) and [Simplified ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#understanding-simplified-id-merge).                                                                                                                                                                                                                                                                                                   |
| \$failure\_description           | Failure Description           | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Mixpanel property explaining in detail why identity merging was not executed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| \$failure\_reason                | Failure Reason                | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Mixpanel property summarizing why identity merging was not executed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| \$identity\_failure\_reason      | Identity Failure Reason       | In [Simplified ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#understanding-simplified-id-merge): Mixpanel property summarizing why identity merging was not executed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| mp\_original\_distinct\_id       | Hotshard Original Distinct ID | Original \$distinct\_id for an event that was identified as contributing to a [hot shard](/docs/debugging/distinct-id-limits#what-is-a-hot-shard).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| mp\_original\_event\_name        | Hotshard Original Event Name  | Original \$event\_name for an event that was identified as contributing to [hot shard](/docs/debugging/distinct-id-limits#what-is-a-hot-shard).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| \$source                         | Source                        | Hidden property used by certain integration partners to denote events were sent by them. Refer to the respective partners under [Cohort Sync -> Integrations](/docs/cohort-sync/integrations/airship).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| \$partner\_id                    | Partner Id                    | Hidden property used by certain integration partners to denote events were sent by them. Refer to the respective partners under [Cohort Sync -> Integrations](/docs/cohort-sync/integrations/airship).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| \$warehouse\_type                | Warehouse Type                | The type of the warehouse sync setup to send the event. See [Supported Warehouses](/docs/tracking-methods/warehouse-connectors#getting-started).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| \$warehouse\_import\_id          | Warehouse Import ID           | The ID of the warehouse sync setup to send this event. See [Data Warehouse](/docs/tracking-methods/warehouse-connectors).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| \$warehouse\_import\_job\_id     | Warehouse Import Job ID       | The internal Mixpanel Job ID of the warehouse sync setup to send this event. See [Data Warehouse](/docs/tracking-methods/warehouse-connectors).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| \$warehouse\_import\_run\_id     | Warehouse Import Run ID       | The internal Mixpanel Run ID of the warehouse sync setup to send this event. See [Data Warehouse](/docs/tracking-methods/warehouse-connectors).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| \$warehouse\_table               | Warehouse Table               | The name of a table (or view) in the warehouse where the event came from; useful for understanding row-level lineage of any event. See [Data Warehouse](/docs/tracking-methods/warehouse-connectors).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| \$duration\_s                    | Session Duration (Seconds)    | The duration between Session Start and Session End events in seconds. See [How Sessions Work](/docs/features/sessions#how-sessions-work).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| \$event\_count                   | Session Event Count           | The number of events during a session (i.e. Session Start and Session End). This does not include [Excluded Events](/docs/features/sessions#excluded-events) and [Hidden Events](/docs/data-governance/lexicon#hide-events-and-properties) in Lexicon. See [How Sessions Work](/docs/features/sessions#how-sessions-work).                                                                                                                                                                                                                                                                                                                                                                                              |
| \$origin\_start                  | Session Start Event Name      | The original event name that triggered Session Start event. See [How Sessions Work](/docs/features/sessions#how-sessions-work).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| \$origin\_end                    | Session End Event Name        | The original event name that triggered Session End event. See [How Sessions Work](/docs/features/sessions#how-sessions-work).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| \$mp\_experiment\_name           | Mp Experiment Name            | Internal Mixpanel property used to track the experiment name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |


# User Profile
Source: https://docs.mixpanel.com/docs/data-structure/user-profiles

Demographic attributes for your users

<Note>
  **Note:** The following terms are used in this section:

  * "Profiles" is used to refer to both "User Profiles" and "Group Profiles"
  * "Profile Properties" is used to refer to both "User Profile Properties" and "Group Profile Properties"
</Note>

## Overview

User Profiles let you enrich events with demographic attributes (i.e. user properties) about the users that performed those events. User Profiles are optional. We recommend starting with events and adding user profiles only if needed.

A user profile has a set of user properties associated with a given user. Under the hood, Mixpanel stores user data for your project in a table wherein each row of user profile contain columns of user properties (e.g. Name, Email, Department) that can be updated:

| **Distinct ID** | **Name** | **Email**          | **Department** |
| --------------- | -------- | ------------------ | -------------- |
| 123             | Alice    | `alice@linear.app` | Engineering    |
| 456             | Bob      | `bob@notion.so`    | Product        |
| 789             | Carol    | `carol@figma.com`  | Design         |

User profiles are joined onto your events based on their [**Distinct ID**](/docs/tracking-methods/id-management/identifying-users#what-is-distinct-id) (Mixpanel's identifier for a user). This lets you join the events performed by a user with user properties describing them. Thus, it is very important that you use the same Distinct ID for both the events and user profile for the same user.

For more information about user profiles refer to the documentation on [The Mixpanel Data Model](/guides/strategic-playbooks/onboarding-playbook/plan/tracking-strategy#the-mixpanel-data-model).

<Note>
  **Note:** If you have [Group Analytics](/docs/data-structure/group-analytics) as an add-on, this section also applies to [Group Profiles](/docs/data-structure/group-analytics#group-profiles).
</Note>

## Importing Profiles via API

You can create or update User Profiles in similar ways you track events: from our [SDKs](/docs/tracking-methods/sdks/javascript#storing-user-profiles), via our [HTTP Engage API](/reference/profile-set), [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors#user-profiles), or via our integrations partners.

Similarly for [Group Profiles](/docs/data-structure/group-analytics#group-profiles), they can be created or updated using our [SDKs](/docs/tracking-methods/sdks/javascript#creating-group-profiles), via our [HTTP Groups API](/reference/group-set-property), [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors#group-profiles), or via our integration partners.

We recommend tracking profiles from as close as possible to the source of truth, which is usually your application database or your CRM. One typical approach (especially for [Server-Side Tracking](/docs/tracking-methods/choosing-the-right-method#server-side-tracking)) is to run an hourly or daily script on your servers that pulls the list of profiles from your database and pushes them to Mixpanel.

### Operators

The [HTTP Engage API](/reference/profile-set) and [HTTP Groups API](/reference/group-set-property) share the same operators.

**Setting profile property**

* `$set` - Sets a profile property or updates a profile property value (if it already exists).
* `$set_once` - Sets a profile property only if they do not yet exist on Mixpanel. This ensures that the previous profile property value is not overwritten.

**Updating numeric profile property**

* `$add` - Increments or decrements a numeric user profile property *(not supported in group profiles)*. To increment, pass in a positive numeric value, and to decrement pass in a negative numeric value. If the property does not yet exist, it will set the value passed in as the initial value.

**Updating list profile property**

* `$union` - Merges a given value or list into a [List](/docs/data-structure/property-reference/data-type#list) data type profile property and ensures there are no duplicate values.
* `$append` - Appends a value to the end of a [List](/docs/data-structure/property-reference/data-type#list) data type user profile property *(not supported in group profiles)*. Does not check for duplicate values.
* `$remove` - Removes a value from a [List](/docs/data-structure/property-reference/data-type#list) data type profile property.

**Removing profile properties**

* `$unset` - Removes a profile property from the profile.
* `$delete` - Removes all profile properties from the profile.

Here's some sample code to get you started, utilizing the `$set` operator to update user profiles:

```python theme={"system"}
# Fill this out. You can get it from https://mixpanel.com/settings/project
PROJECT_TOKEN = ""

import json
import requests


def get_users_from_database():
    # Replace this with code that reads users from your database or CRM.
    # Note: $name and $email are optional, but useful properties that automatically populate certain parts of our UI when Mixpanel detects them.
    return [
        {"user_id": "123", "$name": "Alice", "$email": "alice@linear.app", "department": "engineering"},
        {"user_id": "456", "$name": "Bob", "$email": "bob@notion.so", "department": "product"},
        {"user_id": "789", "$name": "Carol", "$email": "carol@figma.com", "department": "design"}
    ]

def transform_to_mp_format(user):
    """Transform the above into Mixpanel's format"""
    # It's important to set this to the same distinct_id that you use when tracking events.
    # We recommend using the primary key of your users' table for this.
    distinct_id = user.pop("user_id")

    # Note: we set `$ip` to 0 here to tell Mixpanel not to look up the IP of this user.
    return {"$distinct_id": distinct_id, "$token": PROJECT_TOKEN, "$ip": "0", "$set": user}


users = get_users_from_database()
profiles = [transform_to_mp_format(u) for u in users]

# We recommend calling this API with batches of 200 user profiles to do this at scale.
resp = requests.post(
    "https://api.mixpanel.com/engage",
    params={"verbose": "2"},
    headers={"Content-Type": "application/json"},
    data=json.dumps(profiles)
)

print(resp.json())
```

## Importing Profiles via the UI

To get started, click on **Add/Edit Profile** from the [Users](https://mixpanel.com/report/users) page and follow the workflow below.

> **Note**: For customers with [Group Analytics](/docs/data-structure/group-analytics) make sure you first choose either **User** or the **[Group Key](/docs/data-structure/group-analytics#group-keys-in-project-settings) name** depending on which type of profile you wish to import.

<Frame>
  <img alt="/Screen_Shot_2021-12-01_at_11.44.03_AM.png" />
</Frame>

### Create/Update a Single Profile

**Set an Identifier Column**

The most important column is `$distinct_id` for user profiles (or `$group_id` for [Group Profiles](/docs/data-structure/group-analytics#group-profiles)). The value needs to match the `distinct_id` property's value (or the value for the [Group Key](/docs/data-structure/group-analytics#implementation)'s Group ID) that you're sending on your events.

**Add Additional Properties**

After `$distinct_id`, you can add additional properties to the profile by pressing the **"+ Add Property"** button. Mixpanel will help autocomplete profile properties that you may want to set.

<Frame>
  <img alt="/Screen_Shot_2021-12-01_at_12.20.27_PM.png" />
</Frame>

We recommend using the `$name` (or `$first_name`, `$last_name`), `$email`, and `$phone` [Reserved Profile Properties](/docs/data-structure/property-reference/reserved-properties#reserved-profile-properties)) if you're uploading a user's name, email, or phone. Mixpanel shows these properties by default in various parts of our UI and are used for [Cohort Syncs](/docs/cohort-sync) as well.

### Bulk Import from CSV

When preparing the CSV that you want to upload as profiles, you should **not** include column headers (e.g., \$name, \$email,  etc.). Instead, you’ll identify column headers through the CSV upload wizard in the Mixpanel UI.

**Note**:

* If you import profiles using `$distinct_id` (or `$group_id`) values that already exist, those profiles will be updated with the additional profile properties. On the other hand, if you upload a profile that has the same email address or the same name as another existing profile, but a different `$distinct_id` (or `$group_id`), you will be uploading duplicates - they will not be combined.
* If you upload a CSV with new information for existing properties on existing profiles, the existing property values will be overwritten. If the new information is for new properties on existing profiles, it will be added as additional properties for the profiles.
* The maximum size for your CSV should be 1M rows.

#### Upload Your CSV

Go to the **Import from CSV** tab and select your prepared CSV to begin the process.

#### Choose an Identifier Column

The most important column in your CSV is the `$distinct_id` for user profiles (or `$group_id` for [Group Profiles](/docs/data-structure/group-analytics#group-profiles)). The value needs to match the `distinct_id` property's value (or the value for the [Group Key](/docs/data-structure/group-analytics#implementation)'s Group ID) that you're sending on your events.

The import module will preview the column values from your CSV on the right, corresponding to the property name you are currently defining.

If you do not assign an identifier column, Mixpanel will use your `$email` column as the `$distinct_id` (or `$group_id`) value; if you don’t have an `$email` column either, then the `$distinct_id` (or `$group_id`) value will be assigned randomly by default. Thus, it is highly recommended that you assign an identifier column to avoid unexpected results.

#### Choose Desired CSV Columns

You'll have the opportunity to look through all columns in the CSV to preview their values. In this step, you must **uncheck all columns that you DO NOT wish to import**. You must also choose the associated Mixpanel profile property that each CSV column will be associated with. When you're done selecting the columns, and mapping their associated properties, press the **Import profiles** button to proceed.

<Frame>
  <img alt="/Screen_Shot_2021-12-01_at_12.24.00_PM.png" />
</Frame>

## Importing Historical Profile Values

<Note>
  Historical profiles requires the use of [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors) paid add-on to ingest historical properties.
</Note>

Historical profiles layer on additional capabilities by capturing changes in each property over time instead of just the latest value.

See here for more on how to [import](/docs/tracking-methods/warehouse-connectors#user-profiles) historical properties via Warehouse connectors.

Historical properties can be used anywhere that regular profile properties can be used.

For eg, when you apply breakdown by historical plan-type property, the property value will be picked based on the time of the event, instead of the current property value.

<Frame>
  <img alt="image" />
</Frame>

When you hover over a historical property, the context menu that pops up will show that the property was sourced from a history table, as well as the name of the source. This means that the value of the property used in charts can vary over time.

<Frame>
  <img alt="image" />
</Frame>

### Historic Profile Data Modeling

When the data is imported from the warehouse, aside from having it available in dropdowns for query, you can see the raw data in two (2) separate areas.

**Hidden event**: under the hood, the data is modeled through events, linked in a special way, and attribution is used to obtain the value the profile had at a certain point in time. The name of the event takes after the name of the table/view we read from in the warehouse connector, so if the table name is `company_plan_history`, the event will be named `company_plan_history` too (by default it's hidden).

<Frame>
  <img alt="image" />
</Frame>

The event time follows the start time entries in the table, so if you have an entry for say January 1st, there will also be this event with that same time in the project. This is used for attribution. Say you have 2 entries in the table for plan values, January 1st with a value of "plan1" and an entry on June 1st with a value of "plan" 2. If you were to create a report for this user based on the historic property, any event between Jan 1st and Jun 1st would have the "plan1" value, and any event after Jun 1 would have "plan2".

**Profile View**: if you navigate to the profile view of a specific user (or group) that has historic profile data, you will see the property to the left of the screen and, when you hover, you'll see a button to view the changes over time. Once clicked, you will be shown a list of the values the property has had through time.

<Frame>
  <img alt="image" />
</Frame>

For billing details, read the warehouse connectors [billing FAQ section on People/Group updates](../tracking-methods/warehouse-connectors#what-actions-impact-billing-for-warehouse-connectors).

## Viewing User Profiles

To view a specific user's profile and activity feed in Mixpanel, follow these steps:

<Steps>
  <Step title="Navigate to the Users Tab">
    Click on **Data > Users** in the left navigation bar. This will open a view listing all users currently tracked in your project, along with key attributes for each.

    Learn more about the [Users](/docs/users) tab.
  </Step>

  <Step title="Find the User">
    You can browse the list or use the filter at the top of the Users page to narrow down results. For example, filtering by distinct ID, email, or other properties.
  </Step>

  <Step title="Click Into the User's Profile">
    Click on a user's distinct ID (or their name/tile) to open their individual profile.
  </Step>

  <Step title="Explore the Profile">
    Once inside, you'll find two key areas:

    **Activity Feed (center/right panel):** A reverse-chronological list of all tracked interactions (events) attributed to that user. By default, it shows the last 30 days, but you can extend this to 60, 90 days, or a custom date range. You can also hide specific events to focus on the ones you care about.

    **User Profile Properties (left panel):** Attributes that describe who the user is (e.g., city, country, email, custom properties). Unlike event properties, these are mutable — they always reflect the user's latest known state.
  </Step>

  <Step title="Inspect Individual Events">
    Click on any event in the activity feed to expand it and view its event properties. Additional context such as location, device, URL, or any event properties your team has configured is visible here.
  </Step>
</Steps>

## Deleting Profiles

User Profiles can be deleted either via the [Users](https://mixpanel.com/report/users) page or programmatically via our [Engage API](/reference/delete-profile). We also provide a `people_delete` method in the mixpanel-utils library [here](https://github.com/mixpanel/mixpanel-utils#people-delete).

Similarly, [Group Profiles](/docs/data-structure/group-analytics#group-profiles) can also be deleted either via the [Users](https://mixpanel.com/report/users) page or programmatically via our [Groups API](/reference/delete-group).

<Note>
  Deleting a user profile removes only the user property data. It does not delete the user's tracked events; instead, those events continue to appear in your project as if they were tracked by anonymous users without user profile properties.
</Note>

## FAQ

### What should I send as a User Property vs an Event Property?

We recommend primarily using User Properties to track demographic attributes of the user, like their name, email, and domain. Most other properties are better tracked as [Event Properties](/docs/data-structure/events-and-properties).

That said, User Properties are as flexible as any other properties in Mixpanel, so you can send arbitrary JSON.

### How does Mixpanel join Events and User Profiles?

Mixpanel stores Events and User Profiles in two separate tables under the hood. These two tables are joined at query-time, rather than ingestion-time. This means that when you make a report in our UI that uses User Profiles, we run a query that joins the Events table with the User Profiles table.  This has two implications:

* If you track User Profiles after you track events, they'll still join retroactively with all past events. This means that you don't need to worry about tracking Events and User Profiles in lockstep with each other. As long as they have the same values for Distinct ID, they'll join with each other.
* All Events join with the latest state of a User Profile, rather than its state at a point in time. If there are aspects of a user's state that change over time (for example, their plan type), we recommend tracking that as a property on their events, so that you can analyze that change over time.

### How can I update User Properties?

User Profiles are mutable; Mixpanel only stores the latest value of each profile property. We have methods to update profile properties via our [HTTP API](/reference/profile-set).

### Why are empty profiles created when I import profiles from a CSV?

This may occur if you set the incorrect column from your CSV as the `$distinct_id` during your import. You can see which column was erroneously set as the `$distinct_id` by checking the distinct\_id value set on these empty profiles. As a best practice, always check the sample values shown in the import module for each selected profile property.

### How do I bulk delete profiles?

We recommend deleting profiles programmatically via our [Engage API](/reference/delete-profile). We also provide a `people_delete` method in the mixpanel-utils library [here](https://github.com/mixpanel/mixpanel-utils#people-delete).

### What are the limits of User Properties?

Each User Profile can contain up to 2000 properties. User property names can be at most 255 characters in length (longer names are truncated). User property values are limited based on data type, refer to these limits under [Supported Data Types](/docs/data-structure/property-reference/data-type).

Attempts to add more than 2000 user properties for a user profile will fail. You can remove User Properties using the [\$unset](/reference/profile-delete-property) engage operation if you find yourself close to the 2000 per profile limit.

### How can I send User Profiles if I use Segment?

Mixpanel is 100% compatible with Segment; just follow Segment's best practices. If you call the [`analytics.identify()`](https://segment.com/docs/connections/spec/identify/) method, Segment will create a User Profile in Mixpanel. You can learn more about our integration in Segment's [docs](https://segment.com/docs/connections/destinations/catalog/actions-mixpanel/#identify-user).

### What does the "Updated at" (\$last\_seen) property mean?

User Profiles are mutable, which means new ones can be added and existing ones can be updated or deleted. Mixpanel automatically maintains an "Updated at" (`$last_seen`) property, which contains the last timestamp that a user profile was updated. "Updated at" does not change if the user does a new event; it only changes when the profile is updated. "Updated at" also does not change for profile updates made via the UI or if the `$ignore_time` parameter is set to `true` (see example from [PHP SDK](/docs/tracking-methods/sdks/php#setting-profile-properties)).

### Where can I learn more about Group Profiles?

You can get an overview of how Group Profiles relate to Mixpanel's Data Model under the section [Group Level Behaviors and Demographics](/guides/strategic-playbooks/onboarding-playbook/plan/tracking-strategy#group-level-behaviours-and-demographics) in our tutorials. A more detailed explanation of [Group Profiles](/docs/data-structure/group-analytics#group-profiles) is documented under our [Group Analytics](/docs/data-structure/group-analytics) page.

### How are end times applied to the historical property?

The end time will be inferred from the next event sent with a higher `Start Timestamp`. If you do not have an updated value for a property and simply want it to become inactive at a certain timestamp, please set up your DWH table to set undefined for the property at the time that it becomes inactive/expires.

### How do I set the initial set of profile properties for the user?

Historical profile properties can only be imported through a Warehouse Connector sync. For more information about the connectors and which are supported, see our \[docs]/docs/tracking-methods/warehouse-connectors). There is currently no other method to import historical profile properties or set defaults. To set initial values, please ensure that your warehouse table has the rows covering the historical period you want to analyze.

### What if I have the same property name sent as a regular profile property as well as a historic property?

If a regular profile property shares a name with an historic property, the two properties will be treated as distinct and separate entities (they will not be de-dupped).

### What if I have the same property name sent through multiple WH syncs?

If both syncs are regular user tables and they refer to the same Distinct ID(s), they will be de-dupped and only the latest value will be retained. If both syncs are historical user tables, we will have a warning popup if the conflict can be detected at sync creation time and you will have the option of renaming one of the columns. If one sync is for regular user table and the other for a historical one, see [here](/docs/data-structure/user-profiles#what-if-i-have-the-same-property-name-sent-as-a-regular-profile-property-as-well-as-a-historic-property).

### I deleted my historical user table Warehouse sync and data but there are still empty user profiles!

All the historical props will be deleted from the profile but the profile itself remains, along with any non-historical properties. This is to prevent accidentally deleting profile data sent through API/UI/CSV that might have been merged into the profile data sent via the Warehouse sync. To delete profiles yourself, please use this [guide](/reference/delete-profile).

### What is the frequency of updates that are supported?

The feature supports updates at the rate of about one change per day for each user. It is meant to cover use-cases like plan type changes, MRR etc which are slowly changing dimensions. It is not intended for more frequent changes like game score updates.

### How are historic profile properties calculated within custom properties?

You can use historic user and group properties within custom properties; when used in a custom property, the value used will always be based on the time of the event.


# Experiments
Source: https://docs.mixpanel.com/docs/experiments

Measure the impact of a/b testing

<Note>
  The Experiment Report is a separately priced product add-on. It is currently only offered to those on the Enterprise Plan. See our [pricing page](https://mixpanel.com/pricing/) for more details.

  Customers who have not purchased the Experiment add-on will be able to create up to 3 experiments per project. Please note that creation is irreversible, so you would not be able to delete experiments. If you are interested in exploring the features fully, you can request a trial from your account team.
</Note>

## Why Experiment?

Experimentation helps you make data-driven product decisions by measuring the real impact of changes on user behavior. Mixpanel is an ideal place to run experiments because all your product analytics data is already here, providing you with comprehensive insights into how changes affect your users' journey.

## Prerequisites

Before getting started with experiments:

* **Exposure Event Tracking**: [Implement](#implementation-for-experimentation) your experimentation events
* **Baseline Metrics**: Ensure that Mixpanel is already tracking your key metrics

## Overview & Workflow

<Frame>
  <img alt="image" />
</Frame>

The Experiment report analyzes how one variant impacts your metrics versus other variant(s), helping you decide which variant should be rolled out more broadly. To access Experiments, click on the **Experiments** tab in the navigation panel, or **Create New > Experiment**.

### Experiment Process

**Plan** → **Setup & Launch** → **Monitor** → **Interpret Results** → **Make Decisions**

1. **Plan**: Define hypothesis, success metrics, and test parameters
2. **Setup & Launch**: Configure experiment settings and begin exposure
3. **Monitor**: Track experiment progress and data collection
4. **Interpret Results**: Analyze statistical significance and lift
5. **Make Decisions**: Choose whether to ship, iterate, or abandon changes

## Plan Your Experiment

Before creating an experiment report, ensure you have:

* A clear hypothesis about what change will improve which metric
* Defined primary success metrics (and secondary/guardrail metrics)
* Estimated sample size and test duration requirements
* Proper exposure event tracking implemented

## Setup & Launch Your Experiment

### Step 1: Select an Experiment

Click 'New Experiment' from the Experiment report menu and select your experiment. Both experiments run through Mixpanel Feature Flags and experiments tracked via exposure events are detected and populated in the dropdown. To keep the dropdown focused on experiments you're likely to care about, we hide Mixpanel Feature Flag experiments once their flag is archived, and we hide exposure-event experiments that haven't received an exposure event in the last 30 days. To analyze an exposure-event experiment beyond that window, you can hard-code the experiment name by typing `$experiment:Experiment name` as a filter or breakdown property, where `Experiment name` is the value of whichever property you configured as the experiment name on your exposure events.

<Note>
  Two kinds of experiments can be analyzed in the experiment report: experiments run through Mixpanel Feature Flags with the Experiment type, and experiments tracked via exposure events (i.e., `$experiment_started`). Read more on how to track experiments [here](#implementation-for-experimentation).
</Note>

### Step 2: Choose the ‘Control’ Variant

Select the ‘Variant’ that represents your control. All your other variant(s) will be compared to the control, i.e, how much better they perform compared to the control variant.

### Step 3: Choose Success Metrics

Choose the primary metrics of success for the experiment. You can choose from either saved Mixpanel metrics or create a new metric leveraging the query panel. You can also add secondary metrics and guardrail metrics as required.

### Step 4: Select the Test Duration

Enter either the sample size (the number of users to be exposed to the experiment) or the minimum number of days you want the experiment to run. This will determine the test duration. Once the sample size or days are complete, you can conclusively read the experiment results and make a decision.

### Step 5: Confirm other Default Configurations

Mixpanel has set default automatic configurations, seen below. If required, please modify them as needed for the experiment

1. **Experiment Model type**: Sequential. You can also choose Frequentist or Bayesian; see [Experiment Model Types](#experiment-model-types) for how they differ.
2. **Confidence Threshold**: 95%. On a Bayesian experiment this setting is labeled **Decision Threshold** and sets the minimum Chance to Beat Control required to highlight a variant as a winner.
3. **Experiment Start Date**: Date of the first user exposed to the experiment

<Note>
  The Confidence Threshold and the Bayesian Decision Threshold are the same underlying setting: if you switch an experiment's model type, your chosen number carries over and is reinterpreted for the new model.
</Note>

### Experiment JSON Parameters

Each variant can optionally carry a **value** in addition to its name — either a **string** or a **JSON object**. The variant name is what your code switches on to render the right experience. The value is configuration data the SDK returns alongside the assignment, so you can remotely control parameters of your app or site (copy, colors, thresholds, layout configs, pricing, etc.) without a code deploy.

For example, a variant named `treatment` might carry a JSON object value like:

```json theme={"system"}
{
  "cta_text": "Limited time — Buy now",
  "discount": 20,
  "layout": "grid"
}
```

Your client code reads the value from the SDK alongside the variant name. In the JavaScript SDK:

```javascript theme={"system"}
const fallback = { cta_text: "Buy now", discount: 0, layout: "list" };
const config = await mixpanel.flags.get_variant_value("checkout-promo", fallback);

renderCheckout(config.cta_text, config.discount, config.layout);
```

See the [JavaScript Feature Flags guide](/docs/tracking-methods/sdks/javascript/javascript-flags) for the full SDK reference.

### Changing Settings Mid-Experiment

Mixpanel analyzes your experiment on the fly, so you can adjust settings at any time if needed. If you notice a configuration mistake - like selecting Frequentist when you meant Sequential or Bayesian - feel free to correct it, even if the experiment has been running for weeks.

The one thing to avoid is changing settings because the current results aren't what you hoped for. If you adjust the confidence level, metrics, or duration in search of a significant result, you're more likely to find something that looks meaningful but is actually noise. When you roll out that change, it may not deliver the improvement you expected.

If you want to test a different configuration, restart the experiment instead. This resets the data and ensures your analysis starts fresh.

### Reopening a Decided Experiment

Once you've made a decision on an experiment, you can reopen it in place instead of duplicating it.

On the decided banner, use the **Change Decision** dropdown:

* **Edit Decision**: Revise the decision you recorded (for example, change which variant you shipped or update the notes) while keeping the experiment decided.
* **Undo Decision**: Revert the experiment to its concluded, pre-decision state so the decision can be revisited.

Editing settings on a decided experiment also reopens it. If you change the date range, the duration or end condition, or any analysis configuration, the recorded decision is cleared and the experiment is reopened. Mixpanel shows a warning before this happens so you can confirm you want to discard the decision.

Reopen an experiment to fix a genuine mistake, like a misconfigured setting or a decision you recorded in error. Don't reopen it just to change your mind because you didn't like the results. This matters most for Frequentist experiments. Revisiting a decision after you've seen the results inflates the false-positive rate. Each time you look at the data and then keep collecting or re-decide, you give a non-significant result more chances to cross the threshold by chance. That makes a significant outcome less trustworthy. Repeatedly restarting an experiment in search of significance may lead you to incorrect decisions.

<Note>
  For Mixpanel feature-flag experiments, undoing a decision does **not** automatically re-enable the feature flag. If you need the flag serving its variants again, re-enable it separately from the Feature Flags page.
</Note>

## Monitor Your Experiment

Once your experiment is running, you can track its progress in the Experiments dashboard. Monitor key indicators:

* **Sample Size Progress**: Track how many users have been exposed
* **Data Quality**: Ensure exposure events are being tracked correctly
* **Guardrail Metrics**: Watch for any negative impacts on important metrics
* **External Factors**: Note any external events that might affect results

## Interpret Your Results

The Experiments report identifies meaningful differences between the Control and Variant groups. Every metric has two key attributes, and which ones you see depends on your [experiment model type](#experiment-model-types).

**Frequentist and Sequential models:**

* p-value: this shows if the variants’ delta impact vs the control is statistically significant
* lift: the variants’ delta impact on the metric vs control

**Bayesian model:**

* Chance to Beat Control: the probability that the variant's true metric value is better than the control's
* lift: the variants’ delta impact on the metric vs control

Metric rows in the table are highlighted when a difference is calculated with high confidence. For Frequentist and Sequential experiments, this is when the difference is greater than the confidence interval you set up during the experiment configuration. For Bayesian experiments, a variant is highlighted when its Chance to Beat Control reaches your Decision Threshold. For example, at a 95% threshold, a variant is flagged as a winner at 95% or above, and as a loser at 5% or below.

* Positive differences, where the variant value is in the target direction compared to the control, are highlighted in green
* Negative differences, where the variant value is opposite the target direction compared to the control, are highlighted in red
* Statistically insignificant results remain gray

<Note>
  Hover over a value in a metric row to see more detail behind the numbers and to view the metric in Insights.
</Note>

### How do you read statistical significance?

Statistical significance (p-value) helps you determine whether your experiment results are likely to hold true for the full rollout, giving you confidence in your decisions. On Bayesian experiments, the equivalent signal is the Chance to Beat Control, described under [Bayesian](#bayesian) below.

<Frame>
  <img alt="image" />
</Frame>

#### How Mixpanel Calculates Results

How Mixpanel evaluates your experiment depends on two things: the [experiment model type](#experiment-model-types) you selected, and the type of each metric. The Frequentist and Sequential models compute p-values and confidence intervals; the Bayesian model computes a probability that each variant beats control.

##### Frequentist and Sequential

**Metric Types and Their Distributions:**

Mixpanel categorizes metrics into four types, each using different statistical distributions:

1. **Total Events Metrics**: Use **normal distribution** of per-user event counts
   * Examples: Total purchases, total page views
   * Variance is calculated directly from the distribution of per-user event counts

2. **Total Sessions Metrics**: Use **Poisson distribution**
   * Variance equals the mean (characteristic of Poisson distributions)

3. **Rate Metrics** (Conversion rates, Retention rates): Use **Bernoulli distribution**
   * Examples: Signup conversion rate, checkout completion rate, 7-day retention
   * Models binary outcomes (did/didn't convert) across your user base

4. **Value Metrics** (Averages, Sums of properties): Use **normal distribution approximation**
   * Examples: Average order value, total revenue, average session duration
   * Calculates variance using sample statistics

**Statistical Calculation Process:**

For all metric types, we follow the same general process:

1. **Calculate group rates** for control and treatment
2. **Estimate variance** using the appropriate distribution
3. **Compute standard error** from variance and sample size
4. **Calculate Z-score** measuring how many standard errors apart the groups are
5. **Derive p-value** from Z-score using normal distribution

**Statistical Foundation:**
Our calculations assume normal distributions for the sampling distributions of our metrics. While individual data points may not be normally distributed, the Central Limit Theorem tells us that with sufficient sample sizes, the sampling distributions of means and proportions will approximate normal distributions, making our statistical methods valid.

**For Sequential Testing:**

* Uses continuous monitoring with adjusted significance thresholds with [mSPRT method](https://arxiv.org/pdf/1905.10493)
* Allows for early stopping when significance is reached
* More conservative calculations to account for multiple testing

**For Frequentist Testing:**

* Uses traditional hypothesis testing with fixed sample sizes
* Formula: Max Significance Level (p-value) = \[1-CI]/2 where CI = Confidence Interval

In the above image for example, max p=0.025 \[(1-0.95)/2]

So, if an experiment's results show

* p ≤ 0.025: results are statistically significant for this metric, i.e, you can be 95% confident in the lift seen if the change is rolled out to all users.
* p > 0.025: results are not statistically significant for this metric, i.e, you cannot be very confident in the results if the change is rolled out broadly.

###### Example: E-commerce Checkout Experiment

To illustrate how these calculations work in practice, let's walk through a concrete example.

**Scenario:** Testing a new checkout UI on an e-commerce site with 20 users (10 control, 10 treatment).

**Results:**

* **Control group:** 5 users converted (50% conversion rate), average cart size \$60
* **Treatment group:** 6 users converted (60% conversion rate), average cart size \$67

**For Conversion Rate (Rate Metric - Bernoulli Distribution):**

1. **Group rates:** Control = 0.5, Treatment = 0.6
2. **Variance calculation:** Control = 0.5 × (1-0.5) = 0.25, Treatment = 0.6 × (1-0.6) = 0.24
3. **Standard error:** Combined SE = √((0.25/10) + (0.24/10)) = 0.221
4. **Z-score:** (0.6 - 0.5) / 0.221 = 0.45
5. **P-value:** \~0.65 (not statistically significant)

**For Average Cart Size (Value Metric - Normal Distribution):**

1. **Group means:** Control = \$60, Treatment = \$67
2. **Variance calculation:** Uses the sample variance of cart values in each group
3. **Standard error:** Calculated from combined variance and sample sizes
4. **Z-score and p-value:** Computed using the same Z-test framework

This example shows why larger sample sizes are crucial—with only 10 users per group, even a 10-point difference in conversion rate isn't statistically significant.

##### Bayesian

The Bayesian model answers a different question than the Frequentist and Sequential models. Instead of asking "how surprising would this data be if the treatment had no effect?" (a p-value), it estimates a distribution of plausible values for each variant's metric and reports **how likely it is that the variant is actually better than control**. That probability is surfaced as the **Chance to Beat Control** column.

**Priors:**

Bayesian analysis combines the data you observed with a *prior*, an assumption about what the metric's value is likely to be before looking at the results. Mixpanel uses **weakly informative priors** that are automatically scaled to your experiment's own data. The prior is centered on the pooled metric value across control and the variant being compared, weighted by each one's exposures; its spread comes from the pooled variance of that same data; and its strength is a single pseudo-observation.

That last point is what makes it weakly informative. The prior is strong enough to keep results stable when a variant has very few users, and negligible once real data accumulates: at the thousands of exposures a typical experiment reaches, it has effectively no influence on the outcome. You don't have to supply a prior, and the prior won't push results toward a value you didn't choose. It is not a fixed uniform prior, and it is not derived from control alone.

**Models by metric type:**

| Metric type                                     | Data model                                                               | Prior                |
| ----------------------------------------------- | ------------------------------------------------------------------------ | -------------------- |
| Averages, totals, sessions                      | Normal distribution over per-user values                                 | Normal-Inverse-Gamma |
| Conversion rates, retention rates, unique users | Bernoulli (binary converted / didn't convert)                            | Beta                 |
| Formula metrics                                 | Normal, using propagation of uncertainty across the formula's components | Normal-Inverse-Gamma |

<Note>
  Total and session metrics are modeled as normally distributed per-user counts, on the same per-user scale used for averages, rather than as Poisson counts. This differs from the Frequentist path, which applies a Poisson variance on the totals scale.
</Note>

**How it's computed:**

Each variant's distribution is calculated in closed form, then Mixpanel draws 50,000 samples from the control and variant distributions and compares them to derive the Chance to Beat Control and the interval around the lift. The sampler uses a fixed seed, so you get identical numbers on every reload.

Each variant is compared against control only. In an experiment with three or more variants, you get one independent comparison per variant, each reported as its own Chance to Beat Control. Mixpanel does not report a probability that a given variant is the best of all of them.

**Reading Chance to Beat Control:**

With a Decision Threshold of 95%:

* **97%**: above the threshold, highlighted as a winner.
* **60%**: the variant is more likely better than not, but well short of the threshold. You don't yet have enough data to act.
* **2%**: below the 5% lower bound, highlighted as a loser. The variant is very likely *worse* than control.

This value can read exactly 100% or 0% when none of the 50,000 samples fell on the other side.

**Credible intervals:**

Alongside the lift, Bayesian results include a **credible interval**, the range that contains your chosen share of the plausible lift values (95% by default). A credible interval supports the reading that people often incorrectly apply to a frequentist confidence interval: there is a 95% probability the true lift falls inside it.

Compared to other Bayesian tools:

* The interval is a **highest-density interval**, the *narrowest* range containing 95% of the plausible values. Many Bayesian A/B tools instead report an equal-tailed interval, which trims 2.5% from each end and can be wider.
* It is computed on relative lift (percentage difference from control), not on the absolute difference between the two groups.
* Because of this, the interval is generally asymmetric around the reported lift, rather than "lift ± some margin."

The lift shown for Bayesian metrics is the median of the plausible relative-lift values, chosen because it is robust to the long tails a ratio can produce and always falls inside the credible interval.

**Supported metrics:**

The Bayesian model supports averages, totals, sessions, unique users, conversion rates (including funnel conversion rate), retention rates, and formula metrics built from any of these.

Some metric configurations are not yet supported by the Bayesian model, including total-based funnel conversion rates, retention-frequency metrics, and metrics that roll up user or cohort properties. When a metric isn't supported, its values still appear in the results table but without any statistics: no Chance to Beat Control, lift, or interval. If you rely on one of these metrics, use the Frequentist or Sequential model for that experiment. For formula metrics, every component must be supported, or the whole formula shows no statistics.

### How do you read lift?

<Note>
  Lift is always calculated using **exposures** (users assigned to a variant) as the denominator — not the denominator you may see in other tabs like Totals or Chart. For funnel metrics, this means the lift denominator differs from the funnel conversion rate denominator. See the FAQ ["Why does the lift in Results disagree with the conversion rate in Totals or Chart?"](#why-does-the-lift-in-results-disagree-with-the-conversion-rate-in-totals-or-chart) for a worked example.
</Note>

Lift is the percentage difference between the control and variant(s) metrics.
$Lift= { (variant \,group\,rate - control \,group\,rate) \over (control \,group\,rate)}$

The "group rate" in this formula is calculated differently for each metric type. In every case, the denominator is **the number of users exposed to that variant** (i.e., users who received the `$experiment_started` event for that variant):

**Total Events Metrics:**

* **Numerator:** Total event count in the variant
* **Denominator:** Number of users exposed to the variant
* **Group Rate:** Total count ÷ Number of users exposed
* **Variance:** Calculated directly from the per-user event counts, treated as a continuous variable
* **Example:** If the treatment group has 150 total purchases from 100 exposed users, the group rate = 1.5 purchases per user

**Total Sessions Metrics:**

* **Numerator:** Total session count in the variant
* **Denominator:** Number of users exposed to the variant
* **Group Rate:** Total count ÷ Number of users exposed
* **Variance:** Equal to the mean (Poisson distribution property)

**Rate Metrics (Conversion, Retention):**

* **Numerator:** Number of users who converted (or were retained) in the variant
* **Denominator:** Number of users exposed to the variant
* **Group Rate:** Conversions ÷ Exposures
* **Variance:** Calculated using Bernoulli distribution: p × (1-p)
* **Example:** If 25 out of 100 exposed users convert, group rate = 0.25 (25%). Note that this denominator is exposures — not funnel entrants. This is different from the funnel conversion rate you see in the Totals or Chart tabs, which uses funnel entrants as the denominator.

**Value Metrics (Averages, Sums):**

* **Numerator:** Sum of property values across all users in the variant
* **Denominator:** Number of users exposed to the variant
* **Group Rate:** Sum of property values ÷ Number of users exposed
* **Variance:** Calculated from the distribution of individual property values
* **Example:** If the treatment group spent \$5,000 total from 100 users, the group rate = \$50 average per exposed user

**Why This Matters:**
Normalizing by exposed users (not just converters or funnel entrants) helps you understand the impact on your entire user base. A feature that increases average order value among buyers but reduces conversion rate may decrease overall revenue per user.

<Note>
  **Metrics with a Group Identifier:** When you [change a metric's group identifier](/docs/data-structure/advanced/group-analytics#change-the-group-identifier-in-a-report) from Users to a group key (e.g., Company), exposures for that metric are counted at the group level. The number of exposed groups is then used for all of that metric's calculations — normalizing group rates, computing variance, and determining statistical significance. For example, if a metric is set to aggregate by Company and 200 companies have been exposed to the treatment, the group rate is calculated as the total metric value divided by those 200 exposed companies, not by the number of individual users.
</Note>

**Custom Formula Metrics:**
For complex metrics using formulas like `Revenue per User = Total Revenue ÷ Unique Users`, Mixpanel uses propagation of uncertainty to estimate variance. This combines the variances of the component metrics (Total Revenue and Unique Users) to calculate the overall metric's statistical significance. The system assumes metrics in formulas are uncorrelated for these calculations.

### Segment your results

Segmentation lets you break your experiment results down by a property (such as country, platform, plan type, or device) to see how the treatment effect varies across groups of users. This is useful for spotting cases where a change helps one segment but hurts another, which an aggregate result can hide.

**How to use it:** Use the **breakdown picker** above the results table to choose a property to segment by. Mixpanel then computes a separate result (lift, p-value, and confidence) for each value of that property and lays them out in a table, so you can compare the variants within every segment. Each segment row reads exactly like the overall results: green for a significant positive difference, red for a significant negative one, and gray for differences that aren't statistically significant.

This breakdown happens natively inside the Experiment report and is distinct from clicking **Analyze** on a metric, which opens a separate Insights report (see [Diagnosing experiments further](#diagnosing-experiments-further-in-regular-mixpanel-reports)).

#### The risk of post-hoc segmentation

Breaking results down after an experiment has run is a form of *post-hoc analysis*, and it carries a real statistical risk. Every additional segment you inspect is another chance to see a "significant" result that is actually just noise. This is the same multiple-comparisons problem described under [Bonferroni](#bonferroni-correction) and [Benjamini-Hochberg](#benjamini-hochberg-correction), but it's especially easy to fall into when you slice the same results many different ways looking for something that "worked."

This practice is often called *p-hacking*: if you test enough segments, you will eventually find one with a low p-value purely by chance. Reporting that segment as a win, and constructing a story around why that particular group responded, can lead you to ship a change based on a false positive.

<Warning>
  Treat a winning segment as a **lead to investigate, not a conclusion**. If a segment looks promising, the rigorous next step is to run a fresh experiment that targets that segment specifically and confirms the effect.
</Warning>

#### Why Mixpanel corrects segmented results by default

Because segmenting multiplies the number of comparisons being made, Mixpanel corrects segmented results by default. When you don't already have a [Multiple Testing Correction](#bonferroni-correction) enabled, adding a breakdown turns on the [Benjamini-Hochberg correction](#benjamini-hochberg-correction) across its segments. If you already have Bonferroni enabled, Mixpanel keeps it rather than switching to Benjamini-Hochberg, since Bonferroni is the stricter check. Either way the correction is recommended but optional, and you can turn it off from the results if you want to see the uncorrected numbers.

Benjamini-Hochberg controls the **false discovery rate**, the share of your flagged winners that are actually false positives. It does this by making the significance threshold stricter as you add more segments, so a segment still highlighted as a winner after correction is more trustworthy. Segments that only looked significant because you tested many of them are filtered out. See the [Benjamini-Hochberg Correction](#benjamini-hochberg-correction) section for a worked example of how the procedure ranks and thresholds p-values.

This correction operates on the values in your breakdown, which is a different axis from the [Multiple Testing Correction](#bonferroni-correction) you apply across metrics and variants. That means adding more breakdown values doesn't inflate your false positive rate.

### When do we say the Experiment is ready to review?

Once the ‘Test Duration’ setup during configuration is complete, we show a banner that says “Experiment is ready to review”.

Test Duration can be either of two options:

1. Sample size to be exposed
2. Number of days you’d like to run the experiment

NOTE: If you are using a 'sequential' or 'bayesian' experiment model type, you can always peek at the results sooner. Learn more about the [experiment model types](#experiment-model-types).

A Chance to Beat Control describes the data you have collected so far, so unlike a fixed-horizon p-value it does not depend on having reached a predetermined sample size. Mixpanel does not, however, apply an always-valid correction on the Bayesian path the way the Sequential model applies mSPRT. If you want a formal guarantee about stopping early, Sequential is the model built for that. For small expected effects, still run your planned duration: a Chance to Beat Control computed on a few hundred users is very uncertain.

### Diagnosing experiments further in regular Mixpanel reports

Click 'Analyze' on a metric to dive deeper into the results. This will open a normal Mixpanel insights report for the time range being analyzed with the experiment breakdown applied. This allows you to view users, view replays, or apply additional breakdowns to further analyze the results.

You can also add the experiment breakdowns and filters directly in a report via the Experiments tab in the query builder. This lets you do on-the-fly analysis with the experiment groups. Under the hood, the experiment breakdown and filter work the same as the Experiment report.

## Multiple Environments

Multiple Environments lets you treat separate Mixpanel projects as development, staging, and production environments for the same experiment or feature flag. Build and iterate on an experiment (and its underlying flag) in one project, then push it to another project when you're ready — without recreating it by hand. Linked experiments and flags stay connected so you can continue pushing updates over time.

### Other Environments Selector

The "Other Environments" selector appears under the **Configuration** tab of an experiment, inside the **More** section. This panel lets you manage an experiment's links to copies of itself in other projects.

#### Pushing changes

Pushing changes copies the full configuration of the source (original) experiment to the linked destination experiment in the other project. Any changes that exist only on the destination experiment will be overwritten.

#### Other Environments Menu

This menu lists the experiments in other projects that are linked to the current experiment. From here, you can navigate to a linked experiment, push the source experiment's current configuration to it, or remove the connection.

#### Duplicate To Project

To duplicate an experiment to another project, open the Other Environments menu and select **Duplicate To Project**. In the dialog, choose the destination project.

This flow is for duplicating across projects only — to duplicate within the same project, use the existing **Duplicate** option within the experiment's overflow (`...`) menu in the top-right of the experiment page.

Once duplicated, the new experiment is linked to the original and can be managed from the "Other Environments" menu.

#### Feature Flags

If an experiment is linked to a **Mixpanel** Feature Flag, the underlying flag cannot be duplicated on its own from the Feature Flags page — use the experiment's Duplicate flow to copy the experiment and flag together. If your experiment uses a **third-party** flag instead, you can duplicate the experiment directly; no flag duplication step is involved.

When duplicating an experiment that is linked to a Mixpanel Flag to another project, you will be prompted to confirm whether you also want to duplicate the linked flag. If you do, the new experiment will be linked to the new flag, and the new flag will also appear in the "Other Environments" menu of the original flag.

When pushing changes, if both the source and destination experiments are linked to flags that are also linked (i.e., you chose to duplicate the flag as well), you can choose to push any changes from the source flag to the destination project's flag at the same time.

#### Permissions

To duplicate an experiment to another project, you need permission to create and edit experiments in **both** the source and destination projects. The required permission level in the destination project is the same as what's needed to manually create a new experiment there — governed by that project's roles and custom roles.

#### What to expect after duplicating

When an experiment is duplicated to another project, time-based settings (such as the experiment period and day counts) reset to the day the duplicate was created — the same behavior as duplicating within a project.

If your experiment targets a cohort, Mixpanel assumes the event properties referenced by that cohort exist in the destination project. It does not validate property availability at copy time, so verify that your destination project collects the same events and properties before running the experiment there.

#### Removing a connection

Removing an inter-project connection from the "Other Environments" menu unlinks the two experiments — it does **not** delete the experiment in the destination project. The copied experiment remains in the destination project and continues to function independently; it simply loses its link to the original.

<Info>
  **Billing across projects:** You aren't double-charged for using the same feature flag across multiple projects. Mixpanel charges based on active feature flag keys, so the same flag-key shared across projects is counted once.
</Info>

## Advanced Statistical Methods

Mixpanel offers several advanced statistical options to help you get more reliable experiment results. These features address common challenges in experimentation: controlling for multiple comparisons, handling outliers, validating experiment setup, and reducing variance to reach significance faster.

### Methods at a Glance

| Technique                         | What It Does                                                                                                             | When to Use                                                                                                                                           | Actions to Take                                                                                                                                                                                                                         |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bonferroni Correction**         | Makes significance thresholds stricter to account for testing multiple metrics/variants at once                          | You're tracking multiple metrics or testing multiple variants and want maximum protection against any false positive. Frequentist and Sequential only | If a metric loses significance after correction, don't treat it as a confirmed winner. Run a follow-up experiment focused on that metric alone.                                                                                         |
| **Benjamini-Hochberg Correction** | Controls the proportion of significant results that are false positives (false discovery rate)                           | You're tracking many metrics and want to correct for multiple comparisons without being overly conservative. Frequentist and Sequential only          | Treat the surviving significant results as your set of likely winners, knowing a small share may still be false positives. Validate the most important ones in a follow-up.                                                             |
| **Winsorization**                 | Caps extreme outlier values at a percentile you choose                                                                   | Revenue or value-based metrics where outliers are common                                                                                              | If results change substantially after Winsorization, this indicates your original results were driven by outliers. Decide whether your business decision is about typical users or extreme ones. Applies to all experiment model types. |
| **SRM**                           | Checks whether your variant split matches the configured allocation                                                      | Always on as a health check                                                                                                                           | Pause the experiment. Identify and fix the root cause of the mismatch, then restart the experiment.                                                                                                                                     |
| **Pre-Experiment Bias**           | Checks whether variant groups were already different *before* the experiment started                                     | Always on as a health check                                                                                                                           | Your groups had pre-existing bias. Consider enabling CUPED to correct for it. Investigate your assignment logic to prevent it in future experiments.                                                                                    |
| **CUPED**                         | Uses pre-experiment behavior to adjust for natural variance and pre-existing bias, helping you reach significance faster | Your users have pre-experiment history and your metrics have high natural variance                                                                    | If confidence intervals don't noticeably tighten, pre-experiment behavior isn't predictive for your metrics. Results are still valid, you just won't get faster detection.                                                              |

### Which methods apply to Bayesian experiments

Most of the methods below are independent of your experiment model type and work the same way on a Bayesian experiment:

* **Winsorization**, **CUPED**, **segmentation**, **SRM**, and **Pre-Experiment Bias** all apply. They operate on the metric data before the statistical model runs, so the Bayesian model consumes the adjusted values. With CUPED, the effect shows up as narrower credible intervals while the reported lift stays roughly the same.
* **Multiple testing corrections (Bonferroni and Benjamini-Hochberg)** don't apply. Both work by adjusting p-value thresholds, and Bayesian results don't produce a p-value; the decision comes directly from the Chance to Beat Control. The setting is hidden on Bayesian experiments, including when you add a breakdown.

<Note>
  The caution about [post-hoc segmentation](#the-risk-of-post-hoc-segmentation) still applies to Bayesian experiments. Inspecting many segments looking for one that "worked" raises your odds of finding a variant that looks like a winner by chance, whether you're reading p-values or probabilities. Treat a winning segment as a lead to test in a fresh experiment.
</Note>

### Bonferroni Correction

When you track multiple metrics in an experiment, or test multiple variants against a control, you increase the chance of seeing a false positive. This is similar to rolling multiple dice: there's only a 1-in-6 chance of rolling a six with one die, but if you roll 10 dice, the chance that at least one shows a six is much higher.

The same principle applies to experiment metrics. At a 95% confidence level, each metric has a 5% chance of showing a significant result by pure chance. But when you're tracking many metrics, the probability that at least one of them shows a false positive increases substantially.

Bonferroni Correction addresses this by making the significance threshold stricter. When enabled, Mixpanel divides your confidence threshold by the number of comparisons being made (metrics × non-control variants). For example, if you have 3 metrics and 2 treatment variants, that's 6 total comparisons. If you selected a 95% confidence level, we'd increase the threshold to about 99% to compensate.

**When to use Bonferroni Correction:**

* You're tracking multiple primary metrics and want to reduce false positive risk
* You have multiple treatment variants competing against control
* You want higher confidence that significant results are real

Bonferroni Correction is conservative. It reduces false positives but also makes it harder to detect true effects. If you have a single metric that matters most to you, you may prefer to focus on that primary metric without correction. If you're testing many metrics and Bonferroni feels too strict, consider Benjamini-Hochberg below.

### Benjamini-Hochberg Correction

Benjamini-Hochberg (BH) is a more balanced alternative to Bonferroni for handling multiple comparisons. Instead of controlling the probability that *any* significant result is a false positive (the family-wise error rate that Bonferroni targets), BH controls the **false discovery rate** — the expected *proportion* of your "winners" that are actually false positives.

This better matches how experiment decisions are actually made. You only ship winners, so what matters is the share of those winners that are real. If you have 4 significant metrics and on average 1 is a false positive, your false discovery rate is 25% — regardless of how many metrics you tested in total.

**How it works:** Mixpanel ranks all p-values for the experiment from smallest to largest. Each p-value is compared to a threshold of (rank / total tests) × α, where α is determined by your confidence level. The largest p-value that passes its threshold — and every smaller p-value — is marked significant.

For example, with 5 metrics at a 95% confidence level (α = 0.05):

| Metric        | P-value | Rank | BH Threshold (0.05 × rank / 5) | Significant? |
| ------------- | ------- | ---- | ------------------------------ | ------------ |
| Revenue       | 0.003   | 1    | 0.010                          | ✅            |
| Signups       | 0.012   | 2    | 0.020                          | ✅            |
| Click-through | 0.018   | 3    | 0.030                          | ✅            |
| Time on page  | 0.041   | 4    | 0.040                          | ❌            |
| Bounce rate   | 0.062   | 5    | 0.050                          | ❌            |

Under BH, the first three metrics are significant. Under Bonferroni at the same confidence level, only Revenue would pass.

**When to use Benjamini-Hochberg Correction:**

* You're tracking many metrics and want correction without sacrificing too much statistical power
* You're comfortable accepting that a small proportion of your significant results may be false positives, in exchange for catching more real effects
* You want a correction method that scales gracefully as you add metrics

A small proportion of significant results may still be false positives under BH, but you are much more likely to detect real effects than with Bonferroni. BH is the recommended choice when you're tracking many metrics or running multi-variant experiments and want to preserve statistical power.

You can only apply one correction method at a time. Choose Bonferroni when the cost of acting on any false winner is high, and Benjamini-Hochberg when you're testing many metrics and want a more balanced trade-off between false positives and missed effects.

### Winsorization

Outliers can distort experiment results, especially for revenue or value-based metrics. If most customers have cart sizes under \$100 but one customer in the treatment group spends \$100,000, this single extreme value could skew all your results and make it harder to detect real effects.

Winsorization addresses this by capping extreme values at a specified percentile. When enabled, you select a percentile threshold (such as 5%). Mixpanel then finds the values at the top and bottom of that percentile range and caps any values beyond those limits. In the example above, if the 95th percentile corresponds to \$90, then the \$100,000 purchase would be treated as \$90 for the analysis.

**When to use Winsorization:**

* Your metrics have high variance due to extreme values
* You're measuring revenue, order value, or other metrics where outliers are common
* You want to understand the effect on typical users rather than being influenced by rare extremes

Winsorization changes the data being analyzed. If extreme values are genuinely important to your business (for example, if a small number of customers drive most of your revenue), you may want to analyze results without Winsorization to understand the full picture.

### Health Checks

Before trusting your experiment results, it's important to verify that your experiment was set up correctly. Mixpanel offers two health checks to help you validate your experiment's integrity.

#### Sample Ratio Mismatch (SRM)

When randomly assigning users to control or treatment groups, you expect the split to roughly match your allocation targets. If you configured a 50/50 split but ended up with 60% in control and 40% in treatment, something may have gone wrong.

Small imbalances can happen by random chance, but larger mismatches often indicate a bug in your assignment logic, tracking implementation, or user bucketing. SRM uses a Chi-squared test to determine whether the observed split is likely due to chance or signals an actual problem.

If Mixpanel detects a statistically significant sample ratio mismatch, you'll see a warning. We recommend investigating the root cause of the mismatch and restarting the experiment after fixing it.

#### Pre-Experiment Bias Analysis

When you see lift in your experiment, you want to be confident it's caused by your treatment—not by pre-existing differences between the groups. Pre-Experiment Bias helps you check this.

The idea is simple: Mixpanel runs the same statistical analysis on 2 weeks of pre-experiment data. It looks at how each variant's users behaved *before* they were exposed to the experiment, using the same metrics you're measuring during the experiment.

If the groups were properly randomized, there should be no significant difference in the pre-experiment period—users hadn't been treated yet, so nothing should cause a difference. But if Pre-Experiment Bias finds statistically significant lift in the pre-experiment data, that's a red flag. It suggests the groups weren't equivalent to begin with, which means any lift you see during the experiment might not be caused by your treatment.

**Example:** Your experiment shows the treatment group has 15% higher engagement. But Pre-Experiment Bias reveals this same group already had 12% higher engagement before the experiment started. This suggests your randomization may have assigned more naturally-engaged users to treatment, and the lift you're seeing is largely a pre-existing difference rather than a treatment effect.

Pre-Experiment Bias failing for a metric doesn't necessarily invalidate your experiment. Enabling CUPED may help reduce the impact of pre-experiment bias on the data, allowing you to still analyze the results. You may however want to review your implementation to ensure assignment is not biased towards some users.

#### Common reasons health checks may fail:

* Bugs in the randomization or bucketing logic
* Exposure events not firing consistently across variants
* Users being reassigned to different variants mid-experiment

### CUPED (Controlled-experiment Using Pre-Experiment Data)

CUPED is a variance reduction technique that helps you reach statistical significance faster. It uses pre-experiment behavioral data to produce narrower confidence intervals, potentially reducing the time needed to conclude an experiment significantly.

The core insight is that users who had high engagement or revenue *before* the experiment are likely to have high values *during* the experiment as well. By accounting for this correlation, CUPED can separate the natural variation in user behavior from the effect of your treatment.

**How it works:** For each user, Mixpanel looks at their metric value during a pre-exposure period of your choosing and their metric value during the experiment. If these values are strongly correlated (users with high pre-experiment values tend to have high post-experiment values), CUPED uses this relationship to reduce variance in the experiment results. The mean values remain unchanged—CUPED only tightens the confidence intervals. This is applied to all metric categories: primary, secondary, and guardrail metrics.

**Configuring the pre-exposure period:** When you enable CUPED, you can choose the lookback window under **Configuration → CUPED Pre-Exposure Period**. The available options are **1 Week**, **2 Weeks** (default), **4 Weeks**, **60 Days**, and **90 Days**. A longer window queries further back in time, which picks up more users and more historical signal. Choose a window that is long enough to capture your users' typical behavior — if some users are only active once a month, a 1-week window may miss them entirely. Avoid windows that overlap with previous experiments on the same user population, as shared exposure can reduce sensitivity and introduce bias. That said, a longer window is not always better: behavior from far in the past can be less predictive of current behavior, and users with no activity in the window are assigned a pre-exposure value of zero, which dilutes the variance reduction benefit. Two weeks is a good default for most experiments.

**Handling users without pre-experiment data:** Not all users in your experiment will have activity during the pre-exposure period. New users, or users who simply didn't perform the relevant event before the experiment, are assigned a value of zero for the pre-exposure metric. This allows all experiment users to be included while still benefiting from variance reduction for users who do have historical data.

**When to use CUPED:**

* You have sufficient pre-experiment data for most users in your experiment
* Your metrics have high natural variance between users
* You're measuring metrics where past behavior predicts future behavior (engagement, revenue, retention)

CUPED works best when pre-experiment and post-experiment metrics are strongly correlated. If users' behavior is highly unpredictable or your experiment targets new users with no history, you may not see any benefit.

## Looking under the hood - How does the analysis engine work?

<Frame>
  <img alt="image" />
</Frame>

The Experiment report behavior is powered by [borrowed properties](/docs/features/custom-properties#borrowed-properties).

For every user event, we identify if the event is performed after being exposed to an experiment. If it were, then we would borrow the variant details from the tracked `$experiment_started` to attribute the event to the proper variant.

### Implementation for Experimentation

If you're using [Mixpanel Feature Flags](/docs/featureflags), you don't need to do anything extra to send exposure events — Mixpanel's SDKs track them automatically when a user is exposed to a variant. Your experiment will show up in the Experiment report as soon as the feature flag is created with the Experiment type.

If you're using a 3rd party feature flagging service or an in-house feature flag system, you can still analyze your experiments in Mixpanel by sending exposure events yourself in the following format:

**Event Name:** “\$experiment\_started”

**Event Properties:**

* “Experiment name” - the name of the experiment to which the user has been exposed
* “Variant name” - the name of the variant into which the user was bucketed, for that experiment

An example track call would look like this:

`mixpanel.track('$experiment_started', {'Experiment name': 'Test', 'Variant name': 'v1'})`

You can specify the event and property that should be used as the exposure event, name, and variant. Go to **Settings → Project → Experimentation**. This allows you to use an experiment event that you're already tracking, for example, via a 3rd party feature flagging tool. Note, only string properties should be used for the 'Name' and 'Variant'.

<Frame>
  <img alt="image" />
</Frame>

#### Sending multiple experiments in a single exposure event

By default, each `$experiment_started` event records a single experiment and its variant. If a user is exposed to several experiments at the same time, you can instead record all of them on one exposure event, rather than sending a separate event per experiment.

To enable this, open the **Experiment Event Format** settings and set **Experiments in each Exposure Event** to **More than one**. When you do, the **Experiment and Variant format** options change from "Separate values"/"Combined value" to **Dictionary (Key-value pairs)** or **List (Ordered values)**. The exposure event name stays `$experiment_started` in every case.

**Dictionary (Key-value pairs):** each experiment key becomes a property key on the event, and its value is the variant key the user was bucketed into for that experiment:

```json theme={"system"}
{
  "event": "$experiment_started",
  "properties": {
    "[Experiment Key]": "[Variant Key]",
    "[Another Experiment Key]": "[Another Variant Key]"
  }
}
```

**List (Ordered values):** experiments are recorded as an ordered array under a single list property (default key `Experiments`), where each entry pairs the experiment key with its variant key joined by a configurable **String Separator** (default `:`), i.e. `[Experiment Key]:[Variant Key]`:

```json theme={"system"}
{
  "event": "$experiment_started",
  "properties": {
    "Experiments": [
      "[Experiment Key]:[Variant Key]",
      "[Another Experiment Key]:[Another Variant Key]"
    ]
  }
}
```

### When to track an exposure event?

* An exposure event  ONLY needs to be sent the first time a user is exposed to an experiment, as long as the user is always in the initial bucketed variant. Exposure events don’t have to be sent subsequently in new sessions.

* If a user is part of multiple experiments, by default send a separate exposure event for each experiment. Alternatively, if you set **Experiments in each Exposure Event** to **More than one** in the **Experiment Event Format** settings, you can record all of a user's experiments on a single exposure event (see "Sending multiple experiments in a single exposure event" above).

* Send exposure event only when a user is actually exposed, not at the start of a session.

  For example, if you want to run an experiment on the payment page of a ride-sharing app, you only really care about users who open the app, book a ride, and then reach the payment page. Users who only open the app and do other activities shouldn't be considered in the sample size. So exposure event should ideally be implemented to track only once the payment page is reached.

* Send exposure details and not the assignment.

  For example, you begin an experiment on 1st Aug, and 1M users are ‘assigned’ to the control and variant. You do not want to send an ‘exposure’ event for all these users right away, as they have only been assigned to the experiment.  It’s possible that some user gets exposed on 4th Aug and some on 8th Aug. You would want to track \$experiment\_started at the exposure for accurate analysis.

### FAQs

1. If a user switches variants mid-experiment, how do we calculate the impact on metrics?

   We break a user and their associated behavior into fractional parts for analysis. We consider the initial behavior part of the first variant, then once the variant changes, we consider the rest of the behavior for analysis towards the new variant.

2. If a user is part of multiple experiments, how do we calculate the impact of a single experiment?

   We consider the complete user’s behavior for every experiment that they are a part of.

   We believe this will still give accurate results for a particular experiment, as the users have been randomly allocated. So there should be enough similar users, ie, part of multiple experiments, across both control and variants for a particular experiment.

3. For what time duration do we associate the user being exposed to an experiment to impact metrics?

   After the most recent experiment exposure for a user, we consider that user’s behavior as ‘exposed’ to an experiment for a max of 90 days.

#### Why does the lift in Results disagree with the conversion rate in Totals or Chart?

This is expected behavior — the two numbers use different denominators and answer different questions.

**Lift** divides conversions by **exposures** (all users assigned to a variant). **Totals/Chart** for funnel metrics divides funnel completers by **funnel entrants** (users who started the funnel). When a variant changes how many users enter the funnel — for example, a new CTA that attracts more (or less qualified) users — the two rates can move in opposite directions.

**Worked example:**

|                                                      | Control | Variant (v1) |
| ---------------------------------------------------- | ------- | ------------ |
| Exposures (users assigned)                           | 35,350  | 35,620       |
| Funnel entrants                                      | 7,504   | 8,676        |
| Funnel completers                                    | 2,289   | 2,480        |
| **Funnel conversion** (completers ÷ entrants)        | 30.50%  | 28.58%       |
| **Per-exposure conversion** (completers ÷ exposures) | 6.49%   | 6.96%        |

* **Funnel conversion (Totals/Chart tab):** v1 is 28.58% vs control 30.50% — v1 looks **worse** (−6.3%).
* **Per-exposure conversion (basis for Lift):** v1 is 6.96% vs control 6.49% — v1 looks **better** (+7.52%).

Both are correct. The funnel conversion rate answers: "For users who started the funnel, how often did they finish?" The per-exposure conversion rate answers: "For all users assigned to this variant, how often did they convert?"

In this example, the variant brought more users into the funnel (8,676 entrants vs 7,504). Those additional users lowered the funnel completion rate, but the variant still converted a larger share of its total exposed population. Lift uses the per-exposure rate because it measures the overall impact of the variant on your entire user base, not just on users who happened to enter the funnel.

## Experimentation Pricing FAQ

<Note>
  The Experiment Report is a separately priced product offered to organizations on the Enterprise Plan. Please [contact us](https://mixpanel.com/contact-us/sales/) for more details.
</Note>

### Pricing Unit

Experimentation is priced based on MEUs - Monthly Experiment Users. Only users exposed to an experiment in a month are counted towards this tally.

#### How are MEUs different than MTUs (Monthly Tracked Users)?

MTUs count any user who has tracked an event to the project in the calendar month. MEU is a subset of MTU; it’s only users who have tracked an exposure experiment event (ie, `$experiment_started`) in the calendar month.

#### How can I estimate MEUs?

If you actively run experiments, you can look at the number of  monthly users exposed to an experiment. Note that the MEU calculation is different if users are, on average, exposed to 30 or more experiments in a month.

If not running experiments, below are some rough estimations of MEU's based on the number of MTUs being tracked to the project.

| **MTU bucket**          | \*\*Estimated MEU (% MTU) \*\* |
| ----------------------- | ------------------------------ |
| Small (\< 100k)         | 50-100%                        |
| Medium (100k - 1M)      | 40-75%                         |
| Large (1M - 10M)        | 25-60%                         |
| Very large (10M - 100M) | 20-50%                         |
| 100M +                  | 10-25%                         |

#### Does it matter how many experiments a user is exposed to within the month?

We’ve accounted for an MEU to be exposed to up to 30 experiments per month. If the average number of experiment exposure events per MEU is over 30, then the MEUs will be calculated as the total number of exposure events divided by 30.

#### What happens if I go over my purchased MEU bucket?

You can continue using Mixpanel Experiment Report, but you will be charged a higher rate for the overages.

#### Can I analyze experiments prior to the purchase date?

No. You can only analyze experiments starting from your experimentation purchase date. This means that the date used in your experiment cannot start prior to the purchase date.

#### But I am already paying for exposure events in my regular plan. Am I getting double-charged?

If you buy the Experimentation offering, we waive the charge for exposure events in your regular Mixpanel plan. You only get charged for the exposure events via the MEU calculation.

#### How can I monitor my account’s MEU consumption?

You can see your experiment MEU usage by going to Organization settings > Plan Details & Billing.

## References

### Experiment Model Types

* Sequential: Allows you to detect lift and conclude experiments quickly, but may fail to reach significance for very small lifts. **When to use?** For large changes (\~10%+ lift) when you want to stop early once significance is reached.

* Frequentist: Capable of detecting smaller lifts, but requires you to keep experiments for the full duration. You’re discouraged from preemptively making decisions before the test duration is complete. **When to use?** For very small changes (\~1% lift) when precision matters.

* Bayesian: Reports the probability that each variant beats control instead of a p-value, and can be read at any point during the experiment. **When to use?** When you're reporting results to an audience that doesn't work in p-values. Note that a few metric configurations aren't supported, listed under [Bayesian](#bayesian).

### Experiment metric types

* **Primary Metrics:**  Main goals you're trying to improve. These are metrics used to determine if the experiment succeeded. Examples: revenue, conversion rates, ARPU.
* **Guardrail Metrics:** These are other important metrics that you want to ensure haven’t been negatively affected while focusing on the primary metrics. Examples: CSAT, churn rate.
* **Secondary Metrics:** These provide a deeper understanding of how users are interacting with your changes, i.e, help to understand the "why" behind changes in the primary metric. Examples: time spent, number of pages visited, or specific user actions.

## Make Your Decision

Once the experiment is ready to review, you can choose to 'End Analysis'. Use these guidelines to make informed decisions:

### When to Ship a Variant

* **Statistical significance achieved** (or, on a Bayesian experiment, **Chance to Beat Control has reached your Decision Threshold**) AND **practical significance met** (lift meets your minimum threshold)
* **Guardrail metrics remain stable** (no significant negative impacts)
* **Sample size is adequate** for your confidence requirements
* **Results align with your hypothesis** and business objectives

### When to Ship None

* **No statistical significance** achieved after adequate test duration; on a Bayesian experiment, Chance to Beat Control has stayed short of your Decision Threshold
* **Statistically significant but practically insignificant** (lift too small to matter)
* **Negative impact on guardrail metrics** outweighs primary metric gains
* **Results contradict** your hypothesis significantly

### When to Rerun or Iterate

* **Inconclusive results** due to insufficient sample size
* **Mixed signals** across different user segments
* **External factors** contaminated the test period
* **Technical issues** affected data collection

### What to Watch Post-Rollout

* **Monitor guardrail metrics** for 2-4 weeks after full rollout
* **Track long-term effects** beyond your experiment window
* **Watch for novelty effects** that may wear off
* **Document learnings** for future experiments

### Decision Options in Mixpanel

* **Ship Variant (any of the variants)**: You had a statistically significant result. You have made a decision to ship a variant to all users. NOTE: Shipping variant here is just a log; it does not actually trigger rolling out the feature flag unless you are using Mixpanel feature flags **(in beta today)**.
* **Ship None**: You may not have had any statistically significant results, or even if you have statistically significant results, the lift is not sufficient to warrant a change in user experience. You decide not to ship the change.
* **Defer Decision**: You may have a direction you want to go, but need to sync with other stakeholders before confirming the decision. This is an example where you might defer a decision and come back at a later date and log the final decision.

### Experiment Management

You can manage all your experiments via the Experiments Home tab. You can customize which columns you’d like to see.

<Frame>
  <img alt="image" />
</Frame>


# Export Methods
Source: https://docs.mixpanel.com/docs/export-methods

Export raw data and reports from Mixpanel

## Overview

This page provides a high-level overview of your options for exporting event data, profile data, and formatted report data.

You can export data from your project using a variety of methods, including lightweight CSVs generated from the UI, large volume raw data export from our APIs, and data syncs to external destinations through [Cohort Syncs](/docs/cohort-sync) and [Data Pipelines](/docs/data-pipelines).

<Note>
  For GDPR/CCPA-compliant exports, please [see the End User Data Management page](/docs/privacy/end-user-data-management).
</Note>

## Exporting Events

### Event Export via API

<Note>
  The `from_date` and `to_date` params are interpreted using UTC timezones. For projects created before 1 January 2023, the `from_date` and `to_date` params are interpreted using your current project timezone.
</Note>

To export raw event data, use the [Raw Event Export API](/reference/raw-event-export). The events payload is returned as JSONL, where each line is a valid JSON object. This method is recommended for high volume exports.

Example request:

```sh theme={"system"}
# Returning "sample_event" from 2026-01-10 to 2026-01-11
curl -gG --request GET \
     --url 'https://data.mixpanel.com/api/2.0/export?from_date=2026-01-10&to_date=2026-01-11&limit=100' \
     --data-urlencode 'event=["sample_event"]' \
     --header 'accept: text/plain' \
     --header 'authorization: Basic YOUR_TOKEN'
```

Example payload:

```json theme={"system"}
// The entire payload is a JSONL
// Each line of event is a JSON object
{"event":"Signed up","properties":{"time":1602611311,"$insert_id":"ABCDE","mp_processing_time_ms":1602625711874}}
{"event":"Signed up","properties":{"time":1602787121,"$insert_id":"ABCDE","mp_processing_time_ms":1602801521561}}
```

The exported payloads are raw events, containing timestamps as they are stored in your project. For projects created before 1 Jan 2023, your event timestamp is stored in your local project timezone at the time of ingestion. For projects created after 1 Jan 2023, your event timestamp is stored in UTC timezone. Learn more about managing your project timezone [here](/docs/orgs-and-projects/managing-projects#manage-timezones-for-projects).

### CSV Events Export

<Note>
  Only the events visible in the Events table at the time of your export will be included in the CSV. Scroll down and click “Load More” to make more events visible.
</Note>

You may export small batches of events as a CSV for use in quick analysis by navigating to the Events tab, querying the events that you are interested in seeing, then clicking the “Export” button in the top right corner.

By default, only the columns that are shown in the UI will be exported. You can click the “Edit Columns” button to modify the properties columns shown in the Events table.

Select the option to include “All event properties” if you are interested in all of the event properties.

<Frame>
  <img alt="image" />
</Frame>

## Exporting Profiles

### User Profile Export via API

<Note>
  Profiles and events will always export the canonical distinct ID as shown in the UI.
</Note>

To export User Profile data, use the [Engage API](/reference/engage-query). The return payload is a JSON object, where the profiles are stored in the results key, as an array of objects where each profile is its own object.

Sample request:

```sh theme={"system"}
# Returns all user profiles in project 1234567 
curl --request POST \
     --url 'https://mixpanel.com/api/query/engage?project_id=1234567' \
     --header 'accept: application/json' \
     --header 'authorization: Basic YOUR_TOKEN' \
     --header 'content-type: application/x-www-form-urlencoded'
```

Sample payload:

```json theme={"system"}
// Your profiles are stored in an array of objects in the results key
// Each object is a separate profile
{
  "page": 0,
  "page_size": 1000,
  "results": [
    {
      "$distinct_id": 1,
      "$properties": {
        "$created": "2008-12-12T11:20:47",
        "$email": "example1@mixpanel.com",
        "$first_name": "Example1",
        "$last_name": "Name1",
        "$last_seen": "2008-06-09T23:08:40"
      }
    },
{
      "$distinct_id": 2,
      "$properties": {
        "$created": "2008-12-12T11:20:47",
        "$email": "example2@mixpanel.com",
        "$first_name": "Example2",
        "$last_name": "Name2",
        "$last_seen": "2008-06-09T23:08:40"
      }
    }
  ],
  "session_id": "1234567890-EXAMPLE",
  "status": "ok",
  "total": 1
}
```

By default, all profile properties are returned. Use the output\_properties parameter to specify specific profile properties to return.

Example: `output_properties=["$last_name", "$email", "Total Spent"]`

You may export specific cohorts by using the `filter_by_cohort` parameter. You may find the `cohort_id` in the UI next to your cohort or by using the [cohorts-list API](/reference/cohorts-list).

<Frame>
  <img alt="image" />
</Frame>

#### Group Profile Export via API

You can also leverage the [Engage API](/reference/engage-query) to export Group Profiles. To do so, provide  the `data_group_id` parameter in your Engage API request. You can find the `data_group_id` for your group keys in your project settings.

<Frame>
  <img alt="image" />
</Frame>

### CSV User Profile Export

You may export your profiles as a CSV for use in quick analysis by navigating to the Users tab, querying the profiles that you are interested in seeing, then clicking the “Export” button in the top right corner.

Only the columns shown in the UI will be exported in the CSV. You may modify the table by clicking the “Edit Columns” button to choose the profile properties to return before your export.

#### CSV Group Profile Export

To export Group Profiles as a CSV, switch the group key to your group of choice by clicking the “Analyze Uniques by” button in the top left of the UI

<Frame>
  <img alt="image" />
</Frame>

## Exporting Reports

<Note>
  Users with a Growth or Enterprise plan can use our Query API to export formatted report data. Users with a Free plan can export reports as CSV, PNG, or PDF from the UI. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

### Downloading Reports via the UI

You can download any reports as a CSV, PNG, or PDF by clicking the "..." button in the top right corner of the report UI, and then selecting "Export".

**Enterprise plan customers:** When you export a CSV from an Insights report in Bar, Stacked Bar, Pie, Table, or Metric view, you can export up to 50,000 rows of data. For all other views and reports, you can export up to 10,000 rows. If a report exceeds these limits, the export returns only the first rows in ascending order, up to the applicable limit.

**All other customers:** You can export up to 10,000 rows of data for all report types.

### Exporting Reports via API

You may use our [Query API](/reference/query-api) to export the formatted results that you see in our web app. Learn more about the [Insights API](/reference/insights-query), [Funnels API](/reference/funnels-query), and [Retention API](/reference/retention-query).

The Flows report cannot be exported using API. Please use the export method from the UI outlined above.

## Export Integrations

You can sync your Mixpanel data to your other destinations using our native connectors. Learn more about the [Data Pipeline](/docs/data-pipelines) for warehouse syncs and [Cohort Syncs](/docs/cohort-sync) for audience targeting.


# Feature Flags
Source: https://docs.mixpanel.com/docs/featureflags

Rollout with precision control

<Note>
  Feature Flags is a separately priced product add-on. It is currently only offered to those on the Enterprise Plan. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

**Feature Flags** let you control who sees a feature and when. Use them to:

* **Gradually roll out** changes (E.g 1% → 10% → 100%)
* **Target** user and group cohorts, regions, or platforms
* **Kill-switch** risky functionality instantly
* **Serve variants** for A/B/x tests and analyze results with **Mixpanel Experiments**

**Flags** deliver variants to users whereas **Experiments** measure impact with statistical rigor. Use flags to deploy and orchestrate and use experiments to decide.

## Concepts & terminology

* **Flag Key** — unique identifier for a flag used by SDKs.
* **Variant Assignment Key** — the randomization bucket unit: `distinct_id` (user), `device_id`, or a **group key** like `account_id`.
* **Variants** — experience labels (e.g., `control`, `A`, `B`).
* **Variant Splits** — allocation across variants (e.g., 90%/10%).
* **Fallback Value** — variant to use when an assignment is unavailable.
* **Sticky Variants** — the same entity keeps the same variant over time.
* **Rollout Groups** - the configuration determining which users are in the rollout. This is comprised of:
  * **Filters** — the targeting configuration that determines whether a subject is eligible for this rollout. Filter types include Cohort and Runtime filters
  * **Cohort Filter** - a targeting method that uses Mixpanel cohorts to target users or group entities
  * **Runtime Filter** - a targeting method that checks data available at runtime against a Runtime Property or Runtime Event
  * **Rollout %** — percentage of the audience that receives the flag if they are eligible for the rollout group
* **Runtime Properties** — any key/value attributes your application passes as properties in a `custom_properties` object nested within the flag-evaluation `context` at request time; the flag compares these values directly (e.g. equals / contains). They are not limited to device or platform values — any attribute your app can supply at request time, such as `organization_id`, works. Use Runtime Properties when you need **immediate**, per-request targeting on these values (e.g. organization- or account-based targeting). If periodic cohort refresh is acceptable, [group cohort targeting](#rollout-groups) is an alternative for org/account-based use cases.
* **Runtime Events** — event-based targeting (e.g., user clicked button, completed purchase) used to target users immediately after they perform actions.
* **Assignment vs Exposure** — assignment is deciding the variant; exposure is when your app **uses** that variant to render.
* **Feature Flag API Request** - is a call made to a feature flag API to retrieve the current state or configuration of one or more feature flags. This request allows an application to dynamically determine which features should be active for a user
* **Context** - key value pairs mapping variant assignment keys to user values for variant assignment

<Note>
  Users will not be reassigned different variants when purely increasing overall rollout %. If rollout % is initially increased and later decreased, or if variant splits are altered, then variation reassignment may occur for users.
</Note>

## Types of Feature Flags

We support the following types of Flags:

1. **Feature Gate** : Toggle a feature on or off for targeted users or all users. Useful for phased or controlled rollout.
2. [**Experiment**](/docs/experiments) : Deliver different variant experiences (e.g., layouts, flows, pricing) to a targeted group of users. Enables measuring and analyzing impact. Each variant can optionally carry a **string** or **JSON object** value, letting you ship per-variant configuration (e.g., a CTA label, a layout config blob) alongside the variant name. See [Experiment JSON Parameters](/docs/experiments#experiment-json-parameters).
3. **Dynamic Config** : Configure features with flexible key-value pairs instead of just on/off. It lets you:
   * Pass **string** or **JSON object** payloads (e.g., `"Buy now"` or `{"cta_text": "Buy now", "discount": 20}`) to customize behavior or UI dynamically
   * Update values instantly without redeploying code
   <Note>
     Variant values (used by both Experiment and Dynamic Config flags) have a size limit of 32 KB per variant. Within a single flag, all variants must use the same value type — either all string or all JSON object and you can switch the type later from the flag's settings.
   </Note>

## Targeting & Identity Management

<Steps>
  <Step title="Variant Assignment Key">
    This is the randomization bucket unit: `distinct_id` (user), `device_id`, or a **group key** like `account_id`.

    **How to choose the right key?**

    * **User** `distinct_id`  — best for logged-in experiences across device; a user sees a consistent experience across various sessions and devices
    * **Device** `device_id`  — best for pre-auth or acquisition flows; a device keeps a consistent variant between pre-auth and post-auth experiences.
    * **Group** `group_id` — target by account/org using a group key (e.g., `account_id`). Values for group keys will need to be supplied to the Mixpanel feature flag SDK through the `context` parameter. When a group key is selected, cohort targeting targets that group accordingly.  For example, if you have a Franchise data group with key `franchise_id`, and you want to use a flag to rollout a feature to select Franchises, then `franchise_id` should be your assignment key.

    <Note>
      You cannot change the variant assignment key of a flag once it has been enabled.
    </Note>
  </Step>

  <Step title="Variants Management">
    Variants are served / allocated around the `variant assignment key`

    Variant management includes 3 concepts -

    * Variants are the experiences to serve. (e.g., `control`, `A`, `B`).
    * Variant split % is the allocation across the variants.
      * For example, 10% of users in variant A, and 90% in variant B.
    * Sticky Variants ensures continuity in the variant experience served
      * If a user is assigned to a sticky variant B, regardless of how variant splits, rollout percentage, or cohort memberships change in the future, the user will continue to see the variant B.

    <Note>
      Control variant by is always set to non-sticky. This is to ensure this is the only group of users that can move up to other variants if allocation of other variants is increased.
    </Note>
  </Step>

  <Step title="Rollout Groups">
    Feature flags may consist of one or more rollout groups. Users are evaluated against each rollout group in order until one is found that the user qualifies for.

    You can target 'All Users', or optionally target rollout of your feature flags to subsets of your user base rather than to all your users with [Cohorts](/docs/users/cohorts). These are dynamic audiences of Mixpanel users based on user behavior or properties. Use these to target feature flags to specific subsets of your user base. For example, target only users who did 5 purchases in the last week.

    **Group Cohort Targeting**

    When the Variant Assignment Key is set to a group key (e.g., `company_id`, `account_id`), targeting uses **group cohorts** instead of user cohorts. Group cohorts are cohorts of entities matching the group key — for example, a cohort of Companies for a flag keyed on `company_id`.

    * Group cohorts are created in the same [cohort builder](/docs/users/cohorts), scoped to the relevant group key.
    * The cohort builder automatically corresponds to the the flag's assignment key.
    * Example: A flag with assignment key `company_id` lets you target a cohort like "Enterprise companies with >50 seats."

    <Note>
      - Cohorts used in feature flag targeting refresh on a periodic cadence (\~every 2 hours). So once a user or group entity qualifies for a cohort, it can take up to 2 hours before they see a desired experience.
      - If you want users or groups to continue seeing the same variant even if they disqualify from the cohort in the future, couple this with **Sticky Variants.** This will ensure they continue to see the new experience until the flag is turned off.
      - For the optimal performance, cohorts used in feature flag targeting are officially limited to 20 million users.
    </Note>

    <Warning>
      Note that cohort targeting for `device_id` assignment key flags builds cohorts against Users, not devices. Furthermore, since this targeting is against Users, it will only target authenticated Users, which could defeat the purpose of using an auth-insensitive `device_id` rollout.  If you wish to do group cohort targeting against devices, make device a Data Group and then use group targeting against it.
    </Warning>
  </Step>

  <Step title="Runtime Targeting">
    Runtime targeting enables immediate, per-request decisions. There are two types of Runtime Filters:

    **Filter by Runtime Property**

    This method enables targeting users immediately based on arbitrary key/value attributes your application sends as properties in a `custom_properties` object nested within the flag-evaluation `context` at request time. The flag compares these values directly (e.g. equals / contains) for immediate, per-request decisions.

    * Runtime Properties are **not** limited to device or platform values. They can be any attribute your frontend or app supplies at request time — for example, `platform`, `path`, `country`, or a custom value like `organization_id`. This makes them the right tool for **immediate**, per-request targeting, such as organization- or account-based targeting where you need decisions to take effect right away. If a periodic cohort refresh (approximately every 2 hours) is acceptable, [group cohort targeting](#rollout-groups) is an alternative approach for org/account-based use cases.
    * These attributes should be passed to the SDK as properties in a `custom_properties` object that is a sub-node of the feature flag `context`, at the time the flag is evaluated.

    #### Data types for runtime values

    Each condition has a **Data Type** that controls how Mixpanel interprets and compares the value. The value your application sends at request time (in the `custom_properties` object) must be in the format expected for the chosen data type. If the value can't be parsed as that type, the condition will not match. The operators available in the condition adjust automatically to the selected data type.

    | Data Type      | What your app should send                               | How it matches                                                                                                                                                                                   | Operators                                                                                                                                                             |
    | -------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **String**     | A string, e.g. `"enterprise"`                           | Case-insensitive text match for all operators. Ordered comparisons such as Greater Than, Greater than or equal to, Less than, or Less than or equal to compare strings in lexicographical order. | <ul><li>Is</li><li>Is not</li><li>Contains</li><li>In</li><li>Greater than</li><li>Greater than or equal to</li><li>Less than</li><li>Less than or equal to</li></ul> |
    | **Number**     | An integer or floating point number, e.g. `42`, `23.54` | Numeric comparison.                                                                                                                                                                              | <ul><li>Is</li><li>Is not</li><li>Greater than</li><li>Greater than or equal to</li><li>Less than</li><li>Less than or equal to</li></ul>                             |
    | **True/False** | A boolean, `true` or `false`                            | Boolean match                                                                                                                                                                                    | <ul><li>is True</li><li>is False</li></ul>                                                                                                                            |
    | **List**       | A list of values, e.g. `["a", "b"]`                     | Requires any or all elements to satisfy the condition. Each element is compared using its own data type, following that type's rules above.                                                      | <ul><li>any</li><li>all</li></ul>                                                                                                                                     |
    | **Fuzzy**      | Any primitive value                                     | Case-insensitive loose match that coerces across types before comparing, so `"5"` matches `5` and `"1"` matches `true`.                                                                          | <ul><li>Is</li></ul>                                                                                                                                                  |

    <Note>
      **Runtime Property** (targeting based on values your app *sends* in the request context) is distinct from **Runtime Event** (targeting based on Mixpanel events the user *triggers* via `mixpanel.track()`). See the section below for details on Runtime Event filters.
    </Note>

    **Filter by Runtime Event**

    This method enables targeting users immediately when they perform specific actions tracked with `mixpanel.track()`. For example, show a feature to users the first time they complete onboarding, or target users who added items to cart.

    * When adding a new filter to your rollout group, navigate to `+ Create New`, then click on `Runtime Event` to add a new runtime event filter.
    * Select an event, then optionally enable **"First Time"** to trigger only on the user's first occurrence of that event.
    * Configure the **duration** to control how long the variant persists: "End of Session" or "Indefinitely".
    * Add **property filters** for more fine-grained control (e.g., `purchase_amount > 100`, `page_path contains '/checkout'`).
    * **Examples**:
      * Target users the first time they complete the 'Sign Up' event
      * Target users who trigger 'Add to Cart' event with product\_category = 'premium'

    <Note>
      For detailed configuration options and examples, see our [Runtime Events guide](/docs/featureflags/runtime-events).
    </Note>
  </Step>

  <Step title="Rollout Percentage">
    This is the percentage of the requests that should be targeted, according to the Variant Assignment Key.

    Example: If we want to rollout to 50% of Active Users cohort, and 10% to Dormant User Cohort, we would create

    * 2 rollout groups :  Rollout Group 1 - Active Users, Rollout Group 2 - Dormant Users
    * Rollout percentage will be applied to each Rollout Group : 50% and 10% respectively

    Variant allocation happens within the roll-out group.

    Example: Building on the same example above, variant allocation is 50-50 for A/B.

    * Rollout Group 1 - Active users will see  - 25% users in A (50% of 50%); 5% users in B (50% of 50%)
    * Rollout Group 2 - Dormant users will see -  5% users in A (50% of 10%); 5% users in B (50% of 10%)
  </Step>
</Steps>

### Frequently Asked Questions

**How do [Data Views](/docs/data-governance/data-views-and-classification) affect feature flags?**

Feature flags are scoped to data views. If targeting your flag to specific user cohorts, only end users included in the data view where the flag is created, will be targeted. Only users with access to a data-view and can view and edit the flag

**Can I target a cohort, but also include run-time targeting like device or url path?**

Yes. You can couple run-time targeting with both user cohorts and group cohorts. It works with an AND condition across the targeting criteria.

**Why is control variant always non-sticky? I want all my variants to be sticky**

Control variant is set to always be non-sticky to ensure this is the only group of users that can move up to other variants if allocation of other variants is increased. This is to avoid users moving from non-control variants.

NOTE: If you do want all users to be sticky and do not anticipate needing to change the variant allocation, mark control variant as 0%, and allocate all the 100% to the other variants. This is recommended for use-cases where you have no default or control experience, and are testing a brand new experience with 2+ variants

**How do we avoid overlapping target audiences across 2 different feature flags?**

Let's say we have 2 features: feature A and feature B, and we want these to be non-overlapping in audience targeting. In the feature flag B page, in the target audience -

* Create Rollout Group 1: any user who was exposed to feature flag A
  * Variant served: control 100% (no new experience, revert to default)
  * Rollout % : 100%
* Create Rollout Group 2: All users, or any specific users you want for flag B

**Are there any limits to the number of variants per flag?**

Yes, today you can have a maximum of 10 variants per flag.

## Governance, permissions & audit trail

We recommend establishing light-weight controls without slowing teams.

### Permissions

* **Project Role** — you need to have at least an “analyst” role to create and edit feature flags. “Consumer” roles can only view feature flags.
  * \[coming soon] Overall Feature Flag permissions - this setting allows you to give users or teams access to all feature flags. It overrides the permissions set at a per-flag level. For example, you might want your ops-lead team to have edit access to all flags for emergencies.
* **Feature Flag Permissions** — You can manage share settings per flag.. Only editors for a flag will have access to modify a flag generally.

### Audit Trail

This shows the history of changes related to the flag. This allows you to know the change history (who, what, when) of all the updates.

### QA Testers

This section allows you to whitelist users who will receive the experience, vs rolling out more broadly. You can select users based on the \$email user profile property. Once selected, you can specify which experience you would like each user to get.

> #### 📝 Note: Selecting QA testers on Original ID Merge
>
> This behavior applies only to projects on **Original ID Merge (V2)**. Projects on **Simplified ID Merge (V3)** use a deterministic canonical user ID and do not require manual QA tester maintenance.
>
> When you add a user as a QA tester (by email or distinct\_id), Mixpanel saves a snapshot of that user's **most recent `$identified_id`** at the moment of addition, pulled from their `$identify` event history. At flag evaluation time, the `/flags/` endpoint performs an exact string match between the distinct\_id your SDK sends and this saved value — there is no cluster-aware resolution at runtime.
>
> **What this means:** if the user later identifies with a different ID than what was saved (e.g., your app's identification logic changes, the user transitions between anonymous and identified states, or your hashing scheme is updated), the saved QA tester record becomes stale, and the flag will no longer return for that user.
>
> **To recover:** remove the QA tester from the flag's configuration and re-add them. The latest `$identified_id` will be snapshotted again.
>
> **Best practice:**
>
> * Call `identify()` with a stable, consistent value for each logged-in user across sessions.
> * Add QA testers only after the target user has identified at least once with that stable value.
>
> **Debugging tip:** to verify which ID was saved for a QA tester, inspect the `/flags/` network request in your browser's developer tools. The response payload includes a `test_users` field listing the saved IDs. Compare these against the `distinct_id` your SDK is sending — if they don't match, that's the source of the issue. You can also see this in the dropdown when searching for users.

## Performance, Reliability  & security

**Privacy**

* EU & IN projects must initialize the SDK’s with the correct api host endpoints for their regions.
* You should only send the context/runtime properties you need; avoid sensitive PII.

**Regions**

Keep traffic within region by using the correct project & API hosts.

**Reliability**

Mixpanel analytics downtime will result in suspended cohort membership refreshes, though feature flag variants will continue to be served.

* When using sticky variants, the last available variant per user will be served.
* In case of Feature flagging service downtime, your fallback variant will be served by the SDKs.

**Performance**

The latency of Feature flags API responses is usually on the order of milliseconds.

NOTE: Cohort membership is refreshed every 2 hours when targeting anything aside from 'All Users'/'All Entities' or 'Runtime Filters'. Therefore, new users or group entities entering cohorts may not be reflected in Feature flags API responses for up to that 2 hour period.

## Implementation

Feature Flagging is currently supported on a subset of Mixpanel client and server SDK's. There are two modes for using feature flags. Remote evaluation is available for both client and server SDKs whereas local evaluation is available for server SDKs.

### Remote Evaluation

Remote evaluation makes a network call to Mixpanel servers each time you evaluate a flag. The server receives the user context and determines the variant assignment based on your configured targeting rules.

This is ideal for applications requiring cohort-based targeting or sticky variant assignments

### Flag Persistence

<Note>
  Flag persistence is a client SDK feature. It is officially supported on the Android, Swift, Flutter, React Native, and JavaScript (Web) client SDKs.
</Note>

By default, client SDKs fetch flag assignments from Mixpanel feature flag evaluation endpoint. If the call fails due to network issues, the SDK returns the fallback variant, which can result in an undesirable user experience.

Flag persistence lets the SDK persist assignments to the device so that they are made available, even if the network is not. This is useful for reducing latency at startup and for providing graceful degradation when the network is unavailable.

Persistence is configured with a `variantLookupPolicy`, which accepts one of three strategies:

| Policy                           | Behavior                                                                                                                                                                        |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `networkOnly` *(default)*        | No persistence of variants. Every lookup waits for a fresh network response.                                                                                                    |
| `networkFirst`                   | The SDK waits for a network response first. If the network fails, previously persisted variants are served as a fallback                                                        |
| `persistenceUntilNetworkSuccess` | Persisted variants are served immediately on launch. The next time a network call succeeds, the variants will update the in-memory state as well as be persisted to the device. |

**TTL:** Both persistent policies accept a configurable TTL (default: 24 hours). Persisted variants older than the TTL are treated as expiring and not served.

**Identity scoping:** Persisted variants are tied to the current `distinct_id`. Calling `identify()` with a different ID or calling `reset()` clears persisted data and triggers a fresh network fetch.

**Variant source:** Each returned variant carries a `source` indicating where the value came from: `network`, `persistence`, or `fallback`. This lets you know at call time whether you are looking at a fresh or persisted assignment.

**`$experiment_started` properties:** When a variant is served, the `$experiment_started` event includes a new `$variant_source` property (`"network"` or `"persistence"`). For persistence-sourced variants, two additional properties are included: `$persisted_at_in_ms` (the epoch ms when the variant set was persisted) and `$ttl_in_ms` (the configured TTL). Fallback variants do not trigger `$experiment_started`.

See the SDK-specific guides below for implementation examples.

### Local Evaluation

Local evaluation minimizes latency by evaluating flags within your application. This mode is recommended for server-side SDKs used in latency-sensitive server-side applications.

The SDK polls Mixpanel servers for feature flag configurations at a configurable interval (e.g., every 60 seconds). Flag configurations are cached and served via **Google Cloud CDN** for global low-latency access. Flag evaluation happens locally within your SDK with minimal latency (\<1ms).

As evaluation is done completely locally, cohort targeting and sticky variants are not supported.

#### Polling latency by region

Below is a table, demonstrating the average latency of polling latency for cached calls, broken down by approximate caller region.

| Region                   | Polling Latency |
| ------------------------ | --------------- |
| Singapore, APAC          | \~17ms          |
| Belgium, Europe          | \~19ms          |
| São Paulo, South America | \~23ms          |
| Iowa, USA                | \~20ms          |
| Oregon, USA              | \~20ms          |
| Virginia, USA            | \~29ms          |

#### Cache invalidation

When you update the configuration of one of your feature flags, CDN cached settings will be invalidated. Your SDK will receive updated configurations on its next poll cycle.

See our developer guides on implementing feature flags on these platforms below:

### Client Side SDKs

<CardGroup>
  <Card title="Web" href="/docs/tracking-methods/sdks/javascript/javascript-flags" />

  <Card title="iOS" href="/docs/tracking-methods/sdks/swift/swift-flags" />

  <Card title="Android" href="/docs/tracking-methods/sdks/android/android-flags" />

  <Card title="Flutter" href="/docs/tracking-methods/sdks/flutter/flutter-flags" />

  <Card title="React Native" href="/docs/tracking-methods/sdks/react-native/react-native-flags" />
</CardGroup>

### Server Side SDKs

<CardGroup>
  <Card title="Python" href="/docs/tracking-methods/sdks/python/python-flags" />

  <Card title="Ruby (Beta)" href="/docs/tracking-methods/sdks/ruby/ruby-flags" />

  <Card title="Node.js" href="/docs/tracking-methods/sdks/nodejs/nodejs-flags" />

  <Card title="Java" href="/docs/tracking-methods/sdks/java/java-flags" />

  <Card title="Go" href="/docs/tracking-methods/sdks/go/go-flags" />
</CardGroup>

### OpenFeature Providers

Mixpanel also offers [OpenFeature](https://openfeature.dev/) providers, which let you use Mixpanel's feature flags through OpenFeature's standardized, vendor-agnostic API.

#### Client Side

<CardGroup>
  <Card title="Web" href="/docs/tracking-methods/sdks/javascript/javascript-openfeature" />

  <Card title="iOS" href="/docs/tracking-methods/sdks/swift/swift-openfeature" />

  <Card title="Android" href="/docs/tracking-methods/sdks/android/android-openfeature" />
</CardGroup>

#### Server Side

<CardGroup>
  <Card title="Python" href="/docs/tracking-methods/sdks/python/python-openfeature" />

  <Card title="Ruby" href="/docs/tracking-methods/sdks/ruby/ruby-openfeature" />

  <Card title="Node.js" href="/docs/tracking-methods/sdks/nodejs/nodejs-openfeature" />

  <Card title="Java" href="/docs/tracking-methods/sdks/java/java-openfeature" />

  <Card title="Go" href="/docs/tracking-methods/sdks/go/go-openfeature" />
</CardGroup>

<Note>
  If you'd like to see Feature Flags availability in other SDKs, please [reach out to the Support team](https://mixpanel.com/get-support).
</Note>

### Other Implementation Methods

**Mixpanel Feature Flags with a Customer Data Platform (CDP)** You have two options -

* **Option 1:** Use Mixpanel SDK for purely feature flagging assignment and exposure event `$experiment_started`.
* **Option 2:** Use mixpanel SDK for only feature flagging assignment, not exposure event
  * When you initialize the mixpanel feature flag SDK, configure it to not track any `$experiment_started` events directly to Mixpanel.
  * This way you use the mixpanel SDK to serve the feature flags, but when an end-user sees exposure, they manually use their existing method of tracking events through their CDP to mixpanel to track the \$experiment\_started event

**Mixpanel Feature Flags with Google Tag Manager (GTM)** You can implement Mixpanel Feature Flags through Google Tag Manager. See the [Google Tag Manager integration guide](/docs/tracking-methods/integrations/google-tag-manager) for step-by-step instructions on initializing flags, evaluating them, and tracking exposure events via GTM.

## Identifying User Exposures

### User Profile Exposure Table

When using Mixpanel Feature Flags, exposure events will be tracked to Mixpanel, and can be viewed on a specific user's Profile Page. The Profile Page displays a table of the enabled flags that a user has been exposed to.

#### Feature Gate

When a user has been exposed to a feature flag of the type Feature Gate, a row will appear in this table displaying the most recent time that the user was exposed to the gate. When viewing the table, you can click on the right arrow button to open the associated Feature Flag page in a new tab.

#### Experiment & Dynamic Config

The Feature Flags tab on a user's profile page will display the most recently viewed variant seen by the selected user, as well as the time that the exposure event was tracked. If a user later sees a new variant, that will be displayed instead. If the flag is tied to an experiment, clicking on the right arrow will open a menu allowing the user to navigate to the feature flag page of the associated flag, or the related experiment page.

## Multiple Environments

Multiple Environments lets you treat separate Mixpanel projects as development, staging, and production environments for the same feature flag or experiment. Build and iterate on a flag (and any experiment it's tied to) in one project, then push it to another project when you're ready — without recreating it by hand. Linked flags and experiments stay connected so you can continue pushing updates over time.

### Other Environments Selector

The "Other Environments" selector appears under the **Configuration** tab of a feature flag, inside the **More** section. This panel lets you manage a flag's links to copies of itself in other projects.

#### Pushing changes

Pushing changes copies the full configuration of the source (original) flag to the linked destination flag in the other project. Any changes that exist only on the destination flag will be overwritten.

#### Other Environments Menu

This menu lists the feature flags in other projects that are linked to the current flag. From here, you can navigate to a linked flag, push the source flag's current configuration to it, or remove the connection.

#### Duplicate To Project

To duplicate a feature flag to another project, open the Other Environments menu and select **Duplicate To Project**. In the dialog, choose the destination project.

This flow is for duplicating across projects only — to duplicate within the same project, use the same **Duplicate** option within flag's overflow (`...`) menu in the top-right of the flag page .

Note that flags created as part of an experiment (experiment-type flags) cannot be duplicated from the Feature Flags page — duplicate the parent experiment instead, which will optionally duplicate the linked flag with it.

Once duplicated, the new flag is linked to the original and can be managed from the "Other Environments" menu.

#### Permissions

To duplicate a flag to another project, you need permission to create and edit feature flags in **both** the source and destination projects. The required permission level in the destination project is the same as what's needed to manually create a new flag there — governed by that project's roles and custom roles.

#### What to expect after duplicating

When a flag is duplicated to another project, time-based settings reset to the day the duplicate was created — the same behavior as duplicating within a project.

If your flag targets a cohort, Mixpanel assumes the event properties referenced by that cohort exist in the destination project. It does not validate property availability at copy time, so verify that your destination project collects the same events and properties before using the flag there.

#### Removing a connection

Removing an inter-project connection from the "Other Environments" menu unlinks the two flags — it does **not** delete the flag in the destination project. The copied flag remains in the destination project and continues to function independently; it simply loses its link to the original.

#### Data Groups

Feature Flag rollouts may include configuration that references data groups in a given project. For instance, if you change the "Assignment Key" of a flag to a data group key, both the source and destination projects *must* include the referenced data group in order to duplicate or push changes. If the assignment key is *not* present in the destination project, the operation will fail.

<Info>
  **Billing across projects:** You aren't double-charged for using the same feature flag across multiple projects. Mixpanel charges based on active feature flag keys, so the same flag-key shared across projects is counted once.
</Info>

## Feature Flagging Pricing FAQ

<Note>
  Feature Flags is a separately priced product offered to organizations on the Enterprise Plan. Please [contact us](https://mixpanel.com/contact-us/sales/) for more details.
</Note>

Pricing Unit: Feature Flags are priced based on Feature Flag API Requests, and number of 'active' feature flags at any time

**What is a Feature Flag API Request?**

A feature flag API request is a call made by your application to a Feature Flag system’s API to determine **which all features** should be enabled or disabled, or which variant should be served to a user. All the active flags in the system are evaluated as part of this API request.

**How can I estimate Feature Flag API requests?**

In general, you can expect every user session to have 1 API request. When the session starts, all the flags for the user are fetched in the single API request. So monthly API requests is at minimum equivalent to the total user sessions that month. Few notes:

* If you have multiple sdk inits each session, that would increase the count of API requests in a session
* Considering above, general rule of thumb: would consider API requests to be 1.5 x User Sessions considering implementation challenges, or multiple sdk inits in a session

**How do I estimate API requests if implementing via server side sdk?**

* If you are using server side sdk, with only local evaluation: your API requests depend on a) how many server instances you have and b) how frequently you poll your servers
* If you are using server side sdk, but with remote evaluation or leveraging cohorts: your API request estimation is similar to client-side sdk requests laid our above

**What happens if I go over my purchased Feature Flag API Request bucket?**

You can continue using Mixpanel Feature Flags, but you will be charged a higher rate for the overages.

**Is there any limit on number of feature flags per API request?**

Yes, there is a limit depending on the plan you purchase. You can choose from 3 plans: to have upto 50, 200 or 1000 'active flags' per API request.

* Once you reach this limit, no more flags will will be fetched as part of the API request until you disable some others or upgrade your plan
* Active flags are flags which are marked 'Enabled'. Only these flags are counted under the 'active flag' limit
* If you are on the 50 active flag limit, the first 50 flags based on the 'start' date are fetched

**Do I get double charged if I create the same feature flag across projects?**

No. We charge based on active 'feature flag keys'. If the same flag-key is used across projects, it will be charged only once.

**How can I monitor my account’s Feature Flag API requests consumption?**

You can see your feature flag usage by going to Organization settings > Plan Details & Billing.

**If I purchase the feature flag add-on, do I still need to purchase the experimentation add-on as well?**

Yes. Both these are separate add-ons to ensure we're compatible with your tech stack. So, if you are also looking to analyze experiments, please check our \[experimentation offering.] ([https://docs.mixpanel.com/docs/experiments](https://docs.mixpanel.com/docs/experiments))


# Runtime Events
Source: https://docs.mixpanel.com/docs/featureflags/runtime-events

Target Users Based on Behavior

<Note>
  Runtime Events is part of Feature Flags, a separately priced product add-on available to organizations on the Enterprise Plan. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

**Runtime Events** let you target users immediately based on actions they perform, not just who they are. Instead of targeting [cohorts](/docs/users/cohorts) or [properties](/docs/featureflags#runtime-targeting), you can trigger feature variants when users complete specific events tracked with `mixpanel.track()`.

**Traditional targeting**: "Show this variant to premium users"

**Runtime Event targeting**: "Display 'Next Steps' checklist immediately after user creates their first project"

### When to Use Runtime Events

Runtime Events are ideal for behavior-driven experiences:

* **Onboarding flows**: Show tutorial content after a user completes their first action
* **Progressive feature unlocking**: Unlock advanced features after users complete key milestones
* **Conditional promotions**: Display special offers after a user makes their first purchase
* **Behavior-gated experiments**: Run experiments only on users who have demonstrated engagement

## How Runtime Events Work

Think of Runtime Events as a "tripwire" that activates once. Here's the flow:

### Before the Event

1. User requests flag evaluation from your app
2. The flag service recognizes the user hasn't triggered the event yet
3. The SDK watches for the specified event

### When the Event Occurs

1. User performs the tracked event (e.g., "Purchase Complete")
2. The SDK reports the event to Mixpanel

### After the Event

1. On subsequent flag evaluations, the user now receives the active variant
2. The variant persists based on your duration setting (session or indefinitely)
3. If the variant is sticky, the user continues receiving it even if rollout changes

## Configuring Runtime Events

To add a Runtime Event targeting rule to your feature flag:

<Steps>
  <Step title="Navigate to Rollout Groups">
    Open your feature flag and scroll to the **Rollout Groups** section. Click on a rollout group card or create a new one.
  </Step>

  <Step title="Add a Runtime Event Filter">
    In the Rollout Group editor, click **"+ Add"**, then select **"Runtime Event"**. A new filter box for configuring runtime events will appear.
  </Step>

  <Step title="Select the Event">
    Click on the event dropdown (shows "Select Event" initially) and choose the Mixpanel event you want to trigger on. This can be any event tracked via `mixpanel.track()`.

    For example: `Purchase`, `Sign Up Complete`, `Dashboard Viewed`
  </Step>

  <Step title="Configure Time Window">
    The **"While Flag Enabled"** dropdown controls when events count toward activation. Currently, only events that occur while the flag is enabled will activate the variant.

    <Note>
      Only events that occur **after** the flag is enabled count toward activation. Historical events from before the flag was created or enabled are not counted.
    </Note>
  </Step>

  <Step title="(Optional) Add First Time Filter">
    Click the overflow menu (**...**) and select **"First Time"** to make this a first-time event trigger.

    When enabled, a second row appears showing:

    * **"for the"** `First Time` **"until"** `[Duration]`

    The **Duration** dropdown offers:

    * **End of Session**: Variant expires when the user's session ends
    * **Indefinitely**: Variant persists in subsequent sessions
  </Step>

  <Step title="(Optional) Add Property Filters">
    Click **"+ Filter"** to add conditions on event properties. This lets you target more specific behaviors.

    For example:

    * Event: `Purchase` where `amount > 100` (only high-value purchases)
    * Event: `Page View` where `page_path contains '/checkout'` (only checkout views)

    Each property filter has a **Data Type** (String, Number, or True/False) that controls how the event property value is compared. The value tracked on the event must be in the format expected for the chosen type, or the filter will not match. See [Data types for runtime values](/docs/featureflags#data-types-for-runtime-values) for the expected formats and operators.

    <Note>
      These property filters apply to properties of the selected runtime **event**. They narrow which occurrences of the tracked event count toward activation. If you want to target based on a value your application sends at request time (for example, an `organization_id`), use a [Runtime Property](/docs/featureflags#runtime-targeting) filter instead.
    </Note>
  </Step>

  <Step title="Assign Variants">
    On the right side of the rollout card, configure which variant users receive when they trigger the event. You can set variant splits (e.g., 50% variant A, 50% variant B) just like standard targeting.
  </Step>

  <Step title="Save the Flag">
    Click **Save** to activate your configuration. The SDK will begin watching for the specified event.
  </Step>
</Steps>

## Frequently Asked Questions

**Can I use Runtime Events with cohort targeting?**

Yes. You can combine Runtime Events with cohort targeting using AND logic. For example, "Premium users who complete their first purchase."

**What happens if I disable and re-enable the flag?**

The flag's "enabled at" timestamp updates. Users who previously triggered the event must perform it again after re-enablement to receive the variant.

**Are Runtime Events supported on server-side SDKs?**

Runtime Events are designed for client-side SDKs that can monitor events in real-time. Server-side implementations are not supported.

**How quickly does the variant activate after an event?**

The variant activates on the next call to `getVariant` or `isEnabled` after the event is reported.

## Related Documentation

* [Feature Flags Overview](/docs/featureflags)
* [Experiments](/docs/experiments)
* [Cohorts](/docs/users/cohorts)


# Features
Source: https://docs.mixpanel.com/docs/features



<CardGroup>
  <Card title="Alerts" href="/docs/features/alerts" />

  <Card title="Annotations" href="/docs/features/annotations" />

  <Card title="Embeds" href="/docs/features/embeds" />

  <Card title="Chart Customization" href="/docs/features/chart-customization" />

  <Card title="Comments" href="/docs/features/comments" />

  <Card title="Custom Buckets" href="/docs/features/custom-buckets" />

  <Card title="Custom Events" href="/docs/features/custom-events" />

  <Card title="Custom Properties" href="/docs/features/custom-properties" />

  <Card title="MCP Integration" href="/docs/features/mcp" />

  <Card title="Saved Metrics & Behaviors" href="/docs/features/saved-metrics-and-behaviors" />

  <Card title="Sessions" href="/docs/features/sessions" />

  <Card title="Slack Integration" href="/docs/features/slack-integration" />
</CardGroup>


# Alerts
Source: https://docs.mixpanel.com/docs/features/alerts

Get notified about anomalies in your data

<Note>
  Users with a paid plan can access Alerts. Growth plan users can set up to 5 alerts per project. Enterprise plan users can set an unlimited number of alerts. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

Mixpanel provides the ability to create alerts for your Insights and Funnels reports, allowing you to monitor custom report conditions or automatically detect anomalies and receive notifications when those conditions are met.

Alerts are accessible directly from the **bell icon** in any report header, and can be delivered via email, Slack, or webhook. You can also control *when* alerts fire by setting notification windows restricted to specific days and times, so you only get notified when it matters.

When an alert is active, Mixpanel continuously monitors its validity — surfacing warnings if report changes could affect it — and sends a one-time email if an alert ever becomes invalid. Additionally, Mixpanel's Root Cause Analysis feature helps you investigate and understand the underlying data behind any triggered alert.

## Create an Alert

<Note>
  To create and manage alerts, you will need an analyst, admin, or owner project role. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

Create an alert for your Insights and Funnels reports and be notified when report conditions reach certain thresholds. Alerts can be delivered via email, Slack, or webhook, and can be sent to multiple recipients.

**To create an alert, follow these steps:**

1. Open a saved report and click the **bell icon** in the report header. *Note: You won't be able to create an alert if the report has unsaved changes. Save your report before setting up an alert.* If no alerts exist on the report, the modal will show *"No alerts for this report."* Click **Create Alert** in the bottom right of the modal.
2. **Enter a name** for your alert.
3. If your report has more than one event, select an event to track. If your report has a breakdown applied, either select a specific segment to alert on, or select **Any segment** to be alerted when any segment matches the alert criteria.
4. **Set your alert criteria.** Depending on the report type, choose between Anomaly Detection or Custom Threshold. See [Alert Criteria Types](#alert-criteria-types) below for details on each.
5. **Set your notification frequency.** Choose how often *at most* you'll receive an alert — from hourly up to monthly. *Note:*

   * *For time-series reports, how often Mixpanel checks your data is determined by the time bucket of your report visualization. For example, if your chart is hourly, the alert will be evaluated at an hourly interval.*
   * *If you have an hourly chart but set the alert frequency to daily, Mixpanel checks for a match every hour. If a match is found, the alert fires and won't check again until the next day.*
6. **Set your notification timing.** Choose when the alert is allowed to fire:

   * **Any time** — the alert fires whenever the condition is met, regardless of day or time.
   * **During Selected Windows** — restrict the alert to specific days and/or time ranges. See [Notification Windows](#notification-windows) below.
7. **Set your notification delivery preferences.** When alert conditions are met, Mixpanel can notify you via email, Slack, or webhook.

   * **Email** — enter the recipient's email address. You can enter any email, not just Mixpanel users.
   * **Slack** — select the Slack channels to notify. Private Slack channels are not supported. You may need to configure the Mixpanel Slack app first — click **Add Mixpanel to Slack** and follow the prompts.
   * **Webhook** — select a configured webhook from the dropdown. See [Webhook Alerts](#webhook-alerts) for setup instructions.

<Frame>
  <img alt="" />
</Frame>

8. Optionally, click **Test Alert** to send a test notification before saving. See [Test Alert](#test-alert) below.
9. **Save** the alert.

## Notification Windows

When you select **During Selected Windows** in step 6 of alert creation, a day-by-day schedule appears. Each row represents a day and supports an optional time range, letting you restrict when the alert is allowed to fire.

**Adding windows:**

* **Add Single Day Window** — adds a row for a specific day with an optional time range.
* **Weekdays** — quick-adds rows for Monday through Friday.
* **Weekends** — quick-adds rows for Saturday and Sunday.

**Managing individual rows:**

Each day row has a `...` overflow menu with:

* **Duplicate Day Window** — copies the row's time window to a new row.
* **Remove Time Window** — clears the time range from that row but keeps the day active (alert can fire any time on that day).
* **Delete Day Window** — removes the entire day row from the schedule.

*Note: Notification windows restrict when the alert fires, not when Mixpanel checks your data. Mixpanel will still evaluate the alert condition according to its frequency — it just won't send a notification outside your defined windows.*

## Test Alert

The **Test Alert** button is available in both the Create and Edit alert flows. Clicking it sends a test notification to all configured recipients (email, Slack, and/or webhook) immediately — without saving the alert.

Test notifications are identical in format to live alert notifications, but the alert name is prefixed with **\[TEST]** so recipients know it isn't a real firing.

Use Test Alert to confirm your delivery settings are correct before saving.

## Alert Status & Validity

Mixpanel actively tracks whether each alert is in a valid state and surfaces this information directly in the report.

### Bell icon status

When a report has one or more alerts, the **bell icon** in the report header shows each alert's name and current status:

* **✅ Valid** — the alert is active and monitoring as expected.
* **Invalid** — the alert's configuration no longer matches the current report (for example, the event or breakdown it was tracking has changed). Invalid alerts will not fire until corrected.

Click any alert name in the bell icon modal to open it and edit.

### Warning banner for unsaved changes

If you've made unsaved changes to a report that has active alerts, an **orange warning banner** appears in the bell icon modal. This is a preemptive notice — it means your current unsaved changes *could* affect the alert if saved. The alert's status will still show ✅ Valid until you actually save the report.

### Save Report Changes modal

When you save a report that has active alerts, a **Save Report Changes** modal appears listing the affected alerts (name, creator, creation date). This gives you a chance to review the impact before confirming. You can choose to:

* **Save changes** — saves the report and potentially invalidates the listed alerts.
* **Save as new report** — creates a new copy of the report with your changes, leaving the original report and its alerts untouched.

> **Tip:** If you want to update a report without breaking existing alerts, use **Save as new report** and recreate the alert on the new version.

### Invalid alert notification email

When an alert first becomes invalid, Mixpanel sends a **one-time email** to the alert's creator notifying them. This email is sent only once — if the alert remains invalid, no further emails are sent. Open the alert from the bell icon modal to see the reason for invalidation and how to fix it.

## Webhook Alerts

Webhook Alerts allow you to send alert notifications from Mixpanel to third-party platforms via HTTP webhooks. When a configured alert is triggered, Mixpanel will automatically send a payload containing alert details to your specified endpoint.

**Creating a Webhook:**

1. Navigate to **Gear Icon** > **Destinations** > **Notification Webhook**. Note this is separate from [Custom Webhooks](/docs/cohort-sync/webhooks) (which are used to sync cohorts).
2. Under Project Webhooks, click **"+ Add Webhook"**.
3. Complete the webhook configuration:

   * **Name** — enter a descriptive name (e.g., "Production Alerts").
   * **URL** — enter the HTTPS endpoint where alert payloads will be sent.
   * **Username** — if your endpoint requires HTTP Basic Authentication, enter the username.
   * **Password** — enter the corresponding password for authentication.
4. Click **Test connection** to verify connectivity.
5. Click **Submit** to save the webhook.

You can also manage webhooks directly from **Project Settings > Alerts** via the **Manage Webhooks** button in the table toolbar.

**Configuring Webhook Delivery for an Alert:**

1. When creating or editing an alert, scroll to the **Notify** section.
2. Locate the **via Webhook** dropdown.
3. Select your webhook from the available options.

<Frame>
  <img alt="image.png" />
</Frame>

4. Complete the rest of your alert configuration and save.

**Sample payload received from the Webhook:**

```json theme={"system"}
{
    "event_type": "custom_alert_triggered",
    "alert": {
        "id": 123123,
        "name": "Webhook Test",
        "creator": "Last Name, First Name",
        "creator_email": "first_name.last_name@example.com",
        "project_id": 9876543,
        "project_name": "My Prod project",
        "fired_at": "2026-02-06T10:53:30Z",
        "workspace_id": 12345,
        "workspace_name": "All Project Data"
    },
    "condition": {
        "type": "absolute",
        "operator": ">",
        "threshold": 0,
        "current_value": "20,000",
        "formatted_value": "20,000",
        "sentence": "above 0"
    },
    "report": {
        "name": "Custom Alert Insights Report",
        "type": "insights",
        "url": "https://mixpanel.com/project/9876543/view/12345/app/insights?mp_source=webhook&alert_id=123123#report/BOOKMARKID"
    },
    "links": {
        "report_url": "https://mixpanel.com/project/9876543/view/12345/app/insights?mp_source=webhook&alert_id=123123#report/BOOKMARKID",
        "edit_alert_url": "https://mixpanel.com/settings/account/alert-settings/alert/123123?mp_source=webhook",
        "root_cause_analysis_url": "https://mixpanel.com/project/9876543/view/12345/app/boards/?mp_source=webhook#rca=123123&time=1770404010"
    }
}
```

## View & Manage Alerts

### Alerts table (Project Settings)

To view and manage all alerts across a project, navigate to **Project Settings > Alerts**. This table gives you full visibility into every alert in the project, with the following columns:

| Column             | Description                                                |
| ------------------ | ---------------------------------------------------------- |
| **Creator**        | Avatar/initials of the user who created the alert          |
| **Last Modified**  | Relative timestamp of the most recent edit                 |
| **Report**         | The linked report the alert is monitoring                  |
| **Triggers**       | Total number of times the alert has fired                  |
| **Last Triggered** | Date of the most recent firing (or `–` if never triggered) |
| **Status**         | ✅ Valid or invalid                                         |

**Filtering the table:**

Use the filters in the toolbar to narrow the list:

* **All Creators** — filter by alert creator
* **Report** — filter by associated report
* **All Statuses** — filter by valid or invalid
* **Search** — free-text search by alert name
* **Reset Filter** — clears all active filters

**Row actions:**

Each alert row has a `...` overflow menu with:

* **RCA** — opens a Root Cause Analysis board for that alert
* **Alert History** — opens a side panel with a timestamped log of created, edited, and fired events for the alert
* **Edit Alert** — opens the alert configuration
* **Delete Alert** — permanently removes the alert

**Anomaly Detection capacity warning:**

If your organization is approaching the 50 active Anomaly Detection Alert limit, a blue info banner appears at the top of the table:

> *"Your organization is approaching the limit for active anomaly detection alerts. Delete old anomaly detection alerts to make space for new ones. X/50 alerts used. Y% capacity."*

This banner appears when your org reaches 90% of the limit (45 of 50 alerts). Delete old anomaly detection alerts from this table to free up capacity.

**Managing webhooks:**

Click the **Manage Webhooks** button in the table toolbar to add or edit webhook configurations for alert delivery.

### Editing and deleting alerts

* **To edit** an alert you created, click its name from the bell icon modal in any report, or use the **Edit Alert** option in the `...` menu in Project Settings > Alerts.
* **To delete** an alert, hover over it in the Alerts table and click the **trash icon**, or use the **Delete Alert** option in the `...` overflow menu.

### Alert History

Click **Alert History** from any row's `...` menu to view a side panel showing a full timestamped log of activity for that alert — including when it was created, edited, and each time it fired. This is useful for auditing unexpected behavior or understanding alert patterns over time.

### Permissions

| Scenario                                                                 | What you can do                                                                            |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| You have **Edit access** to a report                                     | You can create, edit, and delete all alerts on that report — even alerts created by others |
| You **lack Edit access** to a report                                     | You cannot create alerts on that report                                                    |
| You **lack Edit access** to a report where someone else created an alert | The alert is view-only; an explanatory banner appears in the UI                            |

*Note: Permissions are evaluated at the **report level**, not just the project level. If a user can't edit an alert, confirm their access to the underlying report first.*

## Alert Criteria Types

Alerts can be configured to trigger based on a metric reaching above or below a custom threshold you defined, or through our Anomaly Detection model.

### Custom Threshold

Custom Threshold alerts monitor your metrics and notify you when the metric reaches above or below the threshold that you defined.

* **Above** — the alert fires if the current value is above the set threshold.
* **Below** — the alert fires if the current value is below the set threshold.
* **Increases by more than** — available in line chart reports. Compares the current value with the previous value (based on the report's time-series setting). Fires if the new value has increased by the specified amount or percentage.
* **Decreases by more than** — available in line chart reports. Fires if the new value has decreased by the specified amount or percentage below the previous value.

### Anomaly Detection

<Note>
  Users on the Enterprise plan can create Anomaly Detection alerts. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Anomaly Detection alerts automatically monitor your metrics and notify you when significant anomalies occur. Mixpanel uses advanced forecasting algorithms to calculate expected ranges for your metrics. If a data point falls outside the calculated confidence interval, you'll receive an alert — no manual threshold configuration required.

**Before you begin:**

* Anomaly detection alerts are only available on Insights reports using a time series visualization.
* Anomaly detection is only supported on line charts without comparisons, rolling ranges, cumulative types, or cohorts over time.
* Hourly anomaly detection alerts may produce more false positives due to reduced forecast accuracy at that granularity.

**To set up an Anomaly Detection alert:**

1. Click the **bell icon** in the report header, then click **Create Alert**.
2. Select **Anomaly Detection** as the alert type. *If Anomaly Detection is unavailable, it is not supported for your current report or chart type.*
3. Optionally adjust the confidence interval to tune sensitivity. Higher confidence intervals produce a wider expected range and fewer alerts.
4. Use the alert preview to fine-tune settings, then configure delivery and save.

### Additional information

**Forecasting tool**

Anomaly Detection uses an LLM forecasting tool designed for time series data. This handles missing data points, trend shifts, and large outliers effectively.

**Confidence interval**

The confidence interval reflects the level of certainty that a detected anomaly represents an unexpected change. Higher confidence levels generally result in fewer anomalies detected.

**Anomaly Detection limit**

Each organization has a limit of 50 active Anomaly Detection Alerts. A warning banner appears in Project Settings > Alerts when your org reaches 90% capacity (45/50). Delete old alerts to create space for new ones.

**Rounding in alert messages**

When displaying decimal values, the current value shown in alert messages is rounded to 2 decimal places. This can make it appear to be outside the alert range when it is very close to the boundary. The actual alert is always checked against the full unrounded value.

## Root Cause Analysis

When an alert fires, you can launch AI-powered [Root Cause Analysis](/docs/root-cause-analysis) directly from the trigger notification to automatically diagnose what drove the change. See the [Root Cause Analysis](/docs/root-cause-analysis) page for the full feature.


# Annotations
Source: https://docs.mixpanel.com/docs/features/annotations



## Overview

Annotations add valuable context to your reports by linking notes to specific dates. Use them to highlight events such as product launches, marketing campaigns, or data anomalies, so viewers can clearly understand what influenced the metrics.

You can view Annotations directly on time-series charts and in the Annotations side panel across all reports.

## Adding Annotations

<Steps>
  <Step title="Open the Annotations side panel to create an annotation">
    Select the **Annotations** tab (above the query builder) and click the “+” button to add a new annotation.

    <Frame>
      <img alt="annotations2" />
    </Frame>
  </Step>

  <Step title="Alternatively, you can create annotations from the bottom of a time-series Insights report">
    Charts with time intervals (such as line, stacked line, column, and stacked column charts) are time-series charts and support Annotations.

    Hover over the horizontal axis to locate the time interval, then click the “+” button to create an annotation for that point in time.

    <Frame>
      <img alt="annotations1" />
    </Frame>

    You can also switch over to the [Annotation Timeline](/docs/features/annotations#annotations-timeline) to see all annotations within the date range and create a new annotation.
  </Step>

  <Step title="Select a date and time, then enter a description">
    Add one or more tags to categorize the annotation.

    <Frame>
      <img alt="annotations3" />
    </Frame>

    <Note>
      Use tags consistently (e.g., Launches, Outages, Holidays, and even Team names) so it is easy to filter and spot patterns.
    </Note>
  </Step>
</Steps>

## Viewing Annotations

Annotations appear as markers directly on the chart. Hover over a marker to view its details.

For example, in the chart below, you can see 1 annotation in March, 4 in May, and 2 in July.

<Frame>
  <img alt="annotations4" />
</Frame>

### Annotations Side-panel

Open the Annotations side panel (available in all reports) to view all annotations for your report's date range in one place. Select the **Annotations** tab (above the query builder) to open the side-panel.

From the side panel, you can:

* **Browse** all annotations within your report's date range.
* **Hide/Show** annotations
* **Sort** by date
* **Filter** Annotations by tags

<Frame>
  <img alt="annotations5" />
</Frame>

When you save a report, Mixpanel also saves your current annotation filters. The report will then display only the annotations that match your selected tag filters.

### Annotations Timeline

Open the Annotations Timeline (available in time-series Insights reports) to view all annotations for your report's date range in one place. Once you are on a time-series Insights report (such as a line chart), select the **charts and annotations** view option to open the Annotations Timeline.

From the timeline, you can:

* **View** annotations in a timeline format relative to their position on the time-series chart.
* **Browse** all annotations within your report's date range.
* **Hide/Show** annotations
* **Filter** Annotations by tags

<Frame>
  <img alt="annotations7" />
</Frame>

## Editing and Deleting Annotations

Hover over any existing annotations to see available actions. Clicking the "pencil" button allows you to edit the description and add/remove tags - do note that timestamps can't be edited. Clicking the "trash" button permanently deletes the annotation.

<Frame>
  <img alt="annotations6" />
</Frame>

<Warning>
  Annotations apply globally across the project. Any edits or deletions affect not only the current report but all reports in the project.
</Warning>

## Collaboration and Visibility

* Users with a project role above consumer can create annotations, and each annotation displays the creator’s name.
* Annotations are visible across all reports in the project.
* Use tags and filters to control which annotations appear at the report level.


# Chart Customization
Source: https://docs.mixpanel.com/docs/features/chart-customization

Configure your report axis and color

## Overview

Chart customization allows you to have finer grain control in how you want to visualize your charts in Mixpanel. You can customize the color theme of the visualization, as well as control the axis boundaries, axis labels, choose to use a secondary y-axis, and more. You are able to save these changes to your report and your board so you can present a clearer picture of what is happening with your data.

## Axis Customization

Axis customization is available for all visualizations with a y-axis. The supported visualization types are:

* Line
* Stacked Line
* Column
* Stacked Column
* Funnel Steps
* Retention Curve

### Left & Right Y-Axis

<Frame>
  <img alt="Left Axis" />
</Frame>

For each of the left and right y-axes, you have access to several customizations:

* **Visibility**: "Visible" or "Hidden". Use this to visually hide the axis. Note that axis and its bounds still apply, it is only the axis guides that is hidden. Use this to really focus on the trend.
* **Label**: The y-axis label
* **Axis Unit**: Displays a unit for the axis markers. You can choose to denote a prefix or suffix for the unit.
* **Threshold**: The minimum and maximum value for the axis. Use this to set an explicit range to zoom in or out for your trend.
* **Decimals**: Configures the number of decimals places to show for marker values on the axis. Configurable from 0 to 8.
* **Scale**: "Linear" or "Logarithmic". Use this to more clearly show trends for exponential data.

### X-Axis

<Frame>
  <img alt="X Axis" />
</Frame>

For the x-axis, you have access to the follow customizations:

* **Visibility**: "Visible" or "Hidden". Use this to visually hide the x-axis.
* **Label**: the x-axis label
* **Weekends**: "Visible" or "Hidden". Use this to visually hide weekends from Line and Column charts.

  * Weekend days are determined by your project's weekend settings.
  * This is a visual change only - alerts and aggregations (such as average, max, or sum) are not affected.
  * Annotations from hidden weekends are grouped with the datapoint just before the weekend.

### Axis Assignment

<Frame>
  <img alt="Axis Assigment" />
</Frame>

For every metric in your report, they by default assigned to the left y-axis. To visualize correlation between different metrics on different scales, it can be useful to use a secondary y-axis on the right. You can select the left or right buttons for each metric to choose which axis the metric is assigned to.

## Metric Units

<Frame>
  <img alt="Metric Unit" />
</Frame>

You will find unit configuration in the bottom left of every metric block. This space allows you to configure various aspects of a metric. These selections will update in the chart, tooltip, and the table below the chart. This is saveable to your report, and it will in turn persist to the board view.

Available configurations:

* Unit: choose from the presets, or choose custom to choose any unit for your metric. For certain metrics like conversion rate, Mixpanel will default to the appropriate unit
* Abbreviation: choose whether or not the result should be abbreviated. Useful for large numbers
* Precision: choose how much decimal precision should appear for values

### Units on Formula

<Frame>
  <img alt="Formula Unit" />
</Frame>

For any formula, you can save the unit configuration associated with it. In the example above, this formula is a percentage based metric. The `%` unit is saved to this formula. Any future usage of this formula across all reports will automatically use the `%` unit.

### Units on Numeric Properties

<Frame>
  <img alt="Numeric Property Unit" />
</Frame>

In lexicon, for any numeric property you can save the unit configuration associated with it. For example, if you have a `price` property that you know is in `$`. You can set this, and any future usage of this property in measurements will default to using `$` so this no longer needs to be set on every usage.

## Theme Customization

## Availability

Currently, theme and color customization is available only for customers on our Enterprise plan.

### Selecting a Theme

<Frame>
  <img alt="Select Theme" />
</Frame>

When creating a Mixpanel report, look for the "Chart" tab in the query builder panel. This is located in the top right of the page by default. After selecting "Chart", go to the "Theme" section.

<Frame>
  <img alt="Select Theme" />
</Frame>

You'll see the current default theme, along with other theme options. You can select any of the available themes to apply to your report. You can also [create](/docs/features/chart-customization#creating-&-editing-a-theme) a theme.

### Creating & Editing a Theme

<Frame>
  <img alt="Create Theme" />
</Frame>

Hit "New" in the theme section to create a theme. You will be able to create a theme using the currently selected theme as the starting point. You are able to make these modifications to a theme:

* selecting a color in the theme, then typing in a color hex code, or using the color picker to select the color
* pressing the "plus" button to add an additional color to the theme
* pressing the "trashcan" button to remove a color from the theme
* press the "sun" or "moon" icon to switch between light/dark mode to adjust the theme in each mode

Once you are satisfied with the theme, you can press "Apply" to apply the theme for only this report. You can also choose to [save](/docs/features/chart-customization#saving-a-theme) your theme to reuse in other reports.

<Frame>
  <img alt="Edit Theme" />
</Frame>

When in the theme panel, for any saved theme that you have access to, select the overflow in the top right of the theme, then select "Edit". You'll be able to make any edits to the theme. When ready, select "Update Theme" to completing editing the theme.

### Saving a Theme

After creating or making modifications to a theme, select "Save Theme".

<Frame>
  <img alt="Save Theme" />
</Frame>

You'll be able to see the colors of the theme in light and dark mode. After giving the theme a name, you can save your theme. You can also choose to give other users in your project access to your theme. Choose "Viewer" if you wish other users to have access to your theme, but not to modify it. Choose "Editor" if you wish other users to have full access to your theme.

### Deleting a Theme

<Frame>
  <img alt="Delete Theme" />
</Frame>

When in the theme panel, for any theme that you have access to, select the overflow in the top right of the theme, then select "Delete". You'll be prompted to confirm, and then the theme will be deleted. Any existing report that was using the theme will continue using the same colors of the theme, as if it were using an unsaved theme.

### Setting a Project Default Theme

<Frame>
  <img alt="Project Default Theme" />
</Frame>

You can set a theme as the default theme for a project. This means that any report that has not configured a theme and any new report created will use the chosen theme going forward. By default, every project uses the "Mixpanel" theme. In "Project Settings", under "Overview", go to "Color Theme Settings" and hit the edit icon. Then select your desired theme and press save.

## Segment Coloring

<Frame>
  <img alt="Segment Color" />
</Frame>

Select a segment from the legend and set the color for that segment. By default, Mixpanel will automatically assign a color for the segment, but you have the option to choose a color from the current theme, or choosing a color from outside the theme. You are able to select the segment from the legend in either Boards or in report.

<Frame>
  <img alt="Segment Color" />
</Frame>


# Comments
Source: https://docs.mixpanel.com/docs/features/comments



## Overview

Comments let you discuss data directly on reports and boards in Mixpanel. Instead of switching to Slack or email to share a finding, you can start a threaded conversation right where the data lives — keeping context attached to the chart or dashboard that prompted the discussion.

Comments are available on all report types and on boards. Each report or board has its own comment thread, and all project members with the appropriate permissions can participate.

## Adding Comments

<Steps>
  <Step title="Open the Comments panel">
    Select the **Comments** icon in the report or board header to open the comments side panel.

    <Frame>
      <img alt="comments1" />
    </Frame>
  </Step>

  <Step title="Start a new thread">
    Click the comment composer at the top of the panel to start a new thread. Type your message and press **Enter** (or click the send button) to post.

    <Frame>
      <img alt="comments2" />
    </Frame>
  </Step>

  <Step title="Reply to an existing thread">
    Click on any existing comment to expand the thread and add a reply. Threads keep related discussion grouped together so conversations stay organized.

    <Frame>
      <img alt="comments3" />
    </Frame>
  </Step>
</Steps>

## @Mentions

Tag teammates in a comment by typing `@` followed by their name or clicking the `@` symbol underneath the composer box. Mentioned users will receive a notification in the notification center and, if configured, via email or slack.

<Frame>
  <img alt="comments4" />
</Frame>

## Reactions

React to any comment with emoji reactions. Hover over a comment and click the reaction button to add yours.

## Resolving Threads

Mark a thread as resolved when the discussion is complete. Resolved threads are hidden by default but can be viewed by toggling the **Show resolved** filter in the comments panel.

<Frame>
  <img alt="comments5" />
</Frame>

This is useful for tracking action items — once a question about a metric change is answered or an issue is addressed, resolve the thread to keep the panel focused on active discussions.

## Notification Center

The Notification Center keeps you informed about comment activity across all your reports and boards. Access it from the bell icon in the left navigation panel.

New notifications are indicated by a red bubble on the comment icon.

<Frame>
  <img alt="comments6" />
</Frame>

You will receive notifications when:

* Someone **@mentions** you in a comment
* Someone **replies** to a thread you are participating in
* Someone **replies** to a thread you are subscribed to

Each notification links directly to the relevant report or board, so you can jump straight to the conversation with one click.

### Unread tracking

Unread notifications are indicated by a badge count on the bell icon. Notifications are automatically marked as read when you view them in the Notification Center.

## Enabling and Disabling Comments

The report owner can enable or disable comments on reports. The toggle is located in the caret menu within the report's comment tab.

<Frame>
  <img alt="comments7" />
</Frame>

When comments are disabled, existing comments are preserved but hidden and no new comments can be added. Comments on boards are always enabled for users with the appropriate permissions.

## FAQ

### Are comments shared across the project?

No. Comments are scoped to the individual report or board where they are posted. They are only visible to users who have access to that specific report or board.

### Can I get notified in Slack when someone comments?

Yes, comments are sent through the Mixpanel slack app.

### Do comments appear on public boards?

No. Comments are only available to authenticated project members with the appropriate permissions. Public board viewers cannot see or add comments.


# Computed Properties
Source: https://docs.mixpanel.com/docs/features/computed-properties



## Overview

Computed Properties are a specialized type of property that Mixpanel calculates dynamically at query time on the front end. Unlike standard event or profile properties, Mixpanel does not ingest Computed Properties with your raw data. Instead, it derives them in real time using the existing data in your dataset.

You can find Computed Properties labeled with the 'Computed' tag in the query builder.

<Frame>
  <img alt="/computed_properties" />
</Frame>

## Behavioral Properties

Behavioral properties allow you to use your user's activity and use it as a property in your other analysis. A behavioral property is a virtual property, meaning it's not a property that you are explicitly tracking, but a property that Mixpanel can compute and allow you to use in analysis.

Behavioral properties can be used anywhere, most typically in filters and breakdowns.

### Frequency per User

After selecting this option, you must select an event to compute the frequency of. You can use this to segment your users by how many times they did an event, or use it to filter out users to only those who did an event a certain number of times.

### Aggregate Property per User

After selecting this option, you must select an event, and then a property on that event. Finally, you can choose an aggregation type for this property. You can use this to segment your users by this property aggregation. For example, you may want to filter only for users who have greater than 100 minutes of video watch time, or you may want to segment users by their watch time.

### Time Range

#### Per Interval

In insights, the time at which this computation is done is on a per-interval basis. For a line chart, that will be for each interval plotted on the chart. For bar, table, and pie, this interval is the entire date range selected in the date picker.

#### Between Steps

In funnels, the behavioral property is computed in the time range between 2 steps in your funnel. You can specify which steps in the funnel this applies to. In the case of doing "Frequency per User", the event count does not include the events that make up the funnel itself, and **only** the events between the funnel steps.

#### After Step 1

In retention, the behavioral property is computed in the chosen time range after the entry event, up until the expiration window. For example, there may be a 7-day window in which we're looking for an event. Even if the retaining action happens before the 7 days are up, we continue to count additional events.

## Duration

The duration property returns the duration between 2 instances of an event. This works best for events that occur continuously during a session, such as Page View or Screen View. Users who did not track the same event again will appear in the "Did not convert" segment.

## Attribution

<Note>
  Users on an Enterprise or Growth plan can access the Attribution feature. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Attribution helps teams attribute conversion credit to the touchpoints in a user journey, whether it's to the first or last touch (single-touch attribution models) or to multiple touchpoints using a multi-touch attribution model like U-shape or Linear.

Consider the following example user journey:

1. A user sees an ad for a product on Facebook
2. The user clicks on the ad and is taken to the product page on the company's website
3. The user adds the product to their cart and begins the checkout process
4. The user abandons the checkout process
5. The user receives a retargeting ad for the product on Instagram
6. The user clicks on the ad and completes the purchase

In this example, two touchpoints contribute to the successful conversion: the Facebook ad and the Instagram ad. Using an attribution model, we can assign different weights to these touchpoints to determine their relative importance in the conversion.

* Using a linear attribution model, we could assign a weight of 0.5 to each touchpoint, meaning that both the Facebook ad and the Instagram ad contributed equally to the conversion.
* Using a J-shaped attribution model, we could assign a weight of 0.75 to the Facebook ad and 0.25 to the Instagram ad.
* Using a Last Touch model, the complete conversion can be attributed to the Instagram ad.
* Using a First Touch model, the complete conversion can be attributed to the Facebook ad.

### Usage

<Frame>
  <iframe />
</Frame>

1. Add your conversion metric
2. Attribution makes sense only when distributing the conversion metric across segments. So head to the breakdown section and choose the Mixpanel computed property - `Attributed by..`
3. In the second layer that opens up, choose the property you want to break-down by (eg. UTM medium). You can also choose a custom property to breakdown here, for example marketing channel which generally is a combination of UTM medium, UTM source and referrer.
4. You have a working attribution model.  By default, Mixpanel will assign the metric the Last touch model with a 30 day lookback window. To change the model, head to the metric section
5. If you want to include only certain channels or touchpoints in your attribution analysis, you can filter touchpoints from the breakdown overflow menu. A use-case for this is excluding organic touchpoints from attribution analysis.

👉🏽 NOTE: if you are running attribution predominantly on UTM\_medium, UTM\_source, UTM\_campaign, make sure you’re tracking UTM parameters as event properties on every user touchpoint. If you use a Mixpanel js-sdk, we have updated our sdk to track utm parameters more effectively to support multi-touch attribution models.

### Attribution Models

* First Touch: Gives 100% credit to the first touchpoint within the attribution lookback window
* Last Touch: Gives 100% credit to the last touchpoint within the attribution lookback window
* Linear: Gives equal credit to every touchpoint seen leading up to a conversion within the attribution lookback window
* Participation: Gives 100% credit to every unique touchpoint seen within the attribution window. The total number of conversions is inflated compared to other attribution models. For example, with 5 property values, each would receive 100% credit, showing 5 conversions.
* Time-Decay: The weight of each channel depends on the amount of time that passed between the touch point initiation and the eventual conversion. This model follows an exponential decay with a 7-day half-life parameter.
* U-shaped: Gives 40% credit to the first touchpoint, 40% credit to the last touchpoint, and divides the remaining 20% to any touchpoints in between. With 2 touchpoints, the credit is normalized (50%, 50%). With 6 touchpoints, the middle 4 touchpoints would share the 20% (40%, 5%, 5%, 5%, 5%, 40%).
* J-shaped: Gives 20% credit to the first touchpoint, 60% credit to the last touchpoint, and divides the remaining 20% to any touchpoints in between. With 2 touchpoints, the credit is normalized (25%, 75%). With 6 touchpoints, the middle 4 touchpoints would share the 20% (20%, 5%, 5%, 5%, 5%, 60%).
* Inverse J-shaped: Gives 60% credit to the first touchpoint, 20% credit to the last touchpoint, and divides the remaining 20% to any touchpoints in between. With 2 touchpoints, the credit is normalized (75%, 25%). With 6 touchpoints, the middle 4 touchpoints would share the 20% (60%, 5%, 5%, 5%, 5%, 20%).
* Custom: Customize the weight to be given to the first and last touchpoint, and all other touchpoints in between, based on your use-case.

### Glossary

* **User journey:** Consists of touchpoints and the conversion event. It is possible for a conversion event to have no corresponding touchpoints (e.g., UTM parameters). In this case, we consider it a ‘direct’ conversion.
* **Conversion**: The primary event you are interested in analyzing with multi-touch attribution models. Typically, some final value-generating interaction, such as “Signup”, “Upgrade”, or “Payment”.
* **Touchpoint**: These are actions (events) a user has taken or been exposed to along the journey before doing the conversion event. For example, a user does event A → B → C → D (conversion event) in a 7-day period. For a lookback window of 7 days, A, B, and C are all considered touchpoints.
* **Attributed by property:** This is the property on a touchpoint event that we use for the attribution model. The canonical example is utm\_source.
* **Lookback window:** The time window where a user's events with this attribution property are counted towards the calculation. The window ends when the conversion metric happens.

### Attribution FAQ

**1. How does Mixpanel compute attribution under the hood?**

Please watch [this video](https://www.loom.com/share/1cebcd9687df4046af53ac90980907f7) to better understand how this is computed.

**2. What does attribution on "unique users" mean?**

We need one single conversion event that we can use to “qualify” a user.

For example: between May 1 and May 15, Jack made 3 purchases.

* May 1: Purchase 1: Computer \[came from Instagram]
* May 7: Purchase 2: Laptop \[came from Instagram]
* May 10: Purchase 3: TV \[came from Facebook]

Now note that, while 3 purchases have been made, only one unique user has been converted.

How will attribution work with unique users? There will be 2 options depending on the use-case:

* **Option 1:** When running attribution on Jack, we want to consider Jack on May 10, his last qualifying conversion, run a lookback window starting at this point, and consider all attribution before it influenced the 3 purchases.

  * Last Touch for Jack would be: Facebook -> When would this option be useful? In e-commerce companies, when looking at the cost of acquiring a user, you want to consider all the purchases until their last one.
* **Option 2:**  Consider Jack on May 1, his first qualifying conversion, and run a lookback before it.

  * Last Touch for Jack would be: Instagram -> When would this option be useful? For acquisition teams, when looking at getting a user to the experience for the first time, you want to consider their first qualifying event.

Some nuances to note

* In a time-series chart, the first and last qualifying conversion is within the chart interval. For example, if you have a 6M chart with a monthly interval, you’re looking at first and last conversion within a month, not 6M.

<Frame>
  <img alt="image" />
</Frame>

* In non-time series charts, the chart interval and the qualifying conversion interval are the same. If your chart is for 6M, the first and last conversion is also seen within the 6M period.

<Frame>
  <img alt="image" />
</Frame>

**3. What does filtering do in attribution?**

Once attribution is computed, filtering narrows total conversion events to only include/exclude those with the associated attribution property.

Here's a real-life scenario to better illustrate how this works:

* Purchase 1:

  * Jan 15th: Made purchase (visited via LinkedIn ad)
  * Jan 10th: visited via Google

    * Attribution data:

      * Last Touch: LinkedIn
      * All Sources: LinkedIn, Google
* Purchase 2:

  * Jan 18th: Made Purchase (came directly)
  * Jan 12th: visited via Facebook (Last Touch: Direct; All Sources: Direct, Facebook)

    * Attribution data:

      * Last Touch: Direct
      * All Sources: Direct, Facebook
* Purchase 3:

  * Jan 20th: Made Purchase (came via Google)

    * Attribution data:

      * Last Touch: Google
      * All Sources: Google

On Jan 30th, doing some attribution analysis, here's how you could answer a few of the common questions asked:

* I want to look at purchases that only came from a non-direct channel.

  * Answer: 2 - Purchases 1 and 3

<Frame>
  <img alt="image" />
</Frame>

* I want to look at how many last-touch purchases came via Google.

  * Answer: 1 - Purchase 3

<Frame>
  <img alt="image" />
</Frame>

* I want to look at how many purchases came via Google (can be any touch in the last 30 days).

  * Answer: 2 - Purchases 1 and 3

<Frame>
  <img alt="image" />
</Frame>

You can apply a filter on an attribution property only after an attribution breakdown has been applied. Here's how: 1: Turn on Attribution analysis by going to the breakdown section and choosing `Attributed by..` and property `XYZ`. 2a: Once the attribution model has been applied, go to the Filters section and choose the `Attributed by XXX` computed property - you can apply an attribution filter only on the property used in the attribution breakdown. 2b: Once the attribution model has been applied, click on the chart bar and filter/exclude the segments as needed.

**4. What does the "(not set)" attribution segment mean?**

You may see a "(not set)" segment in your report when using the Attribution feature. This occurs when the attribution property is missing from all events being evaluated for the user.

## Funnels-specific Computed Properties

The [Funnel report](/docs/reports/funnels/funnels-overview) supports two unique computed properties. The [Time to Convert property](/docs/reports/funnels/funnels-advanced#time-to-convert) returns the time in seconds needed to convert between funnel steps, and the [Property Sum property](/docs/reports/funnels/funnels-advanced#property-sum) allows you to sum up a numeric property as a user moves through funnel steps.


# Custom Buckets
Source: https://docs.mixpanel.com/docs/features/custom-buckets



## Overview

Custom buckets let you group existing properties into meaningful segments on the fly. This is focused on enabling everyone to answer common segmentation questions easily, quickly, and in a low-friction way.

Example use-cases include:

* Compare how the core markets are performing between US vs UK vs China vs all others
* Compare how many sign-ups are brought in by organic search vs Google ads vs social media channels together (Facebook, Twitter, LinkedIn)
* Compare # videos watched for users between ages 18-30 vs 30-40 or 40+
* Compare # users based on duration of video watched: \< 30, 30-60, 60-90 mins

## Quickstart

Add a property in Breakdown, then select the **Customize Buckets** option from the overflow menu

<Frame>
  <img alt="/14342458665748" />
</Frame>

Depending on your added property data type - string vs numeric, you will see a different custom buckets modal, designed based on the data-type use-cases **(more detail below)**

Once you define your segment buckets, click **Apply.** Only then will the custom buckets reflect in the visualization. You will also see the custom buckets as an under-item on the property

<Frame>
  <img alt="/14342458667924" />
</Frame>

To modify the segment buckets, click on the **under-item** and the custom buckets model will open. Once you’ve made the changes, click **Apply**

To remove all grouping and revert to the default, open the custom buckets modal and click **Reset**

<Note>
  Note that you cannot have more than 10 uneven (varied) groups.
</Note>

## String Property Use Cases

**Use Case:** Group individual countries into core market regions.

* Segment 1: North America: US & Canada
* Segment 2: Europe: UK, Germany, France, Netherlands, Italy
* Segment 3: China
* Segment 4: Rest of the World

### Creating Custom Buckets for String Property

1. Add a breakdown - Country. Below is the default you will see

<Frame>
  <img alt="/12828869626644" />
</Frame>

2. Choose to bucket segments, by opening the custom buckets model and clicking Apply

   * For each segment, choose the operator “is” and select one or more values
   * “Rest of the World” is auto-generated as **remaining values**

<Note>
  If two segments have the same value, the first segment will consider the value. Custom buckets are non-overlapping and sum up to 100% by definition
</Note>

<Frame>
  <img alt="/14342715436052" />
</Frame>

<Frame>
  <img alt="/12828860042132" />
</Frame>

#### Rename Custom Buckets Segment

1. On the same line of the segment, choose to rename it using the pencil icon
2. Click Apply after creating and naming your segments as desired

<Frame>
  <img alt="/14342752741140" />
</Frame>

<Frame>
  <img alt="/12828869956628" />
</Frame>

## Numeric Property Use Cases

**Use Case:** Group a numeric duration (mins) property into customized buckets.

* Use Case A: Evenly in 10 min groups for the range 50-100 mins
* Use Case B: Specific groups \<10, 10-20, 20-50, 50-100, ≥100
* Use Case C: Want to see all the durations as-is (No grouping)

### Creating Custom Buckets for Numeric Property (Even)

**Use Case A**: Evenly in 10 min buckets for the range 50-100 mins

1. Add a breakdown - “watch time (mins)”

* Every numeric property is \*\*auto-bucketed into even-sized buckets by default without using custom buckets.
* In the example below, the range of duration leads to a default bucket size of 10mins.

<Frame>
  <img alt="/14342489051028" />
</Frame>

<Frame>
  <img alt="/12828860268692" />
</Frame>

2. Go to the overflow and open the custom buckets modal
3. Since looking for even buckets of “30 mins”, choose **Even Bucketing**
4. Modify the min and max values of the desired range, and the bucket size, and click apply

   * Here these buckets are \<50 mins and ≥ 100 mins

     <Frame>
       <img alt="/14342575096724" />
     </Frame>

     <Frame>
       <img alt="/12828860573204" />
     </Frame>

<Note>
  Both a lower-end and upper-end bucket will be auto-generated to ensure your breakdown always adds up to 100%
</Note>

### Creating Custom Buckets for Numeric Property (Varied)

**Use Case B**: Specific groups \<10, 10-20, 20-50, 50-100, ≥100

1. Open the custom buckets modal
2. Since looking for specific buckets with varied bucket ranges, choose **Varied Bucketing**
3. Enter the ‘segment’ breakpoint values in each row and click apply. You can preview the bucket as you enter values in the line item below

<Frame>
  <img alt="/14342546138516" />
</Frame>

<Frame>
  <img alt="/12828860758676" />
</Frame>

<Note>
  Both a lower-end and upper-end bucket will be auto-generated to ensure your breakdown always adds up to 100%
</Note>

#### Disable Bucketing

**Use Case C:** Want to see all the durations as-is (No bucketing)

1. Open the custom buckets modal
2. Since looking for “No bucketing”, choose **None —** This lays out all the numeric property values as-is

<Frame>
  <img alt="/14342547991956" />
</Frame>

<Frame>
  <img alt="/12833587659028" />
</Frame>

## Typecasting Property Use Cases

**Use Case:** Group users based on their current age.

* Segment 1: Age 18 (potential to upgrade)
* Segment 2: Age 60 (potential to downgrade)
* Segment 3: Every other age

### Creating Custom Bucket with Typecasting

1. Add a breakdown age(years). By default, this will add as a numeric property
2. Since you are looking for pin-pointed years and not creating number ranges, this is a question more common to string property data type
3. Change **Data Type** of age(years) to String. Once changed you will see the type-casted property type as an under-item

<Note>
  Only typecasted data types show as an under-item. If the data type was the same as ingested, no under-item for data type will be seen
</Note>

<Frame>
  <img alt="/14342634016660" />
</Frame>

<Frame>
  <img alt="/12833644608148" />
</Frame>

4. Post changing data type, open the custom buckets modal. This will now open a modal meant for string property data type
5. Follow the steps as elaborated for the String property use-case above, and achieve the goal

   <Frame>
     <img alt="/14342637801748" />
   </Frame>

   <Frame>
     <img alt="/14342707763604" />
   </Frame>

   <Frame>
     <img alt="/12833899595284" />
   </Frame>

### FAQ

**Which reports does Custom Buckets work on?**

This feature is available in the Insights, Funnels, and Retention reports.

**Which property types does this support?**

Custom Buckets work on String, Numeric, and List data type

**Can I save a Custom Bucket**?

No, you can’t save a custom bucket. If your custom bucket is something you or your team would like to re-use, we encourage you to instead create a [custom property](/docs/features/custom-properties#creating-a-custom-property).

**How is custom buckets different from [custom property](/docs/features/custom-properties)?**

Custom buckets only support the most common custom-property use-case of **`if else`** to create meaningful segments in a more simplistic UI and a low-lift way to enable quick ad-hoc exploration. You could get this same answer using custom property too, it would just be more effort and not as intuitive

**Can I create over-lapping segments like (US & UK) vs (US & Australia)?**

No, breakdowns are fundamentally designed to sum up to 100%. To ensure your analysis is accurate, please create non-overlapping segments.

If you really need to answer a question like this, the right way here is to create these as two metrics leveraging [inline filters](/docs/reports) and NOT use breakdowns.

<Frame>
  <img alt="/12834111393684" />
</Frame>

**Will Custom Bucket still be available if I typecasted the property?**

Yes, as long as the data type you have changed the property to is supported.

**Can I change the operators on the upper and lower bound for numeric properties?**

No, the operators are fixed. The lower bound is inclusive (≥), and the upper bound is exclusive (\<). If you are looking for more control over the operators, please create a [custom property](/docs/features/custom-properties#creating-a-custom-property).

**Is (not set) included in (remaining values) for string properties?**

No, (not set) is not included in the remaining values.

* (remaining values): refers to ‘set’ values that just don’t fall into any of your defined segments
* (not set) refers to the events where a property value has not been set at tracking/ ingestion. For example, a new video (MixFun) has been added, but during tracking, you forget to send the name of this video. So the count of this video is being tracked, but it’s being associated with a property value (not set) vs (MixFun)

  More details can be found in [this help doc](/docs/features/advanced#undefined-and-null-properties)

**What is the difference between (not set) and (non-numeric values)?**

* (not set) as explained above for string refers to property values that have not been associated with any specific property value
* (non-numeric values) refers to set values that have just been sent in as non-numeric data type. For example, you’re looking to track time spent and have coded that as a numeric property, but for some reason some values are tracked as “a”, or “b” which are not numeric.

**How do I get "not contains" or "not equal to"?**

These values will auto-generate under (remaining values). So just select what should be included

For example — the (remaining values) below is not equal to US or India

<Frame>
  <img alt="/12834082079380" />
</Frame>

**How do I get a bucket of just 0 for numeric properties?**

If you’re purely looking for just how many people have value “0”, we would encourage you to typecast this to a string property, then select "0".

If you’re looking to get the count of 0, in reference to the other numeric buckets, go ahead and create a **Varied Bucketing** custom buckets modal

* If the numeric values are integers:

  * Choose Varied bucket values 0, 1, 2…
  * This would generate buckets: \<0, ≥0 & \<1, ≥1 & \<2, ≥2.
  * ≥0 & \<1 would be equal to bucket 0
* If the numeric values are decimals:

  * Choose Varied bucket values 0, 0.0001, 1, …
  * This would generate buckets: \<0, ≥0 & \<0.0001, ≥0.0001 & \<1, ≥1.
  * ≥0 & \<0.0001 would approximate to bucket 0


# Custom Events
Source: https://docs.mixpanel.com/docs/features/custom-events

Combine multiple events for analyses

## Overview

A custom event is a virtual event that was created from one or more events, optionally filtered down by a particular set of properties, and given a name. You can use custom events to:

* Merge two events into a single event ("User Signup" + "Account Created" -> "Signup")
* Create an event based on a filter on another event ("Purchase" where Country = "US" -> "US Purchases")

Imagine your business has two ways for users to track ads: they can convert from ad, or simply view it. You represent each of these actions with Mixpanel events named "Ad Conversion" and "Ad Impression," respectively. Later, you decide that you want to setup a funnel to track how many users are seeing any ads at all. So what do you do?

You can create a custom event containing "Ad Conversion" and "Ad Impression," and then save it as "Watch Ads.” Now you can use the "Watch Ads" custom event as a funnel step just like a regular event. Then, any time a user performs an "Ad Conversion" or "Ad Impression" action, they'll be included in that step. You can also use this new custom event in your other reports, such as Retention.

## Create a Custom Event

<Frame>
  <img alt="image" />
</Frame>

1. Open the Metrics menu by clicking "Select Metrics" in an Insights report, or clicking "Select Step/Events" in the Funnels/Retention/Flows report.
2. Select "Create New", then choose "Custom Event" in the right column.
3. Select the events and properties you’d like to include.
4. Name your custom event, and click **Save**.

<Note>
  A Custom Event definition can include up to 25 events.
</Note>

<Note>
  Custom events can't include session events (Session Start and Session End). A custom event that references a session event won't return results. To analyze sessions, use the Session Start and Session End events directly in your report.
</Note>

## Edit and Delete Custom Events

To view, edit, or delete any custom event, navigate to [Lexicon](/docs/data-governance/lexicon).

<Frame>
  <img alt="image" />
</Frame>

In Lexicon, click on the **Custom Events** tab.

<Frame>
  <img alt="image" />
</Frame>

Here you can see a list of all the custom events in the project. Click on the **name** of the event to edit its details.

To delete a custom event, check the **box** beside the title of all the custom events you want to delete, then click the **delete** button at the top of the list.

<Frame>
  <img alt="image" />
</Frame>

## Sharing Custom Events

A custom event will be private to the user who created it until it is shared with others. To share this custom event with another user in the project, you can click on "Save and Share" while creating the custom event.

<Frame>
  ![image](https://github.com/user-attachments/assets/277ac882-4ef0-4251-bb1e-107ed38f4f27)
</Frame>

<Frame>
  ![image](https://github.com/user-attachments/assets/6d84dbf7-7bba-45fd-ba25-44e0772752d8)
</Frame>

## Custom Events versus Simple Behaviors

Custom Events and [Simple Behaviors](/docs/features/saved-metrics-and-behaviors#simple-behaviors) are similar in that both allow you to combine multiple events for analysis. However, they serve different purposes. Simple Behaviors are designed for quick editing and reuse within the query builder in the Insights report. In contrast, Custom Events offer greater flexibility, which can be used across various parts of Mixpanel, including cohort definitions, Funnels, and can also be included as events within a Simple Behavior.

As a best practice, follow the guidelines below to determine whether to use Simple Behaviors or Custom Events:

* Use **Simple Behaviors** if you want to create a definition that can be easily viewed and modified from the query builder in Insights reports
* Use **Custom Events** if you need to need to create a virtual event that can be used everywhere in Mixpanel (e.g. inside a cohort definition, Funnels, Flows, or Retention)


# Custom Properties
Source: https://docs.mixpanel.com/docs/features/custom-properties

Calculate new properties on the fly

<Note>
  Free plan users can create custom properties locally within a report. Growth and Enterprise plan users can save the custom properties globally to reuse in other reports. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

Custom properties let you combine existing properties into new properties on the fly, using a simple Excel-like formula language. You can then use these new properties almost anywhere that you can use regular properties, with the ability to save/share them for reuse across your team. For more on why we built this, check out [our blog](https://mixpanel.com/blog/introducing-the-mixpanel-modeling-layer/).

## Creating a Custom Property

<Steps>
  <Step title="Click the plus button to the right of the search bar, then select either “Custom Event Property” or “Custom User Property” to open the property builder">
    <Frame>
      <img alt="image" />
    </Frame>
  </Step>

  <Step title="Give your property a name">
    <Frame>
      <img alt="image" />
    </Frame>
  </Step>

  <Step title="Click the formula bar to start defining the calculations to perform for your property">
    If you're new to this feature, we recommend starting with one of the examples. Click the **Insert Example** drop down to populate the box with a use-case specific custom property.

    When writing your formula, click **Ctrl + Space** to see a list of all the available [functions and their descriptions](/docs/features/custom-properties#functions). Type **period (.)** to open the menu for choosing an event/profile properties to add to the custom property definition.

    If you are creating a “Custom Event Property” both event and user profile properties will be available to select. If you are creating a “Custom Profile Property” only user profile properties will be available for use in the custom property.

    <Note>
      Note that the formula used to compose your custom property can't be longer than 20,000 characters.
    </Note>

    <Frame>
      <img alt="image" />
    </Frame>
  </Step>
</Steps>

## Saving and Reusing a Custom Property

Custom properties are local to the report by default when you select **Apply**. To save the custom property permanently for use in other reports and to make it usable by other project members, click **Save**. We recommend Applying the custom property and using it in your local analysis first, before saving and sharing, to reduce clutter in the project.

When you create custom properties and select **Save as Custom Property**, your created custom property will be private by default. You can also add a description at this stage, so you and your colleagues can know what the custom property is for. You can also decide to save the custom property and **share** that custom property with specific colleagues, teams, or the entire organization by clicking "**Save and Share**":

## Common Use Cases

**Grouping Marketing Channels**

If you're a marketer, using Mixpanel to show the impact of various channels on acquisition, you might want to group your UTM Sources into higher level buckets. For example:

* Facebook, Instagram, Twitter → Social
* Google, Bing → Search
* Everything else → Organic

You can also use the [Channel Classifier](/changelogs/2023-11-16-channel-classifier) template in custom properties as a starting point.

<Frame>
  <img alt="image" />
</Frame>

**Compute Properties Mathematically from Other Properties**

If you have an e-commerce app, you can combine "price" and "quantity" properties into a "total price" property as follows:

<Frame>
  <img alt="image" />
</Frame>

**Compute the Number of Days Between Two Date Properties**

Use custom properties to compute the date/time difference between two date properties. You can also use the special "TODAY()" function to find the difference between a date property and the current date/time. This is ideal when you want to transform a "DateofBirth" property into “age” or a "Created" property into “days active since registration”.

A new custom property can be defined by taking into account the “Created” property and using the following transformation:

<Frame>
  <img alt="image" />
</Frame>

**Compare Different Properties**

Use custom properties to create a new property if two property values are the same.

For example:

A company wants to find out what percentage of purchases are being made by users who have changed countries since signing up.

They can create a custom property to determine whether the two country values are the same with this transformation:

<Frame>
  <img alt="image" />
</Frame>

**Extract Domain from Email Address**

Extract the domain of the email from an email address. You can parse out parts of a string after "@" using the SPLIT function:

<Frame>
  <img alt="image" />
</Frame>

**Query a List with an Index**

Let's say you have a list of recommendations as a property, and you’d like to parse out the first recommendation as another string property.

You can parse out the first delivery ID in a list property with several DeliveryIDs:

<Frame>
  <img alt="image" />
</Frame>

The same syntax works with objects.

## Additional Examples

Below are more formulas for common transformations, covering date math, string parsing, URL handling, and working with lists of objects. You would have to adjust these to meet your use case. Click into any example to see the formula applied in a sample report.

<Note>
  It requires a Mixpanel account and being part of the Demo project to view the example reports.
</Note>

| Use Case                                                                                                                       | Formula                                                                                                                                                                                          | Explanation                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| [Time difference in minutes](https://mixpanel.com/s/4zgrQZ) between two date properties (e.g. `Updated at` & `Created`)        | `(NUMBER(Updated at) - NUMBER(Created)) / 60`                                                                                                                                                    | Converts dates into Epoch time using `NUMBER()`, calculates the difference, then divides by 60 to get minutes.                                  |
| [Check if a URL parameter exists](https://mixpanel.com/s/3kBvKa) (e.g. `ref=email`)                                            | `IF("ref=email" IN Current URL, TRUE, FALSE)`                                                                                                                                                    | Returns `TRUE` if the parameter exists in the URL, otherwise `FALSE`.                                                                           |
| [Combine two string properties](https://mixpanel.com/s/1JC9zr) (e.g. `Name` & `Email`)                                         | `Name + " - " + Email`                                                                                                                                                                           | Uses the `+` operator for string concatenation to join the two properties with `" - "` in between.                                              |
| [Years since a date](https://mixpanel.com/s/2aTWC4) (e.g. `Date of Birth`)                                                     | `DATEDIF(Date of Birth, TODAY(), "Y")`                                                                                                                                                           | Uses `DATEDIF()` to subtract two dates (`TODAY()` − `Date of Birth`) and return the difference in years.                                        |
| [Match a URL pattern](https://mixpanel.com/s/KcJx8) against a specific structure                                               | `REGEX_MATCH(Current URL, "https://.*/example/blog/.*/one")`                                                                                                                                     | Returns `TRUE` if the URL starts with `https://`, followed by any domain, `/example/blog/`, any string, and `/one`. Otherwise `FALSE`.          |
| [Rename property values](https://mixpanel.com/s/1jJpQt) depending on the current value                                         | `IFS(Page Variant == "A", "First test", Page Variant == "B", "Second test", DEFINED(Page Variant), "Others")`                                                                                    | Assigns a new string for each existing value. Unmatched values are classified as `"Others"`.                                                    |
| [Days since first event](https://mixpanel.com/s/2YAcV9) (e.g. within 365 days of `First Seen`)                                 | `DATEDIF(First Seen, Time, "D")`                                                                                                                                                                 | Uses `DATEDIF()` to return the difference between the first and queried event in days.                                                          |
| [Extract the hour](https://mixpanel.com/s/3d0L9K) from an ISO date property                                                    | `NUMBER(MID(STRING(Time), 12, 2))`                                                                                                                                                               | Uses `MID()` to extract the hour, starting at index 12 for 2 characters.                                                                        |
| [Split events into time buckets](https://mixpanel.com/s/4BImgV) (e.g. work shifts)                                             | `LET(X, NUMBER(MID(Time, 12, 2)), IFS(X >= 0 AND X < 6, "Dawn Shift", X >= 6 AND X < 11, "Morning Shift", X >= 11 AND X < 18, "Afternoon Shift", X >= 18 AND X < 24, "Night Shift"))`            | Uses `LET()` to assign the extracted hour to a variable, then groups it into a named shift.                                                     |
| [Group by platform](https://mixpanel.com/s/3eshLv) (Mobile vs. Desktop)                                                        | `IFS(Operating System == "Android", "Mobile", Operating System == "iOS", "Mobile", Operating System == "Windows", "Desktop", Operating System == "Mac OS X", "Desktop", TRUE, Operating System)` | Classifies known Operating System values into Mobile or Desktop groups.                                                                         |
| [Map "not set" to a different value](https://mixpanel.com/s/L9I5t) (e.g. `0`)                                                  | `IF(DEFINED(cost), cost, 0)`                                                                                                                                                                     | `DEFINED()` checks if the property is defined; keeps the value if so, otherwise returns the default.                                            |
| [Event within X seconds/hours/days](https://mixpanel.com/s/42DPMV) of a user date property                                     | `IF((NUMBER(Time) - NUMBER(Registration Date) >= 0) AND (NUMBER(Time) - NUMBER(Registration Date) <= 172800), TRUE, FALSE)`                                                                      | Converts both dates to numbers and checks if the difference is under 48 hours (172,800 seconds).                                                |
| [Filter events between an hour and minute](https://mixpanel.com/s/2YApuz) (e.g. before 17:30)                                  | `LET(TIME_STR, SPLIT(STRING(Time), "T", 2), HOUR, NUMBER(LEFT(TIME_STR, 2)), MIN, NUMBER(MID(TIME_STR, 4, 2)), IF(HOUR < 17 OR (HOUR == 17 AND MIN <= 30), TRUE, FALSE))`                        | Extracts the time string, then hour/minute, and checks if the timestamp falls before or at 17:30.                                               |
| [Sum a property in a list if another matches](https://mixpanel.com/s/1xnyzD) (e.g. sum `Price` where `Category` is `sneakers`) | `SUM(MAP(X, cart, IF(X["Category"] == "sneakers", X["Price"], FALSE)))`                                                                                                                          | Loops through the list; sums the `Price` value wherever `Category` equals `sneakers`.                                                           |
| [Return a UTM parameter from the URL](https://mixpanel.com/s/JKdp4) not automatically extracted                                | `REGEX_REPLACE((REGEX_EXTRACT(Current URL, "utm_source=([^&]*)", 1)), "%20", " ")`                                                                                                               | Extracts the text following `utm_source=` up to the next `&`, then replaces encoded spaces (`%20`) with blank spaces.                           |
| [Change the data type of a value in a list of objects](https://mixpanel.com/s/3Do1pl) (e.g. `Price` to string)                 | `MAP(X, cart, STRING(X["Price"]))`                                                                                                                                                               | Loops through the list of objects, converting each `Price` number value to a string.                                                            |
| [Time difference in seconds](https://mixpanel.com/s/2UisC1) across mixed units (seconds & milliseconds)                        | `((NUMBER(Time Processed (UTC)) / 1000) - NUMBER(Time)) +/- (HOURS IN SECONDS)`                                                                                                                  | Converts both dates to Epoch time, dividing the millisecond timestamp by 1000 to align units, then adjusts for the UTC/project timezone offset. |

## Borrowed Properties

Borrowed properties allow you to take a property from a prior event and automatically add it as a property on a future event without needing to explicitly track the property in the future event.

**Use Cases:**

* Use client-side properties to populate a property on a server-side event. Example: “purchase” event could be a server-side event, while the “product search” event is a client-side event.
* Track a single event property and apply it to subsequent events. Example: It may be hard to track whether every event has dark mode enabled. You would need to keep track of the state of dark mode, and then add a “dark mode” property to every event that you track. Using borrowed events, you can just track one event with a property that indicates whether dark mode has been enabled or not, and have subsequent events borrow the property from that event.

<Note>
  Each project can use up to 20 borrowed properties.
</Note>

### Creating Borrowed Properties

The following is a demonstration of Borrowed Properties using the [E-Commerce demo project](https://mixpanel.com/project/3018488), which anyone with a Mixpanel account can access.

In this demonstration, we present an event called **"Purchase Completed"**, which lacks the event property **"Search term"**. To enable a breakdown by **"Search term"**, we apply the Borrowed Property feature, leveraging the property from another event called **"Product Searched"**.

<Steps>
  <Step title="Purchase Completed does not have “Search term”">
    <Frame>
      <img alt="image" />
    </Frame>
  </Step>

  <Step title="Products Searched does have “Search term”">
    <Frame>
      <img alt="image" />
    </Frame>
  </Step>

  <Step title="Create a custom event property">
    <Frame>
      <img alt="image" />
    </Frame>
  </Step>

  <Step title="Add a borrowed property">
    <Frame>
      <img alt="image" />
    </Frame>
  </Step>

  <Step title="Select an event to borrow from">
    <Frame>
      <img alt="image" />
    </Frame>
  </Step>

  <Step title="Select the property to borrow">
    <Frame>
      <img alt="image" />
    </Frame>
  </Step>
</Steps>

### Borrowing Mechanics

Borrowed Properties capture the value from the most recent borrowed event.

We apply a seven-day lookback window, so the second event must occur within seven days of the first. If no first event exists within this window, the borrowed property is assigned the value (not set).

The video below demonstrates how to create a borrowed property.

<Frame>
  <iframe />
</Frame>

Some key notes

* Borrowed property creation is limited to Admin & Owner Roles only
* List properties are excluded from borrowed properties
* A project can have a maximum of 20 borrowed properties. Hence, you are encouraged to only create borrowed properties useful to the larger team
* A borrowed property, once created, is like any other custom property. It can be accessed by all in the project, depending on permissions
* Borrowing of a property is strictly from the most recent event in the 7-day lookback window. To elaborate

  * Say on event “purchase”, you want to borrow property “search term” from an event “search product”. If there are multiple events “search product” before “purchase”, the property will be borrowed from the most recent “search product” event where the property is set.
  * Lookback is also fixed to a 7-day window. Say the “purchase” event occurred on 31st Jan, if the  most recent “search product” occurred on 20th Jan, the borrow functionality will return “search term” = (not set), since this event happened 11 days ago, which is outside the lookback window range.

To use a borrowed property with other [functions](/docs/features/custom-properties#functions), you would need to:

1. Create a custom property with just the borrowed property on its own <img alt="image" title="Borrowed Property" />\\
2. Create a separate custom property using the borrowed property (i.e., the 1st custom property) <img alt="image" title="Borrowed Property in Custom Property" />\\
3. Here's an example of a [report](https://mixpanel.com/s/1c4Pl9) with *Searched Category* custom property using *Search term (Products Searched)* borrowed property <img alt="image" title="Borrowed Property in Custom Property Report Example" />\\

## Reference

### Functions

Use the following functions in the **Formula** field to modify your custom property:

| Function       | Definition                                                                                                                                                                                                                                                                                         | Syntax & Example                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| if             | Evaluates if an expression is true or false.                                                                                                                                                                                                                                                       | if(condition, value if true, value if false) <br /><br /> Example: <br />`if(A=="Facebook" or A=="Twitter", "Social", A)`<br />                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ifs            | Runs multiple checks and returns a value corresponding to the first true result. If no conditions are true, undefined is returned.                                                                                                                                                                 | ifs(condition1, value1, condition2, value2, …) <br /><br /> Example: <br />`ifs( A<60,"Less than 1 hour",`<br />`A<120, "More than 1 hour but less than 2 hours",`<br />`A>=120, "More than 2 hours")`                                                                                                                                                                                                                                                                                                                                                       |
| not            | Returns values that are not true.                                                                                                                                                                                                                                                                  | not(condition) <br /><br />Example:<br />`not(A == "Facebook")`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| and            | Returns true if both conditions are met. Else, returns false.                                                                                                                                                                                                                                      | x and y <br /><br />Example:<br />`if(A=="San Francisco" and B=="Chrome", "Valid user", "Invalid User")`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| or             | Returns true if either condition is met. Else, returns false.                                                                                                                                                                                                                                      | x or y <br /><br />Example:<br />`if(A=="San Francisco" or B=="Chrome", "Valid user", "Invalid User")`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| in             | Returns true if the first condition is contained in the second condition.                                                                                                                                                                                                                          | x in condition <br /><br />Example:<br />`if("Facebook" in A, "Facebook Corporation", A)`<br /><br /> This can also be used to check against a list of values:<br />`if(A in ["Chrome","Firefox","Edge"],"Acceptable browser","Unsupported browser")`                                                                                                                                                                                                                                                                                                        |
| boolean        | Casts the argument to a boolean.                                                                                                                                                                                                                                                                   | boolean(value)->false, boolean(alternate value)-> true <br /><br />Example:<br />`boolean(A)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| number         | Casts the argument to a number.                                                                                                                                                                                                                                                                    | number(value to cast) <br /><br />Example:<br />`number(A)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| string         | Casts the argument to a string.                                                                                                                                                                                                                                                                    | string(value to cast)<br /><br /> Example:<br />`string(A)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| defined        | Determines if a value exists. If a property is not defined on a parent event or profile, this will return false, otherwise this will return true.                                                                                                                                                  | defined(variable to check for existence) <br /><br />Example:<br />`defined(A)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| has\_prefix    | Determines whether a string starts with another string. This comparison is case-insensitive.                                                                                                                                                                                                       | has\_prefix(string to check, prefix)<br /><br />Example:<br />`has_prefix(A, "United")`                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| has\_suffix    | Determines whether a string ends with another string. This comparison is case-insensitive.                                                                                                                                                                                                         | has\_suffix(string to check, suffix)<br /><br />Example:<br />`has_suffix(A,"States")`                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| min            | Determines the minimum value between two numbers.                                                                                                                                                                                                                                                  | min(number, number)<br /><br />Example:<br />`min(A,B)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| max            | Determines the maximum value between two numbers.                                                                                                                                                                                                                                                  | max(number, number)<br /><br />Example:<br />`max(A,B)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| floor          | Returns the largest integer that is smaller than or equal to the input (ie: rounds down to the nearest integer).                                                                                                                                                                                   | floor(number)<br /><br />Example:<br />`floor(A)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ceil           | Returns the smallest integer value greater than or equal to the input (ie: rounds up to the nearest integer).                                                                                                                                                                                      | ceil(number)<br /><br />Example:<br />`ceil(A)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| round          | Returns the nearest integer value of the input value.                                                                                                                                                                                                                                              | round(number)<br /><br />Example:<br />`round(A)`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| upper          | Cast string property values to uppercase.                                                                                                                                                                                                                                                          | upper(string property)<br /><br />Example:<br />`upper(A); upper("hello")` -> "HELLO"                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| lower          | Cast string property values to lowercase.                                                                                                                                                                                                                                                          | lower(string property)<br /><br />Example:<br />`lower(A); lower("FacEBook")` -> "facebook"                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| parse\_url()   | Extracts the part of the url that is specified: domain(google) or full\_domain(google.co.uk)                                                                                                                                                                                                       | parse\_url(string property, "domain") or parse\_url(string property, "full\_domain") <br /><br />Example: parse\_url(A,"domain")                                                                                                                                                                                                                                                                                                                                                                                                                             |
| regex\_extract | If haystack is a string and pattern matches at least one substring, extracts the result from the first pattern match in haystack. The result is a string equal to the entire regex match, or if a capture group is specified, only that portion of the match. We use the PCRE2 regex engine.       | regex\_extract(haystack, pattern, \<optional capture group#>)<br /><br />Example:<br />`regex_extract("iPhone5.1","iPhone(...)",1)` ->5.1                                                                                                                                                                                                                                                                                                                                                                                                                    |
| regex\_match   | Returns true if the pattern matches any part of the string. We use the PCRE2 regex engine.                                                                                                                                                                                                         | regex\_match(haystack, pattern)<br /><br />Example:<br />`regex_match("zzhaystackzz", "ha(..)ack")` -> true <br /> // Use (?-i) for case-sensitive matching: `regex_match("HAYSTACK", "(?-i)haystack")` -> false                                                                                                                                                                                                                                                                                                                                             |
| regex\_replace | Replaces the parts of a string that match a regular expression with a different string. We use the PCRE2 regex engine.                                                                                                                                                                             | regex\_replace(haystack, pattern, replacement)<br /><br />Example:<br />  // convert currency string to number: `regex_replace("$1,234,567", "[^.0-9]\*", ""))` -> `1234567`                                                                                                                                                                                                                                                                                                                                                                                 |
| datedif        | Subtract two dates. Units:<br />D: days.<br />M:  months.<br />Y: years<br />MD:  days remaining after subtracting whole months.<br />YM:  months remaining after subtracting whole years.<br />YD:  days, assuming start\_date and end\_date are within 1 year.<br />Use TODAY() for current day. | <br />datedif(start\_date,end\_date,unit)<br /><br />Example:<br />`datedif(registration_date,TODAY(), "M")` -> 5                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| len            | Returns the length of the string or the list.                                                                                                                                                                                                                                                      | len(string) or len(list)<br /><br />Example:<br />`len("Canada")` -> 6                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| left           | Returns characters from the beginning of a given string.                                                                                                                                                                                                                                           | left(string, num\_of\_characters)<br /><br />Example:<br />`left("Canada",3)` -> "Can"                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| right          | Returns characters from the end of a given string                                                                                                                                                                                                                                                  | right(string, num\_of\_characters)<br /><br />Example:<br />`right("Canada",3)` -> "ada"                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| mid            | Returns characters from the middle of a given string                                                                                                                                                                                                                                               | mid(string, first\_index, num\_of\_characters)<br /><br />Example:<br />`mid("Canada",1,4)` -> "Cana"                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| split          | Splits a string into different parts based on a user-specified delimiter, and lets you select a particular split. Delimiter must be a single ASCII character. To fetch a list of all splits, don't pass a third argument. The first split is accessible by passing n=1 (second with n=2, ...)      | split(input string, delimiter, \[n: optional]) → string <br /><br />Examples with 1 split:<br />`split("dwight@dm.com","@",2)` -> "dm.com"<br />`split("dwight@dm.com","@",4)` -> undefined<br />`split("dwight@dm.com","/",2)` -> `dwight@dm.com`<br />`split("empty//string/","/",2)` -> "" <br /><br />Examples with all splits:<br />`split("dwight@dm.com","@")` -> \["dwight", "dm.com"]<br />`split("a/b/c/d", "/")` -> \["a", "b", "c", "d"]<br />`split("a/b/c/d", "-")` -> \["a/b/c/d"]<br />`split("a//b/c/d", "/")` -> \["a", "", "b", "c", "d"] |
| let            | Define a variable and use it in an expression. This helps keep the custom property definition neat and non-repetitive. Variables are only active within the scope of the LET function. You can nest multiple let functions to define multiple variables.                                           | let(name, definition, expression)<br /><br />`// define a variable "spend" and use it in an expression`<br /><br />`let(`<br />`spend, <price> * <quantity>,`<br />`ifs(`<br />`spend < 50, "no discount",`<br />`spend < 200, "gold discount",`<br />`spend > 200, "platinum discount",`<br />`TRUE, "invalid"`<br />`)`<br />`)`<br /><br />*Note: \<price> and \<quantity> are event properties.*                                                                                                                                                         |
| any            | Evaluates to TRUE if the given expression is true for any value in the given list. The expression can refer to the current list element by the given name.                                                                                                                                         | any(name, list, expr) <br /><br /> Example:<br />Let's say you had a list of numbers called priceList= \[5,205,178,12,22]<br />`any(X, priceList, X > 300)` -> false.<br />`any(X, priceList, X >= 5 and X < 300)` -> true.                                                                                                                                                                                                                                                                                                                                  |
| all            | Evaluates to TRUE if the given expression is true for all values in the given list. The expression can refer to the current list element by the given name.                                                                                                                                        | all(name, list, expr) <br /><br /> Example:<br />Let's say you had a list of numbers called priceList= \[5,205,178,12,22]<br />`all(X, priceList, X > 5 and X < 200)` -> false.<br />`all(X, priceList, X >= 5 and X < 300)` -> true.                                                                                                                                                                                                                                                                                                                        |
| filter         | Filters the given list to only include items for which the given expression is true. The expression can refer to the current list element by the given name.                                                                                                                                       | filter(name, list, expr) <br /><br /> Example: <br />Let's say you had a list of numbers called priceList= \[5,205,178,12,22]<br />`filter(X, priceList, X>100)` -> new shortened list = \[205,178]                                                                                                                                                                                                                                                                                                                                                          |
| map            | Transforms each value in the given list using the given expression. The expression can refer to the current list element by the given name.                                                                                                                                                        | map(name, list, expr) <br /><br /> Example:<br />Let's say you had a list of states = \["Georgia","Florida","Texas"]<br />`map(X, states, lower(X))` -> \["georgia","florida","texas"]                                                                                                                                                                                                                                                                                                                                                                       |
| sum            | Sums all numbers in the given list. Non-numeric items in the list are ignored.                                                                                                                                                                                                                     | sum(list) <br /><br /> Example:<br />Let's say you had a list of numbers called priceList= \[5,205,178,12,22]<br />`sum(priceList)` -> 422.<br /><br />`sum(filter(X, priceList, X>100))` -> 383, because `filter(X,priceList, X>100)` -> \[205,178] and `sum([205,178])` -> 383.                                                                                                                                                                                                                                                                            |

### Numeric Operators

Use the following numeric operators in the **Formula** field to modify your custom property using:

* `+`: Addition. Operator can also be used to create string concatenation, for example: `"string_to_concatenate" + your string property`
* `-`: Subtraction
* `*`: Multiplication
* `/`: Division
* `%`: Modulo

### Comparison Operators

Use the following comparison operators in the **Formula** field to modify your custom property:

* `<`: The first number is strictly less than the second number.
* `>`: The first number is strictly greater than the second number.
* `>=`: The first number is greater than or equal to the second number.
* `<=`: The first number is less than or equal to the second number.
* `==`: The first argument is equal to the second argument. If both arguments are strings, the comparison is case-insensitive.
* `!=`: The first argument is not equal to the second argument. If both arguments are strings, the comparison is case-insensitive.

### Constants

* `false`: Represents the literal value of boolean false.
* `true`: Represents the literal value of boolean true.
* `undefined`: Represents the literal value of cases that aren't defined.


# Embeds
Source: https://docs.mixpanel.com/docs/features/embeds

View Mixpanel reports in 3rd-party tools

Mixpanel Boards and reports can be embedded in Figma, Coda, Jira, and any third-party tool that supports embedding.

## Using Embeds

Paste the link of the Board or Report into the 3rd-party tool and follow the instructions to authenticate. Here's a [video walkthrough](https://www.loom.com/share/000acdf5b6d94efc98d143316afac1db) of this process.

### Compatibility

| Company    | Status |
| ---------- | ------ |
| Figma      | GA     |
| Coda       | GA     |
| Notion     | GA     |
| Jira       | Beta   |
| Confluence | Beta   |
| Miro       | Beta   |

### Limitations

Though this feature works for any third-party that supports a standard oEmbed, certain integrations may be limited depending on how the third-party has customized their oEmbed settings.

In Safari, you must have "Prevent cross-site tracking" off in order for any embedding to work. Go to Safari -> Preferences -> Privacy -> Website tracking: Prevent cross-site tracking should NOT be checked.

## Supporting Embeds in your Platform

### oEmbed

[oEmbed](https://oembed.com/) is a format for allowing an embedded representation of a URL on third-party sites. It’s a way to embed content from one website onto another website without having to manually copy and paste code.

If your platform supports the oEmbed format, you should be able to support Mixpanel’s Embeddable reports right out of the box.

### Embedly or Iframely

If you don’t currently support oEmbed, [Embedly](https://embed.ly/) or [Iframely](https://iframely.com/) are platforms that can help you get started.

Embedly provides a way to embed content from a variety of sources, including YouTube, Vimeo, SoundCloud, and more. It offers an API that developers can use to embed content on their websites. Embedly also offers a variety of tools and features, including the ability to customize the appearance of embedded content.

Iframely is a similar service to Embedly. It helps websites and applications embed external content such as videos, images, articles, and more. It simplifies the process of embedding content by automatically generating embed codes for various media sources, eliminating the need for developers to manually code each embed.


# Building Revenue Metrics
Source: https://docs.mixpanel.com/docs/features/revenue-analytics



## Overview

Mixpanel's Revenue Analytics gives product teams comprehensive visibility into how their decisions directly impact business outcomes, connecting product usage with financial performance. It also allows revenue teams to work under one umbrella by breaking down silos and streamlining revenue operations across the customer lifecycle.

Revenue Analytics eliminates the traditional barrier between product and financial data by seamlessly integrating with existing data warehouses. Whether your business relies on transaction-based purchases or subscription models, this powerful feature provides a unified view of how product changes translate to revenue results, without complex data engineering or lengthy wait times.

**Key Benefits**

* Eliminate data silos between product analytics and revenue data
* Make data-driven decisions without requiring data team involvement
* Track revenue changes over time, including refunds, charge-backs, and subscription changes
* Analyze both one-time purchases and recurring revenue streams

## How It Works

Revenue Analytics leverages Mixpanel's Warehouse Connectors, utilizing two primary data synchronization mechanisms: Mirror and Profile History.

Mirror maintains parity between your data warehouse and Mixpanel by regularly polling for changes in the data source and updating the values in Mixpanel. This ensures integrity for purchase-based revenue models by accounting for post-purchase modifications such as refunds, charge-backs, and order cancellations.

Profile History utilizes a time-series data structure to track state-based metrics like MRR/ARR at specific points in time. This provides an accurate historical analysis of subscription revenue changes and ties them to user behavior. The system maintains a record of changes to user profiles, which allows for retroactive cohort definitions.

You can look at how to build these metrics in Mixpanel by leveraging our [SaaS KPIs template](https://mixpanel.com/project?show-template-selector=true) on either your data or our public demo data set. There is also a [public dashboard](https://mixpanel.com/p/8R2b9DRvnZfrNXYVqNxFLH) to give you a view of the metrics you can build.

## Common Use Cases

Mixpanel's Revenue Analytics enables you to analyze your data in powerful ways, regardless of your team, the stage of your company, or your business revenue stream.

### Transaction-based Business Models

Revenue Analytics can help answer the following example questions for transaction-based business models.

**Acquisition:**

* What are D7, D30, and D60 Average Revenue Per User (ARPU)? How has this changed month over month?
* Which acquisition channels bring customers with the highest Life Time Value(LTV)?

**Conversion optimization:**

* What is the Average Order Value (AOV) of users who went through the 5-step purchase funnel versus those who did the 3-step funnel?
* Where is revenue dropping in the 5-step purchase funnel?

**Comparing spend across segments:**

* What is the revenue split across the various categories? How has this changed year-over-year?
* How does the revenue generated by first-time buyers compare to that of returning customers during major sales events such as Black Friday?

**ROI Analysis on Ad Spend:**

* Which are our most effective marketing channels, such as those with the highest Total Revenue to Customer Acquisition Cost(CAC) ratio?
* What is the change in the AOV after the launch of a 10% off promotional discount?

#### Building the Metrics

**Total Revenue**: Calculated as the Sum of Revenue made across all purchases.

<Frame>
  <img alt="image" />
</Frame>

**Average Order Value (AOV)**: Calculated as Total Revenue over the Total Number of Purchases. See [this example in our demo project](https://mixpanel.com/s/3VdgsS).

<Frame>
  <img alt="image" />
</Frame>

**Life Time Value (LTV)**: Calculated as the cumulative spend from users since they landed on the platform. Often you look at spending in the first 30 or 60 days by the expected lifetime (2 years, 3 years, etc).

<Frame>
  <img alt="image" />
</Frame>

This report shows the cumulative revenue of new users (identified by the Sign Up event) by cohort over their lifetime (5 days, 30 days, 60 days). It leverages the Property Sum feature of the [Retention report](/docs/reports/retention) to look at retained users' cumulative spending.

**Average Revenue Per User (ARPU)**: Calculated as the Sum of Revenue over time divided by the number of Unique Users. See [this example in our demo project](https://mixpanel.com/s/300OIR).

<Frame>
  <img alt="image" />
</Frame>

**Customer Acquisition Cost (CAC)**: Calculated as the Total Acquisition Costs over the Number of New Customers Acquired. In other words, how much money do we have to spend to acquire a user? A good acquisition strategy would lead to a LTV/CAC value above 1. See [this example in our demo project](https://mixpanel.com/s/2TZJlX).

<Frame>
  <img alt="image" />
</Frame>

The report above leverages Mixpanel's [Ad Spend data model](/docs/tracking-methods/integrations/ad-spend).

### Subscription-based Business Models

Revenue Analytics can help answer the following example questions for subscription-based business models.

**General revenue**

What is our current Annual Recurring Revenue(ARR)? How has this changed over time? What's our current Net Revenue Retention (NRR)?

**Understanding upgrades/churns**

What are the top accounts that have upgraded or churned? What is the average engagement (e.g., Viewed Reports/ARR) for accounts that have upgraded versus churned? Should engagement be a leading indicator?

**Feature usage by plan or revenue bucket**

What is the feature usage and adoption, broken down by plan type? What is the 'time to activation' for accounts in various revenue buckets?

**Impact of product initiatives**

We improved our growth plan last year. How many accounts have come in through our basic plan in the last 12 months? They could be on other plans today. We launched a new offering to upsell customers. Is there a correlation between adoption of the feature and upsell revenue?

#### Building the Metrics

Revenue Analytics makes use of two new computed properties to create subscription revenue metrics. The model is built by comparing two data points:

1. **Recurring Revenue Change**: looks at the 'numerical difference' between the 2 values
2. **Recurring Revenue Change Type**: tells you the 'type of change' listed below:

* 20 → 5 = Downgrade (positive to less positive)
* 5 → 0  = Churn (positive to zero)
* 0 → 5	 = New (zero to positive)
* 5 → 20 = Upgrade (positive to more positive)
* 5 → 5  = Flat (no change)

<Frame>
  <img alt="image" />
</Frame>

<Note>
  The Recurring Revenue Change and Recurring Revenue Change Type computed properties requires the use of [Historical Profile Values](/docs/data-structure/user-profiles#importing-historical-profile-values) imported via [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors).
</Note>

When creating a Revenue Metric (e.g. incremental MRR in the last month), there are two ways to control the calculation: **Time and Change Type**.

1. **Time** lets you analyze based on the past number of months, which allows you to determine “What should today's value be compared versus 1 month ago?”, for example.

<Frame>
  <img alt="image" />
</Frame>

2. **Change Type** enables you to look at the incremental revenue for different types of accounts, whether New, Upsell, Downgrade, or Churn.

<Frame>
  <img alt="image" />
</Frame>

You can also look at the latest value as of a specific time period, or for **any** value during the time period. For example, you might want to answer: show me all customers who were on a free plan in the last 12 months, even if they are on a priced plan, now.

<Frame>
  <img alt="image" />
</Frame>

**Net Revenue Retention (NRR)**: Calculated as the percentage change in revenue base.

* NRR > 100% → Existing customers are being retained and the user base is growing
* NRR \< 100% → Existing customers are a leaky bucket and we are not able to upsell them
* Formula:

  * Current MRR from Existing Biz / Prior MRR
  * (Prior MRR from Existing Biz + (Upsell MRR - Downgrade MRR) ) / Prior MRR

<Frame>
  <img alt="image" />
</Frame>

**MRR Churn**: Calculated as the drop in Revenue for existing users (it does not consider upsells). Typically, the target ARR Churn is below 15%. What does this translate to on a monthly basis?

* Formula

  * 1 - ( (Current MRR from Existing Biz - Upsell MRR) / Prior MRR )

**MRR Growth Rate**: Calculated as the overall growth in MRR (New + Existing Biz)

* Current MRR / Prior MRR

<Frame>
  <img alt="image" />
</Frame>

**MRR by Revenue Type**: Calculated based on the following:

* New Revenue: you want this to go up since this is net - new money (land motion)
* Upsell Revenue: you want this to go up, too, since this is also net - new money (expand motion)
* Downgrade / Lost Revenue: you want this to be minimal
* Flat Renewal: you want this pie to keep growing as you land more logos.

Ultimately, the Goal is to have (New + Upsell) - Downgrade to be positive, which means recurring revenue is growing.

## FAQ

<AccordionGroup>
  <Accordion title="Can all customers use these features?">
    Only customers using the [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors) get access to these features.
  </Accordion>

  <Accordion title="What should be the shape of the data to analyze these metrics?">
    Once you set the [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors), be sure that you have [Mirror Mode](/docs/tracking-methods/warehouse-connectors#mirror) turned on to ensure your data is 100% in sync with the warehouse, even if the warehouse data is updated:

    For transaction-based models - Send purchase value as an event property on every purchase event. Example: `{"event_name": "Purchase completed", "properties": {"item": "clothing", "price": 100}}`

    For subscription-based models - Send a monthly snapshot of the revenue per user/ account as a [Historical Profile Property](/docs/data-structure/user-profiles#importing-historical-profile-values). If a user/account is not active, set the revenue data to zero for the immediate month following so we can tag this as a churned user/account.
  </Accordion>

  <Accordion title="We have multiple SKUs per account, each with its own contract. Can we send this as a revenue object property for an account?">
    We do not support profile history for object-type properties. To be able to look at revenue per SKU, we recommend sending each SKU revenue as a historical numerical property.

    If you have 5 SKUs, send 5 historical properties (SKU\_revenue\_1, SKU\_revenue\_2, …, SKU\_revenue\_5).
  </Accordion>
</AccordionGroup>


# Saved Metrics and Behaviors
Source: https://docs.mixpanel.com/docs/features/saved-metrics-and-behaviors



## Overview

Saved Metrics and Behaviors allow you to define and standardize key measurements and user actions across your product/business. By saving these definitions, you ensure consistency, reusability, and accuracy across your reporting and analysis.

<Frame>
  <img alt="" />
</Frame>

## Saved Metrics

**Saved Metrics** are standardized definitions for your organization's KPIs. They quantify the performance, progress, or success of various aspects of your product/business. Each saved metric is a measurement of an event, behavior, user cohort, or profile.

**Example:** Create a saved metric for your Signup Conversion Rate to consistently track how effectively users complete your signup process.

## Saved Behaviors

**Saved Behaviors** are reusable definitions of specific user actions that represent a meaningful user journey or experience.

**Example:** If your signup process involves multiple steps, you can define this entire sequence as a "Signup Funnel" saved behavior.

Behaviors fall into one of three types: **Simple**, **Funnel**, or **Retention**.

### Simple Behaviors

**Simple Behaviors** are an "or" list of one or more events. These are useful when you have multiple events that need to be looked at together to measure a specific behavior. For example, below is a simple behavior for all product page interactions:

<Frame>
  <img alt="" />
</Frame>

**Simple Behaviors versus Custom Events**

Simple Behaviors and [Custom Events](/docs/features/custom-events) are similar in that both allow you to combine multiple events for analysis. As a best practice, follow the guidelines below to determine whether to use Simple Behaviors or Custom Events:

* Use **Simple Behaviors** if you want to create a definition that can be easily viewed and modified from the query builder in Insights reports
* Use **Custom Events** if you need to create a virtual event that can be used everywhere in Mixpanel (e.g. inside a cohort definition or Funnel)

### Funnel Behaviors

<Note>
  Learn more about the [Funnels report](/docs/reports/funnels).
</Note>

Funnel Behaviors define a sequence of events completed within a specified time frame. For example, save a behavior for the "Product Viewed through Purchased" Funnels.

<Frame>
  <img alt="" />
</Frame>

### Retention Behaviors

<Note>
  Learn more about the [Retention report](/docs/reports/retention).
</Note>

Retention Behaviors look at when a user did an event, then came back to do the same or another event within a window of time. For example, we can save a behavior for our monthly returning purchasers.

<Frame>
  <img alt="" />
</Frame>

## Use Cases

You can use Saved Metrics and Saved Behaviors independently or combine them. Below are example use cases for each:

**Metrics**

* **Save time:** Avoid redundant work. If you frequently recreate the same metric across multiple reports or boards, saving it as a metric streamlines your workflow.
* **Onboarding & ease of use:** Make it easy for anyone to understand what events and properties your organization uses to track your key metrics.
* **Align your teams:** Establish trusted KPIs that all teams can rely on. This ensures everyone is working toward common goals using the same data.

**Behaviors**

* **Save time:** If you find yourself creating different metrics using the same set of events and filters, this is a good signal to create a saved behavior.
* **Simplify updates:** Centralize definition management. If a specific user behavior or flow changes (e.g. your "Signup Flow" removes a step), you only need to update the saved behavior definition once. All saved metrics that rely on that behavior (e.g. "Signup Flow Time to Convert," "Signup Flow Conversion Rate," "Signup Flow Unique Users") will automatically reflect the updated Signup Flow definition.

## Saving

Click on the three dots menu next to the metric name. Select either **Save Metric** or **Saved Behavior**. You will be prompted to add a name and description.

<Frame>
  <img alt="" />
</Frame>

## Sharing

By default, saved metrics and behaviors are private to you. After saving, you will be prompted to share.

<Frame>
  <img alt="" />
</Frame>

**Permissions**

* Viewers: Can use this metric in analysis, but cannot modify the saved definition
* Editors: Can use this metric in analysis, and modify the saved definition

**Audiences**

* Individuals: Set the permission for specific users in the project
* Project: Sets the permission for all users in the project

<Note>
  The best practice is to give the project **View** access and add any **Editors** individually. This ensures that everyone can use the definitions that are managed by select people.
</Note>

## Using a Saved Metric or Behavior

When you click “Select Metric” to populate your report, you will see all events as well as any saved definitions. You can search for a saved metric or behavior by name. Alternatively, you can browse the available saved metrics and behaviors using the tabs on the left.

From an Insights report, you can select metrics and behaviors of all types. From Funnels and Retention reports, you will see only metrics and behaviors for that report type.

<Frame>
  <img alt="" />
</Frame>

## Updating Definitions

Saved metrics or behaviors definitions may change over time. Mixpanel enables you to easily update these definitions and apply the changes across all reports that use them.

After selecting a saved metric or behavior, you can modify the definition in the Query Builder. You will see a dotted line around the metric or behavior icon if the definition has been modified from the last saved state. Click the three-dot menu to make updates.

<Frame>
  <img alt="" />
</Frame>

* **Push Changes:** This applies your new definition to the original saved metric/behavior. All reports using this metric/behavior will be updated with the new definition.
* **Save as New:** Creates a new metric with this new definition. The originally saved metric definition will not be affected.
* **Clear Changes:** Reverts back to the previously saved state.

## Managing Saved Metrics and Behaviors

You can view all Saved Metrics and Behaviors in your project, add descriptions to clearly define them, and delete any unwanted definitions directly from the [Lexicon](/docs/data-governance/lexicon).

From the Lexicon, click the "Metrics" tab to access all [Saved Metrics](/docs/features/saved-metrics-and-behaviors#saved-metrics) and [Formulas](/docs/reports/insights#formulas). Click the Behaviors tab to access all [Saved Behaviors](/docs/features/saved-metrics-and-behaviors#saved-behaviors).

<Frame>
  <img alt="" />
</Frame>

Click on the name of the definition you want to modify or delete. From the detail page, you will see all the options to customize the metric, including:

* **Permissions:** Click "Share" to modify the metrics share settings.
* **Verify:** [Add Verified badges](/docs/data-governance/lexicon#verify-data) to the metric/behavior. Only project Admins and Owners can verify entities in the Lexicon.
* **Display Customizations:** Modify details about how this metric and its data appear by default.
* **Delete:** Remove a saved metric from the project. Note, any reports using that saved metric will retain the definition, but be displayed in an unsaved state.

<Frame>
  <img alt="" />
</Frame>


# Sessions
Source: https://docs.mixpanel.com/docs/features/sessions

Compute sessions based on existing event data

Use Sessions in Mixpanel to answer questions like:

* How much time do users spend on my site per session?
* What are the average number of pages visited per session?
* Which page is the most common landing page for a session?
* What % of sessions lead to a key action (like signing up or purchasing)?

## How Sessions Work

Mixpanel computes sessions automatically from the events you send us. This means you don't need to do any special tracking work on your end to make sessions work.

Sessions consist of two virtual events:

* **Session Start**
* **Session End**

The way sessions are computed, and thus how the Session Start and Session End events are generated, can be configured in any of the following ways:

* **Timeout Based (Default)**: The session starts when a user performs any event, and ends when the user is inactive for some period of time (default: 30 minutes).
* **Event Based**: Provide a starting event and ending event. The session starts when the user performs the starting event and ends when the user performs the ending event.
* **Property Based**: Provide a `session_id` property. All events that a user performs which have the same value for `session_id` are considered part of the same session.

Project Admins or Owners can choose between one of these configurations in [Project Settings](https://mixpanel.com/settings/project) > Overview > Session Settings.

Since Mixpanel computes sessions dynamically at query, you can change this definition at any time and it will apply historically. Read more [below](#session-computation-deep-dive).

## Use Cases

These use cases assume that you're tracking an event for each page a user views. You can do this automatically with our [Javascript SDK](/docs/quickstart/connect-your-data?sdk=javascript) or using a CDP like Segment.

To make these examples more interesting, we're using our own tracking on our [documentation site](/docs/what-is-mixpanel).

### How much time do users spend on my site per session?

Each Session event comes with a "Session Duration (seconds)" property, which is computed by Mixpanel and indicates the amount of time spent during the session.

You can use any of our aggregations (sum, average, 90th percentile, etc.) to study the time spent by your users per session. Here, we look at the average time spent per session:

<Frame>
  <img alt="session-average-duration" />
</Frame>

It looks like people spend \~5 minutes on average on our documentation site. Averages can hide skew, so we can also see a distribution by breaking down by the Session Duration property:

<Frame>
  <img alt="" />
</Frame>

Now we see a bi-modal distribution -- 70% of users spend less than a minute on the site, while only 20% spend more than 5 minutes. From here, you can click into the ">5 minutes" segment, select "View Users", and see a few qualitative examples of users who spent a lot of time on your site (where did they come from and what pages did they view?).

<Frame>
  <img alt="" />
</Frame>

### What are the average number of pages visited per session?

You can do this by dividing the number of Page View events by the number of Session Start events, with a formula.

<Frame>
  <img alt="" />
</Frame>

This tells us that the average number of pages per session is \~1.3 and has been fairly stable. This is fairly common due to bounces (sessions where users just see one page and quickly bounce). To filter out bounces, we can filter for sessions that are longer than 10 seconds:

<Frame>
  <img alt="" />
</Frame>

This looks more reasonable: it seems like most users view \~3 pages per session.

### Which page is the most common landing page for a session?

The Session Start event automatically inherits certain properties from the first event in the session (more on this [below](#session-properties)). Breaking down by the Current URL property tells you which pages are the most common landing pages for a session:

<Frame>
  <img alt="" />
</Frame>

Here we see that the most common landing page is the "What is Mixpanel?" page of our docs, followed by the page on "Identifying Users". We might use this insight to decide which parts of our documentation to invest more in.

### What % of sessions end with a Purchase?

This example uses our [E-Commerce demo dataset](https://mixpanel.com/project/3018488/view/3536632/app/funnels#bgRv2KTan2Tm) and shows how you can use Sessions in our funnels report:

<Frame>
  <img alt="" />
</Frame>

Here we see that \~22% of sessions lead to the user starting the Checkout flow. You can click any step of the funnel to dig into specific sessions that were successful or unsuccessful to understand this more.

## Session Computation Deep-Dive

Here, we provide more detail on how sessions are computed under the hood. Project Admins or Owners can choose between one of these session configurations in [Project Settings](https://mixpanel.com/settings/project) > Overview > Session Settings.

### Timeout-Based Sessions

A Timeout-Based Session in Mixpanel is defined as a group of events one user performs within a given time frame on your website or app. A session starts when a user performs an event that is not excluded from your Sessions Settings.

The set session length is a period of activity at which a session is ended. The end time of the session is the time that the last event was performed before this period of inactivity.

A session starts when a user performs an event and ends when a user stops performing events for long enough that the set session length expires. The time of "Session End" is the time that the last event was performed by the timeout.

A single user can start multiple sessions. Those sessions can occur on the same day, or over several days, weeks, or months. As soon as one session ends, another session can begin with the occurrence of a new event.

#### Session Timeout

This is the length of time that defines a session timeout after a period of inactivity in Mixpanel. You can set the session timeout period in minutes, hours, or days. The default length is 30 minutes.

Any non-excluded event performed within the timeout range of the session will restart the session timeout period on the session.

For example, say you set a session timeout length of 15 minutes. A user begins a session when they log into your app and perform the event “Log In.”

* The “Log In” event marks the beginning of the session, because that user has not performed other events before.
* The user then performs the “Start Game” event on your app after 14 minutes. This will restart the clock on the session timeout.
* If they then perform no events for 16 minutes, however, the session will end. The session ends at the moment that the “Start Game” event was performed, because it was the last event before a complete session timeout period elapsed.

Sessions are reset every 24 hours at midnight (according to your project timezone), so the maximum session timeout length is 24 hours. The minimum session timeout length is one minute.

#### Estimating Ideal Session Length

Use your [Time to Convert Chart in Funnels](/docs/reports/funnels/funnels-advanced#time-to-convert) to help determine an appropriate session timeout period that aligns with your users’ behavior.

<Frame>
  <img alt="image" />
</Frame>

<Frame>
  <img alt="image" />
</Frame>

In your Funnel you can select the event that denotes a "Session Start" in your app (such as “Log In”), and the "Session End" event (such as “Log Out”). Check the time it takes users to convert from the start event to the end event in the Time to Convert Chart, and this will give you an indicator of the average amount of time a session lasts in your app.

Be sure to exclude API-related events in your funnel to ensure that your conversion time is accurate. For example, if a user is receiving notifications from you every 25 minutes, and session timeout is every 30 minutes, then session length will be 24 hours.

Exclude events that don’t denote an action made by the user from your funnel to ensure that your conversion time is accurate. For example, if a user is receiving notifications from you every 25 minutes, and session timeout is every 30 minutes, then session length will be 24 hours.

#### Excluded Events

<Note>
  Events hidden in Lexicon are excluded from session calculations by default so you may notice session numbers change if you change an events status in Lexicon.
</Note>

Exclude events from being tracked as part of a session (such as backend API events that don’t denote an action made by the user on the site), to ensure the validity of session metrics. [Mixpanel API events](/docs/features/sessions#what-mixpanel-api-events-are-by-default-excluded-from-session-calculations) will be excluded by default, but external API events, such as a message sent through another program, will not be excluded. You can exclude events by going under Project Settings to Session Settings and selecting the events you wish to exclude.

For example, you should exclude events triggered when a message is sent to a user or when a user is added to an A/B test, as the user did not cause those events.

Recommended events to exclude that are not triggered by user activity:

* Events triggered when messages are sent to a user (including push notifications)
* Events triggered when a message is received
* Events tracked server-side, such as monthly membership payments not associated with a specific user action
* Events related to API activity

Custom events are not supported for exclusions. If you want to exclude a custom event, you can instead exclude the events that make up that custom event.

#### Examples

##### Example 1

<Frame>
  <img alt="/sessions6.png" />
</Frame>

Session timeout length is set for 30 minutes.

1. A user performs “Event A” at 1:00pm, starting the session and triggering the "Session Start" event.
2. They then wait 10 minutes and perform “Event B” at 1:10pm.
3. They do not perform any other events for 30 minutes, and the session ends and the "Session End" event is triggered. The time of Session End is the time of the last event performed at 1:10pm. Therefore the session length for “Session 1” is 10 minutes.
4. The same user then returns after 40 minutes and performs “Event C” at 1:50pm. As the previous session has already timed out, this triggers a new "Session Start" event and starts a new session.
5. The user then performs “Event D” 20 minutes later at 2:10pm.
6. They perform “Event E” 15 minutes later at 2:25pm.
7. When they do not perform any more events in the next 30 minutes, "Session End" is triggered. The time of the "Session End" is the last event performed at 2:25pm. Therefore the session length for “Session 2” is 35 minutes.

##### Example 2

<Frame>
  <img alt="/sessions7.png" />
</Frame>

Session timeout length is set for 30 minutes.

1. A user performs “Event A” at 11:30pm, starting the session and triggering the "Session Start" event.
2. They then wait 20 minutes and perform “Event B” at 11:50pm.
3. While this session is not timed to expire until 30 minutes after this event, all sessions are reset at midnight. Therefore, when the user performs “Event C” at 12:05am, it triggers a new "Session Start". The "Session End" time is the time that “Event B” was performed. Therefore the length of “Session 1” is 20 minutes.
4. “Event C” performed at 12:05am starts the session and triggers the "Session Start" event.
5. The user then waits 5 minutes and performs “Event D” at 12:10am.
6. They do not perform any other events for 30 minutes, and the session ends. The time of "Session End" is the time of the last event performed at 12:10am. Therefore the session length for “Session 2” is 5 minutes.

### Event-Based Sessions

An Event-Based Session in Mixpanel is defined by an event you choose as the "Session Start" (such as "Login"), and an event you choose as the "Session End" (such as "Log Out").

A single user can start multiple sessions. Those sessions can occur on the same day, or over several days, weeks, or months. As soon as a "Session End" event is performed, another session can begin with the occurrence of a new "Session Start" event.

If you haven't clearly defined events that denote the beginning and end of a session, then a Timeout-Based Session may be a better option for your project.

Sessions are reset every 24 hours at midnight (according to your project timezone), so the maximum session length is 24 hours

#### Examples

##### Example 1

<Frame>
  <img alt="/Untitled__3_.png" />
</Frame>

Session Start Event is set to `Login` and Session End Event is set to `Logout`.

1. A user performs “Login” at 11:15 pm triggering the “Session Start” event.
2. They then wait 30 minutes and perform “Event B” at 11:45 pm.
3. When the user performs “Logout” at 12:15 am, it triggers a new “Session End”. The "Session End" time is the time that “Logout” was performed. However, since all sessions are reset at midnight, the previous “Session Start” event is no longer associated with the “Session End Event”, and the session duration is not calculated for “Session 1”. Similarly, the “Session End Event” does not have an associated “Session Start Event” and session duration is not calculated for “Session 2”.

##### Example 2

<Frame>
  <img alt="/Untitled__4_.png" />
</Frame>

Session Start Event is set to `Login` and Session End Event is set to `Logout`.

1. A user performs “Login” at 11:00 am triggering the “Session Start” event.
2. They then wait 15 minutes and perform a second “Login” at 11:15 am. Since the user is already in a session, a new “Session Start” event is not triggered.
3. They then wait 30 minutes and perform a “Logout” at 11:45 am, ending “Session 1” and triggering a new “Session End” event. The duration for “Session 1” will be 45 minutes.
4. Finally, after 30 minutes, another “Logout” event is received at 12:15. Since there is no previous “Session Start” event, a “Session End” event is not created.

### Property-Based Sessions

A Property-Based Session in Mixpanel is defined by a property you choose as the "Session Id" (such as "session\_id") and the session persists as long as the value of the “Session Id” property remains constant. As soon as the value for “Session ID" changes, another session is started.

Events that do not contain a “Session Id” value are not used in calculating Session Start and End events. Events that contain an empty “Session Id” value (i.e. “session\_id”: “”) will be tracked and session events created upon transition.

Like Event Based Sessions, Sessions are reset every 24 hours at midnight (according to your project timezone), so the maximum session length is 24 hours.

#### Examples

##### Example 1

<Frame>
  <img alt="/10260746661780" />
</Frame>

Session ID Property is set to `session_id`

1. A user performs “Event A” at 11:15 pm with the `session_id` property set to value `456` and triggering the “Session Start” event.
2. They then wait 30 minutes and perform “Event B” at 11:45 pm.
3. Since all sessions are reset at midnight, when the user performs “Event C” at 12:15 am, it triggers new “Session End” and "Session Start" events despite the `session_id` value remaining constant. The "Session End" time is the time that “Event B” was performed resulting in a session length of 30 minutes for “Session 1”.
4. The user then waits 15 minutes and performs “Event D” at 12:30am.
5. Assuming the next event has a different `session_id` or no other events occur before the second day ends, then another "Session End" event will be triggered. The time of the "Session End" is the last event performed at 12:30 am. Therefore the session length for “Session 2” is 15 minutes.

##### Example 2

<Frame>
  <img alt="/Untitled__6_.png" />
</Frame>

Session ID Property is set to `session_id`

1. A user performs “Event A” at 11:00 am with the `session_id` property set to value `123` and triggering the “Session Start” event.
2. They then wait 15 minutes and perform “Event B” at 11:15 am with the `session_id` property set to value `456`. Since the `session_id` property has changed, “Session End” and “Session Start” events are triggered. The "Session End" time is the time that “Event A” was performed resulting in a session length of 0 minutes for “Session 1”.
3. The user then waits 15 minutes and performs “Event C” at 12:45 am.
4. The user then waits 15 minutes and performs “Event D” at 12:15 pm.
5. Assuming the next event has a different `session_id` or no other events occur for the remainder of the day, another "Session End" event will be triggered. The time of the "Session End" is the last event performed at 12:15 pm. Therefore the session length for “Session 2” is 60 minutes.

## Session Properties

Session Events will automatically have the following properties:

* Session Duration (Seconds): The duration between the "Session Start" and the "Session End" events in seconds.
* Session Event Count: The number of events during a session. This does not include Excluded Events and Hidden Events in Lexicon.
* Session Start Event Name: The original event name that triggered the Session Start event.
* Session End Event Name: The original event name that triggered the Session End event.

Mixpanel will also associate properties from the events that are part of a user's session onto the Session events. For Timeout-based sessions, the properties available on the "Session Start" and "Session End" events will be attributed to the first event in which the property is defined of the qualifying sessions. For event and property-based sessions, the properties will be associated with the event that triggers the session starting.

This is useful to answer questions like: "How many Sessions came from a particular country or device?"

By default, the list of associated properties is as follows:

* \$app\_build\_number
* \$app\_version\_string
* \$browser
* \$city
* \$country\_code
* \$current\_url
* \$device
* \$manufacturer
* \$os
* \$region
* mp\_country\_code
* mp\_lib
* mp\_platform
* utm\_campaign
* utm\_content
* utm\_source

You can add additional properties to be associated with the session by going under Project Settings to Session Settings and selecting the list of properties you wish to be associated with. They will then be accessible for analysis in Mixpanel reports. Note that there is a limit of 4 additional properties that can be associated with session analysis.

<Frame>
  <img alt="/10494738316692" />
</Frame>

## Session Controls in Reports

### Funnels

In [Funnels](/docs/reports/funnels/funnels-overview), once you have set up sessions, a “Session Start” and “Session End” events will be generated in the report based on the funnel criteria.

<Frame>
  <img alt="image" />
</Frame>

The event properties "Session Duration (Seconds)", "Session Event Count", "Session End Event Name", and "Session Start Event Name" can be used to break down or filter these results.

<Frame>
  <img alt="image" />
</Frame>

You can also choose to count Sessions instead of Uniques or Totals in the Conversion Details section. If you choose to count Sessions, the conversion window will be limited to one session.

Whenever you make a change to session settings, you can then review the impact of this change in the Funnels Time to Convert Chart. If you see a large group of users doing 4+ hour sessions or just having sessions of \< 1 minute, you can create cohorts from these user segments and then evaluate their behavior in Flows to confirm Sessions is set up correctly.

<Frame>
  <img alt="image" />
</Frame>

If you choose to count Uniques or Totals, you will be able to select a conversion window as usual, including Sessions.

<Frame>
  <img alt="image" />
</Frame>

### Flows

In [Flows](/docs/reports/flows), you can use the “Session Start” and “Session End” events to view the top Flows events within a session.

When you select sessions in Flows, the flow will be weighted by the number of sessions, rather than unique users.

### Insights

In [Insights](/docs/reports/insights), you can use the “Session Start” and “Session End” events to explore a variety of metrics:

* The total number of sessions over time
* The average session length per user
* Session duration broken down across all users
* The average number of sessions per user
* Sessions calculated in formulas

<Frame>
  <img alt="image" />
</Frame>

When you select sessions in Insights, you will be viewing total session counts, rather than uniques or totals.

The event properties "Session Duration (Seconds)", "Session Event Count", "Session End Event Name", and "Session Start Event Name" can be used to break down or filter these results.

#### Aggregation by Sessions

In Insights, you can also count the number of sessions that contained a particular event. Select the **Total** drop-down beside an event in your Insights query to select **Sessions**.

<Frame>
  <img alt="image" />
</Frame>

For example, select an event that determines success for your company, such as "Product Purchase". Using this aggregation you can track how many sessions contained a purchase.

## FAQ

### How can I find the average session duration using Mixpanel?

You can do so using the "Session Duration (seconds)" property associated with our Session Start/End events, which would measure the Session Duration in Seconds. To change it from seconds to minutes, you can use our formula and divide it by 60. To find the average session duration across all users, you may refer to this report here: [https://mixpanel.com/s/vcXKR ](https://mixpanel.com/s/3rXLmT)

### How can I find the average session duration per user using Mixpanel?

Similarly, you can use the same property as above. In this case, you would need to use our aggregate properties per user feature. If you select "Aggregate Properties per User" and then "Sum", it will add up all Session Lengths for any given day and divide it by all unique users. You can then apply a formula to express the values in minutes, simply by dividing by 60: [https://mixpanel.com/s/3k1bct](https://mixpanel.com/s/3k1bct)

For additional information, I've also included Formula B to show how "Sum per User by Average" works.

### What Mixpanel API events are by default excluded from session calculations?

* `$identify`
* `$create_alias`
* `$merge`
* `$hotshard_events`
* Message Sent (`$campaign_delivery`)
* Message Bounced (`$campaign_bounced`)
* Message Marked Spam (`$campaign_marked_spam`)
* Message Suppressed (`$message_suppressed`)
* Message Unsubscribed (`$unsubscribe`)
* Campaign Entered (`$journey_entered`)


# Slack Integration
Source: https://docs.mixpanel.com/docs/features/slack-integration



Connect Mixpanel to your Slack workspace to help share reports with your colleagues faster. You can (1) set up an alert to send a message to a Slack channel, (2) set up a Board Subscription to send a message to a Slack channel, or (3) share previews of any Mixpanel report in Slack.

To send an alert to a Slack Channel, see [Custom Alerts](/docs/features/alerts). To set up a board subscription to a Slack Channel, see [Advanced Board Functionality - Subscriptions](/docs/boards/advanced#board-subscriptions).

The Mixpanel application for Slack will also automatically unfurl a preview of any Mixpanel link, including chart images for certain reports, making it easy for anyone in your Slack workspace to learn from your Mixpanel analyses.

## Enable the Integration

To enable the integration, log in to both Mixpanel and Slack, then click [here](https://mixpanel.com/slack/oauth?slack_v2=true) to authorize the Slack workspace:

<Frame>
  <img alt="/Screen_Shot_2020-06-15_at_10.41.00_PM.png" />
</Frame>

After clicking allow, you'll return to Mixpanel, where you'll see a success banner:

<Frame>
  <img alt="/Screen_Shot_2020-06-15_at_10.42.06_PM.png" />
</Frame>

At this point, Mixpanel is a part of your Slack workspace, and any Mixpanel links you send in Slack will unfurl with metadata, and if applicable a chart preview.

Once at least one member of your Mixpanel organization has set up the Mixpanel Integration for Slack for their account, any other members of the Slack workspace will see a prompt the next time they paste a Mixpanel link. The prompt will ask them to connect their own Mixpanel account to Slack as well. If they choose to do so, Slack will guide them through the authentication flow. Once they have successfully connected Mixpanel to Slack, any further links they paste in Slack will unfurl.

## Using the Integration

Once you've set up the integration, Mixpanel links pasted in Slack will unfurl. Most links will provide some basic link metadata, and links to Insights, Flows, Funnels, or Retention reports will also include a chart preview, for example:

<Frame>
  <img alt="/slack_app_demo.png" />
</Frame>

## Permissions

Mixpanel does not restrict who can enable the Mixpanel integration for Slack. However, your Slack workspace may limit who can perform the connection.

After Mixpanel is connected to Slack, any Slack user who posts a Mixpanel link will be prompted to connect their own account to unfurl report previews. Performing this integration at the user level ensures that only reports the user has access to will unfurl in Slack.

## Privacy

The Mixpanel app for Slack adheres to Mixpanel's overall privacy policy, available in full here: [https://mixpanel.com/legal/privacy-policy/](https://mixpanel.com/legal/privacy-policy/).


# Mixpanel MCP Server
Source: https://docs.mixpanel.com/docs/mcp



## Overview

Mixpanel provides a hosted [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI assistants direct access to your Mixpanel data. Once connected, you can query events, funnels, flows, retention, session replays, and more using natural language — no dashboard navigation required.

A typical workflow looks like:

1. **Discover**: Find your projects, events, and properties
2. **Query**: Run insights, funnels, flows, or retention analyses
3. **Create**: Build dashboards, organize Lexicon, or manage data quality issues
4. **Iterate**: Refine with follow-up questions in the same conversation

## Available Tools

| Category                   | Tool                                             | Description                                                                                            |
| -------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Analytics**              | `Run-Query`                                      | Execute insights, funnels, flows, and retention queries                                                |
|                            | `Get-Query-Schema`                               | Get the full JSON schema for building a query                                                          |
|                            | `Get-Report`                                     | Retrieve a saved report, optionally including results                                                  |
|                            | `Display-Query`                                  | Display an interactive chart widget for a previously-run query                                         |
| **Dashboards** (Boards)    | `Create-Dashboard`                               | Create a new dashboard with text cards and reports                                                     |
|                            | `List-Dashboards`                                | Browse dashboards in a project                                                                         |
|                            | `Get-Dashboard`                                  | Retrieve a dashboard's metadata, text cards, and reports                                               |
|                            | `Update-Dashboard`                               | Modify a dashboard's metadata, rows, and layout                                                        |
|                            | `Duplicate-Dashboard`                            | Create a copy of an existing dashboard                                                                 |
|                            | `Delete-Dashboard`                               | Delete a dashboard                                                                                     |
| **Data Discovery**         | `Get-Business-Context`                           | Get org- and project-specific business context, vocabulary, and query instructions                     |
|                            | `Get-Projects`                                   | List your projects and workspaces                                                                      |
|                            | `List-Organizations`                             | List organizations the current user belongs to                                                         |
|                            | `Get-Events`                                     | Browse and search events in a project, optionally including full metadata                              |
|                            | `List-Properties`                                | List and search event or user properties in a project                                                  |
|                            | `Get-Property-Values`                            | Discover values for a specific property                                                                |
|                            | `Search-Entities`                                | Search across dashboards, reports, experiments, feature flags, and more                                |
|                            | `Get-Issues`                                     | Get data quality issues filtered by event, property, type, or date                                     |
|                            | `Get-Lexicon-URL`                                | Get a direct link to an event or property in Lexicon                                                   |
| **Data Management**        | `Edit-Event`                                     | Update event description, display name, tags, or visibility                                            |
|                            | `Edit-Property`                                  | Update property description, display name, hidden status, or PII classification                        |
|                            | `Bulk-Edit-Events`                               | Edit multiple events at once (up to 50) with uniform or per-event fields                               |
|                            | `Bulk-Edit-Properties`                           | Edit multiple properties at once (up to 50) with uniform or per-property fields                        |
|                            | `Create-Tag`                                     | Create a new tag in Lexicon                                                                            |
|                            | `Rename-Tag`                                     | Rename an existing tag across all associated events and properties                                     |
|                            | `Delete-Tag`                                     | Remove a tag from your project                                                                         |
|                            | `Dismiss-Issues`                                 | Bulk-dismiss data quality issues by event, property, or type                                           |
|                            | `Update-Business-Context`                        | Update business context at the project or organization level                                           |
|                            | `Find-Duplicate-Groups`                          | Find groups of duplicate or near-duplicate names in a Mixpanel project for events and event properties |
|                            | `Dismiss-Duplicate-Group`                        | Dismiss a duplicate-group suggestion                                                                   |
|                            | `Merge-Group`                                    | Merge a group of duplicate names into one entity                                                       |
| **Custom Properties**      | `Create-Custom-Property`                         | Create a custom property                                                                               |
|                            | `Get-Custom-Property`                            | Get the definition and details of a custom property                                                    |
|                            | `Update-Custom-Property`                         | Update an existing custom property's definition                                                        |
| **Cohorts**                | `Create-Cohort`                                  | Create a new cohort                                                                                    |
|                            | `Get-Cohort`                                     | Retrieve a cohort's metadata and definition by ID or name                                              |
|                            | `Update-Cohort`                                  | Update an existing cohort                                                                              |
|                            | `Delete-Cohort`                                  | Delete an existing cohort                                                                              |
|                            | `List-Cohorts`                                   | List cohorts in project                                                                                |
|                            | `Describe-Cohort-Schema`                         | Returns documentation and reference information about the structure of cohort definitions              |
| **Lookup Tables**          | `Create-Lookup-Table`                            | Create a new lookup table                                                                              |
|                            | `Get-Lookup-Table`                               | Read a lookup table's schema, row count, and a preview of its rows by ID/name                          |
|                            | `Update-Lookup-Table`                            | Update an existing lookup table                                                                        |
| **Metrics**                | `Create-Metric`                                  | Create a saved metric (behavior or formula) for reuse across experiments                               |
|                            | `Get-Metric`                                     | Get the full definition of a saved metric                                                              |
|                            | `List-Metrics`                                   | List all saved metrics in a project                                                                    |
|                            | `Update-Metric`                                  | Update a saved metric's name, definition, or description                                               |
| **Session Replays**        | `Get-User-Replays-Data`                          | Analyze a specific user's replays alongside their event data                                           |
| **Experiments** *(Beta)*   | `List-Experiments`                               | List and search experiments in a project                                                               |
|                            | `Get-Experiment`                                 | Retrieve experiment details, configuration, and results                                                |
|                            | `Create-Experiment`                              | Create a new experiment                                                                                |
|                            | `Update-Experiment`                              | Modify an experiment's configuration or manage its lifecycle                                           |
|                            | `Get-Experiment-Setup-Guidance`                  | Get best-practice guidance for designing an experiment                                                 |
|                            | `Get-Experiment-Results-Interpretation-Guidance` | Get best-practice guidance for interpreting experiment results                                         |
|                            | `Explain-Experiment-Health-Check`                | Explain why an experiment's health check is firing, or confirm it's healthy                            |
|                            | `Run-Experiment-Pre-Launch-Checks`               | Cross-reference a draft experiment's config against best practices before launch                       |
|                            | `Search-Prior-Experiments`                       | Search the project's experiment store for prior tests on the same surface                              |
| **Feature Flags** *(Beta)* | `List-Feature-Flags`                             | List and search feature flags in a project                                                             |
|                            | `Get-Feature-Flag`                               | Retrieve feature flag details and targeting rules                                                      |
|                            | `Create-Feature-Flag`                            | Create a new feature flag                                                                              |
|                            | `Update-Feature-Flag`                            | Modify a feature flag's configuration or targeting                                                     |
|                            | `Get-Feature-Flag-Setup-Guidance`                | Get best-practice guidance for creating and configuring a feature flag                                 |
|                            | `Get-Feature-Flag-Lifecycle-Guidance`            | Get best-practice guidance for rollout, kill-switch, and cleanup of a feature flag                     |

<Warning>
  **Experiments and Feature Flags tools are in open beta** and available to all users. Audience targeting and cohort editing are not yet supported via MCP — use the Mixpanel UI instead.
</Warning>

## MCP Server URLs

| Region | URL                               |
| ------ | --------------------------------- |
| US     | `https://mcp.mixpanel.com/mcp`    |
| EU     | `https://mcp-eu.mixpanel.com/mcp` |
| IN     | `https://mcp-in.mixpanel.com/mcp` |

## Permissions & Access

<Note>
  **New free and growth accounts (created after August 1, 2026):** MCP is enabled by default — no admin action required. Organization admins can disable it in **Settings → Org → Overview** if needed.

  **All other accounts:** An organization admin must enable MCP in **Settings → Org → Overview** before anyone can connect.

  Changes can take up to 15 minutes to take effect.
</Note>

Once MCP is enabled, any Mixpanel user in your organization can connect. Users authenticate with their own Mixpanel credentials, so all existing project permissions and roles apply — users can only see data from projects they already have access to.

<Note>
  **Verified Mode.** If an admin has enabled [Verified Mode](/docs/mixpanel-agent#verified-mode) in Project Settings, MCP query results still include **all requested entities** — Verified Mode does not remove or exclude data. Entities that haven't been verified in [Lexicon](/docs/data-governance/lexicon#verify-data) are flagged as unverified, and results prefer verified equivalents where they exist.
</Note>

## Connecting to the MCP Server

Mixpanel's MCP server supports two authentication methods:

* **OAuth** — Users sign in through a browser with their Mixpanel credentials. Best for interactive use in AI assistants like Claude, ChatGPT, or Cursor.
* **Service Accounts** *(Beta)* — A static credential header with no browser login required. Best for CI/CD pipelines, automated agents, and shared team setups.

Choose the method that fits your use case below.

## Connecting with OAuth

### Claude

[Add Mixpanel to Claude](https://claude.ai/directory/connectors/29d60a67-6f16-489b-8a1e-efdcece8d1f6) and complete the Mixpanel OAuth flow.

For EU or IN regions, use **Settings → Connectors → Add Custom Connector** instead, and enter your [MCP Server URL](#mcp-server-urls).

### Claude Code

[Claude Code MCP docs](https://code.claude.com/docs/en/mcp)

```bash theme={"system"}
claude mcp add --transport http mixpanel https://mcp.mixpanel.com/mcp
```

Then authenticate by running `/mcp` inside Claude Code and completing the Mixpanel OAuth flow in your browser.

### ChatGPT

[Add Mixpanel to ChatGPT](https://chatgpt.com/apps/mixpanel/asdk_app_69b2e9aed45c8191b254b207dfcc2bb4) and complete the Mixpanel OAuth flow.

**Note:** If your workspace is in the **EU or IN region** **or** you want to publish a custom plugin to your workspace for teammates to use, you must first enable **Developer Mode**.

Go to **Settings → Security and login**, then enable **Developer Mode**.

Once **Developer Mode** is enabled, add a new plugin.

<Frame>
  <img alt="Image" />
</Frame>

1. Go to Plugins **→** add a New Plugin — set the [MCP Server URL](#mcp-server-urls) to your regional endpoint and Authentication to **OAuth**
2. Complete the Mixpanel OAuth flow
3. Optionally publish the connector to your workspace so teammates can use it

### Codex

1. Go to **Settings → MCP Servers → + Add Server**
2. Provide a name (e.g. Mixpanel) and select **Streamable HTTP**
3. Enter your [MCP Server URL](#mcp-server-urls) and click **Save**

### Codex CLI

Add the following to `~/.codex/config.toml` (use the EU or IN URL if needed):

```toml theme={"system"}
[mcp_servers.mixpanel]
url = "https://mcp.mixpanel.com/mcp"
```

Then authorize:

```bash theme={"system"}
codex mcp login mixpanel
```

### Notion

1. Create a new Agent from the **Agents** section in the Notion sidebar
2. In the Agent's **Settings**, go to **Tools and Access → + Add Connection**
3. Select **Mixpanel** and complete the OAuth flow

### Gemini CLI

```bash theme={"system"}
gemini mcp add mixpanel npx -y mcp-remote https://mcp.mixpanel.com/mcp
```

Or edit `~/.gemini/settings.json` manually and add:

```json theme={"system"}
{
  "mcpServers": {
    "mixpanel": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.mixpanel.com/mcp"]
    }
  }
}
```

### Cursor

1. Go to **Settings → Tools & MCP → New MCP Server** to open `~/.cursor/mcp.json`
2. Add the following (use the EU or IN URL if needed):

```json theme={"system"}
{
  "mcpServers": {
    "mixpanel": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.mixpanel.com/mcp"]
    }
  }
}
```

3. Save the file — Cursor will prompt you to authorize with Mixpanel on first connect

### Microsoft Copilot (JSON-configured clients)

Any client that supports the MCP JSON config format, including Microsoft Copilot, can connect using the same JSON snippet from the Cursor section above. The first time it connects it will prompt you to authorize with Mixpanel.

## Connecting with Service Accounts

<Warning>
  **Beta.** Service account authentication for MCP is in beta. The interface may change.
</Warning>

[Service accounts](/reference/Mixpanel%20APIs/authentication/service-accounts) are non-human Mixpanel users designed for scripts, back-end services, and automated workflows. They authenticate via a static header — no browser-based login is required.

Use service accounts when you need a headless MCP connection, such as CI/CD pipelines, automated agents, or shared team setups. The service account's project permissions apply: it can only access projects it has been added to.

### Prerequisites

1. **Create a service account** in your [Organization settings](https://mixpanel.com/settings/org#serviceaccounts) or [Project settings](https://mixpanel.com/settings/project#serviceaccounts). You need Owner or Admin permissions to do this.
2. **Save the username and secret** — you won't be able to view the secret again after creation.
3. **Ensure the service account has access** to the projects you want to query via MCP.
4. **MCP must be enabled** by an org admin in **Settings → Org → Overview** (free and growth accounts created after August 1, 2026 have it enabled by default).

### Generating the Authorization Header

Encode the service account credentials as a base64 string and construct the authorization header:

```bash theme={"system"}
echo -n "<username>:<secret>" | base64
```

This outputs a base64-encoded string. The full header value is:

```text theme={"system"}
Authorization: Bearer Basic <base64-encoded-credentials>
```

For example, if your username is `my-sa.abc123.mp-service-account` and your secret is `my-secret`, run:

```bash theme={"system"}
echo -n "my-sa.abc123.mp-service-account:my-secret" | base64
# Output: bXktc2EuYWJjMTIzLm1wLXNlcnZpY2UtYWNjb3VudDpteS1zZWNyZXQ=
```

The header would be: `Authorization: Bearer Basic bXktc2EuYWJjMTIzLm1wLXNlcnZpY2UtYWNjb3VudDpteS1zZWNyZXQ=`

<Warning>
  Treat the base64-encoded credentials like a password. Use environment variables or secret managers instead of hardcoding them in config files.
</Warning>

### Claude

[Claude Desktop MCP docs](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)

Open your config file via **Settings → Developer → Edit Config** and add the following (use the EU or IN URL if needed):

```json theme={"system"}
{
  "mcpServers": {
    "mixpanel": {
      "url": "https://mcp.mixpanel.com/mcp",
      "headers": {
        "Authorization": "Bearer Basic <base64-encoded-credentials>"
      }
    }
  }
}
```

Restart Claude Desktop after saving the file.

### Claude Code

[Claude Code MCP docs](https://code.claude.com/docs/en/mcp)

```bash theme={"system"}
claude mcp add --transport http mixpanel https://mcp.mixpanel.com/mcp \
  --header "Authorization: Bearer Basic <base64-encoded-credentials>"
```

Or add it to your `.mcp.json` file using an environment variable:

```json theme={"system"}
{
  "mcpServers": {
    "mixpanel": {
      "type": "http",
      "url": "https://mcp.mixpanel.com/mcp",
      "headers": {
        "Authorization": "Bearer Basic ${MIXPANEL_SA_TOKEN}"
      }
    }
  }
}
```

Set `MIXPANEL_SA_TOKEN` to your base64-encoded credentials before starting Claude Code.

### Codex

1. Go to **Settings → MCP Servers → + Add Server**
2. Provide a name (e.g. Mixpanel) and select **Streamable HTTP**
3. Enter your [MCP Server URL](#mcp-server-urls)
4. Add the [authorization header](#generating-the-authorization-header) and click **Save**

### Codex CLI

Add the following to `~/.codex/config.toml` (use the EU or IN URL if needed):

```toml theme={"system"}
[mcp_servers.mixpanel]
url = "https://mcp.mixpanel.com/mcp"
headers = { Authorization = "Bearer Basic <base64-encoded-credentials>" }
```

### Notion

Service accounts are not supported through the Notion agent connector. Use [Cursor](#cursor-1) or another client that supports custom headers instead.

### Gemini CLI

```bash theme={"system"}
gemini mcp add mixpanel npx -y mcp-remote https://mcp.mixpanel.com/mcp \
  --header "Authorization:Bearer Basic <base64-encoded-credentials>"
```

Or edit `~/.gemini/settings.json` manually and add (use the EU or IN URL if needed):

```json theme={"system"}
{
  "mcpServers": {
    "mixpanel": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.mixpanel.com/mcp",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer Basic <base64-encoded-credentials>"
      }
    }
  }
}
```

### Cursor

[Cursor MCP docs](https://cursor.com/docs/mcp)

1. Go to **Settings → Tools & MCP → New MCP Server** to open `~/.cursor/mcp.json`
2. Add the following (use the EU or IN URL if needed):

```json theme={"system"}
{
  "mcpServers": {
    "mixpanel": {
      "url": "https://mcp.mixpanel.com/mcp",
      "headers": {
        "Authorization": "Bearer Basic ${env:MIXPANEL_SA_TOKEN}"
      }
    }
  }
}
```

3. Set the `MIXPANEL_SA_TOKEN` environment variable to your base64-encoded credentials

### Microsoft Copilot (JSON-configured clients)

Any client that supports the MCP JSON config format, including Microsoft Copilot, can connect using the same JSON snippet from the Cursor section above — adding the `headers` object with the [authorization header](#generating-the-authorization-header).

## Example Queries

Once connected, try asking your AI assistant:

**Understand your data**

* "What projects do I have access to?"
* "What are the most fired events this week?"
* "Which properties on `checkout_completed` are marked as PII?"

**Query & analyze**

* "How many sign ups did we have in February?"
* "What's our signup-to-purchase conversion rate this month vs last month?"
* "Show 7-day retention for users who completed onboarding in Q1"
* "Which acquisition channels have the best 30-day retention?"

**Create & build**

* "Create a board of purchase metrics"
* "Build a weekly growth dashboard with signups, activations, and churn"

**Automate Lexicon work**

* "Add descriptions to any events that don't have one"
* "Tag all checkout-related events with 'Checkout'"
* "Hide any events that haven't fired in the last 90 days"
* "Find all properties that look like PII but aren't flagged yet"

**Triage data quality**

* "Show me all open data quality issues for the Signup event"
* "Dismiss all issues for events we deprecated last quarter"

**Test & ship**

* "Create an experiment to test whether showing a progress indicator during onboarding increases activation rate"
* "Create a feature flag for our new AI-powered search"
* "How did our checkout experiment perform? Did it reach significance?"

**Investigate users**

* "This user reported a bug — what happened in their last 3 sessions?"
* "Walk me through what \[user ID] did before they churned"

## Security Considerations

<Warning>
  The MCP server does not currently support HIPAA requirements. Mixpanel's Business Associate Agreement (BAA) does not cover this feature.
</Warning>

When connected, the AI assistant can both **read and write** to Mixpanel on your behalf. Your Mixpanel data is also sent to whichever AI provider you're using (Claude, ChatGPT, etc.), so review that provider's data handling policies before connecting.

**Access controls**

* MCP must be enabled by an org admin in **Settings → Org → Overview** (free and growth accounts created after August 1, 2026 have it on by default; admins can still disable it)
* Users can only access projects they already have permission to view in Mixpanel
* All existing roles and project-level permissions remain in effect

**Other considerations**

* Check applicable compliance requirements (GDPR, CCPA, etc.) before connecting to projects with personal data
* If using a shared AI environment (e.g., a team workspace), be aware that conversation history may be visible to others

## Troubleshooting

* **"MCP access is not enabled for this project"**: Ask your org admin to enable MCP in **Settings → Org → Overview**.
* **"Missing scope" error**: Your cached auth token was created with an outdated scope list. Delete the `.mcp-auth` folder in the directory where you ran the authorization command, then re-authorize.
* **Authorization fails**: Ensure your Mixpanel account has access to at least one project and that MCP is enabled at the org level.
* **Desktop app doesn't pick up config changes**: Restart the application after editing the config file.

## Rate Limits

* A maximum of 600 MCP requests/hour per user

## Building Custom Integrations (OAuth)

If you're building a third-party MCP client or custom integration, use the following OAuth configuration.

### OAuth Discovery

Mixpanel's MCP server supports OAuth discovery via two well-known endpoints, following RFC 8414 and RFC 9728:

**Protected Resource Metadata (RFC 9728):** Discover which authorization servers can issue tokens for this resource:

```text theme={"system"}
https://mcp.mixpanel.com/.well-known/oauth-protected-resource/mcp
```

**Authorization Server Metadata (RFC 8414):** Discover authorization, token, and registration endpoints:

```text theme={"system"}
https://mcp.mixpanel.com/.well-known/oauth-authorization-server/mcp
```

The following endpoints are deprecated but still available:

```text theme={"system"}
/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server
```

### Dynamic Client Registration

| Region | Registration Endpoint                         |
| ------ | --------------------------------------------- |
| US     | `https://mixpanel.com/oauth/mcp/register/`    |
| EU     | `https://eu.mixpanel.com/oauth/mcp/register/` |
| IN     | `https://in.mixpanel.com/oauth/mcp/register/` |

### Authorization Code Flow with PKCE

Mixpanel uses **Authorization Code + PKCE (S256)**:

* **Authorization endpoint:** `https://{mixpanel_domain}/oauth/authorize`
* **Token endpoint:** `https://{mixpanel_domain}/oauth/token/`
* **Grant types:** `authorization_code`, `refresh_token`
* **Code challenge method:** `S256`
* **Token endpoint auth methods:** `none`, `client_secret_basic`, `client_secret_post`

### Required OAuth Scopes

**Mandatory:**

```text theme={"system"}
projects analysis events insights segmentation retention data:read funnels flows data_definitions
```

**Optional:**

```text theme={"system"}
dashboard_reports bookmarks user_details business_context
```

<Note>
  To request a specific subset of scopes, pass `--static-oauth-client-metadata '{ "scope": "..." }'` to `npx mcp-remote`. Otherwise all available scopes are requested automatically.
</Note>


# Metric Tree
Source: https://docs.mixpanel.com/docs/metric_tree



<Note>
  Metric Tree is a paid add-on. It is currently only offered to those on the Enterprise Plan.
</Note>

## Overview

Mixpanel Metric Tree is a "live" logical decision-making framework used to represent relationships between metrics and show the flow between inputs and outputs. The "live" metrics make it possible to understand the quantitative impact and trace the inputs driving it.

It is one space that simultaneously depicts both quantitative and qualitative data along with additional context, making it possible to discuss insights as a team across functions and make data-driven decisions together.

<Frame>
  <img alt="image" />
</Frame>

## Use Cases

* Data-driven decision: Clearly articulate what’s working vs not by looking at how your input metrics and initiatives are impacting your top business outcomes
* Align with your team, from Execs to ICs, and across teams on growth strategy & metrics by: Use this as the codified strategy map
* Collaborate on strategy, insights & actions during team rituals: Leverage this during weekly rituals to identify which areas require more focus, and add those insights in the tree for others to reference
* Evolve your metric tree, as your strategy evolves: With every planning cycle, update the initiatives and input metrics as goals and focus outcomes change.
* Use this as a plan to ensure you have the right data tracked: Use this as a guide to let you know which additional data needs to be tracked, or to ensure it’s modeled in the right way to define the metric

## Quick Start

### Step 1: Create your Metric Tree outline without data

The idea is to think through your strategy and the various hypotheses without confusing it with the data available today or the current value of metrics. Your strategy is more long-term. Use this strategy map to discuss and align with your teammates before putting in the effort to connect to a metric with data. To create a metric tree outline

* Add empty state metric cards to the tree. To create a metric card, choose `Metric` from the toolbar below.
* You can name these metric cards and link the connections. You can also add strategy cards to show the initiatives in place

<Frame>
  <img alt="image" />
</Frame>

#### Option: Build with AI

Don't know where to start? Skip the blank canvas and let AI draft your first metric tree. When creating a new tree, click "Build with AI" under one of the two available starter templates.

You'll be prompted to enter:

* **Business name** — the name of your company or product
* **Business URL** — your website or product URL, which helps the AI understand your domain and model
* **Custom instructions** (optional) — any specific context about your goals, team focus, or metrics you care about most

Click Submit, and within a few minutes you'll see a fully structured metric tree generated for your business — complete with hypothesized input metrics, drivers, and connections up to your top-level KPI.

Think of it as a first draft, not a final answer. Once it's generated, you can refine the structure, rename metrics, add or remove nodes, and connect real data just as you would with a manually built tree.

<Note>
  **Tip:** The more context you provide in the custom instructions field, the more tailored your tree will be. Custom instructions work at any scope — from a company-wide strategy to a single feature area. Here are some examples:

  For a product leader building a team-wide strategy tree:

  * "We're a B2B SaaS company. Focus on the metrics that drive trial-to-paid conversion and long-term retention across our entire funnel."
  * "Build a tree rooted in ARR, with branches for new business, expansion, and churn. We have separate teams owning each."

  For a PM zeroing in on a specific initiative or feature area:

  * "I own our onboarding flow. I want to understand what behaviors in the first 7 days predict long-term retention."
  * "We just launched a collaboration feature and I need to track whether adoption is driving engagement and upgrades."
  * "Focus on activation. Our north star is users who complete 3 core actions in week 1."
</Note>

### Step 2: Make the metrics real with data

Click on connect metric, and connect the metric card to the metric with data. This is a regular Mixpanel query panel. You can choose to bring in [saved metrics](/docs/features/saved-metrics-and-behaviors), or create a metric.

<Note>
  **NOTE**: We highly recommend saving metrics in the metric tree, especially those on the higher levels, so others on the project use only these standardized, verified metrics. Saved Metrics has additional abilities, such as adding owners to it.
</Note>

<Frame>
  <img alt="image" />
</Frame>

### Step 3: Add more context to your metrics

Make your tree more actionable for yourself and the team by adding context to it - whether it is pinned content with some interesting deep dive reports, or examining correlation and finding interesting insights to add to the logbook. You can learn more [here](/docs/metric_tree#customize-each-metric).

### Step 4: Share your metric tree & get started!

Metric Trees have similar permissions to Mixpanel boards. You can share the tree with anyone in the project: with view or edit access.

* Editors get access to edit the definition of metrics, add new metrics, add context, etc.
* Viewers get access to open and see the underlying formula definitions, and read the context and notes

Metric Tree is a multi-user space meant for collaboration and for you to use during your weekly team rituals. So many of you can be on the tree at the same time and edit it, and most importantly, add insights or actions for metrics you’re accountable for.

<Note>
  **NOTE:** When you hit undo, you undo only your last action. Also, the last edit on a metric persists for all.
</Note>

## Customize each metric

## Time comparisons that are relevant to the metric

To ensure your metric is showing the most apt time comparisons, you can now customize at a metric level which time comparisons do you want to show in the metric tree view.

For example, if I wanted a QoQ view instead of YoY, I would select:

* **Time range:** Last 3M
* **Compare to:** Previous quarter
* **Interval:** week; Interval determines the number of data points you have displayed in the metric line chart

<Frame>
  <img alt="image" />
</Frame>

<Note>
  * You can change the default time comparison settings for your tree, i.e, all metrics, by clicking on `Apply to All Metrics` after setting up the right time ranges for one metric
  * You can add up to 3 time ranges per metric card
  * On the metric card view, when you click on MoM, it shows the absolute value of the metric for the last 30 Days. If you switch and click on QoQ it will show you the absolute value of the metric for the last 3M
  * If you switch the default “display” on the metric card, all the other cards that have that time range will also switch, so you can compare metrics across the tree in a similar period.
</Note>

## Add owner to keep a person accountable for the metric

For any eligible metric, you can click on the owner icon and assign an owner

<Note>
  You can assign an owner only to a [saved metric](/docs/features/saved-metrics-and-behaviors)
</Note>

<Frame>
  <img alt="image" />
</Frame>

## Pin contextual reports & boards to the metric, to enable deep-dive

Click on a metric. When the query panel opens, navigate to the Context tab. Within the Context tab, pin reports and board in the ‘Pinned’ tab

<Frame>
  <img alt="image" />
</Frame>

## Add important insights to the logbook for future reference

Click on a metric. When the query panel opens, navigate to the Context tab. Within the Context tab, add entries into the ‘Logbook’ tab

<Frame>
  <img alt="image" />
</Frame>

## FAQ

### How do AI-generated metric trees work, and what data does Mixpanel use to generate them?

AI-generated metric trees are built using an outside-in analysis powered by OpenAI. The system draws on industry best practices, common growth models, and the context you provide about your product in the custom instructions field — such as your business model, team focus, or the specific outcome you're trying to drive.

At this time, none of your Mixpanel data is used. The AI has no access to your events, user data, or existing metrics. Everything it generates is based on publicly available information and the details you choose to share in the prompt.

This means the generated tree is a starting hypothesis, not a data-validated model. Treat it as a well-informed first draft that reflects what's known about your industry and product category — and then make it yours by connecting real metrics from your Mixpanel data.

### What does the "As Of" control on the top left of the metric tree do?

`As of` determines the end date reference point for the metric tree.

For example, if you want to look at how the metric tree looked at the end of Q1, i.e, March 2025, you could set "As of 31 March 2025". All the metrics in the metric tree which are based on last 30 Days, or the last 3 months etc, will look at measuring the value of last 30D as of 31 March 2025, i.e, 2-31 March 2025, instead of last 30D as of today.

<Frame>
  <img alt="image" />
</Frame>

### What does Filtering a tree do?

Filtering a tree is similar to filtering a board. It filters every metric in the metric tree. If you’re looking to filter only a specific metric, please use [inline filters](/docs/reports/funnels/funnels-advanced#inline-filtering-pre-query).

### How do I see the metric trend chart (metric time series)?

Access the 3-dot overflow menu on the top right of the metric tree. Click on Show/ Hide > Show Metric Chart.

If you want to look at a longer time series chart for a particular metric, go to the specific metric card, click on the overflow menu, and choose View Chart.

#### I want to move trees across projects. How do I do that?

You can copy a tree and paste a tree in a new project. To select the whole tree, use the `select tool` in the toolbar below, in the middle of the screen. Then  Copy (Cmd + C), and Paste (Cmd + V) in the new project.

### How many trees do you suggest we create?

Create minimal trees so there is a complete map of the strategy in one place vs across disparate trees. Ideally, start with one tree per company, and depending on the size, maybe create separate trees for each function or business line if required

### Does the top of a metric tree have to be revenue-related?

No, it doesn’t have to. We generally ask people to start a tree at L2 or L3 level where there is more functional ownership, for example, marketing can own Volume of Sign-Ups or Product can own WAU (Weekly Active Users).

### What is correlation? How do I access it?

Access the 3-dot overflow menu on the top right of the metric tree. Click on Show/ Hide > Show Correlation. Correlation numbers should show up across all the edges, i.e the connection between two metric cards.

<Frame>
  <img alt="image" />
</Frame>

Mixpanel shows Pearson Correlation Coefficient. It measures the strength and direction of a linear relationship between two time-series data sets. It produces a value between **-1 and 1**

For two metrics, **A** and **B**, each return time-series data, we compute Pearson correlation using the following formula:

$r = \frac{\sum{(A_i - \overline{A})(B_i - \overline{B})}}{\sqrt{\sum{(A_i - \overline{A})^2} \sum{(B_i - \overline{B})^2}}}$

Where:

* **$A_i$** and **$B_i$** are individual values in the time-series data of metrics A and B.
* **$\overline{A}$** and $\overline{B}$ are the mean (average) values of metrics A and B over the observed time period.
* **$r$** is the Pearson correlation coefficient.

The resulting **r-value** determines the correlation score displayed on the edge.

#### Interpreting the Correlation Score

* **(0.6 to 1.0) Strong Positive Correlation:** The two metrics tend to move in the same direction strongly. As one metric increases, the other increases. Similarly, as one metric decreases, the other decreases
* **(0.3 to 0.6) Moderate Positive Correlation :** Some relationship exists
* **(0.0 to 0.3) Weak Positive Correlation :** Some relationship exists, but it is not strong
* **(0.0) No Correlation:** Changes in one metric do not seem to have changes on the other
* **(-0.3 to 0.0) Weak Negative Correlation :** Some inverse relationship exists, but it is not strong
* **(-0.6 to -0.3) Moderate Negative Correlation :** Some inverse relationship exists.
* **(-1.0 to -0.6) Strong Negative Correlation :** The two metrics strongly move in opposite directions. As one metric increases, the other decreases and vice versa.

#### To compute the Pearson correlation, we use:

* **Time-series data** from both metrics.
* **Matching timestamps**: Data points are aligned by timestamp to ensure proper comparison.
* **A configurable time window**: The correlation is typically calculated over a specified time range (e.g., the last 30 days)
* **Some specific aspects to call out:**

  1. If 2 time-series data have different lengths, correlations are calculated based on the overlapping lengths between the 2
  2. All correlations are run on a daily granularity, since event data is available on a daily basis to compute metrics at that granular view.

#### Limitations of Correlation

* **Correlation does not imply causation**: A high correlation does not necessarily mean that one metric influences the other.
* **Non-linear relationships**: Pearson correlation captures only linear relationships. If the metrics are related in a non-linear way, this score might not reflect the true relationship.
* **Data Quality Matters**: Missing or misaligned data points can affect the accuracy of the correlation score.


# Migrating to Mixpanel
Source: https://docs.mixpanel.com/docs/migration



If you’re reading this, congrats on considering making the switch from another analytics provider to Mixpanel 🎊  Our migration guides are intended to outline how a migration works, what to expect, and how to mitigate the risks and switching costs of a migration whilst accelerate time to value.

## What a migration will solve

* Cut-over sending live data to Mixpanel
* Historical backfill of existing data (subject to what data can be modeled as events)
* Integrates easily with existing event data collection methods - SDKs, CDPs, DWH, RETL

## What a migration won’t solve

* Existing issues with data trust/quality or data governance → As part of the migration, we recommend a data audit as the first step to only transfer your valuable data and clean up trust/quality issues
* Reporting, Dashboards, and Saved Entities → As part of the migration, you should review your top used reports and dashboards from other tools and sit down with each team to re-build them in Mixpanel

## What level of effort does the migration take?

A migration primarily consists of 4 phases:

1. Technical migration of data → Data audit, Live data cut-over, Historical data import
2. Change management migration of end users → Champion identification, User interviews, Team by team specific trainings, Ensuring adoption for each team
3. Data governance and implementation optimization → Improving/Implementing data governance processes, Identifying missing or incorrect data, Optimizing workflows for adding/editing data
4. Ongoing success planning → Building a product analytics practice

From a technical perspective, the migration process is relatively straightforward. If you have an engineer with access to your data and the ability to write code/transforms to send data to new destinations, this can be done in a single sprint (1-3 weeks).

From an end user perspective, Mixpanel is simpler and easier to learn than other analytics tools but there of course will be a learning curve. The largest hurdle is copying over key saved reports, dashboards, etc. that the team is familiar with in your current tool and teaching them how to rebuild these in Mixpanel. We recommend doing this process in detail for each team, showing them how to recreate key analyses side-by-side in Mixpanel. You can then leverage your team champions to force multiply your adoption efforts.

When going through this migration, there is no better time to audit your own data and reports to only migrate what matters. Most data and reporting is stale after some time anyways, prioritize the data and reports your team uses every day for their Top 10 key questions. These can be easily copied over and Mixpanel also provides Customer Success resources during Onboarding to assist with this.

## Technical migration of data

### Migrating live data tracking

Depending on your current setup, the steps for migrating your live data tracking will differ. Please see the appropriate provider specific guides for more details on how to migrate your existing live data tracking and get started with Mixpanel.

* [Adobe Analytics Migration Guide](/docs/migration/adobe-analytics)
* [Amplitude Migration Guide](/docs/migration/amplitude)
* [Google Analytics Migration Guide](/docs/migration/google-analytics)

### Data audit

We’ve found from experience that \<20% of the data in a product analytics tool is used for 80%+ of the queries. This is especially true the longer you have been using a tool - over time teams add more and more tracking for new events and properties, and without strong data governance practices, you will inevitably have some messy data in your current analytics tool(s).

In the spirit of making sense of the mess, we don't recommended that you bring all historical data into Mixpanel. A common practice is to leverage your current providers' tooling to understand which reports, events, and properties are queried by your users. No queries in the past 30 days? These events and properties have probably gone stale - there is low value and high effort in bringing them to Mixpanel, so cut them from your import and do not migrate the existing tracking.

After you’ve gotten rid of the obvious (the reports, events, and properties no one uses), you can fine tune this approach by doing user interviews with your top users/champions. These users can help you explicitly define the data they need brought along to Mixpanel (mapped to their key questions and KPIs) so you can focus on what matters. Because these users are the ones building reporting others use, capturing their use cases and making them change agents can be highly beneficial to your migration.

This data audit step is optional, but highly recommended - It is a larger upfront investment to make it easier for your users to find useful metrics / reports and avoid higher maintenance costs in the future.

### Loading historical data

To backfill data, we recommend the following approaches:

* If you have a data warehouse: Leverage our [data warehouse connector](/docs/tracking-methods/warehouse-connectors) or our [Import API](/reference/import-events) to import to Mixpanel.
* If you have a data warehouse without your current provider's data: Export your data to the data warehouse so you have a record, and then use our data warehouse connector or Import API
* If you do not have a data warehouse: Since there is no historical record of data, for this method you will need to export your data from your current provider and move it into Mixpanel - we provide an easy to use helper function for this [here](https://github.com/mixpanel/mixpanel-utils)

To perform a successful historical data load, we recommend:

* Have your Mixpanel champion or owner first set up your [Organization settings](/docs/best-practices/project-setup#mixpanel-organization) and [Project settings](/docs/best-practices/project-setup#mixpanel-projects). This will ensure the right access level for your team and enable you to prepare the workspace for ingesting data. This can be done later but doing it up front will allow for you to set key settings for data ingestion (US vs EU servers, project timezone, etc.).
* Load a limited subset of the data into a test project (for example, a single day or data or a sample of the entire dataset) to get started. This will help you identify any errors in the end to end process before you do a full historical data load.
* Load a year’s worth (or less) of historical data during your migration. This will allow your team to review year-over-year trends easily and do historical analysis as needed, without sending a bunch of data which is stale and unlikely to be used.

For a more in-depth look into the steps required for a successful project migration, check out our [project migration playbook](/guides/strategic-playbooks/project-migration).

Note that backfilling historical data can have significant impact on your billing. Refer to [this section](/docs/pricing#are-monthly-events-calculated-based-on-ingestion-time-or-event-timestamp) for more details.

## Change management migration of end users

Once data is live, shift our focus to change management and migrating the existing users. You can mitigate risk here by:

* Going team by team to assess currently used reports in other analytics providers, as starting with a baseline of key known reports from another tool helps build trust and confidence for new users to Mixpanel
* Running targeted trainings where you re-build known reports side-by-side in Mixpanel to teach users to fish
* Building a product with awesome UI/UX that will make up for the up-front costs in simpler, more powerful analysis down the line

The goal is to focus on each team individually, and you can process multiple in parallel. A team is the perfect unit to focus on as they have shared context and goals, so their needs as far as metrics and analysis will be similar. You can then help each team to the point they can self-serve answers from Mixpanel to answer their questions.

## Data governance and implementation optimization

In many cases, your goal in a migration will be to complete the process as quickly as possible - after all, you may be paying for multiple providers at once. Assessing your data quality and governance is likely to be less of a priority in the short term.

We recommend once your data and users are migrated to utilize your learnings from these processes to assess the current state of your data trust and where you need to address data issues to gain adoption. This might mean needing to implement new datasets or improve existing tracking to increase the number of use cases which can be explored by end users. You can read more around our recommended approach and questions to ask yourself [here](https://mixpanel.com/blog/5-questions-for-planning-your-data-architecture/).

## Ongoing success planning

After the migration, we recommend you focus on longer term goals like:

* Improving Data Governance → Creating scalable processes and strategies for managing data at scale
* Optimizing Analysis → Helping end users analyze data for more use cases, faster via training and documentation
* Building a Product Analytics Practice → Cultural change to be a self-serve, data democratized organization

You can read more about how we do this [here](https://mixpanel.com/blog/establish-a-product-analytics-practice/).

## Not sure where to start or need help?

Mixpanel’s Customer Success team has worked with 10,000+ customers over the past 10+ years to help drive outcomes with product analytics. We’re always happy to discuss your team’s individual needs, our migration process, the support you’ll receive, or any other question you have — drop us a line at [success@mixpanel.com](mailto:success@mixpanel.com).


# Migrating from Adobe Analytics
Source: https://docs.mixpanel.com/docs/migration/adobe-analytics



If you haven't already, we recommend starting with our [Migration Guides Overview](/docs/migration) as it details the key components of migrating to Mixpanel from other analytics tools. Below we outline specific steps and considerations when migrating from Adobe Analytics.

## Differences in the data models

### Data Model

Mixpanel’s data model is based on events and properties, rather than Adobe which is schema-based with many different configurable data types. While this might be a shift if you come from the schema model where you define your data to be captured upfront before sending any data, we’ve found [schema-on-read](https://medium.com/mixpaneleng/under-the-hood-of-mixpanels-infrastructure-0c7682125e9b#schema-on-read) to be both more flexible and easier to set up and use.

* [Events](/docs/what-is-mixpanel#events) capture granular user actions, like a Pageview, Signup, or Purchase.
* [Properties](/docs/what-is-mixpanel#properties) capture attributes of those events, like which page was viewed, the UTM Campaign that led to a Signup, or the Item that was purchased.

Events and properties with schema-on-read let you get more granular than an enforced schema so you can spend your time analyzing data versus formatting it. Mixpanel automatically constructs a schema from the events and properties you send, so you can answer the same questions as before faster and with less development headaches.

In contrast, on Adobe, every user interaction comes across as a “hit”. Within “hits”, there are what Adobe terms “eVars”, which are variables that can be customized to the organization’s requirements. The following diagram helps to illustrate the key differences between Adobe and Mixpanel’s instrumentation: on Adobe, an administrator needs to manually instrument every metric before it can be used in the platform. For example, the administrator would need to create a separate metric for “Total Page Views” and “Unique Page Views” before an end user can query it. Whereas on Mixpanel, once the event “Page View” is sent, the end user easily, on the fly, whip up a report to show the page views by total vs. unique users.

<Frame>
  <img alt="image" />
</Frame>

In Mixpanel, we also have a separate table for users and user properties. If using Mixpanel’s SDK, unique users are identified by a `$device_id` to associate events to the same anonymous user. Once a user signs up or logs in, you’ll call .identify(\<user\_id>) to map users’ known user\_id to their `$device_id`. In Adobe on the other hand, unique users are identified by the concatenation of post\_visid\_high and post\_visid\_low properties on the “hit”. Adobe will take the first ID present from in the “hit” as the official visitor ID, and then use the concatenation of post\_visid\_high and post\_visid\_low as the standard of identifying unique visitors regardless of how they were identified as a [unique visitor](https://experienceleague.adobe.com/docs/analytics/export/analytics-data-feed/data-feed-contents/datafeeds-calculate.html?lang=en). For example, if you are setting a custom visitor ID (included in the "vid" query parameter), that ID will be used before other IDs that might be present on that same hit.

### Frequently used key metrics on Adobe and how they differ on Mixpanel

**A visit**: Always tied to a time period, so you know whether to count a new visit if the same user returns to your site. A visit ends when they meet any of the following criteria:

* **30 minutes of inactivity**: Almost all sessions end in this manner. If more than 30 minutes lapse between hits, a new visit begins.
* **12 hours of activity**: If a user consistently fires image requests without any 30-minute gaps for more than 12 hours, a new visit automatically starts.

  So for example, if a user visits the site for 20 hours without any 30-minutes gap:

  * In Mixpanel, we will register it as 1 session
  * In Adobe, this will be registered as 1 session, but 2 visits (assuming they default to the 30-minute gapped session)
* **2500 hits**: If a user generates a large number of hits without starting a new session, a new visit is counted after 2500 image requests.
* **100 hits in 100 seconds**: If a visit has more than 100 hits that occur in the first 100 seconds of the visit, the visit automatically ends. This behavior typically indicates bot activity, and this limitation is enforced to help increase report performance.

⚠️ **Caveats to behaviors that could affect Visit metrics**

If a visitor performs any of these actions, a new visit starts:

* Clears their cache mid-session and continues browsing your site
* Leaves your site open in a tab for longer than 30 minutes, then continues browsing
* Opens a different browser and navigates to your site on the same computer
* The same person browsing your site on different devices

**Page Views**: Not to be confused with Visits. Page views count the number of times a page is being viewed. Visits count the number of sessions for visitors. One visit can consist of one or more page views.

**Unique visitors**: Adobe has a rather complicated mechanism of identifying unique user as illustrated in the table on their help docs [here](https://experienceleague.adobe.com/docs/analytics/components/metrics/unique-visitors.html?lang=en). It lists the ways a visitor is identified, along with its priority. Some hits can have multiple visitor identification methods; in these cases the higher priority method is used.

\*\* As unique visitor identifiers are typically stored in a browser cookie, a new unique visitor is counted if they perform any of the following:

* Clears their cache at any time
* Opens a different browser on the same computer. One unique visitor is counted per browser.
* The same person browsing your site on different devices. A separate unique visitor is counted per device.
* Opens a private browsing session (such as Chrome’s Incognito tab).

As a result, many internal Adobe users aren't too sure of how unique visitors are actually calculated given that it’s also dependent on how their data set up is done by the consultants they hire, eventually making these calculations somewhat of a black box.

## Track forward looking real-time data

Choose your current implementation method for Adobe Analytics and follow the below steps for starting to send live data to Mixpanel.

### Warehouse Connectors

[Mixpanel Warehouse Connectors](/docs/tracking-methods/warehouse-connectors), allows you to natively import data from Snowflake, BigQuery or Redshift into Mixpanel. With this feature, you can set up recurring syncs from your data warehouse and ensure that Mixpanel is always in sync with your trusted data.

### Client-side SDKs & Server-side SDKs

You’ll have to setup Mixpanel fresh given Mixpanel leverages an event-based model that does not exist in Adobe Analytics. Depending on your current setup and how you’ve enabled data capture in Adobe, these steps will likely be as if you are starting an [entirely new implementation](/docs/getting-started/plan-your-implementation).

The rest of this guide will cover the Mixpanel JavaScript SDK for brevity, but the steps apply for any of our libraries.

We recommend the following steps to get started quickly:

* Configure the [Mixpanel JavaScript SDK](https://developer.mixpanel.com/docs/javascript-full-api-reference) to automatically track page views, where UTM params are tracked by default

  ```js theme={"system"}
  mixpanel.init('YOUR_TOKEN', {track_pageview: true});
  ```
* Track a few key [“value moment” events](/docs/getting-started/plan-your-implementation#value-moment-event) of interest

  ```js theme={"system"}
  // Send a "Played song" event to Mixpanel
  // with a property "genre"
  mixpanel.track(
      "Played song",
      {
          "genre": "hip-hop"
      }
  );
  ```
* Use the [Mixpanel Marketing KPI Template](https://mixpanel.com/project?show-template-selector=true) to build your initial board

This will allow you to explore Mixpanel’s capabilities with the lowest amount of lift to see value. The reporting around marketing analytics will also showcase reporting that end users are used to coming over from Adobe Analytics.

### Customer Data Platforms (CDPs)

CDPs like [Segment](https://segment.com/) have always tracked event data and synthesized them into a specific schema format for Adobe Analytics. You can add Mixpanel as a destination to your CDP and immediately start receiving the same data as your other destinations.

Since CDPs already collect all your data via 1 SDK and route to many downstream destinations, enabling Mixpanel is straightforward. Simply go to your CDP settings and add Mixpanel as a destination:

<Frame>
  ![Segment Connection](https://user-images.githubusercontent.com/129823695/234812593-dffee962-bb34-49b8-9686-96bc0f0565d8.png)
</Frame>

Once you set up the connection to Mixpanel, you can proceed with configuring key settings like:

* Which events and properties to send → only send what matters
* Edit any mappings/editing/filtering that has to be done on the data → ensure high data quality and governance
* Connection settings, or CDP specific settings for data syncs → control over how data is sent

We provide Mixpanel as a destination and setup guides for all of the most popular CDPs:

* [Segment](https://segment.com/docs/connections/destinations/catalog/actions-mixpanel/)
* [mParticle](https://docs.mparticle.com/integrations/mixpanel/audience/)
* [Rudderstack](https://www.rudderstack.com/docs/destinations/streaming-destinations/mixpanel/)

### Data Warehouse

If you have your Adobe Analytics instance sitting on top of data that you collect and store in your data warehouse, getting started is simple. Instead of transforming and modeling that data to send to Adobe, you would model the data as [Events](/docs/how-it-works/concepts) and send it to Mixpanel via a Reverse ETL (RETL) tool or via directly hitting our [Import API](/reference/import-events).

## Loading historical data

For most cases, we recommend starting fresh when migrating from Adobe Analytics. If you must import Adobe data, we strongly encourage loading historical data into a separate project as data structures, identity management, user cohort definitions, etc. are completely different in Adobe than in Mixpanel. In certain situations, retaining historical data in Mixpanel serves the purpose of enabling the team to visualize past trends. However, as this set of historical data would reside in a separate project, visualizing trends over time periods may pose challenges. For instances where historical data proves essential, we advise importing a year's worth (or less) of historical data during the migration process.

Note that backfilling historical data can have significant impact on your billing. Refer to [this section](/docs/pricing#are-monthly-events-calculated-based-on-ingestion-time-or-event-timestamp) for more details.

### Undertaking discovery: Why and what is historical data for

1. **Whats the purpose of bringing in historical data?**

   It’s key to understand if you would just like a place to store historical data once Adobe is sunset or would you actually need those historical data for key metrics analysis. If its the former, the recommendation would be to send those data into a warehouse rather than Mixpanel.
2. **What is the time frame which you are looking at for historical data?**

   We recommend up to 2 years worth of data and usually the cut off time to be the last month before the complete set of data flows into Mixpanel.
3. **Are there specific events and event properties which you would most likely query on Mixpanel?**

   Instead of running the full load which would take a long time for the data to be available in the Mixpanel project, are there specific events and properties which are considered P0 for your team? In that case when running the script the data will be available in a much shorter period of time.
4. **Given the complexity of unique identifiers in Adobe (also dependent on consultants have implemented for the organization), what is the logic for the main identifier for your unique visitors.**
5. **What is the limit to the % of discrepancies in which they are willing to accept**

   The differences in the data model between Mixpanel and Adobe means that there will be a higher than expected discrepancy range and based on some previous projects we have done with customers. The range looks to be around 5% for most metrics.

To backfill data, we recommend:

* If you already have your historical data in a warehouse,

  * Utilize our [warehouse connector](/docs/tracking-methods/warehouse-connectors), to send historical data into a separate Mixpanel project
* If you have a CDP, this should be straightforward

  * Utilize the CDPs backfilling feature, like [Segment Replay](https://segment.com/docs/guides/what-is-replay/), to re-send historical data to Mixpanel
* For any other implementation method

  * First, export your data to the data warehouse so you have a record of Adobe Analytics
  * Once exported, your data warehouse tables can be transformed and modeled into the [event format](/docs/data-structure/events-and-properties) Mixpanel expects
  * Leverage our [Import API](/reference/import-events) to send us the formatted events from your data warehouse

The process of importing old data with a different format has many potential issues - identity management, data discrepancies, etc. - as Mixpanel is fundamentally different than Adobe Analytics. It may be worth considering your use cases for importing old data before proceeding, as matching users and data across the systems can be time consuming.

For Adobe Analytics specifically, due to the complexity of the data format and the fact it is a specific schema for each customer means we are unable to provide advice for all scenarios without speaking to your team directly.

### Setting Up the Project(s)

To prevent any potential issues with identity management due to the drastic difference in data model, we recommend that the customer set up separate projects when importing historical data from Adobe.

We recommend customers use Simplified API for their identity management, because they can easily designate their anonymous id and prefix it with a \$device.

For any 3rd party integrations, the recommendation is to populate the identifiers that are being used on those 3rd party systems as user profile properties and utilize that as a mean to identify users when exporting out cohorts.

***This step needs to be done before any data is sent to the project.***

## Not sure where to start or need help?

If you're unsure how you currently track data, or might want to consider tracking data differently as you migrate to Mixpanel, we recommend starting [here](https://mixpanel.com/blog/guide-to-choosing-your-data-architecture/).

Mixpanel Customer Success and Support have been helping thousands of customers migrate from other tools to Mixpanel over the past decade. You can see an overview of the process we run with our Enterprise plan customers migrating from Adobe Analytics [here](https://mxpnl.notion.site/Adobe-Migration-Package-4035f7e2f62f43adb65e34b23ad14d23?pvs=4).

If you need help, just [reach out here](https://mixpanel.com/get-support) and we'll be ready to assist with advice specific to your situation.


# Migrating from Amplitude
Source: https://docs.mixpanel.com/docs/migration/amplitude



If you haven't already, we recommend starting with our [Migration Guides Overview](/docs/migration) as it details the key components of migrating to Mixpanel from other analytics tools. Below we outline specific steps and considerations when migrating from Amplitude.

## Differences in the data models

Both Mixpanel and Amplitude are product analytics tools which collect event-based behavioral data about your users. [Events](/reference/import-events) are commonly expressed as JSON which represent the name of the user action, the ID of the user, the time at which the action took place, and all associated metadata. Events are immutable, and represent data at the time of which an action takes place.

```json theme={"system"}
{
	"event": "Signup",
	"properties":
	{
		"time": 1618716477000,
		"distinct_id": "91304156-cafc-4673-a237-623d1129c801",
		"$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4",
		"Referred by": "Friend",
		"URL": "mixpanel.com/signup"
	}
}
```

In addition to events, Mixpanel supports an additional type of data that Amplitude does not. This data is known as [user profiles](/reference/profile-set), which represents dimensional data that is always updated to the most recent value for a user. User data allows you to segment your reporting by both historical point-in-time data as well as real-time dimensional data about your users.

```json theme={"system"}
{
	"$distinct_id": "13793",
	"$set":
	{
		"name": "Robert"
	}
}
```

We also support additional data for extending your use cases with Mixpanel:

* [Group profiles](/reference/group-set-property): Used with our Group Analytics product add-on to allow you to pivot quickly between users and other entities in your analysis. A common use case is for a B2B company to pivot between analyzing users and analyzing accounts.
* [Lookup tables](/reference/lookup-tables): For event data which was already sent, you can use these to extend the data already sent into Mixpanel. A common use case is taking an identifier like a transaction ID, item ID, etc. and using lookup tables to enrich the data with additional information like the amount, category, etc. from your data warehouse.

## Loading historical data

### Mixpanel's Migration Service

If you have under 15M events in Amplitude, you can migrate your historical Amplitude data using Mixpanel's free migration service.

Note that while the migration tool is free to use, backfilling historical event data can have significant impact on your billing. Refer to [this section](/docs/pricing#are-monthly-events-calculated-based-on-ingestion-time-or-event-timestamp) for more details.

Here's an example request to the migration service which you can customize:

```bash theme={"system"}
curl --request POST \
  --url https://migrate.api.mixpanel.com/amplitude \
  --header "Content-Type: application/json" \
  --data '{
	"AMPLITUDE_API_KEY": "YOUR_AMP_KEY",
	"AMPLITUDE_API_SECRET": "YOUR_AMP_SECRET",
	"MIXPANEL_TOKEN": "YOUR_MP_TOKEN",
	"START_DATE": "YYYY-MM-DD",
	"END_DATE": "YYYY-MM-DD"
  }'
```

This service will use your provided credentials to export Amplitude data, transform the data, and load event + user profiles into your Mixpanel project. If no dates are provided, the service defaults to a 30 day duration relative to the present.

[Watch the demo tutorial](https://www.loom.com/share/f947d42db01541a0b74953461e3c6cc0?sid=43c1ef52-d008-4b6d-9015-afa14b05901c) for more in-depth instructions on how to use the migration service.

Notes:

* Any events ingested via this method in the current month will count toward your plan. We recommend testing this while on a Free plan first. You may also pass a `"DRY_RUN" : true` param in the JSON which will show you how many events will be migrated.
* If you are using Mixpanel or Amplitude's EU data residency, pass `"REGION": "EU"` with your request.
* This migration service is in beta -- if you have questions or run into issues, please reach out to us [here](mailto:amplitude-migration@mixpanel.com).

### Data Warehouse Connectors

If you have access to your Amplitude data in your data warehouse, the most scalable way to bring this historical data into Mixpanel is by using our warehouse connector. At a high-level, the migration consists of 3 steps:

1. Set up a new Mixpanel project which is on [Simplified ID Merge system](/docs/tracking-methods/id-management#identity-merge-apis).
2. Transform Amplitude data in your data warehouse (sample SQL transformation included below).
3. Set up [Mixpanel Warehouse Connector](/docs/tracking-methods/warehouse-connectors) to initiate data sync from your data warehouse to Mixpanel.

##### Amplitude event schema

SQL query to flatten the JSON columns into individual columns:

```jsx theme={"system"}
SELECT
-- required fields
event_type,          -- to map Event Name
event_time,          -- to map Event Time

-- to map Insert ID
TO_HEX(SHA1(CONCAT(
      CONCAT('[amp] ', event_type),
      COALESCE(user_id, ""), 
      "-",
      CAST(event_time as STRING),
      "-",
      COALESCE(CAST(amplitude_id as STRING), "")
))) AS insert_id,

-- ID management
user_id,         -- to map User ID
amplitude_id,    -- to map Distinct ID
device_id,       -- to map Device ID

-- event properties
JSON_EXTRACT_SCALAR(event_properties, "$['artist']") AS artist,
JSON_EXTRACT_SCALAR(event_properties, "$['genre']") AS genre,
JSON_EXTRACT_SCALAR(event_properties, "$['song_title']") AS song_title,
JSON_EXTRACT_SCALAR(event_properties, "$['song_name']") AS song_name,
JSON_EXTRACT_SCALAR(event_properties, "$['page_name']") AS page_name,

-- user properties as event properties
JSON_EXTRACT_SCALAR(user_properties, "$['$email']") AS email,
JSON_EXTRACT_SCALAR(user_properties, "$['$name']") AS name,
JSON_EXTRACT_SCALAR(user_properties, "$['last_genre']") AS last_genre,
JSON_EXTRACT_SCALAR(user_properties, "$['lifetime_purchase']") AS lifetime_purchase

FROM `project.dataset.tablename`
```

Note: Make the `event_time` column as NOT NULLABLE so that it can be chosen to be a Full Sync.

Amplitude does not export `insert_id` column but even when it is an optional field in Mixpanel, it is recommended to generate it and pass it as best practice.

##### Amplitude user schema

For Users too, it would be important to flatten the JSON columns into individual columns. It is also important to reduce unnecessary engage calls hence, we’ll be extracting the latest event time of that user\_id to get all the user properties.

```jsx theme={"system"}
SELECT
    event_time,
    user_id,
    -- user properties
    JSON_EXTRACT_SCALAR(user_properties, "$['$email']") AS email,
    JSON_EXTRACT_SCALAR(user_properties, "$['$name']") AS name,
    JSON_EXTRACT_SCALAR(user_properties, "$['last_genre']") AS last_genre,
    JSON_EXTRACT_SCALAR(user_properties, "$['lifetime_purchase']") AS lifetime_purchase
FROM `project.dataset.tablename` t1
INNER JOIN (
    SELECT
        user_id,
        MAX(event_time) as max_event_time
    FROM `project.dataset.tablename`
    WHERE user_id IS NOT NULL
    GROUP BY user_id
) t2
ON t1.user_id = t2.user_id AND t1.event_time = t2.max_event_time
```

## Setting up Warehouse Connectors

Once you've transformed your data in your data warehouse, you can set up the [Mixpanel Warehouse Connector](/docs/tracking-methods/warehouse-connectors) to migrate your historical data into Mixpanel. We'd recommend first sending a month of data into a test project for validation.

You can learn more about event mappings [here](/docs/tracking-methods/warehouse-connectors#events). Here's an example of mappings for event table:

<Frame>
  <img alt="image" />
</Frame>

You can learn more about user mappings [here](/docs/tracking-methods/warehouse-connectors#user-profiles). Here's an example of mappings for user table:

<Frame>
  <img alt="image" />
</Frame>

##### Post-migration data validation

You can use our [Lexicon](/docs/data-governance/lexicon) or Events page to check that your data has successfully been ingested. However, if your historical events are older than 30 days, they will not show up on Lexicon, Events page or in the event dropdown menu across all reports. In this case, you can leverage our [Insights report](/docs/reports/insights) to validate the historical events, by selecting the import time frame and filtering by the following default properties:

* Warehouse Import ID (tracked as `$warehouse_import_id`)
* Warehouse Import Job ID (`$warehouse_import_job_id`)
* Import = true (`$import`)
* Source = warehouse-import (`$source`)

Please filter by tracked name, \$warehouse\_import\_id instead of the display name, “Warehouse Import ID”. You can find the properties values on the Warehouse Connector’ sync logs:

<Frame>
  <img alt="image" />
</Frame>

## Identifying your implementation method

Mixpanel accepts event data from a variety of different sources. Choose your implementation method first and then you can follow the below steps for sending data to Mixpanel.

We support the following data collection mechanisms:

* [Data Warehouse Connectors](#data-warehouse-connectors): Natively import data from Snowflake, BigQuery, Redshift, & Databricks into Mixpanel. Set up recurring syncs from your data warehouse and ensure that Mixpanel is always in sync with your trusted data.
* [Client-side SDKs & Server-side SDKs](#client-side-sdks--server-side-sdks): Simply replace Amplitude code calls to track events with Mixpanel calls instead
* [Customer Data Platforms (CDPs)](#customer-data-platforms-cdps) like [Segment](https://segment.com/): Go into your CDP settings to add Mixpanel as a destination, and point your data stream to Mixpanel
* [Import API](#import-api): Point your event ingestion pipeline to [Mixpanel’s robust API](/reference/import-events) for data ingestion
* [Reverse ETL](#reverse-etl-retl) (RETL) tools like [Census](https://getcensus.com): Go into your RETL settings to add Mixpanel as a destination, and point your syncs to Mixpanel

### Data Warehouse Connectors

You can set up the [Mixpanel Warehouse Connector](/docs/tracking-methods/warehouse-connectors) to set your implementation to Mixpanel. You can learn more about event mappings [here](/docs/tracking-methods/warehouse-connectors#events) and about user mappings [here](/docs/tracking-methods/warehouse-connectors#user-profiles).

### Client-side SDKs & Server-side SDKs

Fortunately, Mixpanel and Amplitude’s client side SDKs have *very similar* developer facing APIs. This makes it fairly easy to “find and replace” embedded Amplitude calls and swap them for Mixpanel calls.

This section will detail the Javascript SDKs (for the sake of brevity), although both analytics platforms have fairly uniform tracking APIs for other SDKs (mobile, server-side).

Amplitude JS Docs: [https://amplitude.github.io/Amplitude-TypeScript/modules/\_amplitude\_analytics\_browser.html](https://amplitude.github.io/Amplitude-TypeScript/modules/_amplitude_analytics_browser.html)

Mixpanel JS Docs: [https://developer.mixpanel.com/docs/javascript-full-api-reference](https://developer.mixpanel.com/docs/javascript-full-api-reference)

Note: Ensure that your projects have been defaulted or updated to Simplified ID Management before any data is sent to the project. This is the ID management compatible with Amplitude’s.

#### Installing the Mixpanel SDK

Before getting started, initialize the Mixpanel SDK according to the directions [here](https://developer.mixpanel.com/docs/javascript-quickstart#1-initialize-the-library)

#### Initialization

Amplitude’s `init()` method:

```jsx theme={"system"}
var amplitudeClient = new AmplitudeClient();
amplitudeClient.init('API_KEY')
```

Mixpanel’s `init()` method:

```jsx theme={"system"}
mixpanel.init('new token')
```

[Docs Reference](https://developer.mixpanel.com/docs/javascript-full-api-reference#mixpanelinit)

[Initialization (init) options](https://developer.mixpanel.com/docs/javascript-full-api-reference#mixpanelset_config)

#### Events

Amplitude’s `logEvent()` method:

```jsx theme={"system"}
amplitudeClient.logEvent('Clicked Button', {'finished_flow': false });
```

Mixpanel’s `track()` method:

```jsx theme={"system"}
mixpanel.track('Clicked Button', {'finished_flow': false })
```

[Docs Reference](https://developer.mixpanel.com/docs/javascript-full-api-reference#mixpaneltrack)

#### Identity Management

Amplitude’s `setUserId()` method:

```jsx theme={"system"}
amplitudeClient.setUserId('joe@gmail.com');
```

Mixpanel’s `identify()` method:

```jsx theme={"system"}
mixpanel.identify('joe@gmail.com')
```

[Docs Reference](https://developer.mixpanel.com/docs/javascript-full-api-reference#mixpanelidentify)

#### User Properties

Amplitude’s `setUserProperties()` method:

```jsx theme={"system"}
amplitudeClient.setUserProperties({'gender': 'female', 'sign_up_complete': true})
```

Mixpanel’s `people.set()` method:

```jsx theme={"system"}
mixpanel.people.set({'gender': 'female', 'sign_up_complete': true})
```

Note: `identify()` should be called at some point in each user’s session to propagate people methods

[Docs Reference](https://developer.mixpanel.com/docs/javascript-full-api-reference#mixpanelpeople)

#### Group Analytics

Amplitude’s `setGroup()` method:

```jsx theme={"system"}
amplitudeClient.setGroup('orgId', 15); 
```

Mixpanel’s `set_group()` method:

```jsx theme={"system"}
mixpanel.set_group('orgId', 15)
```

[Docs Reference](https://developer.mixpanel.com/docs/javascript-full-api-reference#mixpanelset_group)

### Customer Data Platforms (CDPs)

Since CDPs already collect all your data via 1 SDK and route to many downstream destinations, enabling Mixpanel is straightforward. Simply go to your CDP settings and add Mixpanel as a destination:

<Frame>
  ![Segment Connection](https://user-images.githubusercontent.com/129823695/234812593-dffee962-bb34-49b8-9686-96bc0f0565d8.png)
</Frame>

Once you set up the connection to Mixpanel, you can proceed with configuring key settings like:

* Which events and properties to send → only send what matters
* Edit any mappings/editing/filtering that has to be done on the data → ensure high data quality and governance
* Connection settings, or CDP specific settings for data syncs → control over how data is sent

We provide Mixpanel as a destination and setup guides for all of the most popular CDPs:

* [Segment](https://segment.com/docs/connections/destinations/catalog/actions-mixpanel/)
* [mParticle](https://docs.mparticle.com/integrations/mixpanel/audience/)
* [Rudderstack](https://www.rudderstack.com/docs/destinations/streaming-destinations/mixpanel/)

Note depending on your CDP provider, they may also be able to help with migrating historical data as well. Features like [Segment Replay](https://segment.com/docs/guides/what-is-replay/) enable you to quickly backfill historical data during your migration versus needing to do this work with your developer resources.

### Import API

If you currently send data to Amplitude directly to their API, you can simply swap out the Amplitude API with the Mixpanel API.

#### Sending Events

Amplitude’s `/track` API Endpoint is `https://api2.amplitude.com/2/httpapi` (documented [here](https://www.docs.developers.amplitude.com/analytics/apis/http-v2-api/)). A sample request from your server for this API would look like:

```bash theme={"system"}
curl -X POST https://api2.amplitude.com/2/httpapi \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
--data '{
    "api_key": "YOUR_API_KEY",
    "events": [{
    "user_id": "203201202",
    "device_id": "C8F9E604-F01A-4BD9-95C6-8E5357DF265D",
    "event_type": "watch_tutorial"
    }]
    }'
```

Mixpanel’s `/track` API endpoint is `https://api.mixpanel.com/import` (documented [here](/reference/import-events)). A sample request from your server for this API would look like:

```bash theme={"system"}
curl --request POST \
 --url 'https://api.mixpanel.com/import?strict=1&project_id=%3CYOUR_PROJECT_ID%3E' \
 --header 'Content-Encoding: gzip' \
 --header 'Content-Type: application/json' \
 --header 'accept: application/json' \
 --header 'authorization: Basic cnlhbjpyeWFu' \
 --data '[
    {
        "event": "string",
        "properties": {
            "time": 0,
            "distinct_id": "string",
            "$insert_id": "string"
         }
    }
]'
```

The big difference between the APIs are:

* **Authentication:** Amplitude authenticates in the request payload, whereas Mixpanel uses your project token in the request URL alongside basic auth. Mixpanel authentication can be done via a service account as described [here](/reference/ingestion-api-authentication). Be sure to move the authentication outside the payload.
* **Event JSON Structure:** Amplitude and Mixpanel have slightly different structures (explained [here](/docs/migration/amplitude#differences-in-the-data-models)). You will want to remap the Amplitude event format to the expected Mixpanel JSON payload as described [here](/docs/migration/amplitude#differences-in-the-data-models).

### Reverse ETL (RETL)

If you already send data to Amplitude with your data warehouse as the source of truth using reverse ETL, sending data to Mixpanel requires adding a new destination and syncing the same models you have been syncing to Amplitude. This option is like a hybrid between the CDP and Import API options above - you can use the reverse ETL tool to set Mixpanel up simply as a destination and then the tool will handle all of the remapping at the API level for you.

Simply go to your RETL settings and add Mixpanel as a connection:

<Frame>
  ![Census Connection](https://user-images.githubusercontent.com/129823695/234812805-ded7dcef-9d47-4375-b52e-a229e4832477.png)
</Frame>

We provide Mixpanel as a destination and setup guides for all of the most popular RETL tools:

* [Census](https://docs.getcensus.com/destinations/mixpanel)
* [Hightouch](https://hightouch.com/docs/destinations/mixpanel)
* [Segment](https://segment.com/docs/connections/reverse-etl/)

## Not sure where to start or need help?

If you're unsure how you currently track data, or might want to consider tracking data differently as you migrate to Mixpanel, we recommend starting [here](https://mixpanel.com/blog/guide-to-choosing-your-data-architecture/).

Mixpanel Customer Success and Support have been helping thousands of customers migrate from other tools to Mixpanel over the past decade. You can see an overview of the process we run with our Enterprise plan customers migrating from Amplitude [here](https://mxpnl.notion.site/Amplitude-Migration-Package-264ed076292e41e9b29a2c4f26851e9b?pvs=4).

We’re always happy to discuss your team’s individual needs, our migration process, the support you’ll receive, or any other question you have — drop us a line at [success@mixpanel.com](mailto:success@mixpanel.com).


# Migrating from Google Analytics
Source: https://docs.mixpanel.com/docs/migration/google-analytics



If you haven't already, we recommend starting with our [Migration Guides Overview](/docs/migration) as it details the key components of migrating to Mixpanel from other analytics tools. Below we outline specific steps and considerations when migrating from Google Analytics.

## Currently using Google Analytics 4 (GA4) and not seeing value?

Try unifying your marketing and product data in one place. This guide will outline the steps needed in order to bring your GA4 data into Mixpanel allowing you to dig deeper into how users across different channels are interacting with your product, learn where the points of friction are, and where you should be investing your marketing spend to maximize engagement with your product.

### Loading historical data

Given GA4 has a similar data format to Mixpanel, it is possible to migrate some of your historical data to see trends. In the cases where historical data is essential, we recommend loading a year’s worth (or less) of historical data during your migration. This will allow your team to review year-over-year trends easily and do historical analysis as needed.

Note that backfilling historical data can have significant impact on your billing. Refer to [this section](/docs/pricing#are-monthly-events-calculated-based-on-ingestion-time-or-event-timestamp) for more details.

#### Loading historical data via Mixpanel BigQuery Warehouse Connector

<Frame>
  <img alt="image" />
</Frame>

At a high-level, the migration consists of 4 steps:

1. Set up a new Mixpanel project which is on [Simplified ID Merge system](/docs/tracking-methods/id-management#identity-merge-apis).
2. Set up GA4 BigQuery Export following the instructions [here](https://support.google.com/analytics/answer/9823238?hl=en#zippy=%2Cin-this-article).
3. Set up [Mixpanel Warehouse Connector](/docs/tracking-methods/warehouse-connectors) to initiate data sync from BigQuery to Mixpanel

##### Pre-migration data audit

Before migrating your data to Mixpanel, you should conduct a data audit to quickly identify the key events and properties that you want to migrate over. You can learn more about the importance of pre-migration data audit [here](/docs/migration#data-audit).

The following SQL queries can be used to conduct a data audit in BigQuery.

SQL query to return events by volume:

```jsx theme={"system"}
SELECT 
    event_name, 
    COUNT(event_name) AS total_rows
FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131` 
GROUP BY event_name
ORDER BY total_rows DESC
```

SQL query to return event properties by volume:

```jsx theme={"system"}
SELECT DISTINCT
    event_name,
    ep.key  AS event_properties,
    COUNT(event_name) as total_rows
FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131` , UNNEST(event_params) as ep
GROUP BY event_name, ep.key
ORDER BY event_name ASC
```

SQL query to return sample values of the event properties:

```jsx theme={"system"}
SELECT 
  event_name,
  ep.key,
  COALESCE(ep.value.int_value, ep.value.float_value, ep.value.double_value) AS value
FROM `bigquery-public-data.ga4_obfuscated_sample_ecommerce.events_20210131`, UNNEST(event_params) AS ep
LIMIT 100
```

SQL query to return user properties by volume:

```jsx theme={"system"}
SELECT 
    up.value.user_property_name AS user_properties, 
    COUNT(up.value.user_property_name) AS total_users
FROM `mixpanel-sa.analytics_406874950.users_20231002` , UNNEST(user_properties) AS up
GROUP BY up.value.user_property_name
```

##### Setting up BigQuery Warehouse Connectors

Our [Warehouse Connector](/docs/tracking-methods/warehouse-connectors) will automatically detect GA4 datasets in BigQuery. You can use this to migrate your historical data from BigQuery to Mixpanel as well as seamlessly import new data going forward.

Once you've given your new Mixpanel project, that is leveraging Simplified ID Merge, access to your [BigQuery Instance](/docs/tracking-methods/warehouse-connectors#step-1-connect-a-warehouse) in the [Warehouse Sources](https://mixpanel.com/report/settings/%23project%2F%24project_id%24%2Fwarehousesources/) tab of your project settings it's time to import your data. Navigate to [Project Settings → Warehouse Data](https://mixpanel.com/report/settings/%23project%2F%24project_id%24%2Fwarehousedata/) and click +Event Table.

Under setup select your BigQuery source you gave Mixpanel access to. In the dataset drop-down, choose your GA4 dataset, then select the GA4 events table. Your Event Name, Event Time, and Distinct ID columns will automatically map for you. If you're tracking users in an anonymous state with GA4 you can select user\_pseudo\_id for the Device ID column.

Under sync settings select One Time to backfill the data or Append to bring in new data based on Insert Time (sync mode doesn't include Mirror, only Append and One Time). If you choose Append for Sync Mode, set the frequency to daily. Insert time will default to event\_timestamp.

Preview the events and associated event properties to ensure the data looks as expected then select Create to import the data into Mixpanel.

<Frame>
  <img alt="image" />
</Frame>

Navigate to [Project Settings → Warehouse Data](https://mixpanel.com/report/settings/%23project%2F%24project_id%24%2Fwarehousedata/) and click +User Table.

Under setup select your BigQuery source you gave Mixpanel access to. In the dataset drop-down, choose your GA4 dataset, then select the GA4 users table. Your Distinct ID column will automatically map to user\_id for you.

Under sync settings select One Time to backfill the data or Append to bring in new data based on Insert Time (sync mode doesn't include Mirror, only Append and One Time). If you choose Append for Sync Mode, set the frequency to daily.

<Note>
  GA4 Append syncs use BigQuery's change history ([time travel](https://docs.cloud.google.com/bigquery/docs/time-travel)) to detect newly appended rows. BigQuery retains change history for up to 7 days (configurable, minimum 2 days). If the Mixpanel sync does not run within this window, it must be reset for a full re-sync. We recommend keeping the default of 7 days to allow time to correct any unexpected access issues (e.g., a credentials change).
</Note>

Preview the users and associated user properties to ensure the data looks as expected then select Create to import the data into Mixpanel. Once the import is complete, navigate to the Users tab and ensure the profiles have been imported as expected.

<Frame>
  <img alt="image" />
</Frame>

##### Post-migration data validation

You can use our [Lexicon](/docs/data-governance/lexicon) or Events page to check that your data has successfully been ingested. However, if your historical events are older than 30 days, they will not show up on Lexicon, Events page or in the event dropdown menu across all reports. In this case, you can leverage our [Insights report](/docs/reports/insights) to validate the historical events, by selecting the import time frame and filtering by the following default properties:

* Warehouse Import ID (tracked as `$warehouse_import_id`)
* Warehouse Import Job ID (`$warehouse_import_job_id`)
* Import = true (`$import`)
* Source = warehouse-import (`$source`)

Please filter by tracked name, \$warehouse\_import\_id instead of the display name, “Warehouse Import ID”. You can find the properties values on the Warehouse Connector’ sync logs:

<Frame>
  <img alt="image" />
</Frame>

### Track forward looking real-time data

The Warehouse Connectors support for GA4 allows you to automatically bring in your event and user data. But if you're looking to replace tracking for your current GA4 implementation, you can follow the steps below to send live data to Mixpanel.

#### Client-side SDKs & Server-side SDKs

Mixpanel and GA4’s client-side SDKs have *very similar* developer facing APIs. This makes it fairly easy to “find and replace” embedded GA4 calls and swap them for Mixpanel calls.

This section will detail the Javascript SDKs (for the sake of brevity), although both analytics platforms have fairly uniform tracking APIs for other SDKs (mobile, server-side, etc.)

##### Events

GA4 method

```jsx theme={"system"}
gtag('event', 'event_name', {
    'param1': 'value1',
    'param2': 'value2'
});
```

Mixpanel method

```jsx theme={"system"}
mixpanel.track('event_name', {
    'param1': 'value1',
    'param2': 'value2'
});
```

##### Identity Management

GA4 method

```jsx theme={"system"}
gtag('config', 'GA_MEASUREMENT_ID', {
    'user_id': 'USER_ID'
});
```

Mixpanel method

```jsx theme={"system"}
mixpanel.identify('USER_ID');
```

##### User Properties

GA4 method

```jsx theme={"system"}
gtag('set', 'user_properties', {
    'property1': 'value1',
    'property2': 'value2'
});
```

Mixpanel method

```jsx theme={"system"}
mixpanel.people.set({
    'property1': 'value1',
    'property2': 'value2'
});
```

##### Super Properties

GA4 method → GA4 doesn't have a direct equivalent, but you can set global properties on the SDK config we recommend moving to Mixpanel

```jsx theme={"system"}
gtag('config', 'GA_MEASUREMENT_ID', {
    'custom_map': {
        'dimension1': 'property1',
        'dimension2': 'property2'
    },
    'property1': 'value1',
    'property2': 'value2'
});
```

Mixpanel method

```jsx theme={"system"}
mixpanel.register({
    'property1': 'value1',
    'property2': 'value2'
});
```

Keep in mind that you will need to initialize the [Mixpanel SDK](https://developer.mixpanel.com/docs/javascript-full-api-reference) by adding the Mixpanel snippet to your website before using these tracking calls. Replace the placeholders (e.g., 'event\_name', 'USER\_ID', 'value1', etc.) with the appropriate values from GA4 in your code as you migrate the code.

#### Google Tag Manager (GTM)

Mixpanel has a [Google Tag Manager (GTM) custom template](/docs/tracking-methods/integrations/google-tag-manager) which can be leveraged to implement events within an hour. Simply load the template, and you can send Mixpanel the same events you’ve setup for your GA4 instance.

This method is straightforward since you’ve already setup your SDK to track “events” and are using Google Tag Manager. You can leverage this same setup to implement Mixpanel.

#### Customer Data Platforms (CDPs)

CDPs like [Segment](https://segment.com/) will already be tracking events to GA4 that you want to duplicate to Mixpanel. You can add Mixpanel as a destination to your CDP and immediately start receiving the same data as your other destinations.

CDPs like [Segment](https://segment.com/) have always tracked event data and synthesized them into sessions for Universal Analytics. You can add Mixpanel as a destination to your CDP and immediately start receiving the same data as your other destinations.

Since CDPs already collect all your data via 1 SDK and route to many downstream destinations, enabling Mixpanel is straightforward. Simply go to your CDP settings and add Mixpanel as a destination:

<Frame>
  ![Segment Connection](https://user-images.githubusercontent.com/129823695/234812593-dffee962-bb34-49b8-9686-96bc0f0565d8.png)
</Frame>

Once you set up the connection to Mixpanel, you can proceed with configuring key settings like:

* Which events and properties to send → only send what matters
* Edit any mappings/editing/filtering that has to be done on the data → ensure high data quality and governance
* Connection settings, or CDP specific settings for data syncs → control over how data is sent

We provide Mixpanel as a destination and setup guides for all of the most popular CDPs:

* [Segment](https://segment.com/docs/connections/destinations/catalog/actions-mixpanel/)
* [mParticle](https://docs.mparticle.com/integrations/mixpanel/audience/)
* [Rudderstack](https://www.rudderstack.com/docs/destinations/streaming-destinations/mixpanel/)

## Currently using Universal Analytics with Google?

### Differences in the data models

Mixpanel’s data model is based on events and properties, rather than sessions. While this might be a shift if you come from the sessions-based model, we’ve found it to be both more flexible and easier to set up and use.

* [Events](/docs/what-is-mixpanel#events) capture granular user actions, like a Pageview, Signup, or Purchase.
* [Properties](/docs/what-is-mixpanel#properties) capture attributes of those events, like which page was viewed, the UTM Campaign that led to a Signup, or the Item that was purchased.

Events let you get more granular than [sessions](/docs/features/sessions), so that you can deeply understand user behavior. At the same time, Mixpanel automatically constructs sessions from events, so you can answer session-level questions too.

### Track forward looking real-time data

Choose your current implementation method for Universal Analytics (UA) and you can follow the below steps for starting to send live data to Mixpanel.

#### Client-side SDKs & Server-side SDKs

You’ll have to setup Mixpanel fresh given Mixpanel leverages an event-based model that does not exist in Universal Analytics. The good news is you can get started within an hour, which is lesser or equivalent work to setting up GA4 from an SDK perspective, since both need a fresh implementation to be setup on an “events” model vs UA’s “sessions” model.

We recommend the following steps to get started quickly:

* Configure the [Mixpanel JavaScript SDK](https://developer.mixpanel.com/docs/javascript-full-api-reference) to automatically track page views, where UTM params are tracked by default

  ```jsx theme={"system"}
  mixpanel.init('YOUR_TOKEN', {track_pageview: true});
  ```
* Track a few key conversion events of interest

  ```jsx theme={"system"}
  // Send a "Played song" event to Mixpanel
  // with a property "genre"
  mixpanel.track(
      "Played song",
      {
          "genre": "hip-hop"
      }
  );
  ```
* Use the [Mixpanel Marketing KPI Template](https://mixpanel.com/project?show-template-selector=true) to build your initial board

#### Google Tag Manager (GTM)

Mixpanel has a [Google Tag Manager (GTM) custom template](/docs/tracking-methods/integrations/google-tag-manager) which can be leveraged to implement events within an hour. The template initializes the Mixpanel JavaScript SDK with similar calls as outlined in the above section.

We recommend setting up the following in the custom template to get started quickly: a) Choose to auto-track pages, b) Set your conversion events. Once done, Mixpanel will start receiving page views and key conversion events.

#### Customer Data Platforms (CDPs)

CDPs like [Segment](https://segment.com/) have always tracked event data and synthesized them into sessions for Universal Analytics. You can add Mixpanel as a destination to your CDP and immediately start receiving the same data as your other destinations.

Since CDPs already collect all your data via 1 SDK and route to many downstream destinations, enabling Mixpanel is straightforward. Simply go to your CDP settings and add Mixpanel as a destination:

<Frame>
  ![Segment Connection](https://user-images.githubusercontent.com/129823695/234812593-dffee962-bb34-49b8-9686-96bc0f0565d8.png)
</Frame>

Once you set up the connection to Mixpanel, you can proceed with configuring key settings like:

* Which events and properties to send → only send what matters
* Edit any mappings/editing/filtering that has to be done on the data → ensure high data quality and governance
* Connection settings, or CDP specific settings for data syncs → control over how data is sent

We provide Mixpanel as a destination and setup guides for all of the most popular CDPs:

* [Segment](https://segment.com/docs/connections/destinations/catalog/actions-mixpanel/)
* [mParticle](https://docs.mparticle.com/integrations/mixpanel/audience/)
* [Rudderstack](https://www.rudderstack.com/docs/destinations/streaming-destinations/mixpanel/)

### Loading historical data

Mixpanel's data model is fundamentally different from UA. As such, the process of importing old data with a different format has many potential issues - identity management, data discrepancies, etc. It may be worth considering your use cases for importing old data before proceeding, as matching users and data across the systems can be time consuming. [Mixpanel Support](https://mixpanel.com/get-support) is here to help if you need advice how to go about importing the historical data.

Consequently, for most cases, we recommend starting fresh when migrating from UA. In the cases where historical data is essential, we recommend loading a year’s worth (or less) of historical data during your migration. This will allow your team to review year-over-year trends easily and do historical analysis as needed.

To backfill data, we recommend:

* If you have a CDP, this should be straightforward

  * Utilize the CDP's backfilling feature, like [Segment Replay](https://segment.com/docs/guides/what-is-replay/), to re-send historical data to Mixpanel
* For any other implementation method

  * First, export your data to the data warehouse so you have a record of Universal Analytics
  * Once exported, your data warehouse tables can be transformed and modeled into the [event format](/docs/data-structure/events-and-properties) Mixpanel expects
  * Leverage our [Import API](/reference/import-events) to send us the formatted events from your data warehouse

## Not sure where to start or need help?

If you're unsure how you currently track data, or might want to consider tracking data differently as you migrate to Mixpanel, we recommend starting [here](https://mixpanel.com/blog/guide-to-choosing-your-data-architecture/).

Mixpanel Customer Success and Support have been helping thousands of customers migrate from other tools to Mixpanel over the past decade. You can see an overview of the process we run with our Enterprise plan customers migrating from Google Analytics [here](https://mxpnl.notion.site/Google-Analytics-Migration-Package-8020a686880a4caab4dd6653b777892e?pvs=4).

If you need help, just [reach out here](https://mixpanel.com/get-support) and we'll be ready to assist with advice specific to your situation.


# Mixpanel Agent
Source: https://docs.mixpanel.com/docs/mixpanel-agent



## Overview

Mixpanel Agent is an AI analyst built into Mixpanel. Ask it questions or give it tasks and the Agent interprets your intent and selects the right tools automatically. A single prompt can run an analysis, build a report, create a cohort, or walk you through a user's session replays without you specifying each step.

## Core Capabilities

The Mixpanel Agent has access to a broad set of Mixpanel capabilities and selects tools automatically based on what you ask.

| Capability                  | What the Agent can do                                                                                                                                                                                 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Report Creation & Editing   | Create new Insights, Funnels, Retention, and Flows reports from a description. Adjusts existing report metrics, filters, breakdowns, and time ranges.                                                 |
| Boards Creation & Editing   | Create new Boards or use the Agent to edit an existing Board's layout and content                                                                                                                     |
| Metrics                     | Define metrics in plain language and save them for reuse across your project                                                                                                                          |
| Cohorts                     | Build behavioral cohorts from a description and save them for analysis or targeting                                                                                                                   |
| Search project data         | Search across your project's events, properties, saved reports, Boards, feature flags, and experiments to find what already exists before building something new                                      |
| Analyze reports & Boards    | Interpret, explain, and investigate any report or Board. Automatically picks up the context of whatever you currently have open, so you don't need to describe your setup                             |
| Session replay analysis     | From a prompt or existing playlist, Mixpanel curates relevant replays, analyzes them alongside your events data, summarizes findings for follow-up questions, and surfaces timestamps for key moments |
| Experiments & Feature Flags | Reference experiments and feature flags in any investigation, interpret experiment results in plain language, and create new experiments or flags through a conversational flow                       |
| Mixpanel Docs               | Answer questions about how Mixpanel features work                                                                                                                                                     |
| Root Cause Analysis         | Run a root cause analysis for a metric change. [See Root Cause Analysis for details](/docs/root-cause-analysis)                                                                                       |
| Automations                 | Create, inspect, edit, activate, pause, and delete Agentic Automations, and check their run history. [See Agentic Automations for details](/docs/agentic-automations)                                 |

**Working on an analysis?** The Agent automatically picks up your current page as context. Ask it to explain a trend, dig into an anomaly, or modify what's in front of you. No need to describe what you're looking at first.

## Access

Where you'll find the Mixpanel Agent:

* **Side navigation:** Click Mixpanel Agent to open a full-page experience
* **Contextual panel:** Click "Open in side view" to open the Agent in a side panel so you can bring the Agent with you as you navigate Mixpanel
* **Create New:** Click Mixpanel Agent from the Create New menu

<Frame>
  <img alt="Image" />
</Frame>

## Example Use Cases

### Explore a direction

You have a theory or idea. The Mixpanel Agent helps you test it quickly.

*Does our new onboarding flow actually improve activation?*

*I think users who invite a teammate in their first week retain better. Can you validate that?*

### Put your ideas into action

You've landed on a direction. Now ship the change and measure the impact.

*Set up an experiment to test a simplified checkout against the current flow*

*Roll out the new pricing page to 10% of users behind a feature flag*

### Investigate what happened

Something moved in your metrics. The Agent helps you get a clear picture to get to the bottom of it.

*Explain this spike in signups*

*Did anything unusual happen with our checkout flow*

### Get up to speed fast

You need context before a meeting or decision. The Agent searches what already exists in your project so you're not starting from scratch.

*Show me our top of funnel KPIs.*

*Summarize this analysis for me before my meeting*

*What tracking do we have on our messaging feature*

### Build your analysis

Build out boards, reports, metrics, and cohorts to share across your team for analysis.

*Make a Board for our weekly growth review*

*Save our activation definition*

*Create a cohort of power users so we can target them in experiments*

### Understand your users

Dive deeper to understand what individual users or segments actually experienced.

*Find sessions where users hit an error during checkout, walk me through what they did, and surface timestamps of key moments*

*This user churned after 3 days. Walk me through their sessions*

## Business Context

The Mixpanel Agent uses your project's [Business Context](/docs/business-context) to give more relevant answers. The more context you provide, the better the Agent's answers.

## Verified Mode

Admins can control what data the Agent surfaces by enabling Verified Mode in Project Settings. When enabled, Mixpanel AI will only use [Verified Data](/docs/data-governance/lexicon#verify-data). Verified Data is events, metrics, behaviors, and cohorts that your team has explicitly reviewed and verified in Lexicon. This ensures AI responses are grounded in data your organization trusts.

When unverified data is excluded from a response, users are notified that additional relevant data exists but wasn't included.

## Sharing

To share a Mixpanel Agent chat, click on the chat name and select **Share Link.**

<Frame>
  <img alt="Agent Share Link" />
</Frame>

Shared chats are view-only. Anyone with the link who has access to the project can view the chat.

<Frame>
  <img alt="Agent Chat Sharing" />
</Frame>

The link shows the chat as it existed when you generated it, up to the most recent message at that time.

Optionally, you can share the chat along with the current page content. This is useful if the context of your chat is about a Board, Report, Experiment, or Session Replay Playlist.

To make a chat private again, select **Keep Private**. Existing share links stop working once the chat is private.

## Chat History

Access more options for managing chats from the chat header, including:

* **New Chat:** Click the pencil icon to start a new chat. When you start a new chat, your previously active chat is still available in history.
* **Rename chat:** Change the title of a chat
* **Delete chat:** Remove a chat from history
* **Chat history:** Access all your previous chats when working in the side panel. If you're viewing the Agent as a full page you will see the chat history on the left automatically.

<Frame>
  <img alt="2026 07 16 15 12 54" />
</Frame>

## Security & Privacy

Mixpanel’s AI is built with privacy-by-design principles. For details:

* [Mixpanel AI Compliance](https://mixpanel.com/legal/ai-compliance/)
* [Mixpanel’s Data Processing Addendum](https://mixpanel.com/legal/dpa/)

## FAQ

**1. What AI models does it use?**<br />The Mixpanel Agent is powered by Claude.

**2. How can I influence what Mixpanel Agent surfaces?**<br />Adding Organization and Project [Business Context](/docs/business-context). Saving [Metrics and Behaviors](/docs/features/saved-metrics-and-behaviors). [Verifying Data](/docs/data-governance/lexicon#verify-data). The Agent uses all this context you provide to craft the best response for your prompt.

**3. How do I share feedback or request new capabilities?**<br />Use the feedback buttons inside the Agent experience to share what's working, what's missing, or what you'd like to see. We're actively building. Your feedback directly shapes the roadmap.

<Frame>
  <img alt="Mixpanel Agent Feedback" />
</Frame>

**5. How can I enable or disable AI features?**<br />Access to Mixpanel AI features can be managed from your Org settings. Org Admins can change these settings. Note, disabling Mixpanel AI removes access for all users.

<Frame>
  <img alt="Mixpanel AI Settings" />
</Frame>

**6. What happened to Spark?**<br />Looking for Spark? This is the right page. Mixpanel Agent is the next evolution of Spark.


# Mixpanel Headless
Source: https://docs.mixpanel.com/docs/mixpanel-headless



Mixpanel Headless is an open-source SDK that exposes the full Mixpanel platform — every query engine, report type, and configuration — as a single Python object. Build agents, notebooks, scheduled scripts, or ETL pipelines that work with your product data the same way a human analyst would, without a browser.

## When to use Mixpanel Headless

Headless is for coding agents and developers — anything that writes or generates Python to call Mixpanel.

* [**Mixpanel Agent**](/docs/mixpanel-agent) is the conversational AI inside the Mixpanel UI.
* [**MCP Server**](/docs/mcp) connects chatbots (Claude, ChatGPT, and others) to your data for natural-language Q\&A.
* **Mixpanel Headless** is the SDK for coding agents (Claude Code, Codex, Cursor) and for scripts, notebooks, and pipelines you write yourself.

## Get started

```bash theme={"system"}
pip install mixpanel-headless
```

Then follow the [quickstart on GitHub](https://mixpanel.github.io/mixpanel-headless/getting-started/installation/).

## Rate limits

The default API limit is 60 requests per hour. For production workloads or higher volume, [request early access](https://docs.google.com/forms/d/e/1FAIpQLScHVIS-rnKuvoHdkjRoG5YaevfQ2INXjD-pjiJlQQzJylmyJA/viewform).

## Resources

* [Full documentation](https://mixpanel.github.io/mixpanel-headless/)
* [GitHub repository](https://github.com/mixpanel/mixpanel-headless)
* [Request early access](https://docs.google.com/forms/d/e/1FAIpQLScHVIS-rnKuvoHdkjRoG5YaevfQ2INXjD-pjiJlQQzJylmyJA/viewform)


# Mixpanel Administrative System
Source: https://docs.mixpanel.com/docs/orgs-and-projects



The Mixpanel administrative system includes organizations, projects, and teams.

An **Organization** is the controlling entity that links projects, users, and a plan together. Each organization has a single Mixpanel plan associated with it and that plan is what determines the data volume limits and features available across all projects in the organization.

A **Project** is a container for your product's analytics data, including saved entities like custom events, or saved reports. Projects house the events, properties and user profiles sent to them which can then be queried with Mixpanel’s web interface and APIs. A single organization can contain multiple projects and each project’s data tallies are summed together to give the organization-level usage.

A **Team** is a group of users in your organization that shares the same project access permission, which makes it easier to manage roles and permissions for a group of users. A team contains a roster of users, the projects they are assigned to, the role permission in each project, Data View access, and Classified Data access.

<Frame>
  <img alt="Organization Overview 1 Image" />
</Frame>


# Managing Projects
Source: https://docs.mixpanel.com/docs/orgs-and-projects/managing-projects



## Creating Projects

<Note>
  To create a project, you will need an admin or owner organization role. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

Your first project will be created automatically when you create an Organization in Mixpanel. You can create additional projects as follows -- we recommend creating a Development project to test any tracking changes before pushing them to production.

<Frame>
  <img alt="manageprojects 1 Image" />
</Frame>

To create a new Mixpanel project:

1. In Organization Settings, click **Projects** in the left-side menu.
2. Click **Create Project**. A pop-up will appear.
3. Enter a name for the project and click **Create Project**.
4. Choose the residency of your data. **ATTENTION!** This can't be changed once the project is created.
5. Choose the timezone of your project.
6. Click on "Create".
7. The new project will appear now in the list of projects.

<Frame>
  <img alt="manageprojects 2 Image" />
</Frame>

## Viewing Project Information

To view project information:

1. In Organization Settings, click **Projects**.
2. Click a project. You’ll see information about project details, usage statistics, and access keys.

### Project Details

You can edit the name of the project and its time zone. To edit, click the Pencil icon in the "Name" and "Timezone" fields.

<Frame>
  <img alt="manageprojects 3 Image" />
</Frame>

This table describes the type of details Mixpanel provides for your project.

| **Fields**     | **Description**                                                           |
| -------------- | ------------------------------------------------------------------------- |
| Organization   | The name of the organization where the project is.                        |
| Project ID     | The ID number of the project.                                             |
| Data Residency | Where the data centers hosting the data pool of this project are located. |
| Timezone       | The time zone you assign to the project.                                  |
| Created By     | The name of the user who created the project.                             |
| Date Created   | The date when the project was created.                                    |
| Access URL     | The URL where you can access the project.                                 |

### Access Keys

This table provides the values for the **project token** and the **API secret**. The token is necessary when setting up your tracking.

<Warning>
  <strong>API Secret Deprecation</strong>

  The project API secret is deprecated and will be retired on **March 3rd, 2027**. For new projects or integrations, use [Service Accounts](/reference/service-accounts) instead. Existing API‑secret workflows will continue to work until retirement, but should be migrated when convenient.
</Warning>

<Frame>
  <img alt="manageprojects 4 Image" />
</Frame>

## Reset Projects

<Note>
  Only project owners and organization owners may reset projects. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

You can reset the current project in Project Settings. When you reset the project, Mixpanel deactivates the project and all its data and settings, and then generates a new project.

<Frame>
  <img alt="manageprojects 11 Image" />
</Frame>

A warning indicates this reset deactivates the project and all its data and project settings, and then generates a new project.  Mixpanel stores a backup of the deactivated project and will delete it based on the data retention policy.

<Frame>
  <img alt="manageprojects 12 Image" />
</Frame>

## Delete Projects

<Note>
  Only project owners and organization owners may delete projects. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

<Warning>
  Data will be retained for **60–90 days** before being permanently deleted and unrecoverable. The project will be immediately inaccessible via the Mixpanel interface and API.
</Warning>

To delete a project:

1. In **Organization Settings**, click **Projects**.
2. Select the project you want to delete.
3. Above the **Project Details** section, click **Delete Project**.
4. Review the warning, then click **Delete Project** to confirm.

<Frame>
  <img alt="manageprojects 5 Image" />
</Frame>

Learn more about our [data retention policy](/docs/privacy/gdpr-compliance#data-retention-policy).

## Find Your Project Tokens

Each Mixpanel account can contain multiple projects. Each project has its own unique routing number, which we call a project token. Whenever you want to send data to a specific project, you'll need to specify the project token so we know where to put the data.

### Locate Current Project Token

Click the Settings gear in the lower left-hand corner of your Mixpanel project and select Project settings to see your Project Token under the Access Keys table.

<Frame>
  <img alt="manageprojects 4 Image" />
</Frame>

### Locate Tokens for All Projects in Your Mixpanel Account

To view the project tokens for all your projects, click the **Settings** gear icon and select **Personal Settings**.

<Frame>
  <img alt="manageprojects 7 Image" />
</Frame>

Then select the Projects tab.

<Frame>
  <img alt="manageprojects 8 Image" />
</Frame>

#### Reset Project API Secret and API Key

You can reset the API Secret and API Keys for any projects you own. To do so, go to **Settings** → **Profile** → **Projects** → **Your Projects**, and click **Reset** next to the desired project.

#### Reset Project Token

Project Token cannot be reset in a self-serve manner. If you need to reset your project token for any reason, please [reach out to our Support team](https://mixpanel.com/get-support). After rotating it, the original one becomes invalid, so you will need to replace it with the new one in your implementation's code. Otherwise, no new events will be sent to your Mixpanel project.

## Manage Timezones for Projects

<Note>
  For projects created before January 1st, 2023, Mixpanel converts event timestamps to your project timezone before writing the event to your Mixpanel data stores, meaning that event timestamps are stored based on the project timezone setting at the time of ingestion.
</Note>

Mixpanel records all events in [Coordinated Universal Time (UTC)](https://www.worldtimeserver.com/learn/what-is-utc/) at intake. Changing the timezone for any project under Project Settings only affects the timezone in which Mixpanel outputs results.

Mixpanel sets project time zones by city or region. If a city or region observes Daylight Saving Time, the ingestion offset adjusts appropriately.

### Changing your Timezone

<Note>
  You must have an admin or owner project role to change your project timezone setting. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

By default, Mixpanel sets your timezone to UTC.

Only project owners and admins can change project settings.

To change the project's timezone:

1. Navigate to **Settings** -> **Project Settings**.
2. In **Overview**, select the pencil icon in the **Timezone** field to display a list of timezones.
3. Select a timezone and click **Save**.

> Note that changing the timezone will not affect any data; it only affects the timezone in which we output results.

#### Sending Date Properties to Mixpanel

[Date properties are one of the five data types](/docs/data-structure/property-reference/data-type#date) Mixpanel accepts. Mixpanel events should be ingested with timestamps set to Coordinated Universal Time (UTC). If you overwrite the default timestamp, import old data, or set a property that is in date format (e.g., Account Created Date), be sure to send the timestamp or date in UTC.

For this type of property, Mixpanel recommends an ISO-formatted date string (YYYY-MM-DDTHH:mm:ss) to use in your Mixpanel reports.

Below are some code examples from Mixpanel's client-side libraries that allow you to send a property to Mixpanel with a correctly formatted UTC timestamp.

```text theme={"system"}
JavaScript: new Date().toISOString()
mixpanel.track("Sign Up", {"Account Created Date": new 
Date().toISOString()});
iOS: [NSDate date]
NSDate *today = [NSDate date];
[mixpanel.people set:@{@"Account Created Date": @today}];
Android: dateFormat.format(new Date()) 
final DateFormat dateFormat = new 
SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss", Locale.US); 
dateFormat.setTimeZone(TimeZone.getTimeZone("UTC"));
JSONObject props = new JSONObject(); 
try {
props.put("time-example", dateFormat.format(new Date())); 
} catch (Exception e) {
}
Mixpanel.track("Account Created Date", props);
```

#### Exporting Data from Mixpanel

<Note>
  For projects created before 1 January 2023, the `from_date` and `to_date` params for the Export API are interpreted using your project's current timezone setting.
</Note>

When you’re exporting raw data from Mixpanel using the [Export API](/reference/raw-event-export), your request requires the date parameters `from_date` and `to_date` to determine which date range of data to return. Mixpanel's raw export API interprets the "from\_date" and "to\_date" parameters using UTC timezone.

The `$time` property values from your raw event export are Unix timestamps, which represent the number of seconds that have elapsed since 00:00:00 on January 1, 1970. Note that [the timezone of the `$time` property in your exports depends on how your project records time at ingestion](/docs/orgs-and-projects/managing-projects#manage-timezones-for-projects).

#### Importing Data into Mixpanel

Always send imported data to Mixpanel in UTC to ensure it displays correctly in your project.

Mixpanel stores your data in UTC, then uses your project timezone setting to output data in your selected timezone. For projects created before January 1st, 2023, your UTC timestamps are converted to the project's timezone before ingestion, meaning that your event data is stored in the project's timezone.

## Time Period Settings

Time period settings control how Mixpanel groups data into weeks and quarters across reports in your project. They are configured at the project level and apply to every report.

To configure these settings, navigate to **Settings** -> **Project Settings**. You can set:

* **Start of week** — the day Mixpanel treats as the first day of the week (for example, changing it from Monday to Saturday). This affects weekly bucketing and any report that groups or rolls up data by week.
* **Start of quarter** — the month Mixpanel treats as the first month of each quarter, for organizations whose fiscal calendar doesn't begin in January.

<Note>
  These settings are respected by relative date range presets. For example, [Week to Date](/docs/reports#to-date) begins counting from your configured start of week.
</Note>

Viewing and editing time period settings is governed by the **Access Time Period Settings** permission. Editing requires a role with edit access (project Owners and Admins), while Analysts and Consumers have view-only access. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).

## Transfer Project to Another Organization

Organization owners and project owners in a project can transfer that project to another organization to which they have permission.

When a user transfers a project to another organization, the project members and service accounts don't transfer with the project. As a result, project members will lose access to the project if they aren't members of the target organization, and service accounts will need to be recreated.

To transfer a project to another organization:

1. Under **Project Settings**, click a project.
2. Click the **Transfer** button on the top right of the page.

<Frame>
  <img alt="manageprojects 13 Image" />
</Frame>

3. The Transfer Project box appears. In the dropdown menu, select the organization where you want to transfer the project and click **Done**. You'll see a message that indicates the project has been transferred successfully.

<Frame>
  <img alt="manageprojects 14 Image" />
</Frame>

> Note that project tallies will be transferred along with your project to the new Organization.

## Merge Mixpanel Projects

If, for any reason, you need to combine two or more Mixpanel projects, it is possible to do so. Here are a few things to consider before proceeding with the merge to ensure you maintain data integrity:

* If you're using the 'alias' method, bear in mind that aliases are project-specific. As such, before importing data into the new project from the old project, you'd need to recreate the aliases from your old project. Mixpanel cannot provide a historical table of your project’s aliases.
* Merging projects involves exporting and importing data, so to make sure you only have to go through the process once, ensure you have stopped sending data to the old project(s) before beginning to export.

### How to Merge

To merge projects:

1. Stop sending data to the old project(s).
2. Begin sending all data to the new project.
3. Once the old project has completely stopped receiving data, export that data via the [raw data export API](/reference/raw-event-export) and import the data into the new project via Mixpanel’s [import API](/reference/import-events).

### Additional Tips

* When you export raw event data, the timestamps on those events will be in the timezone of your project.
* Before importing into your new project, convert those timestamps to UTC so that they are correctly transformed to the timezone of the new project.
* Read more about timezones and how Mixpanel handles time [here](/docs/orgs-and-projects/managing-projects#understanding-how-timezones-affect-data).


# Organizations
Source: https://docs.mixpanel.com/docs/orgs-and-projects/organizations



## Overview

An Organization is an entity that links your projects, users, and subscription plan.

## Creating an Organization

A user who signs up for a new Mixpanel account without being invited by an existing Mixpanel user will be prompted to create a new organization. This is the only way a new organization is created.

[Contact the Support team](https://mixpanel.com/get-support) if you need to create a new organization as a member of an existing organization.

## Accessing your Organization's Settings

To access your organization's different settings, click the gear icon located on the bottom-left side of the screen, then 'Settings', and then the 'Organization Settings' option.

## Organization Discoverability

Organization Discoverability makes it seamless for new users with a shared work email domain to connect with teammates in an existing organization in Mixpanel, allowing them to access their team’s projects, data, and reports, instead of joining a new, empty org.

This feature is accessible to new users who have verified their email, as well as existing organizations that are on an Enterprise plan and do not have SSO enabled.

<Frame>
  <img alt="Organization Discoverability 1 Image" />
</Frame>

### Setting Discoverability

Only **organization owners** and **billing admins** can access Organization Discoverability by going to Organization Settings > Users & Teams > Organization Discoverability.

<Frame>
  <img alt="Organization Discoverability 2 Image" />
</Frame>

They can enable Organization Discoverability by first specifying the private (i.e., work) email domain(s) that should be granted access when a new user signs up for Mixpanel. Please note that public email domains, such as Gmail or Yahoo, cannot be used.

The org owner or admin can then designate the level of discoverability of their organization: **open to join**, **subject to admin approval**, or **invite only**.

**Open Organization:** An organization designated “open to join” is discoverable and joinable to any new users with an admin-specified email domain(s).

**Admin Approval:** An organization designated as requiring “admin approval” is discoverable to any new user signing up with a specified email domain, but can only be joined upon request. Admins will receive an email notification to authorize access.

**Invite Only:** An organization designated “invite only” is undiscoverable regardless of email domain. New users must be invited by the admin.

## Transferring ownership of an Organization

<Note>
  To complete this process, you will need the "Owner" organization role. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).

  If the only organization owner is no longer with your company and you'd like to become its new owner, please [contact the Support team](https://mixpanel.com/get-support).
</Note>

### Internally

To make an existing user the new owner of your organization, follow these steps:

1. Under "Organization Settings", click **Users & Teams** and you will land on the Users tab.
2. Find the user's account in the list and click their name.
3. Change their organization role to 'Owner', and click 'Save'.

### Externally

<Note>
  If you're using a paid plan and would like to remove your credit card details from your account for security reasons, please [contact the Support team](https://mixpanel.com/get-support) for assistance.
</Note>

To make a new person the owner of your organization, follow these steps:

1. Under "Organization Settings", click **Users & Teams** and you will land on the Users tab.
2. Click **Invite Users**. The “Invite New Users” box appears.
3. Enter the email address of the person and select their **Organization Role** ("Owner"), **Projects** to add them to, and **Project Role** ("Owner").
4. Click **Invite** to complete the process.
5. They will receive an email to create a user account and, afterwards, have full control of the organization.

## Deleting an Organization

<Info>
  Only **Organization Owners** may delete an organization. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Info>

<Warning>
  Deleting an organization will remove all existing projects and all data contained within them. **This action is irreversible.**
</Warning>

To delete your organization:

1. Go to **Organization Settings** (from the left nav, select→ **Settings** → **Organization Settings**).
2. Open the **Overview** tab.
3. Click the **Delete Organization** button.
4. Confirm the deletion.

Users will maintain access for **90 days** before the organization and all its data are permanently deleted.

Learn more about [privacy and compliance](https://docs.mixpanel.com/docs/privacy).

[Contact the Support team](https://mixpanel.com/get-support) if you have any questions about deleting your organization or its data.


# Roles & Permissions
Source: https://docs.mixpanel.com/docs/orgs-and-projects/roles-and-permissions



## Overview

Your team members access your organization and its projects using individual user accounts, which is what you use to sign into Mixpanel. An account must be part of an organization, but it does not need to be part of all projects in the organization. Each account will have a single organization role per organization and one or more project roles for each project it is a part of. These roles can further limit what an account will have access to in Mixpanel.

<Note>
  To invite and manage users in your organization and project, you will need an admin or owner organization role.
</Note>

### Invite Users

You can invite users to an organization or to a project with specific role permissions. See [Permissions](/docs/orgs-and-projects/roles-and-permissions#permissions) to learn more about organization roles and project roles.

Mixpanel enforces a domain-based rate limit of about 10 invite emails per hour per email domain for organization/project user invitations.

#### Invite Users to an Organization

To invite a user to an organization:

1. Under "Organization Settings", click **Users & Teams** and you will land on the Users tab.
2. Click **Invite Users**. The “Invite New Users” box appears.
3. Enter the email address of the user and select their **Organization Role**, **Projects** to add them to, and **Project Role**.
4. Click **Add another user** to invite additional users.
5. Click **Invite** to complete the process.

<Frame>
  <img alt="image" />
</Frame>

You may also bulk invite users by selecting **Bulk invite** and uploading a CSV file following the format of the provided **CSV template** linked in the UI.

<Frame>
  <img alt="image" />
</Frame>

#### Invite Users to a Project

To invite a user to a project:

1. Under "Project Settings", click **Project Users**.
2. Click **Invite Users**.
3. Click the **User** dropdown menu to select existing users in your organization or type an email to invite a new user.
4. Assign a role in the **Role** dropdown menu.
5. Click **Add another user** to invite additional users.
6. Click **Invite** to complete the process.

<Frame>
  <img alt="image" />
</Frame>

If there are projects that you wish for everyone in your organization to have some baseline access, you can choose **All Users in the Organization** from the **User** dropdown menu and then select a default role to provide all current and future users in your organization with this default access.

<Frame>
  <img alt="image" />
</Frame>

#### Resend an invite

To resend an invite to a user:

1. Under "Organization Settings", click **Users & Teams**, and then the **Invited Users** tab.
2. After locating the user's email address, click the 'Resend Invite' button located on the right side of the screen.
3. A pop-up window appears, giving you the option to either automatically resend the invite email by clicking the "Resend" button or copy a link to manually send it to the user, in case they have problems receiving our emails.

### Change a User's Role

Owners and Admins can update the role of an existing user at any time. You can only assign a role at or below your own permission level.

#### Change an Organization Role

To change a user's organization role:

1. Under "Organization Settings", click **Users & Teams** and you will land on the Users tab.
2. Find the user's account in the list and click their name.
3. Next to **Organization Role**, click the edit (pencil) icon, select the new role from the dropdown, and click **Save**.

<Note>
  Only an Owner can assign the Owner role; Admins can assign roles up to Admin. See [Organization Roles](#organization-roles) for what each role can do.
</Note>

#### Change a Project Role

To change a user's project role:

1. Under "Project Settings", click **Project Users** to open the **Current Users** tab.
2. Find the user in the list and click the **Role** dropdown in their row.
3. Select the new role from the dropdown.

<Note>
  See [Project Roles](#project-roles) for what each role can do.
</Note>

### Remove Users

You can remove users from an organization or project. You can only remove users with a role permission below your own.

#### Remove User from an Organization

1. Under "Organization Settings", click **Users & Teams**.
2. Find the user(s) to remove and click the checkbox next to their name.
3. Click the **Delete** button that appears at the top of the table.

<Note>
  Deleting a user from an organization will remove them from all projects and teams within the organization and is non-reversible.
</Note>

<Frame>
  <img alt="image" />
</Frame>

#### Remove User from a Project

To remove a user from a project:

1. Under "Project Settings", click **Project Users**.
2. Find the user(s) to remove and click the checkbox next to their name.
3. Click the **Delete** button that appears at the top of the table.

A user can belong to multiple projects. Removing a user from one project does not affect their access to other projects within the organization. Any assets the user created (such as boards or reports) remain available in the project and are not automatically removed when the user is removed.

<Note>
  Only users with Organization Owner or Organization Admin roles can remove users who have access to a project granted through a [Team](/docs/orgs-and-projects/roles-and-permissions#teams).
</Note>

<Frame>
  <img alt="image" />
</Frame>

## Permissions

In Mixpanel, users have roles in an organization and in a project. The types of organization and project roles a user has should be based on the required permissions users need for specific levels.

### Organization Roles

<Note>
  Users on an Enterprise or Growth plan have access to four roles: Owner, Admin, Billing Admin, and Member.

  Users on a Free plan have access to two roles: Owner and Billing Admin.

  See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

The table below breaks down the roles and permissions of each role:

| **Organization Role**                                              | **Owner** | **Admin** | **Billing Admin** | **Member** |
| ------------------------------------------------------------------ | --------- | --------- | ----------------- | ---------- |
| Manage Billing Plans                                               | ✅         | ❌         | ✅                 | ❌          |
| Create Projects                                                    | ✅         | ✅         | ❌                 | ❌          |
| Delete Projects                                                    | ✅         | ❌         | ❌                 | ❌          |
| Create/Delete Teams                                                | ✅         | ✅         | ❌                 | ❌          |
| Transfer Projects Between Organizations                            | ✅         | ❌         | ❌                 | ❌          |
| Add/Invite/Remove users to an Organization and or Projects         | ✅         | ✅         | ❌                 | ❌          |
| Add/Modify/Remove Service Accounts to Organization and or Projects | ✅         | ✅         | ❌                 | ❌          |
| Modify Roles - Organization Level                                  | ✅         | ✅         | ❌                 | ❌          |
| Modify Roles - Make themselves an Owner                            | ✅         | ❌         | ❌                 | ❌          |
| Modify Roles - Project/Team Level                                  | ✅         | ✅         | ❌                 | ❌          |
| Modify 2FA and SSO                                                 | ✅         | ✅         | ❌                 | ❌          |
| Request Organization Deletion                                      | ✅         | ❌         | ❌                 | ❌          |

**Owner**

<Note>
  It is recommended to have at least 2 Organization Owners at all times, in case an owner loses access to their account or is no longer working with the company.

  If all existing owners are no longer working with the company and you need to assign a new owner, please [reach out to the support team](https://mixpanel.com/get-support).
</Note>

Organization Owners have administrative permissions for the organization and all the projects in the organization. Multiple users can be Owners. However, each organization must have at least one Owner.

**Admin**

Organization Admins have permissions to manage projects, members, and roles in the organization. Organization Admins have the same permissions as Organization Owners **except** for the following:

* Request Organization deletions
* Delete Projects
* Transfer Projects between Organizations
* Manage Billing Plans

In addition, an Organization Admin would not be able to assign any user to anything higher than Admin (i.e., Organization Owner).

**Billing Admin**

Organization Billing Admins can only manage billing plans for your company. The Billing Admin does not have to belong to a team or project. A user can be a Billing Admin and also a member of a Project or a Team simultaneously.

Billing admins can view organization settings solely to:

* Manage Billing Plans
* Update Billing Information
* View Receipts
* Submit a Downgrade Request

**Member**

Organization Members have no permissions to control or manage organization settings. In order for a user to have access to project(s) and/or team(s), they must first be added to the organization as a Member.

### Project Roles

Users in a Project can be assigned to 4 roles: Owner, Admin, Analyst, and Consumer. The table below is an overview of the permissions per role on a project level.

| **Project Roles**              | **Owner** | **Admin** | **Analyst** | **Consumer** |
| ------------------------------ | --------- | --------- | ----------- | ------------ |
| Transfer/Reset/Delete Projects | ✅         | ❌         | ❌           | ❌            |
| Edit Project Timezones         | ✅         | ✅         | ❌           | ❌            |
| Edit Project Name              | ✅         | ✅         | ❌           | ❌            |
| View Access Keys               | ✅         | ✅         | ❌           | ❌            |
| View Usage Statistics          | ✅         | ✅         | ❌           | ❌            |
| Access Time Period Settings    | Edit      | Edit      | View Only   | View Only    |
| Invite Project Users           | ✅         | ✅         | ❌           | ❌            |
| Change Project Users Role      | ✅         | ✅         | ❌           | ❌            |
| Approve Access Requests        | ✅         | ✅         | ❌           | ❌            |
| Create Service Accounts        | ✅         | ✅         | ❌           | ❌            |

The table below is an overview of the permissions per role for reports and other features.

| **Project Roles**                       | **Owner** | **Admin**        | **Analyst**      | **Consumer**             |
| --------------------------------------- | --------- | ---------------- | ---------------- | ------------------------ |
| Create and View Insights Reports        | ✅         | ✅                | ✅                | ✅                        |
| Create and View Flows Reports           | ✅         | ✅                | ✅                | ✅                        |
| Create and View Funnels Reports         | ✅         | ✅                | ✅                | ✅                        |
| Create and View Retention Reports       | ✅         | ✅                | ✅                | ✅                        |
| Download Reports                        | ✅         | ✅                | ✅                | ❌                        |
| Create Custom Alerts                    | ✅         | ✅                | ✅                | ❌                        |
| Edit Custom Alerts                      | ✅         | ❌                | ❌                | ❌                        |
| View Users Report                       | ✅         | ✅                | ✅                | ✅                        |
| Export Users Report                     | ✅         | ✅                | ✅                | ❌                        |
| Create/Edit Cohorts                     | ✅         | ✅                | ✅                | ✅                        |
| Export Cohorts                          | ✅         | ✅                | ✅                | ❌                        |
| Create/Edit User Profiles               | ✅         | ✅                | ❌                | ❌                        |
| Delete User Profiles                    | ✅         | ✅                | ❌                | ❌                        |
| Create and View Boards                  | ✅         | ✅                | ✅                | ✅                        |
| Create Subscriptions for Boards         | ✅         | ✅                | ✅                | ❌                        |
| Edit Subscriptions for Boards           | ✅         | Only the Creator | Only the Creator | Only the Creator         |
| Create/Edit Custom Events               | ✅         | ✅                | ✅                | ✅ Can save only for self |
| Create/Edit Saved Behaviors             | ✅         | ✅                | ✅                | ✅ Can save only for self |
| Create/Edit Saved Formulas              | ✅         | ✅                | ✅                | ✅ Can save only for self |
| Create/Edit Custom Properties           | ✅         | ✅                | ✅                | ✅ Can save only for self |
| Create/Edit Borrowed Properties         | ✅         | ✅                | ❌                | ❌                        |
| Upload a Lookup Table                   | ✅         | ✅                | ✅                | ✅                        |
| Map Property to Lookup Table in Lexicon | ✅         | ✅                | ❌                | ❌                        |
| Hide Data in Lexicon                    | ✅         | ✅                | ❌                | ❌                        |
| Edit Descriptions in Lexicon            | ✅         | ✅                | ❌                | ❌                        |
| Add Tags in Lexicon                     | ✅         | ✅                | ❌                | ❌                        |
| Merge Data in Lexicon                   | ✅         | ❌                | ❌                | ❌                        |
| Drop Data in Lexicon                    | ✅         | ❌                | ❌                | ❌                        |
| Download CSV in Lexicon                 | ✅         | ✅                | ✅                | ❌                        |

**Owner**

When a user creates a project, they own and have complete control over it. They have all permissions at the project level and can provision project ownership to other project users.

Organization Owners, by default, have administrative permissions to assume an owner role in a project.

**Admin**

Project Admins have the same set of permissions as project owners. However, they cannot delete or reset the project or manage its security. In addition, a Project Admin would not be able to assign any user to anything higher than Admin (i.e., Project Owner).

Organization Admins, by default, have administrative permissions to assume an admin role in a project.

**Analyst**

Project Analysts can create and save Mixpanel reports and Boards. They can also share their saved reports and Boards, along with reports and Boards in which they have editor permissions. They, however, do not have permissions to manage project user roles.

**Consumer**

Project Consumers can:

* Add saved reports to their own Boards.
* Duplicate another user's Board and edit it.
* Edit reports and Boards on which they have been added as an editor. However, they cannot change the sharing settings of these reports and Boards.
* Cannot create public Boards.

Boards created by Project Consumers will not be surfaced to other users in Mixpanel. Project Consumers also cannot manage project user roles.

#### Multiple Roles at Once

It is possible to have multiple or conflicting roles on a project via teams or organization roles. Within Mixpanel, all roles are additive and strictly give permissions to an action. They do not remove any abilities. For example:

1. A project Owner who is an organization Admin will have both project Owner and project Admin permissions in the project. For all intents and purposes, this is the same as having just the project Owner role.
2. If a user is assigned both the Consumer role individually and the Analyst role via a team. The user would be able to do anything a Consumer can do and anything an Analyst can do.

#### Grant Types

A user's project role(s) can be granted in different ways:

* Organization Role - Project Owner or Admin role was granted because the user is an Organization Owner or Admin
* Team Grant (Team Name) - user is part of the indicated team where the project role was granted
* Individual Grant - role was explicitly granted to the user at the project level
* All Users Grant - current project has enabled "All Users in the Organization" to have the default indicated role

<Frame>
  <img alt="image" />
</Frame>

## Teams

Mixpanel enables you to create and delete Teams within an organization. Teams make it easier to manage roles and permissions for a group of users. Users who are members of a Team will be provisioned with the same role and permissions that are assigned to the team.

<Frame>
  <img alt="image" />
</Frame>

### Creating Teams

To create teams in Mixpanel:

1. Under "Organization Settings", click **Users & Teams** and you will land on the Users tab.
2. Click **Teams** to see a list of current teams in your organization.
3. Click **Create Team** and provide a team name.
4. Click **Done** to complete the process and see the team's permission and membership.

### Adding Users to Teams

All users added to a team will receive the same role and permissions that are assigned to the team. To add users to a team:

1. Under "Organization Settings", click **Users & Teams** and you will land on the Users tab.
2. Select the **Teams** tab and select the team to add users to.
3. Click **Add Users** to select users to add to the team.
4. Click **Done** to complete the process.

[Service Accounts](/reference/service-accounts) can also be added to teams, similar to how you would add a user to teams.

### Managing Team Permission

<Frame>
  <img alt="image" />
</Frame>

#### Adding Projects to Teams

Adding projects to a team gives all individuals in the team access to that project with the specified project role. To add projects to a team:

1. Under "Organization Settings", click **Users & Teams** and you will land on the Users tab.
2. Select the **Teams** tab and select the team to manage.
3. Click **Add Projects** and select the project(s) and appropriate project role.
4. Click **Add** to complete the process.
5. You can also grant [Classified Data](/docs/data-governance/data-views-and-classification#data-classification) access by ticking the checkbox under **Classified Data** column.

#### Adding Data Views to Teams

Adding project [Data Views](/docs/data-governance/data-views-and-classification#data-views-overview) to a team will filter data access to all individuals within the team. Click [here](/docs/data-governance/data-views-and-classification#add-users-or-teams) for instructions on how to add a team to a Data View under **Project Settings --> Data Views**.

### Deleting Teams

Deleting a team will revoke all access permissions that were granted to users and service accounts as part of their team assignments. Permissions given through other [grant types](/docs/orgs-and-projects/roles-and-permissions#grant-types) will be retained.

To delete a team in Mixpanel:

1. Under "Organization Settings", click **Users & Teams** and you will land on the Users tab.
2. Click **Teams** to see a list of current teams in your organization.
3. Find the team(s) to remove and click the checkbox next to the team name.
4. Click the **Delete** button that appears at the top of the table.

<Frame>
  <img alt="image" />
</Frame>

## Custom Roles

<Note>
  Custom Roles is available to organizations on **Enterprise** plans. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Custom roles let you create specialized access profiles beyond the four default project roles (Owner, Admin, Analyst, Consumer). With custom roles, you can define granular permissions tailored to specific job functions or workflows. Each project can have up to **5 custom roles**.

Only project **Owners** and **Admins** can create and manage custom roles.

### Creating a Custom Role

To create a custom role:

1. Under "Project Settings", click **Project Users**.
2. Select the **Project Roles** tab to see a list of current roles in the project.
3. Click **Create Custom Role**.
4. Enter a **Name** and optional **Description** for the role. Names must be unique within the project.
5. Optionally, select an existing role as a template to start with its permissions pre-selected.
6. Configure permissions by toggling individual permissions on or off across the available categories (see [Permission Categories](#permission-categories) below).
7. Click **Save** to create the role.

<Frame>
  <img alt="create_custom_role" />
</Frame>

Once created, the custom role will appear alongside default roles when assigning project roles to users, teams, and service accounts.

### Permission Categories

When creating or editing a custom role, you can configure permissions across six categories:

| **Category**                          | **Configurable Permissions**                                                                                                                                                                             |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Analysis**                          | Save Reports and Boards, Create Custom Data Definitions (cohorts, metrics, custom events and properties), Manage All Analysis and Custom Data Definitions                                                |
| **Feature Flags and Experimentation** | Experimentation Creation, Feature Flag Creation, Full Feature Flag Access                                                                                                                                |
| **Data Management**                   | Edit Metadata, Set Event and Property Visibility, Data Verification, Manage Schemas, Manage Lookup Tables, Mark Data Classified, Edit Profiles, Data Deletion Dropping and Merging, Data Settings Access |
| **Data Access, Exports, and Alerts**  | Public Boards, Classified Data Access, Export Lexicon, Export Reports as CSV, Export Users as CSV, Export Events as CSV, Create Alerts, Create Board Subscriptions, Manage All Alerts                    |
| **Data Sources and Definitions**      | Create and Manage Cohort Syncs, Create and Manage Pipelines, Create and Manage Data Warehouses                                                                                                           |
| **Settings and Notifications**        | View and Edit Project Settings                                                                                                                                                                           |

<Note>
  All custom roles automatically include base permissions: viewing reports, editing visibility of entities you created, and sharing entities you created. These permissions cannot be removed.
</Note>

### Managing Custom Roles

To manage a custom role, navigate to **Project Settings** → **Project Users** → **Project Roles** tab. Click the overflow menu (three dots) on any custom role card to access the following options.

#### Editing a Custom Role

Select **Edit** to modify the role name, description, or permissions, then click **Save**. Changes take effect immediately for all users assigned to that role.

#### Copying a Custom Role to Another Project

Select **Copy to Another Project** to copy a custom role from one project to another within the same organization. Choose the target project, then modify the name, description, or permissions as needed before saving.

<Note>
  Cloning a role to another project requires the **manage custom roles** permission on the target project. Any permissions gated by features that are not enabled on the target project will be automatically excluded from the cloned role.
</Note>

#### Deleting a Custom Role

Select **Delete** and confirm the deletion. When a custom role is deleted, all users, service accounts, and teams currently assigned to that role are automatically reassigned to the **Consumer** role — the least-privileged default role. Review the list of affected users before confirming deletion, and reassign them to an appropriate role afterward.

<Note>
  When a custom role is deleted, all users currently assigned to that role will be automatically reassigned to the **Consumer** role. Review the list of affected users before confirming deletion.
</Note>

### Assigning Custom Roles to Service Accounts

Service accounts can be assigned custom roles the same way project users can. To assign a custom role to a service account, navigate to **Project Settings** → **Service Accounts** and select the custom role when creating or editing a service account.

### Assigning Custom Roles to Organization Teams

Custom roles can be applied to organization-level teams for bulk role assignment. When a team is given access to a project that has custom roles, those custom roles appear in the role dropdown alongside the default roles.

To assign a custom role to a team:

1. Navigate to **Organization Settings** → **Users & Teams** → **Teams**.
2. Select the team you want to configure.
3. Under **Projects**, add the project or find an existing project assignment.
4. Click the role dropdown for that project and select the custom role.

All members of the team inherit the assigned role for that project.

### Changes to Classified Data Access (April 2026)

Previously, classified data access was managed through a separate per-user toggle on the Project Users page. Admins could individually grant or revoke a user's ability to view sensitive properties, independent of their project role.

With Custom Roles, classified data access is now a permission called **Classified Data Access** under the **Data Access, Exports, and Alerts** category. This gives you a single place to define what a role can and cannot do, rather than managing access through a separate toggle.

No default role — including Owner and Admin — has the ability to view classified data by default. This is intentional: access to classified data should always be an explicit decision, not an inherited side effect of a role. Owners and Admins retain the ability to control who gets classified data access, but must be explicitly granted viewing access themselves through a custom role.

Note the distinction between two related permissions:

* **Mark Classified Data** (under Data Management) — Controls which properties are classified as sensitive. Does not grant the ability to view that data.
* **Classified Data Access** (under Data Access, Exports, and Alerts) — Grants the ability to view properties that have been marked sensitive.

These are intentionally separate so that someone can classify data without being able to see it.

### FAQs

#### Can I modify the default project roles?

No. Default roles (Owner, Admin, Analyst, Consumer) cannot be edited. Create a custom role instead — optionally starting from a default role as a template.

#### Why can't Owners or Admins see classified data by default?

By design, no role can view classified data by default — including Owner and Admin. Owners and Admins can control who gets access, but cannot view classified data themselves unless explicitly granted via a custom role. This ensures classified data access is always intentional.

#### Can Custom Roles change how Mixpanel looks for a user?

No. Custom Roles control what actions a user can perform, not the UI. Navigation and layout do not change based on role.

#### Does this include resource-level access control?

No. Custom Roles operate at the project level. Per-board, per-report, or per-cohort permissions are not supported.

#### Do service accounts support custom roles?

Yes. Service accounts can be assigned custom roles the same way project users can.


# Pricing
Source: https://docs.mixpanel.com/docs/pricing

How Mixpanel pricing works

## How Mixpanel Pricing Works

### Events

An event is a data point that represents an interaction between a user and your product. Events can be a wide range of interactions. Here are some examples:

* Social: Post Created, Friend Added
* E-Commerce: Added to Cart, Purchase Completed
* Media: Video Watched, Article Read
* SaaS: Document Created, Call Started

To decide which Mixpanel plan is right for you, first think about [what events you want to track](/docs/quickstart/what-to-track) and the number of active users you have.

### Computed Monthly Across Projects

Event-based pricing calculates the amount you are charged based on the number of events across all projects in your organization. Certain events and API updates are non-qualifying and **excluded from the Monthly Events calculation**:

* Identify (`$identify`)
* Create Alias (`$create_alias`)
* Merge (`$merge`)
* Opt In (`$opt_in`)
* Session Recording Checkpoint (`$mp_session_record`)
* User profile creation/updates

### Plan Differences

There are three event-based billing plans to choose from: Free, Growth, and Enterprise. Growth and Enterprise plans have optional add-ons for Group Analytics (recommended for B2B) and Data Pipelines (exports your events to a data warehouse or cloud storage bucket). Refer to our [pricing page](https://mixpanel.com/pricing/) for more information on the benefits and features of each plan.

The high-level differences between the three are:

* **Free:** Mixpanel is usage-based, and you can use it for free for as long as you want, no trial needed. If you are new to Mixpanel and want to test it out, we encourage you to use our free plan and upgrade once you have an estimate of your project’s volume. Limited to a maximum of 5 saved reports per user account and 1M total events. Features like cohorts, lookup tables, custom properties, or permissions are not included.
* **Growth:** The typical Growth plan customer is a small team using Mixpanel (fewer than 50 employees). Growth plans purchased after February 2025 include the first 1M events free.
* **Enterprise:** Designed for large teams that require access controls and permissions, data governance features, dedicated onboarding support, and account management. Some exclusive reports for Enterprise are Signal, Experiments, and Impact, with features like Data Views and sensitive data classification.

## Choosing the Right Plan

### How do I estimate how much Mixpanel will cost?

If you're already using another tool, you might have the exact numbers you need. However, if you aren’t using another tool, the best way to estimate costs is to [sign up](https://mixpanel.com/register/) and use our generous free plan. After a week, you'll get a good estimate of your projected volume on your "Plan Details & Billing" page (see below).

### **View Events Usage**

If you are currently tracking data and have either the "Owner" or "Billing Admin" organization role, you can see your events’ consumption in your organization's Settings screen. To do so, click on the gear icon in the lower left corner of Mixpanel, “Organization Settings”, and then the “Plan Details & Billing” tab.

From here, you can quickly view this billing period’s usage on the right side of the screen as well as the historical one by accessing the "Data Usage" tab and clicking the “View Historical Usage” button:

<Frame>
  <img alt="Events Usage" />
</Frame>

<Frame>
  <img alt="Historic Usage" />
</Frame>

### Group Analytics Add-On

The Group Analytics add-on enables behavioral analysis at the business or group level, as opposed to the individual level.

Check [here](/docs/data-structure/advanced/group-analytics) for the technical documentation for Group Analytics, keeping in mind that implementing this feature is not trivial and includes sending your events with the key of the [group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties) they belong to. Group Analytics **can’t be implemented retroactively** for already ingested events.

This is a recommended feature for all B2B products that want answers to questions such as:

* What companies are engaging the most with a product?
* In instances with more than one user per account, such as a video streaming service, how are events triggered at an account level?
* What groups convert through a funnel to a goal event (as opposed to what individual users convert)?

### Data Pipelines Add-On

The Data Pipelines Add-On exports the events in your Mixpanel project to a cloud storage bucket or data warehouse of your choice. It's useful if you want to analyze Mixpanel events using SQL in your own environment. We offer a 30-day free trial of this feature; see the [FAQ](/docs/data-pipelines#how-does-the-free-trial-work) on how to enable it.

### Metric Tree Add-on

The Metric Tree Add-On enables you to map your growth strategy quantitatively and measurably, and understand the logical relationship between your input metrics and output business outcomes. It is a collaborative space for you and your team to identify opportunities, have prioritization and trade-off discussions across Exec to ICs, and eventually take data-backed decisions. You can read more about the functionality of Metric Trees [here](/docs/metric_tree).

## Billing & Payment

Mixpanel runs on a subscription service in which your card is charged at the beginning of every month or every year (depending on the plan you purchased) to cover reporting services for that period of time.

<Note>
  This can only be done by "Owner" and "Billing Admin" users. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).

  If you don't see these sections, please contact your organization's owner or billing admin. If there isn't one, please [contact the Support team](https://mixpanel.com/get-support).
</Note>

### Update billing information

To update your credit card or download invoices, please follow these steps:

1. Click the gear icon at the lower-left corner of the purple menu at Mixpanel and then the “Organization Settings” option.
2. Then, select the “Plan Details & Billing” tab, and click “Manage Billing & Payment”.

<Frame>
  <img alt="Manage Billing & Payment" />
</Frame>

### Troubleshoot payment issues

If you received an email or in-app notification that your payment didn't go through, don't worry! It's quick and easy to get back up and running.

1. Click on “Update the Payment Method” in the notification to be taken to your organization's "Billing & Payment" section.
2. Edit the credit card details by clicking the “pencil” icon:

<Frame>
  <img alt="Edit Payment Method" />
</Frame>

3. Lastly, click on the “Rerun Payment” button on the right side.

If the payment is successful, you will see a success message in the bottom left corner, and an error icon should no longer appear next to your payment information - do note that this can take a few minutes to process. You may check back later, and it will not interrupt processing. If you and your bank are unable to resolve the issue, please reach out to our Support team.

### Downgrade your plan to Free

<Note>
  You can only edit or downgrade your plan if you have “Owner” or “Billing Admin” permissions over your Mixpanel organization.
</Note>

<Warning>
  Downgrading to the Free plan does not take effect immediately. You will keep your current plan through the rest of this billing cycle, and the Free plan starts on your next billing date.
</Warning>

To submit a downgrade request:

1. In your organization's “Plan Details & Billing” tab, click "Modify Plan", and then "Downgrade to Free Plan".
2. A pop-up window will appear, informing you that your account will remain active and be automatically moved to a Free plan after your current monthly/annual subscription ends.
3. After clicking the "Submit" button, a Downgrade Request Email is sent to all organization owners as proof of your request, and a copy of it goes to Mixpanel's Billing Team for processing.

<Frame>
  <img alt="Switch to Free" />
</Frame>

## FAQs

### How do I reduce my Mixpanel bill?

The best way to reduce your bill is to send fewer events to Mixpanel. Check your project’s [Lexicon](/docs/data-governance/lexicon#viewing-query-volumes-for-events-and-properties) for events you are not querying, or for events with few queries and a high volume not providing value.

You can also check the top events contributing towards your event count by creating a monthly Insights report querying “All Events” with a breakdown by “Event Name” ([example](https://mixpanel.com/project/3018488/view/3536632/app/insights#J1ZGYyVkWKpK)).

[Hiding events](/docs/data-governance/lexicon#hide-events-and-properties) in Lexicon won’t stop their ingestion. [Dropping an event](/docs/data-governance/lexicon#dropping-events) in Lexicon will only block its ingestion from the moment it was dropped, not removing it retroactively.

### What if I go over my event plan allowance? Do you stop tracking my events?

If you go over your plan's events, Mixpanel won't stop collecting your data:

* If you're using a Free plan, Mixpanel limits your platform access once you reach 1M monthly events, but doesn't charge overages. Once you hit the limit, you will be blocked from viewing your reports until you either upgrade to a Growth plan that supports your current usage or wait until the following month, when your allowance automatically resets.
* If you're using a Growth plan, the additional cost will be charged at the beginning of the next month based on your À La Carte rate, which you can find in the "Plan Details & Billing" section in your Organization Settings. On the contrary, if you want to avoid paying for overages, you can either [downgrade your paid plan to the Free one](/docs/pricing#downgrade-your-plan-to-free) or upgrade to one that covers your additional usage before the end of the billing cycle - the more events your plan includes, the less you pay per event.

#### Alerts for Additional Data Charges

Organization owners and billing admins are sent an alert email if their paid account reaches the following percentages of their plan volume: 85%, 100%, 110%, 120%, 200%, 300%, and 400%. If an account reaches two or more of these thresholds, it is possible to receive multiple alerts in one month. Additionally, email addresses that are CC'd on invoice receipts will also be CC'd on alert emails.

#### Can I set a billing limit?

While it's not possible to set a billing limit at this moment, read [this article](https://github.com/orgs/mixpanel/discussions/526) to learn how to create a report and get warning alerts when you’re close to exceeding your plan limit.

### I’m on a Growth plan and paying for less than 1M monthly events. How do I switch to the more recent one?

The easiest way to switch is to go to Mixpanel’s [pricing page](https://www.mixpanel.com/pricing) and select “Make the Switch” on the Growth plan card. From there, you can move to the latest plan. If you are unable to adjust your plan, reach out to our Support team.

### Why can I only select a volume of 1M monthly events on monthly Growth plans, but not annual ones?

Our latest pricing plans include the first 1M events free each month. We require a larger pre-committed volume (more than 1M monthly events) in order to purchase an annual plan. Annual plans still include the first 1M events free each month.

### I signed up for the 1 million event Growth plan. What happens if I go over that amount?

The first 1 million events ingested are free! If you go over 1 million events, each event ingested will be charged at the additional data rate seen in the “Plan Details & Billing” section in your Organization Settings. If you're only on a 1M monthly events plan, the additional data rate is \$.00028 per event. Purchasing higher volumes upfront will lower that additional data rate, as we include volume discounts in our pricing.

If you have the Data Pipeline or Group Analytics add-ons, you will also be charged 20% for Data Pipelines and/or 40% for Group Analytics based on the additional data ingested.

As an example:

* You signed up for the 1 million monthly event Growth plan with Group Analytics
* If you send 1.1 million events in a month, you’ll be charged for the 100,000 events over the plan at the additional data rate, along with 40% of the calculated overage for the Group Analytics add-on.

We bake volume discounts into our pricing, so if you are often tracking more than 1 million monthly events, it may be better to upgrade to the right-sized plan on the Pricing page — you’ll pay less per event.

### Is Mixpanel’s pricing based on MTUs?

Mixpanel’s default pricing option is based on events because it is a better option for the majority of customers. Mixpanel also offers an MTU-based Enterprise plan, which **starts at \$20,000 per year** and isn’t available online. If you are interested in learning more about it, [contact our sales team](https://mixpanel.com/contact-us/sales/).

If you are an existing customer on an MTU plan, [refer to our MTU Pricing Guide](/docs/pricing/legacy-mtu-billing).

### Are monthly events calculated based on ingestion time or event timestamp?

Events are calculated based on the ingestion time, defined as the time an event is processed by Mixpanel servers. Ingestion time is [stored by default](/docs/data-structure/property-reference/default-properties#event-properties) as the Time Processed (UTC) property on all events. For example, if on January 10th an event is sent to Mixpanel that is timestamped December 10th, it will be included in January's monthly tallies.

Some accounts are on legacy event timestamp billing. In this case, monthly events are tallied based on the timestamp of the event. For example, if on January 10th an event is sent to Mixpanel that is timestamped December 10th, it won’t be included in any tallies because the timestamp is from a previous month.

You can see if your account is on ingestion time billing in Organization Settings > Plan Details & Billing > Data Usage.

### Is old event data billed when imported to Mixpanel?

This depends on whether your account is on ingestion time or event timestamp billing. Refer to the section above for details.

For accounts on ingestion time billing, old events will be included in billing tallies since they’re calculated based on ingestion time. For example, if April 1st - April 30th is the current billing cycle, importing data from March **will** be included in the April event count. If you’re planning on backfilling a significant amount of historical events and need help understanding how it will impact your costs, please reach out to your Mixpanel account manager or [contact support](https://mixpanel.com/get-support).

For legacy accounts on event timestamp billing, events imported with timestamps outside the current billing cycle will not contribute to event tallies. For example: if April 1st - April 30th is the current billing cycle, importing data from March will **not** be included in the April event count.

### I am using the Warehouse add-on for ingesting data. How does this impact billing?

Events imported through a warehouse connection are treated as any other source (same as importing through our SDKs or API directly). Warehouse data, similar to other sources, is billed in accordance with general Mixpanel pricing policies.

There is one additional field you will see in the Billing Page on your Data Usage Table called "Updates". Updates (updating an existing event or deleting an event) are generated by Mirror-type syncs and are tracked separately from event volume. Each update is counted as one event towards billing, and they are counted and billed for the month they were triggered on, even if the record being updated is for a previous month. You can read more about these updates and how warehouse connectors may affect billing from the warehouse perspective [here](/docs/tracking-methods/warehouse-connectors#faq)

### I received an email asking me to upload my company's tax information. Is it a scam? Why are you asking for that?

Those emails are real and part of our ongoing efforts to ensure that our customers' billing and tax data is as up-to-date as possible. This allows us to generate invoices with the correct information and helps reduce billing issues.

To do so, you can either use the link provided in the email or go to your organization's Settings -> 'Plan Details & Billing' tab -> 'Billing Info' tab -> 'Manage Billing & Payment' button -> 'Tax Information' tab -> 'Manage Tax Info' button on the top-right side of the screen.

If you or your Finance team have any additional questions about it, please [contact the Support team](https://mixpanel.com/get-support).


# MTU billing
Source: https://docs.mixpanel.com/docs/pricing/legacy-mtu-billing



## What is an MTU?

Monthly Tracked User (MTU) is a way to calculate your billing based on the number of visitors that perform a qualifying event each month, rather than individual user profiles or events. MTU plans start at \$20,000 per year and are **not available to be purchased directly via our Pricing page**. [Our sales team can consult you](https://mixpanel.com/contact-us/sales/) to choose the best option.

MTU can be considered when tracking more than 100k users or 5M monthly events.

## MTU Calculation

An MTU is a visitor that **tracks at least one qualifying event** within your projects within the calendar month, independent of whether they have a user profile in [Users](/docs/users#basic-features). Mixpanel determines unique users using the `$distinct_id`. Users are only counted once per month, even if they perform multiple actions across devices.

An organization is charged based on the total number of MTUs across all projects. This means that if a user performs a qualifying event in multiple projects, they are **counted once per project**. MTUs are *not* User Profiles – the number of MTUs in your project will not match the number of [User Profiles](/docs/data-structure/user-profiles) in your project.

## MTU Guardrail

In most cases, the tally of MTUs is equal to the number of distinct IDs who have performed a tracked event this month. The only exception to this rule is **if your users average more than 1,000 events each**, in which case MTUs are equal to:

Total number of events / 1,000

## Excluded Events

Certain events and API updates are non-qualifying and excluded from the MTU calculation:

* Identify (`$identify`)
* Create Alias (`$create_alias`)
* Merge (`$merge`)
* Opt In (`$opt_in`)
* Session Recording Checkpoint (`$mp_session_record`)
* Message Sent (`$campaign_delivery`)
* Message Received (`$campaign_received`)
* Message Bounced (`$campaign_bounced`)
* Message Marked Spam (`$campaign_marked_spam`)
* Message Suppressed (`$message_suppressed`)
* Message Unsubscribed (`$unsubscribe`)
* Campaign Entered (`$journey_entered`)
* Experiment Started (`$experiment_started`)
* Mailchimp Campaign - Open
* Mailchimp Campaign - Click
* Mailchimp Campaign - Sent
* Mailchimp Campaign - Unsubscribed
* Mailchimp Campaign - Bounce
* Updates to user profiles
* Warehouse Mirror Event Updates
* Warehouse Mirror Profile Updates

While Mixpanel events generated by messages do not count toward your total MTU calculation, Message Open events do count towards MTU Guardrail.

Similarly, while Mixpanel Warehouse driven Event Updates & Deletes and Profile Mirror Updates do not count towards your total MTU calculation, they do count towards the MTU Guardrail.

> Note: Mixpanel has deprecated the Messages & Experiments feature since Jan 1, 2022; the above documentation is kept for existing customers who may have had these events in the past while using those features.

In addition, Mixpanel also excludes a number of inbound events sent by partner products. Refer to a given partner's [integration page](/docs/cohort-sync/integrations/airship) to see if it has events excluded from MTU calculations.

## Estimate MTU Usage

If you haven't implemented tracking yet, you can estimate your current MTU usage by looking at your Monthly Active User (MAU) count. Your MTU and MAU counts should be similar, provided they account for anonymous visitors identically.

## View MTU Usage

MTU calculations **include anonymous visitors**. This means users who only visit your homepage can still count towards MTU calculations.

You can see your MTU consumption in your Organization Settings:

1. Click on the gear icon in the upper right corner of Mixpanel, and select “Organization Settings”
2. Then click on "Plan Details & Billing" and then on “Data Usage”

To view detailed historical data usage, or download a CSV of usage from the last 12 months for each project, click on “View Historical Usage” in the top right of Plan Details & Billing.

<Frame>
  <img alt="Plan Details and Billing" />
</Frame>

View the top events contributing towards your MTU count by creating a monthly Insights report and querying \$all\_mtu\_events which filters out event names excluded from Mixpanel's MTU calculation and applying a breakdown by “Event Name” (example report)

## What if I go over my MTU plan allowance?

If you go over the limit of your plan, Mixpanel won't stop collecting your data. You'll be charged the additional data rate for each additional MTU. Automatic alerts are in place to notify Organization Owners and Billing Admins of potential additional data charges.

For example, let’s say you are on a Growth plan including 1,000 MTUs:

* In January you tracked 1,500 MTUs, which went over by 500 MTU.
* Around January 1, you would have paid your base monthly fee for January.
* Then around February 1, you will pay your base monthly fee for February plus the January additional data rate charges you incurred.

We recommend upgrading to a pricing plan that fits all your traffic. View the additional data rate for your paid plan in Organization Settings > Plan Details & Billing:

<Frame>
  <img alt="Additional Data Rate" />
</Frame>

## What caused an unexpected spike in my MTU count?

Typically, MTU counts increase when you have an increase in users in your app.

The main scenarios that usually increase the number of MTUs:

* A marketing campaign (can lead to an increase in tracked users due to an influx of anonymous visitors).
* An update that adds tracking to new parts of your product.

To assist in analyzing potential sources of MTU spikes, create a copy of [this board](https://mixpanel.com/project/3409416/view/3914056/app/boards#id=10860850) from our demo project into the main project contributing to MTU charges. Once you open the board linked above, you can click on the 3 dots menu located on the top right-hand corner to duplicate the board, then move the duplicated board into your project.


# Startup Program
Source: https://docs.mixpanel.com/docs/pricing/startup-program

Use Mixpanel for free for the first year

The Mixpanel for Startups program empowers early-stage companies to easily track and analyze data to find product-market fit and more. The program is open to startups that meet the following requirements:

* Incorporated less than five years ago.
* Raised no more than \$8 million (USD) in total funding.
* Haven't previously redeemed other Mixpanel offers.
* Haven’t been on a paid plan.

Eligible startups receive their first year free on the Startup Plan, an exclusive offering for startup program participants. The Startup Plan allows you to take advantage of the full analytics capabilities of Mixpanel, without any feature limits. This includes access to all advanced reports such as [Signal](/docs/reports/apps/signal) and [Experiments](/docs/experiments), our add-on packages (Data Pipelines, Group Analytics, Warehouse Connectors), and Session Replays. The Startup Plan covers data volumes of up to 1 billion events per year. With the Startup Plan, unlock all the power of Mixpanel you'll need to launch, grow, and scale your product.

In order to maintain status in the program, participants must begin sending data to Mixpanel within 90 days of acceptance. If you are not ready to begin implementation, we encourage you to wait and apply once ready.

Participants will be invited to join our exclusive Mixpanel for Startups Community in Slack where you’ll have access to curated content, workshops, resources, and opportunities to learn from other startups as well as the team at Mixpanel.

[Apply for the startup program](https://mixpanel.com/startups-apply/)

### Startup Plan Details

#### What is included in the Startup Plan?

The Startup Plan is designed specifically for participants in the Mixpanel for Startups program. It includes all our advanced reports, as well as add-on packages (Data Pipelines, Group Analytics, Warehouse Connectors, and Session Replay). The Startup Plan is valid for 12 months, has an annual data limit of 1 billion events, and includes 500,000 Session Replay recordings. The Startup Plan is not eligible for BAAs or MSAs.

#### What is the implementation requirement?

Once accepted into the program, startups must start sending data to Mixpanel within the first 90 days to maintain eligibility. If a participating startup doesn’t meet the implementation requirement within the first 90 days, they’ll be removed from the program and prohibited from rejoining. This isn’t to deter startups from joining, but rather encourage them to only apply once truly ready so as to take full advantage of the program and maximize value from Mixpanel.

#### What happens if my usage exceeds 1B events?

If you send over 1B events to Mixpanel during the startup program, you’ll have the option to upgrade to a paid Growth or Enterprise plan, or downgrade to the Free plan. If you’re close to exceeding the limit of the Startup Plan, our team will reach out in advance to discuss your options.

#### Can I continue with the Startup Plan after the first year and receive a second year free?

No. The Mixpanel for Startups program offers eligible companies their first year of Mixpanel for free on the Startup Plan. After the first year, startups are able to move to a Free, Growth, or Enterprise plan. The Startup Plan is only available through the startup program, and cannot be purchased as a standalone plan.

### Program FAQ

#### How does the startup program work?

Once accepted into the program, your Mixpanel account will be provisioned with the Startup Plan. This plan is valid for one year and the term will begin once your application is approved. In order to maintain your eligibility status in the program, startups must begin sending data to Mixpanel within 90 days of your acceptance. If you are not ready to begin implementation, we encourage you to wait and apply once ready.

#### How do I apply?

Eligible startups can [apply here](https://mixpanel.com/startups-apply/)! If you were referred to the program through your VC or accelerator, please select the referral partner from the dropdown menu. Once you confirm your eligibility and submit the form, your account will automatically be provisioned with the Startup Plan and your free year in the program will begin.

#### What if my VC or accelerator is not listed in the application dropdown?

Not all of our partners are currently listed on the application. Please select “Other” from the dropdown menu and enter the name of your VC, accelerator, incubator, or other referral partner. If you were not referred, please select "I do not have a referral partner".

#### Will I receive help getting started with Mixpanel?

Yes! We’ll provide self-serve resources to help with your onboarding and provide access to our [Mixpanel Community](https://community.mixpanel.com/) where you’ll be able to engage with other users and our team. Our Support team is on hand to assist with technical questions as needed, too.

#### Can I apply now and save the offer for later?

No. Once you confirm your eligibility and enroll in the program, the offer through Mixpanel for Startups is activated. Your one free year on the Startup Plan begins at enrollment. Additionally, if you do not start sending data to Mixpanel within 90 days of joining, you will be removed from the program. If you are not ready for the startup program, you can sign up for a [Free plan](https://mixpanel.com/pricing/) and apply to the program when you’re ready to take advantage of the offer. Startups are in Mixpanel’s DNA — so we have a generous free plan (1M events per month) to help you get started.

#### What happens after my year in the startup program?

Once you complete your year in the startup program, our team will work with you and advise on the best Mixpanel plan based on your usage and growth plans. We can help determine whether a Free, Growth, or Enterprise plan will best suit your needs going forward.

#### Why is the startup program offer so generous?

Startups are a part of Mixpanel’s DNA! We are dedicated to having the best startup program on the market and supporting as many founders as we can. The Mixpanel for Startups program provides the first year free on our exclusive Startup Plan, which allows participants to utilize all our features and functionality. Startups should focus on building world-class products and not worry about short-term trials, restrictive data plans, and hidden pricing.

### Eligibility Criteria

#### What do you consider a startup?

To be eligible for the program and considered a startup, you cannot have raised more than \$8 million USD and must have been founded less than 5 years ago. The Mixpanel for Startups program is not available for startups who are already a paid customer, have been on a paid plan in the past, or previously participated in the program. If you have questions about your eligibility status, please reach out to our team at [startups@mixpanel.com](mailto:startups@mixpanel.com).

#### Do I have to be new to Mixpanel to join the program?

No. As long as your startup has not redeemed another exclusive offer or has already been a paid customer, you are eligible to apply.

#### What offers prevent me from qualifying for the startup program?

If you have already redeemed an offer through the [Product School](https://productschool.teachable.com/p/productanalytics) or another partner, you are not eligible for the startup program. Startups are only able to participate in the Mixpanel for Startups program once.

#### Do I need to be associated with a VC or accelerator to join?

No! As long as you meet the eligibility criteria, you’re welcome to join. When you submit the form, please select ‘I do not have a referral partner’ from the dropdown menu.

#### What happens if I misrepresent my eligibility status?

When you applied to participate in the Startup Program, you are asked to confirm that you meet the following eligibility criteria:

1. Have not been on a paid Mixpanel plan;
2. The entity you represent was founded less than 5 years ago (at the time of sign up);
3. The entity you represent has not raised more than \$8M in total funding (at the time of sign up). If Mixpanel becomes aware that your entity may not meet one or more of the aforementioned eligibility criteria, Mixpanel may, at its sole discretion, work with you to transition the account to a paid account, suspend the account until additional information is provided to validate adherence to the eligibility criteria, or where sufficient evidence is present to indicate that your account does not meet the eligibility criteria, terminate your startup account, by providing written notice.

### \[Legacy] Credit-Based Program FAQ

If you are in the earlier version of the Mixpanel for Startups program which utilized “startup credits” and have specific questions regarding your account, please reach out to [startups@mixpanel.com](mailto:startups@mixpanel.com).

#### What is the credit-based startup program?

Prior to September 2024, the Mixpanel for Startups program provided eligible startups with their first year of Mixpanel free, valued up to \$50,000. Startups in this program are able to purchase an annual Growth plan as well as Group Analytics and Data Pipelines add-on packages utilizing credits.

After acceptance to the program, \$50,000 in credits were added to participants’ Mixpanel account and automatically applied to eligible line items when purchasing an annual [Growth plan](https://mixpanel.com/pricing/#edit-plan) via our plan-builder. The credits cover up to \$50,000 in total usage within the first year. Any additional usage costs in excess of \$50,000 are not covered by the program and will be charged to the credit card on file.

#### Is eligibility different for the credit-based startup program?

No. The startup program – be it the credit or Startup Plan version – have the same eligibility requirements ([outlined above](/docs/pricing/startup-program#eligibility-criteria)).

#### How do I know if I am in the credit-based startup program?

The credit-based startup program was valid prior to September 4, 2024. If you are currently in this version of the program, \$50,000 worth of credits were added to your account to apply to eligible purchases and upgrades made in your first year. You can see these credits in your Mixpanel account under Organization Settings > Plan Details & Billing.

The Manage Billing & Payment section displays detailed information about the credits that are used to cover your first year of Mixpanel. Eligible credits will also appear in the checkout process when purchasing a Growth plan and premium features through the online plan-builder.

#### Will the startup credits in my account expire?

Yes. The credit-based startup program provides your first year of Mixpanel for free, valued up to \$50,000. After one year, the unused credits expire and are no longer valid. You can see the expiration date in the Credits tab under Plan Details & Billing in the Organization Settings. Once the year elapses, the credits expire and the credit card on file will be charged to cover the subscription renewal and additional data costs.

#### Other questions about Mixpanel for Startups?

Please reach out to the team at [startups@mixpanel.com](mailto:startups@mixpanel.com).


# Privacy Overview
Source: https://docs.mixpanel.com/docs/privacy



Mixpanel believes in respecting and protecting people’s fundamental online privacy and data rights. This is why we've built Mixpanel's analysis tools in compliance with industry best practices and global data regulations like the GDPR and the CCPA.

Visit our [Privacy Hub](https://mixpanel.com/legal/privacy-hub/) to see how we comply with various privacy guidelines.

## Storing Your Data in the European Union

Mixpanel provides you with the option to process and store your customers' personal data in Europe via our [EU Data Residency Program](https://mixpanel.com/legal/eu-data-residency/). You can enable this by selecting the "EU Data Residency" option when creating a new project and using our EU subdomain during all API calls.

See [EU Data Residency](/docs/privacy/eu-residency) for detailed information on how to use EU Data Residency with Mixpanel.

## Storing Your Data in India

You may process and store your customers' personal data in India via our [India Data Residency Program](/docs/privacy/in-residency). Contact your Mixpanel account manager to learn more about enabling India Data Residency for your account.

See [India Data Residency](/docs/privacy/in-residency) for detailed information on how to use India Data Residency with Mixpanel.

## Manage Personal Data

[Mixpanel deletion and retrieval APIs](/reference/gdpr-api) are in place to help Mixpanel implementations meet the requirements outlined by the General Data Protection Regulation (GDPR) legislation.

<Note>
  **GDPR Request Rate Limits**

  You can batch up to 2000 distinct IDs per deletion request and up to 2000 for a retrieval request. Request rates are limited for GDPR API requests.
</Note>

### User Opt-Out

While the following API can be used to delete or retrieve personal data as outlined by the GDPR, it is important to also opt users out of subsequent tracking. If tracking using a client-side Mixpanel library, you can opt users out of tracking using Mixpanel's opt-out methods. These are available in the following client-side libraries:

* [JavaScript](/docs/tracking-methods/sdks/javascript#opting-users-out-of-tracking)
* [iOS - Objective-C](/docs/tracking-methods/sdks/ios#opting-users-out-of-tracking)
* [iOS - Swift](/docs/tracking-methods/sdks/swift#opting-users-out-of-tracking)
* [Android](/docs/tracking-methods/sdks/android#opting-users-out-of-tracking)

See Mixpanel’s [Managing Personal Information](/docs/privacy/protecting-user-data) guide for more information on best practices when handling personal information in Mixpanel.

### Authentication

Authentication occurs via a user-specific OAuth token with a scope that only includes the following deletion and retrieval APIs. Users can retrieve this token from their [Account Settings](https://mixpanel.com/settings/account#data-privacy) by selecting their initials in the top right of Mixpanel and selecting **Profile & Preferences**, and then the Data & Privacy tab. The OAuth token has a one-year expiry. It should be passed in the Authentication header. Users are eligible to generate an OAuth token if they are the [project owner](/docs/orgs-and-projects/roles-and-permissions#project-roles), or if they are a project owner or admin of a project that supports [team member roles](/docs/orgs-and-projects/roles-and-permissions#project-roles).

<Frame>
  <img alt="" />
</Frame>


# End User Data Management
Source: https://docs.mixpanel.com/docs/privacy/end-user-data-management

Making GDPR and CCPA requests

Mixpanel supports account holders’ ability to request the deletion or export of end user data.

Requests can be submitted through either a form found in a Mixpanel project or through a personal data export and deletion API that is documented below.

Only organization owners and admin can access or submit end user export or deletion requests.

These tools can be used to exercise Right to Access, Right to Portability, and Right to be Forgotten for end users or “data subjects” as part of the General Data Protection Regulation (GDPR). [Learn more about GDPR here](https://mixpanel.com/legal/mixpanel-gdpr/). These tools also can help satisfy requirements stated in the California Consumer Privacy Act (CCPA). [Learn more about CCPA here](https://mixpanel.com/legal/mixpanel-ccpa/).

Requests to export or delete end user data can take multiple weeks to process.

## Generate OAuth Token

In order to submit a request, you must first generate a GDPR OAuth token from your Personal Settings. This token is required for requests submitted both through the Mixpanel interface and through Mixpanel's APIs. Users can retrieve this token from their [Account Settings](https://mixpanel.com/settings/account#data-privacy) by selecting their initials in the top right of Mixpanel and selecting **Profile & Preferences**, and then the Data & Privacy tab. The OAuth token has a one year expiry. For requests submitted via API, the token should be passed in the Authentication header. Users are eligible to generate an OAuth token if they are the Project Owner, or if they are a Project Owner or Admin of a project that supports team member roles.

<Frame>
  <img alt="" />
</Frame>

## Gather the Project Information and Distinct\_ids

Mixpanel exports or deletes end user data according to the user's distinct\_id. To export or delete end user data, first select a project that you own and collect the distinct\_id of the user(s). Like all data in Mixpanel, the distinct\_id can be custom specified in a tracking implementation. As this is the case, it is necessary to ensure that any provided distinct\_id is accurate and stored in a project. Any incorrect identifiers submitted as part of export or deletion requests will result in inability to process the request.

It is possible to submit a request from Mixpanel once you gather the distinct\_ids of end users requesting exports or deletions. If you implemented Mixpanel before 2020 and are using the alias method to manage user identity, it is possible to submit either the end user’s alias or their distinct\_id as part of a deletion request. All data associated with a submitted alias will be deleted. In addition, all data associated with the distinct\_id(s) that the alias maps to will be deleted.

## Submit Requests via Request Form in Mixpanel

To access the "Data & Privacy" modal containing the end user data request form:

1. Navigate to "Data & Privacy" by clicking on the settings gear in the upper-right corner and navigating to Organization Settings.
2. Select Data & Privacy on the left hand side.

<Frame>
  <img alt="Data & Privacy" />
</Frame>

### Exporting User Data

You must submit an export request to export end user data. This is done to satisfy a GDPR right to access request from your users.

1. In the “Data and Privacy” section, click Request Export.
2. In the “Export User Data” box:

* Select the either CCPA or GDPR under type of export.
* Select a project in the "Project" dropdown.
* Under “User Data To Export”, select to export data for a single user or multiple users.

  * For a single user, provide the distinct\_id of the user.
  * For multiple users, upload a list of distinct\_ids as a .csv file. There is a limit of 2000 Users.

3. Click Submit Request. Note that requests can take multiple weeks to process.

<Frame>
  <img alt="Data & Privacy" />
</Frame>

### Deleting User Data

You must submit a deletion request to delete end user data. This is done to satisfy a GDPR right to erasure request from your users.

1. In the “Data and Privacy” section, click Request Deletion.
2. In the “Request User Data Deletion” box:

* Select the either CCPA or GDPR under type of export.
* Select a project in the "Project" dropdown.
* Select to delete data for a single user or multiple users.

  * For a single user, provide the distinct\_id of the user.
  * For multiple users, upload a list of distinct\_ids as a CSV file. There is a limit of 2000 users per request, which may be lower if your project uses Group Analytics.

3. Click Submit Request. Note that requests can take up to several weeks to process.

<Frame>
  <img alt="Data & Privacy" />
</Frame>

### GDPR Requests

GDPR requests are specifically designed to satisfy requirements as outlined in the General Data Protection Regulation.

**Export** A GDPR export contains all data connected to the requested distinct\_id.

**Deletion** A GDPR deletion includes all data connected to the requested distinct\_id.

### CCPA Requests

CCPA requests are specifically designed to satisfy requirements as outlined in the California Consumer Privacy Act.

**Export** A CCPA export contains all data from the previous year connected to the requested distinct\_id.

**Deletion** A CCPA deletion includes all data connected to the requested distinct\_id.

**Disclosure types** There are three different disclosure types as outlined in the CCPA. To export or delete everything, you can select “Data” as the disclosure type. Select “Categories” to export or delete the data table headers. Select “Sources” to export or delete data connected to the means of data collection.

## Opt Out Users

While the following API can be used to delete or retrieve personal data as outlined by the GDPR, it is important to also opt users out of subsequent tracking. Deleting data from Mixpanel will remove it permanently, but it will not prevent the data from being collected moving forward. If tracking using a client-side Mixpanel library, you can opt users out of tracking using Mixpanel's opt-out methods. These are available in the following client-side libraries:

* [JavaScript](/docs/tracking-methods/sdks/javascript#opting-users-out-of-tracking)
* [iOS - Objective-C](/docs/tracking-methods/sdks/ios#opting-users-out-of-tracking)
* [iOS - Swift](/docs/tracking-methods/sdks/swift#opting-users-out-of-tracking)
* [Android](/docs/tracking-methods/sdks/android#opting-users-out-of-tracking)

See Mixpanel’s [Privacy-Friendly Tracking](/docs/privacy/protecting-user-data#opting-users-out-of-tracking) guide for more information on best practices when handling personal information in Mixpanel.

## Submit Requests via API

Mixpanel deletion and retrieval APIs are in place to help Mixpanel implementations meet the requirements outlined by the General Data Protection Regulation (GDPR) legislation.

<Note>
  **GDPR Request Rate Limits**

  You can batch up to 2000 distinct IDs per deletion request and up to 2000 for a retrieval request. Request rates are limited for GDPR API requests.
</Note>

Please [see our GDPR API Reference](/reference/gdpr-api) to learn more about the deletion/retrieval endpoints.


# EU Residency
Source: https://docs.mixpanel.com/docs/privacy/eu-residency



## Overview

Mixpanel believes in respecting and protecting people’s fundamental online privacy and data rights, which is why we've built Mixpanel's analysis tools in compliance with industry best practices and global data regulations like the GDPR and the CCPA.

Visit our [Privacy Hub](https://mixpanel.com/legal/privacy-hub/) to see how we comply with various privacy guidelines.

## Storing Your Data in the European Union

By default, Mixpanel stores user data on its US Servers via the Google Cloud Platform. However, Mixpanel also provides you with the option to process and store your customers' personal data in Europe via our [EU Data Residency Program](https://mixpanel.com/legal/eu-data-residency). You can enable this by selecting the "EU Data Residency" option when creating a new project and using our EU subdomain during all API calls.

<Warning>
  Important: For new EU projects created on or after August 18, 2025, no data will be ingested into your new EU data residency project unless your SDK is sending data to the EU endpoint. Ensure you are using the EU endpoint in your SDK configuration. For EU Projects created before August 18, 2025, US-to-EU Data Forwarding ends July 2026, please ensure you are using the EU endpoint in your SDK configuration. See [changelog here](/changelogs#deprecation-notice-legacy-us-to-eu-data-forwarding-ends-july-2026-for-eu-projects).
</Warning>

For existing EU projects created prior to August 18, 2025, we encourage you to update your SDK configuration to use the dedicated EU endpoint. This is a best practice that ensures your project is correctly aligned with its data residency.

| API                                                        | Standard Server                    | EU Residency Server                   |
| ---------------------------------------------------------- | ---------------------------------- | ------------------------------------- |
| [Ingestion API](/reference/ingestion-api)                  | `api.mixpanel.com`                 | `api-eu.mixpanel.com`                 |
| [Query API](/reference/query-api)                          | `mixpanel.com/api`                 | `eu.mixpanel.com/api`                 |
| [Raw Data Export API](/reference/raw-data-export-api)      | `data.mixpanel.com/api/2.0/export` | `data-eu.mixpanel.com/api/2.0/export` |
| [Data Pipelines API](/reference/create-warehouse-pipeline) | `data.mixpanel.com/api/2.0/nessie` | `data-eu.mixpanel.com/api/2.0/nessie` |
| [Lexicon Schemas API](/reference/lexicon-schemas-api)      | `mixpanel.com/api/app/projects`    | `eu.mixpanel.com/api/app/projects`    |

You can find where your data is stored under Project Settings > Data Residency for existing projects. Additionally, projects stored in the EU will have a URL that starts with 'eu.mixpanel.com', whereas projects stored in the US will have a 'mixpanel.com' URL. If the wrong Data Residency location was chosen before implementation, you will need to create a new project with the applicable data storage option and migrate all your existing data. Mixpanel cannot assist with migrating an existing project with the wrong residency location. You can find out more about creating a new project [here](/docs/orgs-and-projects/managing-projects#creating-projects).

## Using Our SDKs

Next, you'll need to set the server location to EU when initializing the Mixpanel library. You can find instructions for the required config settings for each SDK below:

* [JavaScript](/docs/tracking-methods/sdks/javascript#eu-data-residency)
* [Objective-C](/docs/tracking-methods/sdks/ios#eu-data-residency)
* [Swift](/docs/tracking-methods/sdks/swift#eu-data-residency)
* [Android](/docs/tracking-methods/sdks/android#eu-data-residency)
* [Python](/docs/tracking-methods/sdks/python#eu-data-residency)
* [Java](/docs/tracking-methods/sdks/java#eu-data-residency)
* [Ruby](/docs/tracking-methods/sdks/ruby#eu-data-residency)
* [Node.js](/docs/tracking-methods/sdks/nodejs#eu-data-residency)
* [React Native](/docs/tracking-methods/sdks/react-native#eu-data-residency)
* [Flutter](/docs/tracking-methods/sdks/flutter#eu-data-residency)

## Log in via SSO

If you want the IdP-initiated flow to direct to [eu.mixpanel.com](https://eu.mixpanel.com/), prepend "eu." to your postback URL. For example, `mixpanel.com/security/login/1` would need to be changed to `eu.mixpanel.com/security/login/1`.

## EU Residency and CDPs

If you are coming to use Mixpanel from a Customer Data Platform (CDP), we cannot guarantee that data ingestion, processing, and storage will always stay within the EU region. Please work with your CDP to ensure they are sending your data to the EU endpoint.

The following diagram shows how Mixpanel's Data Residency works:

<Frame>
  <img alt="image" />
</Frame>


# GDPR Compliance
Source: https://docs.mixpanel.com/docs/privacy/gdpr-compliance



## Supporting Data Subject Rights

As controllers of personal data, Mixpanel and its customers must uphold certain rights stated by the GDPR, including:

## Right to Access and Data Portability

Mixpanel supports individuals’ right to access and right to portability of their personal data through individual export requests. Any Mixpanel account holder will be able to request an export of one’s personal data, as well as the personal data of their end-users. [The form for submitting end-user personal data export requests](/docs/privacy/end-user-data-management) and for submitting account holder data export requests is available through Personal Settings > Data & Privacy.

## Right to Erasure

We support individuals’ right to erasure through a permanent deletion of personal data upon request. [Deletion API](https://developer.mixpanel.com/docs/privacy-security#manage-personal-data) is available to all users.

## Right to Object

Our customers control what data is sent to Mixpanel, and may decide to halt the sending of personal data at any time. To assist with supporting individuals’ right to object to the collection of one’s personal data, Mixpanel also has built dedicated methods for our client-side SDKs that can be used to [opt end users out of tracking](/docs/privacy/protecting-user-data).

Mixpanel collects information about how customers use the product, and uses this data to identify product gaps and improve existing products. While this information is useful, Mixpanel recognizes the importance of an individual's right to object. Mixpanel has therefore streamlined opt-out systems for its customers, who can opt out of tracking through simple controls, located under Personal Settings > Data & Privacy.

## Data Retention Policy

As the processor of its customers’ data and to protect the privacy of information it stores, Mixpanel holds data no longer than is needed to provide its services. To further support this, Mixpanel has implemented the following data retention policy:

Section 1. Events are automatically deleted after 2\* years on an ongoing basis from all projects.

* The start of the retention period is the date that is transferred to Mixpanel with an Event (i.e., the “Event Date”), which typically corresponds to the date a user completed an action on a web or mobile application. In the event that an Event Date is not transferred to Mixpanel with an Event by our Customer, the Event Date is recorded as the date we received the Event.
* \*As of September 1, 2025, Mixpanel's event retention period is 2 years. If your project was created prior to September 1, 2025 the retention period is 5 years; provided, that your project retention period will be reduced to 2 years in the event that you modify your plan or move to Mixpanel's Free Plan.

Section 2. User data is retained for the duration of an active Subscription Plan. Customers are given the ability to delete profiles using the [Engage API](/reference/delete-profile).

* Custom data retention windows can be set for user data by sending regular deletion requests to the Engage API. For more questions about setting custom data retention windows, [contact our support team](https://mixpanel.com/get-support).

Section 3. Session Replays (i.e., all of the session data necessary for replaying user sessions in Mixpanel's user interface) are stored for 30 days from ingestion date.

* Custom retention periods for Session Replay are available to customers on certain plans for a period of up to 12 months. Please review Mixpanel's Session Replay Documentation for additional information regarding custom retention period. Changes to the retention period impact replays ingested after the change. Sessions captured and ingested before a retention period change retain the previous retention period.
* Underlying Events (e.g., for visualization in metrics, dashboards, etc.) will be retained for the period set out in Section 1 of this Policy.

This policy includes projects that were deleted or reset through the Project Settings - deleting a project through the Project Settings triggers a soft deletion. The data in the deleted or reset project will remain stored in Mixpanel for 60-90 days, after which it will be hard deleted and unrecoverable.

## Rate Limit

We place a [rate limit](/docs/privacy/end-user-data-management#rate-limit) in place to ensure the integrity of our system as well as prevent a single project from monopolizing the available resources for other projects


# India Data Residency
Source: https://docs.mixpanel.com/docs/privacy/in-residency



## Overview

Mixpanel believes in respecting and protecting people’s fundamental online privacy and data rights, which is why we've built Mixpanel's analysis tools in compliance with industry best practices and global data regulations like India's DPDPA.

Visit our [Privacy Hub](https://mixpanel.com/legal/privacy-hub/) to see how we comply with various privacy guidelines.

<Note>
  If you would like access to the India Data Center, reach out to your Mixpanel account manager or [contact us here](https://mixpanel.com/m/india-mixpanel-analytics-for-fintech/).
</Note>

## Storing Your Data in India

Mixpanel provides you with the option to process and store your customers' personal data in India via our India Data Residency Program. You can enable this by selecting the "India Data Residency" option when creating a new project and using our India subdomain during all API calls.

<Warning>
  No data will be ingested to your India data residency project unless your SDK is sending data to the India URL endpoint. Ensure you are using the India URL endpoint in your SDK configuration.
</Warning>

| API                                                        | Standard Server                    | India Residency Server                |
| ---------------------------------------------------------- | ---------------------------------- | ------------------------------------- |
| [Ingestion API](/reference/ingestion-api)                  | `api.mixpanel.com`                 | `api-in.mixpanel.com`                 |
| [Query API](/reference/query-api)                          | `mixpanel.com/api`                 | `in.mixpanel.com/api`                 |
| [Raw Data Export API](/reference/raw-data-export-api)      | `data.mixpanel.com/api/2.0/export` | `data-in.mixpanel.com/api/2.0/export` |
| [Data Pipelines API](/reference/create-warehouse-pipeline) | `data.mixpanel.com/api/2.0/nessie` | `data-in.mixpanel.com/api/2.0/nessie` |
| [Lexicon Schemas API](/reference/lexicon-schemas-api)      | `mixpanel.com/api/app/projects`    | `in.mixpanel.com/api/app/projects`    |

You can find where your data is stored under Project Settings > Data Residency for existing projects. Additionally, projects stored in the India will have a URL that starts with 'in.mixpanel.com', whereas projects stored in the US will have a 'mixpanel.com' URL. If the wrong Data Residency location was chosen before implementation, you will need to create a new project with the applicable data storage option and migrate all your existing data. Mixpanel cannot assist with migrating an existing project with the wrong residency location. You can find out more about creating a new project [here](/docs/orgs-and-projects/managing-projects#creating-projects).

## Using Our SDKs

Next, you'll need to set the server location to India when initializing the Mixpanel library. **This is required for all SDKs.** No data will be ingested to your India data residency project unless your SDK is sending data to the India endpoint. You can find instructions for the required config settings for each SDK below:

* [JavaScript](/docs/tracking-methods/sdks/javascript#india-data-residency)
* [Objective-C](/docs/tracking-methods/sdks/ios#india-data-residency)
* [Swift](/docs/tracking-methods/sdks/swift#india-data-residency)
* [Android](/docs/tracking-methods/sdks/android#india-data-residency)
* [Python](/docs/tracking-methods/sdks/python#india-data-residency)
* [Java](/docs/tracking-methods/sdks/java#india-data-residency)
* [Ruby](/docs/tracking-methods/sdks/ruby#india-data-residency)
* [Node.js](/docs/tracking-methods/sdks/nodejs#india-data-residency)
* [React Native](/docs/tracking-methods/sdks/react-native#india-data-residency)
* [Flutter](/docs/tracking-methods/sdks/flutter#india-data-residency)

## Log in via SSO

If you want the IdP initiated flow to direct to [in.mixpanel.com](https://in.mixpanel.com/), prepend the "in." subdomain to your postback URL. For example, `mixpanel.com/security/login/1` would need to be changed to `in.mixpanel.com/security/login/1`.

## India Residency and Customer Data Platforms (CDPs)

If you are coming to use Mixpanel from a CDP, please work with your CDP to ensure they are sending your data to the India endpoint. No data will be ingested to your India data residency project unless your CDP is sending data to the India endpoint.


# Protecting User Data
Source: https://docs.mixpanel.com/docs/privacy/protecting-user-data

Opting users out of tracking and anonymizing data

## Overview

Mixpanel gives you full control over the data you send to Mixpanel and provides you with the tools necessary to respect a customer's request to opt out of tracking. When a user is opted out, no data is sent to Mixpanel for that user, meaning their events won't be tracked or available in Mixpanel. Here, we share best practices for tracking in a privacy-friendly way.

## Opting Users Out of Tracking

Mixpanel's client-side libraries include an 'opt\_out' method that allows you to manage a user's request to opt out of tracking. This allows you to quickly flag a user when they choose to opt out of tracking during the cookie consent management process.

The client-side 'opt\_out' method sets a flag in the user's browser cookie or local storage, preventing data from being sent to Mixpanel. The opt-out state persists across sessions, meaning that if a user has opted out, they will remain opted out even if they close and reopen the app or website, unless the cookie/local storage is cleared or they explicitly opt back in.

For mobile SDKs, when the 'opt\_out' method is called, any events and people updates that have not been sent to Mixpanel (i.e., those still in the local queue) are deleted from the device. This ensures that even data collected just before opting out, like App Open events, does not get sent to Mixpanel.

Once opted out, the Mixpanel SDKs will continue to function normally, but will not send any data to the Mixpanel project. This means that calls to tracking methods, like track or identify, will essentially be ignored for the opted-out user.

The client-side 'opt out' call will not affect server-side events. For server-side implementations, you need to manage the opt-out process manually. The server is responsible for generating IDs, maintaining ID persistence, and managing the opt-out state of users.

<CodeGroup>
  ```javascript Javascript theme={"system"}
  mixpanel.opt_out_tracking();
  ```

  ```objc Objective-C theme={"system"}
  Mixpanel *mixpanel = [Mixpanel sharedInstance];\n[mixpanel optOutTracking];
  ```

  ```swift Swift theme={"system"}
  Mixpanel.mainInstance().optOutTracking();
  ```

  ```java Android theme={"system"}
  mixpanel.optOutTracking();
  ```

  ```javascript React Native theme={"system"}
  mixpanel.optOutTracking();
  ```
</CodeGroup>

You can also configure our SDKs to opt users out of tracking by default:

<CodeGroup>
  ```javascript Javascript theme={"system"}
  mixpanel.init(YOUR TOKEN, {opt_out_tracking_by_default: true});
  ```

  ```objc Objective-C theme={"system"}
  Mixpanel *mixpanel = [Mixpanel sharedInstanceWithToken:@YOUR_API_TOKEN trackAutomaticEvents:NO optOutTrackingByDefault:YES];
  ```

  ```swift Swift theme={"system"}
  let mixpanel = Mixpanel.initialize(token: YOUR PROJECT TOKEN, trackAutomaticEvents: no, optOutTrackingByDefault: true)
  ```

  ```java Android theme={"system"}
  MixpanelAPI mixpanelOptOutDefault = MixpanelAPI.getInstance(context, YOUR PROJECT TOKEN, true, true /* opt out by default */);
  ```

  ```javascript React Native theme={"system"}
  const trackAutomaticEvents = false;
  const optOutTrackingDefault = true;
  const mixpanel = new Mixpanel('your project token', trackAutomaticEvents, optOutTrackingDefault);
  mixpanel.init();
  ```
</CodeGroup>

## Opting Users In For Tracking

The 'Opt In' methods in used to allow users to opt into tracking after they have been previously opted out or when the SDK is initialized with users opted out by default.

When the Opt In method is called, it triggers an event called "\$opt\_in", which appears as "Opt In" in your project. This event is sent to Mixpanel to indicate that the user has opted into tracking. Locally, a flag is set in the user's cookie/local storage to indicate to the SDK that the user consents to data tracking.

After calling the 'Opt In' method, Mixpanel will start collecting and sending data for that user. This includes events, user properties, and other tracking information.

<CodeGroup>
  ```javascript Javascript theme={"system"}
  mixpanel.opt_in_tracking();
  ```

  ```objc Objective-C theme={"system"}
  Mixpanel *mixpanel = [Mixpanel sharedInstance];\n[mixpanel optOutTracking];
  ```

  ```swift Swift theme={"system"}
  Mixpanel.mainInstance().optInTracking();
  ```

  ```java Android theme={"system"}
  mixpanel.optInTracking();
  ```

  ```javascript React Native theme={"system"}
  mixpanel.optInTracking();
  ```
</CodeGroup>

## Disabling Geolocation

Mixpanel's Web and Mobile libraries use IP addresses to enrich events with geographic information like city, country, and region. Mixpanel does not store IP addresses, but rather, only uses IPs to assign [geolocation properties to data upon ingestion](/docs/tracking-best-practices/geolocation). You can disable this using the following configuration options in each of our SDKs:

<CodeGroup>
  ```javascript Javascript theme={"system"}
  mixpanel.init("YOUR_TOKEN", {"ip": false})
  ```

  ```objectivec Objective-C theme={"system"}
  useIPAddressForGeoLocation = NO
  ```

  ```swift Swift theme={"system"}
  Mixpanel.initialize(token: "MIXPANEL_TOKEN", useIPAddressForGeoLocation: false)
  ```

  ```xml Android theme={"system"}
  <meta-data android:name="com.mixpanel.android.MPConfig.UseIpAddressForGeolocation" android:value="false" />
  ```

  ```javascript React Native theme={"system"}
  setUseIpAddressForGeolocation(false)
  ```
</CodeGroup>

You can also disable geolocation for individual payloads by setting the `ip` property value to 0. Learn more about ignoring IP addresses [here](/docs/tracking-best-practices/geolocation#ignore-ip-address).

## Anonymizing Users

Mixpanel does not know, or need to know, any identifying information about users (like email or phone number). Mixpanel only needs to know that a set of events was performed by a particular user ID. You choose the ID and how you want to send that to Mixpanel.

If you want to analyze aggregate user behavior without being able to drill down into any particular user, we recommend generating a hash of some unique ID of the user and using that hash as the user's ID when you call the `.identify()` method in our SDKs.

## Blacklisting Default Properties

Our JavaScript library [automatically captures default properties](/docs/data-structure/property-reference/default-properties) to help enrich your data, but you can choose to prevent the setting of default properties using the property\_blacklist config option. To prevent default event properties from being sent, specify a list of properties to blacklist on library load, for example:

```javascript Javascript theme={"system"}
mixpanel.init("YOUR_TOKEN", {
  property_blacklist: ['$referrer', 'custom_property']
});
```

## FAQ

**Is opting users out of tracking compliant with privacy regulations like GDPR?**

While Mixpanel provides tools to help our customers remain compliant with privacy regulations (such as methods for opting users in and out of tracking), it is the responsibility of the implementing company to ensure compliance with privacy regulations. Typically, organizations must obtain explicit consent from individuals before collecting, using, or sharing their personal data.

For GDPR purposes, Mixpanel is considered the data processor, whereas you (the customer) are considered the data controller. Your end user's data is your responsibility.

**Can users request a copy of their data?**

Yes, Mixpanel provides tools for handling user data requests. However, it is important to note that Mixpanel doesn't handle end-users' requests directly. The company implementing Mixpanel is responsible for using Mixpanel's tools to fetch the data and provide it to its end-users. Learn more about our [GDPR Data Retrieval API Endpoint](/reference/create-retrieval-1).

**What happens to previously collected data when a user opts out?**

When a user is opted out of tracking, no subsequent data moving forward is sent to Mixpanel for that user. This means that future events won't be tracked or available in Mixpanel. However, data previously collected will remain in your project until the data retention period has passed, a data deletion is performed for that user's data, or a GDPR deletion is requested and performed. Learn more about [Data Deletion](/docs/data-governance/data-clean-up#2-deleting-problematic-data) and [GDPR Deletion requests](/docs/privacy/end-user-data-management).


# Quickstart
Source: https://docs.mixpanel.com/docs/quickstart



<CardGroup>
  <Card title="Install Mixpanel" href="/docs/quickstart/install-mixpanel" />

  <Card title="Identify Users" href="/docs/quickstart/identify-users" />

  <Card title="Capture Events" href="/docs/quickstart/track-events" />
</CardGroup>

### Install Mixpanel with your coding agent

The Mixpanel Implementation Skill guides your AI coding agent — Claude Code, Cursor, ChatGPT, or any other assistant — through setting up Mixpanel in your codebase. The skill handles SDK selection, identity management, event tracking, and compliance gates through a guided conversation, with paths ranging from a one-session Quick Start to a full production-ready rollout.

<div>
  <br />

  <ExtendedButton title="Get Started with AI" />
</div>


# Capture Events
Source: https://docs.mixpanel.com/docs/quickstart/capture-events



<CardGroup>
  <Card title="Autocapture" href="/docs/quickstart/capture-events/autocapture" />

  <Card title="Track Events" href="/docs/quickstart/capture-events/track-events" />
</CardGroup>


# Autocapture
Source: https://docs.mixpanel.com/docs/quickstart/capture-events/autocapture



Starting with SDK version 2.60.0, the Javascript SDK can autocapture events when you enable it. To do so, enable the autocapture configuration:

```javascript theme={"system"}
// create an instance of the Mixpanel object
mixpanel.init('YOUR_PROJECT_TOKEN', {
    autocapture: true,    // enable autocapture
});
```

If you'd like to change the default Autocapture settings, you can use custom configs. These are the default configs:

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
  autocapture: {
    pageview: "full-url",
    click: true,    
    input: true,
    rage_click: true,
    dead_click: true,
    scroll: true,
    submit: true,
    capture_text_content: false,
  },
});
```

[You can read more about custom configuration of Autocapture here](/docs/tracking-methods/sdks/javascript).


# Track Events
Source: https://docs.mixpanel.com/docs/quickstart/capture-events/track-events



## Overview

This step introduces the `track` method, which allows you to see how your users are using your product.

Use the track method to track events on behalf of your users. Add this code snippet to basic events like "Sign Up" and any additional events that may track the core features of your product.

## Code

Replace `Sign Up` with a unique identifier for the event. Passing additional information is possible using the properties object.

<Tabs>
  <Tab title="Javascript">
    ```js Javascript theme={"system"}
    mixpanel.track('Sign Up', {
      'Signup Type': 'Referral'
    })
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events).

    **More resources:** \_ Video: [Debug Common Issues When Installing Mixpanel on Web](https://www.loom.com/share/fbba03274dc441b49b578e8a734b1d99). \_ Docs: [Read the Full Javascript SDK Docs](/docs/tracking-methods/sdks/javascript/) \* Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="Python">
    ```python Python theme={"system"}
    # Note: you must supply the USER_ID
    mp.track('USER_ID', 'Sign Up',  {
      'Signup Type': 'Referral'
    })
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events).

    **More resources:** \_ Docs: [Read the Python SDK Doc](/docs/tracking-methods/sdks/python/) \_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="PHP">
    ```shell php theme={"system"}
    $mp->track("button clicked", array("label" => "sign-up"));
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events).

    **More resources:** \_ Docs: [Read the Python SDK Doc](/docs/tracking-methods/sdks/php/) \_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="Node">
    ```js Node.js theme={"system"}
    // Note: you must supply the USER_ID
    mixpanel.track("Sign Up", {
      distinct_id: "USER_ID",
      "Signup Type": "Referral",
    });
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events).

    **More resources:** \_ Docs: [Read the Node.js SDK Doc](/docs/tracking-methods/sdks/nodejs/) \_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="Go">
    ```go Go theme={"system"}
    exampleEvent = mp.NewEvent("Sign Up", "USER_ID", map[string]any{
        "Signup Type": "Referral",
    })

    err := mp.Track(ctx,
    []\*mp.PeopleProperties{
    exampleUser,
    },
    )
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events).

    **More resources:**

    * Docs: [Read the Go SDK Doc](/docs/tracking-methods/sdks/go/)
    * Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="Ruby">
    ```ruby Ruby theme={"system"}
    # Note: you must supply the USER_ID
    mp.track('USER_ID', 'Sign Up', {
      'Signup Type' => 'Referral'
    })
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events).

    **More resources:** \_ Docs: [Read the Ruby SDK Doc](/docs/tracking-methods/sdks/ruby/) \_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="Java">
    ```java Java theme={"system"}
    import com.mixpanel.mixpanelapi.ClientDelivery;

    // You can send properties along with events
    JSONObject props = new JSONObject();
    props.put("Signup Type", "Referral");

    // Create an event
    JSONObject sentEvent = messageBuilder.event(userId, "Sign Up", props);

    ClientDelivery delivery = new ClientDelivery();
    delivery.addMessage(sentEvent);

    // Send the update to mixpanel
    MixpanelAPI mixpanel = new MixpanelAPI();
    mixpanel.deliver(delivery);
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events).

    **More resources:**

    * Docs: [Read the Java SDK Doc](/docs/tracking-methods/sdks/java/)
    * Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="React Native">
    ```javascript theme={"system"}
    mixpanel.track("Sign Up", {
      "Signup Type": "Referral"
    })
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page.

    **More resources:** \_ Docs: [Read the React Native SDK Doc](/docs/tracking-methods/sdks/react-native/) \_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="Flutter">
    ```java theme={"system"}
    mixpanel.track('Sign Up', {
      'Signup Type': 'Referral'
    });
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page.

    **More resources:**

    * Docs: [Read the Flutter SDK Docs](/docs/tracking-methods/sdks/flutter/)
    * Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="iOS (Objective-C)">
    ```objc theme={"system"}
    [mixpanel track:@"Signed Up" properties:
        @{ @"Signup Type": @"Referral" }
    ];
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page.

    **More resources:**

    * Docs: [Read the iOS (Objective-C) SDK Doc](/docs/tracking-methods/sdks/ios/)
    * Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="iOS (Swift)">
    ```swift theme={"system"}
    Mixpanel.mainInstance().track(event:"Sign Up", properties: [
        "Signup Type": "Referral",
    ])
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page.

    **More resources:** \_ Docs: [Read the iOS (Swift) SDK Doc](/docs/tracking-methods/sdks/swift/) \_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="Android">
    ```java theme={"system"}
    JSONObject props = new JSONObject();
    props.put("Signup Type", "Referral");
    mp.track("Signed Up", props);
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page.

    **More resources:** \_ Docs: [Read the Android SDK Doc](/docs/tracking-methods/sdks/android/) \_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="Unity">
    ```csharp theme={"system"}
    var props = new Value();
    props["Signup Type"] =  "Referral";
    Mixpanel.Track('Sign up', props);
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page.

    **More resources:** \_ Docs: [Read the Unity SDK Doc](/docs/tracking-methods/sdks/unity/) \_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel)
  </Tab>

  <Tab title="HTTP API">
    If you don't see an SDK or an integration in your language, you can send events to our API directly.

    Here's a sample script. Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```python test.py theme={"system"}
    # Fill this out
    import json
    import time
    import requests

    events = [
        {"event": "my_test_event", "properties": {"time": int(time.time()), "distinct_id": "test_user_1", "$insert_id": "04ce0cf4-a633-4371-b665-9b45317b4976", "city": "San Francisco"}},
        {"event": "another_event", "properties": {"time": int(time.time()), "distinct_id": "test_user_2", "$insert_id": "3b033b9a-6bc9-4b70-90c3-a53e11f6896e", "city": "Seattle"}}
    ]
    resp = requests.post(
        "https://api.mixpanel.com/import",
        params={"strict": "1"},
        auth=("YOUR_TOKEN", ""),
        headers={"Content-Type": "application/json"},
        data=json.dumps(events)
    )

    print(resp.json())
    ```

    🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page.

    See our [API reference](/reference/import-events) for more details.

    **Best Practices for Scale**

    You can use this API at scale, for example to backfill historical data into Mixpanel or as part of a high-throughput streaming pipeline. We provide walkthroughs for [Amazon S3](/docs/data-pipelines/old-pipelines/integrations/schematized-aws-pipeline) and [Google Cloud Storage](/docs/data-pipelines/old-pipelines/integrations/schematized-gcs-pipeline) to provide a more production-grade example of how to use this API at scale.

    Here are some other best practices:

    * Be explicit about what is tracked to Mixpanel rather than implicitly tracking everything, both for performance and security reasons. Avoid sending user generated content, high-cardinality IDs, or large semi-structured objects.
    * Import a more recent time window first (last 7 days or last 30 days) before backfilling historical data. Mixpanel's autocomplete menus populate events and properties based on the last 30 days of data, so this is the best way to test that data looks as expected.
    * Leverage batching and compression. Each request to /import can send 2000 events to Mixpanel and can be sent compressed using gzip. The sample code in this guide does both.
    * When using Cloud Storage, partition files into \~200MB of JSON (or \~200K records) each. Each file is processed in parallel by Cloud Functions/Lambda and must be ingested by the function within the configured timeout.
    * Log any 400 errors returned by the API. These are non-retryable and indicate something malformed with the data. This should be extremely unlikely once the API is up and running. If a batch contains a mix of valid and invalid data, we will ingest the valid data.

    **Limits**

    Our Import API is built to ingest billions of events per day across our customers. That said, we do rate limit at very high scale to ensure quality of service and real-time ingestion. Please refer to our [Import API docs](/reference/import-events) for details.

    All of our sample code transparently retries and backoff from rate limit exceptions. If you require a higher-limit for a 1-time backfill, please reach out to us at [apis@mixpanel.com](mailto:apis@mixpanel.com).
  </Tab>
</Tabs>

<hr />

<div>
  <div>
    <h2>
      You're Ready to Start Using Mixpanel
    </h2>

    <p>
      It's time to create your first [report](/docs/reports) or use one
      of our [many templates](/docs/boards/templates).
    </p>

    <br />

    <ExtendedButton title="Open Mixpanel" />
  </div>
</div>

## FAQ

<AccordionGroup>
  <Accordion title="Does Mixpanel automatically track page views?">
    Yes, if you pass `track_pageview: true` in the `mixpanel.init()` call, Mixpanel will automatically track a "Page View" event every time a new page is loaded. Learn more [here](/docs/tracking-methods/sdks/javascript#tracking-page-views).
  </Accordion>

  <Accordion title="Why aren't my events showing up?">
    If tracking from the web, make sure you've disabled ad blockers and your Do Not Track (DNT) browser settings are set to false when testing your JavaScript implementation. If the DNT setting is set to true, then Mixpanel won't collect information from that Mixpanel instance. We also recommend [setting up a proxy server](/docs/tracking-methods/sdks/javascript#tracking-via-proxy) so that you don't lose events due to ad-blockers.

    If tracking from a mobile device, events may take 1-2 minutes to appear because Mixpanel's mobile SDKs buffer events for 1 minute, or when the app transitions to the background, to conserve battery life and bandwidth. You can call `.flush()` in the mobile SDKs to manually flush events to Mixpanel.
  </Accordion>
</AccordionGroup>


# Identify Users
Source: https://docs.mixpanel.com/docs/quickstart/identify-users



## Overview

This step introduces the `identify` method, which allows you to see which users triggered each event in Mixpanel.

It also introduces the `people.set` method, which allows you to define the attributes of each user.

## Code

Replace `USER_ID` with a unique identifier, preferably the user ID from your database.

Including the user's email is also suggested, along with any additional **User Properties** such as name, avatar, created date, etc.

<Tabs>
  <Tab title="Javascript">
    ```js Javascript theme={"system"}
    mixpanel.identify('USER_ID')

    mixpanel.people.set({ '$name': 'Jane Doe',
                          '$email': 'jane.doe@example.com',
    'plan' : 'Premium'
    // Add anything else about the user here
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    mp.people_set('USER_ID', {'$name'  : 'Jane Doe',
                              '$email' : 'jane.doe@example.com',
                              'plan' : 'Premium'
                              # Add anything else about the user here
    })
    ```

    You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices)
  </Tab>

  <Tab title="PHP">
    ```shell php theme={"system"}
    // create/update a profile for user id 12345
    $mp->people->set('USER_ID', array(
        '$name'             => "John Doe",
        '$email'            => "john.doe@example.com",
        '$phone'            => "5555555555",
        "Favorite Color"    => "red"
    ));
    ```

    You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices)
  </Tab>

  <Tab title="Node">
    ```javascript theme={"system"}
    mixpanel.people.set('USER_ID', {
        $name: 'Jane Doe',
        $email: 'jane.doe@example.com',
        plan: 'premium'
        // Add anything else about the user here
    });
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={"system"}
    exampleUser := mp.NewPeopleProperties("USER_ID", map[string]any{
      "$name": "Jane Doe",
      "$email": "jane.doe@example.com",
      "plan": "Premium"
      // Add anything else about the user here
    })

    err := mp.PeopleSet(ctx, []\*mixpanel.PeopleProperties{
    exampleUser,
    },
    )
    ```

    You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices)
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={"system"}
    mp.people.set('USER_ID', {
        '$name' => 'Jane Doe',
        '$email' => 'jane.doe@example.com',
        'plan' => 'Premium'
        # Add anything else about the user here
    });
    ```

    You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices)
  </Tab>

  <Tab title="Java">
    ```java theme={"system"}
    JSONObject props = new JSONObject();
    props.put("$name", "Jane Doe");
    props.put("$email", "jane.doe@example.com");
    props.put("plan", "Premium");
    JSONObject update = messageBuilder.set("USER_ID", props);

    // Send the update to mixpanel
    mixpanel.sendMessage(update);
    ```
  </Tab>

  <Tab title="React Native">
    ```javascript Javascript theme={"system"}
    mixpanel.identify("USER_ID");

    // Identify must be called before properties are set
    mixpanel.getPeople().set("$name", "Jane Doe");
    mixpanel.getPeople().set("$email", "jane.doe@example.com");
    mixpanel.getPeople().set("plan", "Premium");
    ```

    You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices)
  </Tab>

  <Tab title="Flutter">
    ```java theme={"system"}
    mixpanel.identify("USER_ID");

    // Identify must be called before properties are set
    mixpanel.getPeople().set("$name", "Jane Doe");
    mixpanel.getPeople().set("$email", "jane.doe@example.com");
    mixpanel.getPeople().set("plan", "Premium");
    ```
  </Tab>

  <Tab title="iOS (Objective-C)">
    ```objc Objective-C theme={"system"}
    [mixpanel identify:@"USER_ID"];

    [mixpanel.people set:@{@"$name": @"Jane Doe"}];
    [mixpanel.people set:@{@"$email": @"jane.deo@example.com"}];
    [mixpanel.people set:@{@"plan": @"Premium"}];
    ```
  </Tab>

  <Tab title="iOS (Swift)">
    ```swift Swift theme={"system"}
    Mixpanel.mainInstance().identify(distinctId: "USER_ID")

    Mixpanel.mainInstance().people.set(properties: [ "$name":"Jane Doe",
    "$email":"jane.doe@example.com",
    "$plan":"Premium"])
    ```
  </Tab>

  <Tab title="Android">
    ```java Java theme={"system"}
    // The second param is a flag for allowing profile updates
    mp.identify("USER_ID", true);

    // Identify must be called before properties are set
    mp.getPeople().set("$name", "Jane Doe");
    mp.getPeople().set("$email", "jane.doe@example.com");
    mp.getPeople().set("plan", "Premium");
    ```
  </Tab>

  <Tab title="Unity">
    ```csharp theme={"system"}
    Mixpanel.Identify("USER_ID");

    // Identify must be called before properties are set
    Mixpanel.People.Set("$name", "Jane Doe");
    Mixpanel.People.Set("$email", "jane.doe@example.com");
    Mixpanel.People.Set("plan", "Premium");
    ```
  </Tab>

  <Tab title="HTTP API">
    If you don't see an SDK or an integration in your language, you can send events to our API directly.

    Here's a sample script. Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```python test.py theme={"system"}
    import requests

    url = "https://api.mixpanel.com/engage#profile-set"

    payload = [
        {
            "$token": "YOUR_TOKEN",
            "$distinct_id": "USER_ID",
            "$set": {
                "$name": "Jane Doe",
                "$email": "jane.doe@example.com",
                "plan": "Premium"
            }
        }
    ]
    headers = {
        "accept": "text/plain",
        "content-type": "application/json"
    }

    response = requests.post(url, json=payload, headers=headers)

    print(response.text)
    ```

    **Best Practices for Scale**

    You can use this API at scale, for example to backfill historical data into Mixpanel or as part of a high-throughput streaming pipeline. We provide walkthroughs for [Amazon S3](/docs/data-pipelines/old-pipelines/integrations/schematized-aws-pipeline) and [Google Cloud Storage](/docs/data-pipelines/old-pipelines/integrations/schematized-gcs-pipeline) to provide a more production-grade example of how to use this API at scale.

    Here are some other best practices:

    * Be explicit about what is tracked to Mixpanel rather than implicitly tracking everything, both for performance and security reasons. Avoid sending user generated content, high-cardinality IDs, or large semi-structured objects.
    * Import a more recent time window first (last 7 days or last 30 days) before backfilling historical data. Mixpanel's autocomplete menus populate events and properties based on the last 30 days of data, so this is the best way to test that data looks as expected.
    * Leverage batching and compression. Each request to /import can send 2000 events to Mixpanel and can be sent compressed using gzip. The sample code in this guide does both.
    * When using Cloud Storage, partition files into \~200MB of JSON (or \~200K records) each. Each file is processed in parallel by Cloud Functions/Lambda and must be ingested by the function within the configured timeout.
    * Log any 400 errors returned by the API. These are non-retryable and indicate something malformed with the data. This should be extremely unlikely once the API is up and running. If a batch contains a mix of valid and invalid data, we will ingest the valid data.

    **Limits**

    Our Import API is built to ingest billions of events per day across our customers. That said, we do rate limit at very high scale to ensure quality of service and real-time ingestion. Please refer to our [Import API docs](/reference/import-events) for details.

    All of our sample code transparently retries and backoff from rate limit exceptions. If you require a higher-limit for a 1-time backfill, please reach out to us at [apis@mixpanel.com](mailto:apis@mixpanel.com).
  </Tab>
</Tabs>

🎉 Congratulations, you've tracked your first user! You can see them in Mixpanel via the [Users page](https://mixpanel.com/report/users).

<hr />

<div>
  <div>
    <h2>
      Next: Track Events
    </h2>

    <p>
      Once you've implemented `identify`, it's time to track what your users are
      doing in your product.
    </p>

    <br />

    <ExtendedButton title="Track Events in Your Product" />
  </div>
</div>

## FAQ

<AccordionGroup>
  <Accordion title="How do I connect events from logged-out to logged-in users?">
    If tracking client-side, just call `.identify(<user_id>)` when a user logs in and `.reset()` when they log out. Mixpanel will automatically stitch the user journey across logged out and logged in.

    If tracking server-side, check out our [server-side best practices guide](/docs/best-practices/server-side-best-practices). For more information, read our comprehensive guide on [Identifying Users](/docs/tracking-methods/id-management/identifying-users).
  </Accordion>

  <Accordion title="What does Mixpanel track automatically?">
    Mixpanel's Data Ingestion APIs and Client-Side SDKs automatically collect certain properties on every event or user profile update. Examples include: location, operating system, device, etc. Mixpanel calls this auto-generated data "Default Properties".

    [Learn More About Default Properties](/docs/data-structure/property-reference#default-properties)
  </Accordion>

  <Accordion title="How can I track in a privacy compliant way?">
    If a user opts out of tracking, you can call the `.optOutTracking()` method on any of our client-side SDKs; this prevents any subsequent data being tracked from that user's device. Learn more [here](/docs/privacy/protecting-user-data).

    For iOS specifically: Mixpanel does not use IDFA, so it does not require user permission through the AppTrackingTransparency(ATT) framework. For more details, refer to our [Apple App Developer Privacy Guidance](https://mixpanel.com/legal/app-store-privacy-details).
  </Accordion>
</AccordionGroup>


# Install Mixpanel
Source: https://docs.mixpanel.com/docs/quickstart/install-mixpanel



## Overview

Installing Mixpanel is easy. This guide will show you how to do it with our SDKs.

Already collect product data? Connect your [**Data Warehouse**](/docs/tracking-methods/warehouse-connectors) or via [**3rd Party Integrations**](/docs/tracking-methods/integrations/).

## Code

Choose from the methods below. Not sure how to choose? [Read our guide](/docs/tracking-methods/choosing-the-right-method).

<Tabs>
  <Tab title="Javascript">
    ##### Install the SDK

    <Tabs>
      <Tab title="snippet">
        ```html theme={"system"}
        <!-- Paste this right before your closing </head> tag -->
        <script type="text/javascript">
          (function (f, b) { if (!b.__SV) { var e, g, i, h; window.mixpanel = b; b._i = []; b.init = function (e, f, c) { function g(a, d) { var b = d.split("."); 2 == b.length && ((a = a[b[0]]), (d = b[1])); a[d] = function () { a.push([d].concat(Array.prototype.slice.call(arguments, 0))); }; } var a = b; "undefined" !== typeof c ? (a = b[c] = []) : (c = "mixpanel"); a.people = a.people || []; a.toString = function (a) { var d = "mixpanel"; "mixpanel" !== c && (d += "." + c); a || (d += " (stub)"); return d; }; a.people.toString = function () { return a.toString(1) + ".people (stub)"; }; i = "disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking start_batch_senders people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split( " "); for (h = 0; h < i.length; h++) g(a, i[h]); var j = "set set_once union unset remove delete".split(" "); a.get_group = function () { function b(c) { d[c] = function () { call2_args = arguments; call2 = [c].concat(Array.prototype.slice.call(call2_args, 0)); a.push([e, call2]); }; } for ( var d = {}, e = ["get_group"].concat( Array.prototype.slice.call(arguments, 0)), c = 0; c < j.length; c++) b(j[c]); return d; }; b._i.push([e, f, c]); }; b.__SV = 1.2; e = f.createElement("script"); e.type = "text/javascript"; e.async = !0; e.src = "undefined" !== typeof MIXPANEL_CUSTOM_LIB_URL ? MIXPANEL_CUSTOM_LIB_URL : "file:" === f.location.protocol && "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\/\//) ? "https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js" : "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"; g = f.getElementsByTagName("script")[0]; g.parentNode.insertBefore(e, g); } })(document, window.mixpanel || []);
        </script>
        ```
      </Tab>

      <Tab title="npm">
        ```text theme={"system"}
        npm install --save mixpanel-browser
        ```
      </Tab>

      <Tab title="yarn">
        ```text theme={"system"}
        yarn add mixpanel-browser
        ```
      </Tab>
    </Tabs>

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    You can learn more about configuring Session Replay and Heatmaps [here](/docs/tracking-methods/sdks/javascript/javascript-replay).

    ```js Javascript theme={"system"}
    //Import Mixpanel SDK (only required for npm and yarn)
    import mixpanel from "mixpanel-browser";

    // Near entry of your product, init Mixpanel
    mixpanel.init("YOUR_TOKEN", {
      debug: true,
      track_pageview: true,
      persistence: "localStorage",
      record_sessions_percent: 100, //records 100% of all sessions
      record_heatmap_data: true,
    });
    ```
  </Tab>

  <Tab title="Python">
    ##### Install the SDK

    ```shell Python theme={"system"}
    pip install mixpanel
    ```

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```python Python theme={"system"}
    from mixpanel import Mixpanel

    mp = Mixpanel("YOUR_TOKEN")
    ```
  </Tab>

  <Tab title="PHP">
    ##### Install the SDK

    **Install with Composer**

    1. Add mixpanel/mixpanel-php as a dependency and run composer update:

    ```shell php theme={"system"}
    "require": {
        ...
        "mixpanel/mixpanel-php" : "2.*"
        ...
    }
    ```

    **Install Manually**

    1. [Download the Mixpanel PHP Library](https://github.com/mixpanel/mixpanel-php/archive/master.zip)
    2. Extract the zip file to a directory called "mixpanel-php" in your project root

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```shell php theme={"system"}
    <?php
    // import Mixpanel
    require 'mixpanel-php/lib/Mixpanel.php';

    // get the Mixpanel class instance, replace with your project token
    $mp = Mixpanel::getInstance("YOUR_TOKEN");

    ?>
    ```
  </Tab>

  <Tab title="Node">
    ##### Install the SDK

    ```shell Node.js theme={"system"}
    npm install mixpanel
    ```

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```js Node.js theme={"system"}
    // Grab the Mixpanel factory
    var Mixpanel = require("mixpanel");

    // Create an instance of the mixpanel client
    var mixpanel = Mixpanel.init("YOUR_TOKEN");
    ```
  </Tab>

  <Tab title="Go">
    ##### Install the SDK

    ```shell Go theme={"system"}
    go get github.com/mixpanel/mixpanel-go
    ```

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```shell Go theme={"system"}
    package main

    import (
    	"context"
    	"github.com/mixpanel/mixpanel-go"
    )

    func main() {
    ctx := context.Background()
    mp := mixpanel.NewApiClient("YOUR_TOKEN")
    }
    ```
  </Tab>

  <Tab title="Ruby">
    ##### Install the SDK

    ```shell Ruby theme={"system"}
    gem install mixpanel-ruby
    ```

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```ruby Ruby theme={"system"}
    require 'mixpanel-ruby'

    mp = Mixpanel::Tracker.new(YOUR_TOKEN)
    ```
  </Tab>

  <Tab title="Java">
    ##### Install the SDK

    ```xml Java theme={"system"}
    <!--Include the following in your project's pom.xml-->
    <dependency>
      <groupId>com.mixpanel</groupId>
      <artifactId>mixpanel-java</artifactId>
      <version>1.4.4</version>
    </dependency>
    ```

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```java Java theme={"system"}
    //Import Mixpanel API
    import com.mixpanel.mixpanelapi.MessageBuilder;
    import com.mixpanel.mixpanelapi.MixpanelAPI;

    // Set up an instance of MixpanelAPI
    MixpanelAPI mixpanel = new MixpanelAPI();

    MessageBuilder messageBuilder = new MessageBuilder('YOUR_TOKEN');
    ```
  </Tab>

  <Tab title="React Native">
    ##### Install the SDK

    Under your app's root directory, run:

    ```sh theme={"system"}
    npm install mixpanel-react-native
    ```

    Under your application's iOS folder, run:

    ```sh theme={"system"}
    pod install
    ```

    Note: For XCode 12.5+, there is a known compile issue, please refer to this [workaround](https://github.com/mixpanel/mixpanel-react-native/issues/43#issuecomment-829599732).

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```javascript theme={"system"}
    //Import Mixpanel API
    import { Mixpanel } from "mixpanel-react-native";

    // Set up an instance of Mixpanel
    const trackAutomaticEvents = false;
    const mixpanel = new Mixpanel("YOUR_TOKEN", trackAutomaticEvents);
    mixpanel.init();
    ```
  </Tab>

  <Tab title="Flutter">
    ##### Install the SDK

    Add `mixpanel_flutter: ^2.0.0` to your package's pubspec.yaml file and run:

    ```sh theme={"system"}
    flutter pub get
    ```

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```dart theme={"system"}
    import 'package:mixpanel_flutter/mixpanel_flutter.dart';
    class _YourClassState extends State<YourClass> {
      Mixpanel mixpanel;

      @override
      void initState() {
        super.initState();
        initMixpanel();
      }

      Future<void> initMixpanel() async {
        // Once you've called this method once, you can access `mixpanel` throughout the rest of your application.
        mixpanel = await Mixpanel.init("YOUR_TOKEN", trackAutomaticEvents: false);
      }
    }
    ```
  </Tab>

  <Tab title="iOS (Objective-C)">
    ##### Install the SDK

    <Tabs>
      <Tab title="Swift Package Manager">
        Note: Swift Package Manager requires Xcode 12+ 1. In Xcode, select File > Swift Packages > Add Package Dependency. 2. Follow the prompts using the URL for this repository and must select a version greater than or equal to v4.0.0
      </Tab>

      <Tab title="Cocoapods">
        1. Create a Podfile in your Xcode project directory by running `pod init` in your terminal, edit the Podfile generated, and add the following line: `pod
             'Mixpanel'`. 2. Run `pod install` in your Xcode project directory. CocoaPods should download and install the Mixpanel library, and create a new Xcode workspace. Open up this workspace in Xcode or typing `open *.xcworkspace` in your terminal.
      </Tab>

      <Tab title="Carthage">
        Add `github "mixpanel/mixpanel-iphone"` to your Cartfile.
      </Tab>
    </Tabs>

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```objc theme={"system"}
    #import "Mixpanel/Mixpanel.h"

    - (BOOL)application:(UIApplication _)application
      didFinishLaunchingWithOptions:(NSDictionary _)launchOptions {
      ...
      Mixpanel \*mixpanel = [Mixpanel sharedInstanceWithToken:@"YOUR_TOKEN"
      trackAutomaticEvents: NO];
      ...
      }
    ```
  </Tab>

  <Tab title="iOS (Swift)">
    ##### Install the SDK

    <Tabs>
      <Tab title="Swift Package Manager">
        Note: Swift Package Manager requires Xcode 12+

        1. In Xcode, select File > Swift Packages > Add Package Dependency.
        2. Paste the URL `https://github.com/mixpanel/mixpanel-swift` and a minimum semantic version of v2.8.0.
      </Tab>

      <Tab title="Cocoapods">
        1. Create a Podfile in your Xcode project directory by running `pod init` in your terminal, edit the Podfile generated, and add the following line: `pod 'Mixpanel-swift'`.
        2. Run `pod install` in your Xcode project directory. CocoaPods should download and install the Mixpanel library, and create a new Xcode workspace. Open up this workspace in Xcode or typing `open *.xcworkspace` in your terminal.
      </Tab>

      <Tab title="Carthage">
        Add `github "mixpanel/mixpanel-swift"` to your Cartfile.
      </Tab>
    </Tabs>

    ##### Configure the SDK

    1. Import Mixpanel into `AppDelegate.swift`
    2. Initialize Mixpanel within `application:didFinishLaunchingWithOptions` as seen below

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```swift theme={"system"}
    import Mixpanel

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        ...
        // Replace with your Project Token
        Mixpanel.initialize(token: "YOUR_TOKEN", trackAutomaticEvents: false)
        ...
    }
    ```
  </Tab>

  <Tab title="Android">
    ##### Install the SDK

    Add `implementation 'com.mixpanel.android:mixpanel-android:7.+'` as a dependency to your `build.gradle` file.

    Once you've updated `build.gradle`, you can force Android Studio to sync with your new configuration by clicking the Sync Project with Gradle Files icon at the top of the window:

    <Frame>
      ![Sync Android With Gradle](https://storage.googleapis.com/cdn-mxpnl-com/static/readme/android-sync-gradle.png)
    </Frame>

    If it cannot find the dependency, you should make sure you've specified `mavenCentral()` as a repository in `build.gradle`.

    Next, add the following permissions in your AndroidManifest.xml:

    ```java theme={"system"}
    <!--Required to allow the application to send events to Mixpanel.-->
    <uses-permission android:name="android.permission.INTERNET" />

    <!--Optional, but recommended so we can send data intelligently based on network conditions -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <!-- Optional, but recommended so events will contain information about bluetooth state-->
    <uses-permission android:name="android.permission.BLUETOOTH" />
    ```

    ##### Configure the SDK

    Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project).

    ```java theme={"system"}
    import com.mixpanel.android.mpmetrics.MixpanelAPI;

    public class MainActivity extends ActionBarActivity {
      private MixpanelAPI mp;

      @Override
      protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        trackAutomaticEvents = false;
        // Replace with your Project Token
        mp = MixpanelAPI.getInstance(this, "YOUR_TOKEN", trackAutomaticEvents);
      }
    }
    ```
  </Tab>

  <Tab title="Unity">
    ##### Install the SDK

    Add `https://github.com/mixpanel/mixpanel-unity.git#master` to the dependencies section of `com.mixpanel.unity`.

    Alternatively, you can download and install the .unitypackage file from our [releases page](https://github.com/mixpanel/mixpanel-unity/releases).

    ##### Configure the SDK

    To initialize the library, first open the unity project settings menu for Mixpanel. (Edit -> Project Settings -> Mixpanel) Then, enter your project token into the Token and Debug Token input fields within the inspector. You can find your token [here](https://mixpanel.com/settings/project).

    <Frame>
      ![unity\_screenshots](https://user-images.githubusercontent.com/36679208/152408022-62440f50-04c7-4ff3-b331-02d3d3122c9e.jpg)
    </Frame>

    Note: If you prefer to initialize Mixpanel manually, you can select the `Manual Initialization` in the settings and call `Mixpanel.Init()` to initialize.

    To use mixpanel, add the following sample code to a part of your application:

    ```csharp theme={"system"}
    using mixpanel;
    ```

    You're
  </Tab>

  <Tab title="HTTP API">
    ##### Install the SDK

    <Note>
      No install required
    </Note>

    Using the HTTP API does not require an installation. **You're ready to move to the next step.**
  </Tab>
</Tabs>

# Integration / Framework Guides

<CardGroup>
  <Card title="Segment" href="/docs/tracking-methods/integrations/segment" />

  <Card title="Google Tag Manager" href="/docs/tracking-methods/integrations/google-tag-manager" />

  <Card title="Ad Spend" href="/docs/tracking-methods/integrations/ad-spend" />

  <Card title="Amazon S3" href="/docs/tracking-methods/integrations/amazon-s3" />

  <Card title="Amazon Kafka" href="/docs/tracking-methods/integrations/aws-kafka" />

  <Card title="CMS & E-Commerce" href="/docs/tracking-methods/integrations/cms-ecommerce" />

  <Card title="Customer.io" href="https://customer.io/docs/cdp/destinations/connections/mixpanel?utm_source=mixpanel&utm_medium=partner" />

  <Card title="Freshpaint" href="/docs/tracking-methods/integrations/freshpaint" />

  <Card title="Google Cloud Storage" href="/docs/tracking-methods/integrations/google-cloud-storage" />

  <Card title="Google Pubsub" href="/docs/tracking-methods/integrations/google-pubsub" />

  <Card title="Google Sheets" href="/docs/tracking-methods/integrations/google-sheets" />

  <Card title="Langfuse" href="/docs/tracking-methods/integrations/langfuse" />

  <Card title="LaunchDarkly" href="/docs/tracking-methods/integrations/launchdarkly" />

  <Card title="mParticle" href="/docs/tracking-methods/integrations/mparticle" />

  <Card title="Next.js" href="/docs/tracking-methods/integrations/nextjs" />

  <Card title="Mobile Attribution Tracking" href="/docs/tracking-methods/integrations/mobile-attribution-tracking" />

  <Card title="Rudderstack" href="/docs/tracking-methods/integrations/rudderstack" />

  <Card title="Shopify" href="/docs/tracking-methods/integrations/shopify" />

  <Card title="Vendo for Shopify" href="https://apps.shopify.com/vendo?utm_source=mixpanel&utm_medium=partner" />

  <Card title="Snowplow" href="/docs/tracking-methods/integrations/snowplow" />

  <Card title="Stripe" href="/docs/tracking-methods/integrations/stripe" />

  <Card title="Tealium" href="/docs/tracking-methods/integrations/tealium" />
</CardGroup>

<hr />

<div>
  <div>
    <h2>
      Next: Identify Your Users
    </h2>

    <p>
      With Mixpanel installed, you’re now ready to identify the users who use
      your product.
    </p>

    <br />

    <ExtendedButton title="Identify Your Users" />
  </div>
</div>

## FAQ

<AccordionGroup>
  <Accordion title="Does Mixpanel automatically track page views?">
    Yes, if you pass `track_pageview: true` in the `mixpanel.init()` call, Mixpanel will automatically track a "Page View" event every time a new page is loaded. Learn more [here](/docs/tracking-methods/sdks/javascript#tracking-page-views).
  </Accordion>

  <Accordion title="What are the recommended web configuration options?">
    When tracking on web, we recommend using localStorage, as this is more reliable:

    ```javascript theme={"system"}
    mixpanel.set_config({ persistence: "localStorage" });
    ```

    Please note that cross-subdomain tracking is not possible when using local storage. If your implementation requires cross-subdomain tracking, remove the persistence flag and use the default "cookie" persistence option.
  </Accordion>

  <Accordion title="Does Mixpanel use third-party cookies?">
    No, our Mixpanel JavaScript SDK does not set or use any third-party cookies. If you wish to disable cookies entirely, you can set the disable\_persistence option to true when initializing your Mixpanel JS instance. Note that disabling persistence will disable the use of super properties and anonymous -> identified user tracking.
  </Accordion>

  <Accordion title="How can I track in a privacy compliant way?">
    If a user opts out of tracking, you can call the `.optOutTracking()` method on any of our client-side SDKs; this prevents any subsequent data being tracked from that user's device. Learn more [here](/docs/privacy/protecting-user-data).

    For iOS specifically: Mixpanel does not use IDFA, so it does not require user permission through the AppTrackingTransparency(ATT) framework. For more details, refer to our [Apple App Developer Privacy Guidance](https://mixpanel.com/legal/app-store-privacy-details).
  </Accordion>
</AccordionGroup>


# Install with AI
Source: https://docs.mixpanel.com/docs/quickstart/install-with-ai



The Mixpanel Implementation Skill installs Mixpanel into your project through your AI coding agent. It handles SDK selection, identity management, event tracking, and compliance gates through a guided conversation — with paths ranging from a one-session Quick Start to a full production-ready rollout.

## What You'll Need

Before starting, make sure you have:

* A Mixpanel account with Admin or Owner access ([sign up](https://www.mixpanel.com/signup) if you don't have one)
* An AI coding agent with access to your project files (Claude Code, Cursor, ChatGPT, GitHub Copilot, Windsurf, etc.)

  * Use the most advanced model your tool offers
* A development or staging environment where you can test the changes

## Step 1: Get Your Mixpanel Project Token

1. **Log into your Mixpanel account** at [mixpanel.com/login](https://www.mixpanel.com/login).
2. **Open project settings** by clicking the gear icon in the bottom left.
3. **Click "Overview"** in the left sidebar.
4. **Copy your Project Token** from the Access Keys section. It's a long string of letters and numbers. *Note: You'll need to be an Admin or Owner in your project.*
5. **Keep this handy** — you'll give it to your coding agent in the next step.

## Step 2: Run the Mixpanel Implementation Skill

The skill runs inside your coding agent. To start it:

1. **Open your AI coding agent** and make sure it has access to your project files.
2. **Paste this prompt** into the chat:

```text theme={"system"}
Set up Mixpanel tracking in this project.
Use the Mixpanel setup skill: https://storage.googleapis.com/cdn-mxpnl-com/libs/mixpanel-skill/skill.md
```

3. **Answer the skill's questions.** The skill scans your codebase, confirms a few one-way-door details (platform, CDP usage, EU/CA users, your most important user action), and then writes the integration code.

## How the Skill Works

The skill starts by asking which mode fits your goal:

| Mode                    | What it covers                                                                                                                |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Quick Start**         | Get your first two events into Mixpanel in one session — sign-up plus your Value Moment.                                      |
| **Full Implementation** | Build a complete, production-ready setup: discovery, analytics strategy, data model, tracking plan, identity, and governance. |
| **Add Tracking**        | Extend an existing Mixpanel implementation with new events.                                                                   |
| **Audit**               | Diagnose an existing implementation and produce a prioritized fix list.                                                       |

You can switch modes mid-flow. If Quick Start surfaces consent, CDP, or identity complexity, the skill offers to escalate to Full Implementation. If Full Implementation feels heavy, you can downshift to Quick Start.

### What the Skill Does

* **Scans your codebase** to identify your platform, framework, auth flow, and candidate events — so you don't answer questions the code already answers.
* **Selects the correct SDK** for your platform (JavaScript, React Native, iOS Swift, Android, Python, Node.js, Flutter, Go, Ruby, PHP, Java, Unity).
* **Routes through your CDP** if you use Segment, Rudderstack, or mParticle, instead of installing the SDK directly.
* **Gates SDK initialization behind consent** when you have EU or California users.
* **Wires identity correctly** — `identify` on login or signup, `reset` on logout, in the right files.
* **Drops an `AGENTS.md` file** in your repo so future AI agents know Mixpanel is your analytics tool, how it's configured, and how to add tracking consistently.
* **Verifies events in Live View** before considering the work done.

### If You Don't Have Codebase Access

The skill also supports a developer handoff path. Tell the skill you're scoping the work for a developer to implement later, and it generates a `MIXPANEL_IMPLEMENTATION_SPEC.md` file with copy-paste-ready code, business context, verification steps, and troubleshooting — instead of writing code directly.

## Step 3: Test Your Installation

After the skill finishes, confirm events are flowing:

1. **Deploy the changes** to your testing environment.
2. **Use your app or website** the way a user would.
3. **Open the [Events page](https://mixpanel.com/report/events)** in Mixpanel.
4. **Confirm events appear** as you interact with your app. You may need to refresh.

### What You Should See

The skill names events based on your product, but a typical implementation includes:

* `sign_up_completed` — when a user finishes account creation
* A **Value Moment** event named for the most important action in your product (e.g., `report_generated`, `purchase_completed`, `prompt_sent`)
* Identity tied to your authenticated user ID

If you chose Full Implementation, you'll also have a full tracking plan, governance setup in Lexicon, and a documented identity flow.

## Troubleshooting

#### No events showing up?

1. Confirm you used the correct project token.
2. Make sure your app is running and you're actually interacting with it.
3. Wait a minute or two — there can be a small delay.
4. Open your browser console (F12) and check for errors.

#### Events tracking with the wrong name or properties?

Tell the skill to switch into **Audit** mode. It reviews what's currently tracked and produces a prioritized fix list.

#### Wrong SDK installed?

The skill checks platform during its Pre-Flight scan, but if it picked the wrong SDK, tell it and ask it to redo the implementation step. The skill rolls back and tries again with the correct SDK.

#### The skill is asking for information I don't have?

Pause and gather it, or tell the skill you don't have codebase access — it will generate a developer handoff specification instead of writing code.

#### Need more help?

* Browse the [Mixpanel documentation](/).
* Ask your coding agent to explain what it installed.
* Contact [Mixpanel support](https://mixpanel.com/contact-us/support/).

## FAQ

#### Which coding agents does the skill work with?

Any agent that can fetch a URL and follow instructions — Claude Code, Cursor, ChatGPT, GitHub Copilot Chat, Windsurf, and others. The skill is a plain Markdown file your agent reads at runtime.

#### Is my code or project token sent to Mixpanel?

No. The skill runs entirely inside your coding agent. Your code never leaves your environment, and your project token is used only by the Mixpanel SDK that gets installed in your project.

#### Can I run the skill again later?

Yes. Add new events through **Add Tracking** mode, or review your setup through **Audit** mode. The `AGENTS.md` file the skill drops in your repo gives future agents the context they need to add events consistently.

#### What if I'm not technical?

The skill works whether or not you know how to code. If you don't have codebase access, choose the developer handoff path — the skill generates a complete specification your developer can implement.

#### Does the skill work with a CDP like Segment?

Yes. If you route data through Segment, Rudderstack, or mParticle, the skill skips direct SDK installation and configures Mixpanel through your CDP instead.

<Warning>
  The skill generates production code. Always review what your AI agent writes before merging or deploying. Human oversight is recommended for every integration.
</Warning>


# Reports Overview
Source: https://docs.mixpanel.com/docs/reports



A report is a visual display of your tracked Mixpanel data.

Mixpanel has several types of reports: [Insights](/docs/reports/insights), [Funnels](/docs/reports/funnels/funnels-overview), [Flows](/docs/reports/flows), [Retention](/docs/reports/retention) and other advanced reports, each with their specialized use, and they can be accessed from the top-left side of the screen by clicking the '+ Create New' button.

This article focuses on the key concepts that are applicable across the four basic report types (Insights/Funnels/Flows/Retention).

<Note>
  Mixpanel's core reports are available on all free and paid subscription plans.
</Note>

## Metrics

Metrics are the values that the report will display. Every metric consists of a **measurement** of a **behavior**. An example of a metric is "Unique Users" doing "Sign up", which is the measurement of unique users, on the behavior of "Sign up".

## Behaviors

A behavior is an event or a sequence of events performed within some criteria. A behavior can be something simple, such as a single event, or it can be more complex, like completing a multi-step funnel.

## Measurements

The measurement tells the metric how to evaluate the behaviors. Some examples of measurements are: total events, unique users, total sessions, conversion rate, retention rate, and aggregate property.

Depending on the behavior, certain measurements may not be possible. For example, you cannot use the conversion rate measurement when the metric only has a single event.  The measurement is selected in the bottom-left area of the metric.

<Frame>
  <img alt="measurement" />
</Frame>

## Visualizations

You can change the type of visualization by clicking the dropdown in the upper right corner of the report. The options available will depend on the type of report that you started with. In this case, we switched to a bar view, allowing us to see the total number of "login" events across the entire time range, broken down by the "Platform" property.

<Frame>
  <img alt="/Screen_Shot_2022-07-11_at_3.07.02_PM.png" />
</Frame>

## Filters

Filters are used to narrow events or behaviors that qualify for analysis. For example, you may want to only consider "Sign Up" events that came from Android. In this case, you would be filtering the "Sign Up" event to only include the "Sign Up" events where the property "Device" is equal to "Android".

### Global Filters

A global filter applies to the entire report. Filter by properties or cohorts by clicking the **Filter** button. This will filter the results of the entire report to show only data with that property or cohort.

<Frame>
  <img alt="image" />
</Frame>

### Inline Filters

An inline filter applies to one particular event in the report.

Add a filter to your query by clicking on the **…** icon beside an event, profile, cohort, or step.

<Frame>
  <img alt="image" />
</Frame>

Then, select a property from the drop-down list that appears and specify which values to filter.

<Frame>
  <img alt="image" />
</Frame>

In Funnels, filtering a step by a particular property will limit the data you see in the funnel to events with that property value.

You can choose multiple property filters for each item in your query.

You can select whether you would like the query to match any of these filters, or all of the filters, by clicking on **and/or** beside the filters.

<Frame>
  <img alt="image" />
</Frame>

### First Time Ever Filter

Sometimes, you might want to filter an event to only the first time that it's performed by a user. This helps answer the following questions:

* How many users sign up or perform another key event for the first time each week?
* Which referrers do most first-time users come from?
* How quickly do users make a purchase after their first time engaging with the app?
* How well do users retain after performing a key event for the first time?
* What events do users perform before and after making their first purchase?

You can do this by adding a First Time Filter to any event in Mixpanel. This filters the event down to only the first instance of the event performed by a user:

<Frame>
  ![233894752-93851682-9d83-4c87-937d-8fd90db465c6.png](https://user-images.githubusercontent.com/2077899/233894752-93851682-9d83-4c87-937d-8fd90db465c6.png)
</Frame>

Mixpanel computes this on-the-fly by scanning each user's history to determine if this was the first instance of the event performed by the user, based on timestamp. Note that when there's a tie in the timestamps of the first event (e.g., the user does multiple first-time Purchases in the same second), all of those events will be considered the "first time" and will match the filter. The impact will be that Mixpanel includes multiple events for those users, so if you break down by user ID, you may see that the user did multiple first events.

## Breakdowns

Breakdown groups the results of your metrics in Insights, Funnels, Flows, or Retention reports by a property or cohort, allowing you to examine which properties or cohorts have a significant impact on your query.

This feature is useful for determining if a group factor, such as browser type, is having an impact on the way users interact with your product. Breakdown will display counts, such as the number of events performed or the conversion rates with that property value.

Select the **Breakdown** button, and select the property or cohort you want to break down your results by.

<Frame>
  <img alt="image" />
</Frame>

For cohorts, you will be shown groups of users both in and not in the cohort in your results.

It is only possible to either group by properties or group by cohorts, but not both.

## Events Menu

This is the menu that appears under "Add Metric" or "Select Step".

By default, the event menu shows all events, except for [hidden events](/docs/data-governance/lexicon#hide-events-and-properties).

If you organize your events using [tags](/docs/data-governance/lexicon) in Lexicon, the tags will show up as filtering options in the event menu. When you select a tag, a list of events that share the same tag appears:

<Frame>
  <img alt="/Untitled__1_.png" />
</Frame>

## Properties Menu

This menu appears when adding a filter, an inline filter on an event, or a breakdown.

By default, the menu shows all properties; this includes event properties, profile properties, group properties, lookup properties, and cohorts.

You can select the following filtering options to show a subset of the properties in the menu:

* Select "Event" to show only the [Event properties](/docs/data-structure/events-and-properties).
* Select "User" to show only the [Profile properties](/docs/data-structure/events-and-properties).
* Select "Computed" to show only the [Computed properties](/docs/features/computed-properties).
* If you set up [Group Analytics](/docs/data-structure/advanced/group-analytics), the group keys will appear individually under their respective display names. You can select any Group key to show only the Group properties relevant to the selected Group key.
* Select "Cohorts" to show only the [Cohorts](/docs/users/cohorts).
* If you set up [Experiments](/docs/experiments), they will appear individually under their respective display names.

<Frame>
  <img alt="/insights_properties_section.png" />
</Frame>

### Duplicating Metrics

To duplicate any metrics or properties in your query, select the inline action menu and choose **Duplicate**. Delete any events or properties by clicking the **Remove** button.

<Frame>
  <img alt="Event Options" title="Event Options" />
</Frame>

## Date Range

Determine the time range of a query by clicking on the date range selector. The date range selector is common across all reports.

All dates and times in Mixpanel reflect the project's timezone [(by default, UTC)](/docs/orgs-and-projects/managing-projects#changing-your-timezone). The default for most reports is “Last 30 days” (displayed as "30D"), but there are a variety of preset options, as well as the option to select a custom date range.

<Frame>
  <img alt="new date rate" />
</Frame>

For these date ranges, the output shows results from the last complete days, plus any results from the current incomplete day.

| Preset         | Description                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------- |
| Custom         | Gives multiple customization possibilities, explained below.                                 |
| Today          | Includes the current incomplete day up to the current second.                                |
| Yesterday      | Includes the whole of the previous day from midnight to midnight.                            |
| Last 7 days    | Last 7 days and the query count from the current incomplete day up to the current second.    |
| Last 30 days   | Last 30 days and the query count from the current incomplete day up to the current second.   |
| Last 3 months  | Last 3 months and the query count from the current incomplete day up to the current second.  |
| Last 6 months  | Last 6 months and the query count from the current incomplete day up to the current second.  |
| Last 12 months | Last 12 months and the query count from the current incomplete day up to the current second. |

### Custom

Selecting **Custom** on the date range selector opens up some additional options: "Recently Applied", "Fixed", Last", Since", "Period to date", and "Previous period".

### Recently Applied

This option will give you access to a prompt field, where you can type the range you're looking for (*'last 16 days starting on June 4th'*) for the AI to resolve for you, and also see a list of the last ranges used.

<Frame>
  <img alt="Date Picker Recently Applied" title="Date Picker Recently Applied" />
</Frame>

### Fixed

“Fixed” allows you to select two dates to query between by entering the same start and end date.

<Frame>
  <img alt="Date Picker Fixed" title="Date Picker Fixed" />
</Frame>

### Last

“Last" allows you to select a rolling time range similar to the default “last 30 days”, but you have the flexibility to choose the time value and scale, either days, weeks, months, or quarters.

<Frame>
  <img alt="Date Picker Last" title="Date Picker Last" />
</Frame>

If needed, you can adjust the desired time window backward by the selected number of days in the "Ending" section. For instance, in the example below, we are still looking at a 2-week window that is shifted 7 days back.

<Frame>
  <img alt="Date Picker Last Rolling Window" />
</Frame>

### Since

“Since” allows you to select a specific date to query for all data since that start date.

<Frame>
  <img alt="Date Picker Since" title="Date Picker Since" />
</Frame>

### Period to date

This option allows you to select a date range that will update dynamically to fit the current interval - you can choose "Day", "Week", "Month", "Quarter", and "Year". When the boundary of the interval is passed, the date range will automatically update to include only the current interval. For example, if "Month" was selected on June 27, the date range would include Jun 1 - Jun 27. The next month, after June has passed, the date range would include Jul 1 - Jul 8, as shown in the image below.<br />"Period to date" respects the start of the week and start of quarter settings under Project Settings.

<Frame>
  <img alt="Date Picker Period To Date" />
</Frame>

### Previous period

Choosing this option allows you to query information tracked only in the selected period: "Day", "Week", "Month", "Quarter", and "Year".

<Frame>
  <img alt="Date Picker Previous Period" />
</Frame>

### Minute Level Granularity

Enable hourly and minute-level granularity by clicking the "Enable Time Ranges" toggle on the bottom-left side of the date range picker. This enables you to select time ranges up to the minute. You can also use this for the "Last" time range to monitor only the past few hours or minutes.<br />This setting only works for the "Fixed", "Last", and "Since" options; it's not available for "Period to date" and "Previous period".

<Frame>
  <img alt="Date Picker Fixed Time Ranges" title="Date Picker Fixed Time Ranges" />
</Frame>

## Zoom In

To zoom in, click on the graph and drag to highlight a specific window of time in your report. Click **Reset zoom** to return to the previous view.

<Frame>
  <img alt="zoom (1)" />
</Frame>

## Comparisons

Comparisons allow you to compare metrics or broken-down segments of metrics against each other. Depending on the type of comparison, you are also able to see the lift of a segment or metric against another.

### Compare to Past

'Compare to Past' allows for comparing a metric against itself on a different time period. You are able to compare against the previous day, week, month, quarter, and year. You are also able to choose a custom time comparison window.

<Frame>
  <img alt="/compare_to_past.png" />
</Frame>

By default, Mixpanel will visualize the values for both time periods. If you wish to see the lift of the current time period against the past time period, you can select the "Percent Change over Baseline" option to see the lift of your metric over time.

<Frame>
  <img alt="/compare_to_past_lift.png" />
</Frame>

### Compare to Segment

Compare to segment allows you to set a property value as a baseline and see how every other property compares.

<Frame>
  <img alt="/compare_to_segment.png" />
</Frame>

### Compare to Overall

'Compare to Overall' allows you to compare each segment value and see what proportion it makes of the overall value.

<Frame>
  <img alt="/compare_to_overall.png" />
</Frame>

#### Supported Charts

Comparisons are supported across all insights chart types. Depending on the exact configuration chosen, certain comparison operations may be disabled.

| Chart Type            | Time Comparison Supported | Percentage change over Baseline Supported | Percentage of Overall Supported |
| --------------------- | ------------------------- | ----------------------------------------- | ------------------------------- |
| Insights Line         | Yes                       | Yes                                       | Yes                             |
| Insights Stacked Line | No                        | No                                        | Yes                             |
| Insights Bar          | Yes                       | Yes                                       | Yes                             |
| Insights Stacked Bar  | Yes                       | No                                        | No                              |
| Insights Pie          | No                        | No                                        | No                              |
| Insights Metric       | Yes                       | Yes                                       | Yes                             |
| Funnels Steps         | Yes                       | Yes                                       | No                              |
| Funnel Trends         | Yes                       | Yes                                       | No                              |
| Retention Curve       | No                        | Yes                                       | No                              |
| Retention Trends      | Yes                       | Yes                                       | No                              |

## Saving to a board

<Note>
  Free plans allow each user to save up to 5 reports, while Growth and Enterprise plan users can save an unlimited number of reports. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

When you are satisfied with the analysis and decide that this is something that you are likely to revisit, you save the report to a [board](/docs/boards) by pressing "Save" in the top right and selecting the board you would like to save to, or creating a new board.

All reports are saved to a board, which inherits the sharing settings and permissions applied to that board. Learn more about saving, sharing, and permission for your reports and boards [here](/docs/boards/sharing-and-permission).

<Frame>
  <img alt="Reports Save To Board" title="Reports Save To Board" />
</Frame>

## Typecasting

Mixpanel allows you to force Properties into another [data type](https://help.mixpanel.com/hc/en-us/articles/115004547063) by using the **"Data Type"** option in the overflow menu for property filters and breakdowns.

<Frame>
  <img alt="/Kapture_2022-01-04_at_11.38.41.gif" />
</Frame>

Typecasting is helpful when one of your properties is a number but is sent to Mixpanel as a string, and you want to see histogram data for that property. Or if one of your properties is a Unix timestamp and got sent as a number, and you want it to be treated as a date Property instead.

**How do I see the exact numeric values when applying a breakdown to a number data type in Insights?**

Insights will automatically bucket high-cardinality segments of number data types into ranges.

You can either customize the ranges by clicking "[Customize Range](/docs/features/advanced#custom-buckets)".

Alternatively, if you'd like to see the exact numeric values, you can typecast the Number property to a String to remove the range bucketing.

## View Users

View Users is a streamlined process for exploring the users contributing to a specific metric or point on a chart. By interacting with the chart, you can view a group of users experiencing friction or dig deep into which users are driving feature adoption.

View Users can help you:

* See the users contributing to any metric and view their recent activities & properties.
* Save these users as a cohort.
* Export these users to a CSV file.

<Frame>
  <img alt="Reports View Users" />
</Frame>

## Segment Limits and Ordering

<Warning>
  When you encounter a "cardinality limit" error or see a "-" in your report despite having data, it indicates that the query returned more unique segments than the UI can display. To resolve this, narrow the time range, apply filters to specific events or properties, or reduce the number of breakdowns. These steps limit the segments, making your report easier to interpret and reducing the strain on the querying capacity of your projects.
</Warning>

In order to keep the interactive analysis experience snappy for projects of all sizes, Mixpanel limits how many segments are returned when using breakdowns. When breakdown (also referred to as segmentation) limits are reached, the response will be truncated to only return the top N segments. We have higher limits available via CSV exports.

### UI

We are changing how many segments are returned to the report (visible limit), how many segments can be selected at a time for visualization (selection limit), as well as the number of segments selected by default (default selection).

Here is the breakdown per report visualization type:

| **Report Viz**            | **Default Selection** | **Selection Limit** | **Visible Limit** |
| ------------------------- | --------------------- | ------------------- | ----------------- |
| Insights (table)          | 12                    | 3000                | 3000              |
| Insights (bar)            | 12                    | 300                 | 3000              |
| Insights (line & pie)     | 12                    | 50                  | 3000              |
| Insights (metric, column) | 6                     | 12                  | 3000              |
| Retention                 | 6                     | 12                  | 200               |
| Funnels                   | 6                     | 12                  | 200               |

### CSV Export

When exporting a report as CSV, we offer elevated limits. For most reports, the CSV export limit is 10,000. For insights non-line charts, we allow for up-to 50,000.

### Top Segments logic

The way we pick the top segments differs according to the type of query. We choose the top segments based on the value shown in the metric value column.

| **Query type**                 | **How we select top segments**                                  |
| ------------------------------ | --------------------------------------------------------------- |
| Total                          | Total number of occurrences of the chosen event                 |
| Unique                         | Number of unique users who performed the chosen event           |
| Sum of property values         | Sum of the chosen property                                      |
| Min/max of property values     | Lowest/highest value of the chosen property                     |
| Average                        | Number of events (or users) that contribute to the average      |
| Median/Percentile/Distribution | Number of events (or users) that contribute to the distribution |
| Distinct count                 | Number of distinct values of the chosen property                |
| DAU/WAU/MAU                    | Number of unique users                                          |
| Sessions                       | Number of sessions that contain the chosen event                |
| Funnels                        | Total number of times the first funnel step was completed       |
| Retention                      | Total number of times the first event was completed             |

### Multi-metric and formula reports

Since our top N logic is determined per metric, multi-metric and formula reports that have breakdowns that exceed segment cardinality limits may experience a few awkward edge cases where the different metrics’ top N segments are misaligned. We highly recommend using filters to bring your segment count under our cardinality limit to ensure the same segments are selected across metrics - ensuring formula accuracy and a more user-friendly report viewing experience. You may also wish to use CSV exports for these cases.

### Multi-breakdown reports

For multi-segmentation or multi-breakdowns, we define the top N segments based on the top N flattened segments, which are the combination of the individual segment values across all breakdowns. For example, for a breakdown by Country and Browser, we treat “United States/Chrome” as one flattened segment for our segmentation limits.

### How will I know if my results are being truncated?

You will see a banner at the top of your report indicating that results were truncated, what limit was applied, and what CSV export limit is available.

<Frame>
  <img alt="image" />
</Frame>

## Query Time Sampling

<Note>
  This feature is available to customers with an Enterprise subscription plan in projects with over 2 billion monthly events.
</Note>

Query-time sampling allows you to query a subset of users and shorten the time it takes for a report to load results. The Insights, Funnels, Retention, and Flows reports all support sampling at query time.

### Enable Sampling

From the report in which you would like to use sampling, click the **lightning bolt** in the upper-right corner of the query builder. This will enable sampling on the report and will be indicated by the lightning bolt symbol turning blue.<br />The percentage of the total that is included in the query calculations will be indicated in the banner shown above the report.

<Frame>
  <img alt="Reports Query Time Sampling" title="Reports Query Time Sampling" />
</Frame>

To turn off sampling, simply click the lightning bolt toggle again.

### Query Time Sampling Calculation and Presentation

Mixpanel will not sample or drop events at ingestion. Instead, Mixpanel will ingest all event data and sample it at query time. This prevents the loss of important data and, therefore, allows you to toggle sampling on and off depending on need.

For example, if you need iterative querying, then sampling will greatly speed up this process. When you build the proper query, you can turn off sampling and query the entire dataset.

The following occurs when sampling is enabled:

1. Mixpanel selects a uniformly random sample of users on which to run the analysis.
2. The sample size is 10% of the total population.
3. The report is generated using that subset of users.
4. Mixpanel up-samples the data by multiplying by the inverse of the sampling factor. This is done for [functions](/docs/reports/insights) such as totals and uniques. Functions that do not scale with users (average, min, max) will not be up-sampled.
5. The effect is that numbers should closely approximate results seen without sampling enabled. This works better as the number of users increases, particularly for customers with more than 5 million users.
6. Mixpanel adds an annotation to reports.

<Note>
  If you save a report that uses query time sampling, then a version of the report *without* sampling is saved. This ensures that boards and saved reports are computed on the entire dataset for high fidelity.
</Note>

## Query Result Caching

Mixpanel stores the results from a report query in our server cache and presents these results from there when appropriate. This saves time when running a complicated query multiple times, and allows you to surface previously calculated results near-instantaneously. The date range of the query will adjust how Mixpanel presents results from the server cache.

* If the query date range is 1 year or over, then the query results are cached for up to 14 days.
* If the query date range is under 1 year, then the query results are cached for up to 7 days.
* If the query date range is under 6 months, then the query results are cached for up to 3 days.
* If the query date range is under 2 months, then the query results are cached for up to 2 days.
* If the query date range is under 1 month, then the query results are cached for up to 1 day.
* If the query date range is under 1 week, then the query results are cached for up to 12 hours.
* If the query date range is under 1 day, then the query results are cached for up to 1 hour.

While this highlights the default server cache behavior, you can always refresh a report to include the most current data as described below.

### Refreshing the Query Results Cache

To refresh the query results cache, navigate to the report, click the three dots overflow menu at the top of the report and select **Refresh Data**.

<Frame>
  <img alt="public/Refresh_Data_Report.png" />
</Frame>

To refresh the query results' cache in a board, click the three dots overflow menu at the top of the board and select **Refresh Data**.

<Frame>
  <img alt="public/Refresh_Data_Board.png" />
</Frame>

To refresh the query results' cache in a board card, click the three dots overflow menu at the top of the card and select **Refresh Data**.

<Frame>
  <img alt="public/Refresh_Data_Board_Card.png" />
</Frame>

## Find Interesting Segments

Determine which users are either driving conversion and retention or behaving as outliers by using the built-in “Find Interesting Segments” feature.

Find Interesting Segments can help you discover:

* Whether certain property segments outperform the overall funnel conversion or retention rates.
* Cohorts that perform best to optimize for those behaviors.
* Segments that are under-performing.
* Changes in the conversion or retention rates of segments.
* Change in population over time in funnels.

User properties are not yet supported.

### Interesting Segments in Funnels

View the top and bottom converting segments in your funnel by clicking the **Find interesting segments** button at the bottom of the segmentation chart.

<Frame>
  <img alt="/10038188905364" />
</Frame>

Rather than searching through multiple property breakdowns to find significant data, this feature automatically identifies this data for you. Mixpanel combs through your event properties and cohorts to show you which of those segments convert higher or lower than average, and are therefore statistically significant.

There are two reports you will receive in your email: segment analysis and time comparison.

### Segment Analysis

An email that breaks down the top and bottom converting segments of your funnel based on statistical significance and other factors is automatically sent after you click the button. If no statistically significant segments are found, then the email shows non-statistically significant segments.

Segment Analysis helps answer questions such as:

* Which groups of users are driving my conversion rate?
* Which groups of users are decreasing my conversion rate?

This is done by examining which segments of users are converting at a high rate and have a large enough population size, or which segments are converting at a low rate and have a large enough population size. In the first scenario, this segment would raise the overall conversion rate, while in the second scenario, this segment would lower the overall conversion rate.

### Time Comparison

A time comparison chart is also included in the email. This chart shows a segment's behavior over time (in terms of both conversion rate change and population size change) as it relates to the overall population trend (population and conversion rate change).

Time comparison answers questions such as:

* Which groups of users are trending in a way that is different from the overall behavior?
* Which groups of users are driving the overall behavior?

Mixpanel automatically compares the currently selected date period to the previous one. For example, if you are viewing the current week, the email will compare to the week before.

### Interesting Segments in Retention

View the top and bottom converting segments in your retention report by clicking the **Find interesting segments** button at the bottom of the retention chart. This feature is not currently available for Frequency Retention.

<Frame>
  <img alt="/10037069627156" />
</Frame>

Rather than searching through multiple segment breakdowns to find significant data, this feature automatically identifies that data for you. Mixpanel combs through your event properties and cohorts and shows you which of those segments retain at a higher or lower rate than average.

An email that breaks down the top and bottom retaining segments of your Retention report based on changes in retention rates is automatically sent after you click the button.

### Interpret Email Results

When your analysis email says “no interesting segments”, this means that none of the segments you analyzed were behaving significantly differently from the overall population at a large enough volume. To resolve this issue, try extending the date range of the report or try a different report.

If the analysis request included dates in the past five days and is sent from the mobile SDK, data may be delayed and therefore not included at the time of the analysis. Likewise, the date window selected might still fall under the conversion window, and more conversions have yet to come through.

Results are sorted by taking into consideration the property, the number of users in the report, as well as the deviation from overall conversion or retention behavior to surface the most meaningful segments to you.


# Other Apps
Source: https://docs.mixpanel.com/docs/reports/apps



<CardGroup>
  <Card title="Impact" href="/docs/reports/apps/impact" />

  <Card title="JQL" href="/docs/reports/apps/jql" />

  <Card title="Signal" href="/docs/reports/apps/signal" />
</CardGroup>


# Impact
Source: https://docs.mixpanel.com/docs/reports/apps/impact

Measure the effect of a launch on your KPIs

<Note>
  Users on a Growth or Enterprise plan can access the Impact report. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

Mixpanel’s Impact report measures the effects of product or marketing launches on your key metrics. Impact calculates the user adoption of the launch, the impact of the launch on an important event, and the differences between users who adopt the launch and those who do not.

To access **Impact**, go to the Applications section on the bottom left-side of the screen, and then select **Impact**.

<Frame>
  <img alt="Applications Impact" title="Applications Impact" />
</Frame>

## Use Cases

Here are some of the sample questions you can answer in Impact:

* How is the adoption of my feature changing over time?
* Did my feature launch affect the rate of another key value moment?

## Quick Start

<Frame>
  <iframe />
</Frame>

### Step 1: Select a launch event

To build an Impact query, first select a launch event. This is the event that you are measuring as the cause of change.

<Frame>
  <img alt="Impact Add Event" />
</Frame>

Select the start date of this launch event. Add any additional filters to narrow the launch event parameters by clicking the "**..." button** and then "Filter".

<Frame>
  <img alt="Impact Add Filters" />
</Frame>

### Step 2: Select metric events

Select a metric event by clicking the **Add** button under **IMPACTED EVENTS**. You are measuring the impact of the launch event on this metric event. Add additional filters to narrow the impacted event parameters.

<Frame>
  <img alt="Impact Add Impacted Event" />
</Frame>

### Step 3: Add breakdown (optional)

Breakdown impacted events further by clicking the "**…" icon**, selecting **Add Aggregation**, and then selecting an event property, such as “Amount”. This will add up the value of this property for all of the times this event happened in this time range. All aggregate properties are typecast to numeric properties to calculate the sum of that property. For example, aggregate the property “Amount” under the event “Process Payment” to analyze revenue.

<Frame>
  <img alt="Impact Aggregate Event" />
</Frame>

### Step 4: Select user group

Under **USER DEFINITION,** select whether you would like to count users who did **only the impacted event** or **any event**.

<Frame>
  <img alt="Impact User Definition" />
</Frame>

### Step 5: Select time range

The time range is a fixed period of time that determines the adopters and non-adopters of the launch event. The default is "15 days before and after", meaning that the 15 days preceding the fixed launch event date and the 15 days following the launch event will be included in the results. This will allow you to see the difference in the metric event before and after the launch event.

The chart will not necessarily change if you change the time range.

<Frame>
  <img alt="Impact Date Range Picker" title="Impact Date Range Picker" />
</Frame>

## Reference

### Adoption

Adopters are users who have triggered the launch event. Non-adopters are users who haven't triggered the launch event. Both adopters and non-adopters must perform the metric event to be included in the report.

The Adoption Rate is the number of users who perform the launch event divided by the total user count:

$\%\,adoption = average\left( (adopters) \over (adopters + non\,adopters) \right)$

### Impact Chart

The Impact Chart shows how the rate of metric event occurrence changes over time. The y-axis of the chart is the average number of the metric event's count, and the x-axis is time spanning 30 days.

Unlike other Mixpanel charts, the Impact Chart displays time in relative time, not calendar time. The chart centers around the first day that the launch event is available, or “day zero”. The chart displays the 15 days before and after day zero.

<Frame>
  <img alt="Impact Impact Trends Graph" />
</Frame>

Every user in the report can have a different day zero. For users in the adopter group, day zero is the first day that they perform the launch event. For users in the non-adopter group, day zero is the day the first adopter performed the launch event (which is most likely the launch day of the feature).

Each data point on the chart is calculated as follows:

$metric\,event\,rate = { (metric\,event\,count) \over (total\,user\,count)}$

Each point on the line is the average number of times users in the group did the metric event on that relative day.

For example, if 10 adopters did the launch event for the first time five days ago, and they then did the metric event a total of 30 times today. The +5 days point on the adopter line would read 3. The math would be as follows:

* 30 = The number of metric events performed by the adopters on day 5.
* 10 = The number of users who did the launch event 5 days before the first day.
* 3 = 30/10.

You can see how frequently users in each group perform the metric event, both before and after the launch.

The chart also contains average lines for non-adopters and adopters both before and after day zero (or launch), and the unobserved counterfactual of the adopters (UCA), formerly called projected adopters, average after day zero.

<Frame>
  <img alt="/Screen_Shot_2019-12-09_at_2.05.03_PM_copy.png" />
</Frame>

### Impact Table

The Impact Table summarizes the results of the Impact chart. It displays the average rate at which users in the adopter and non-adopter groups performed the metric event over the course of the 15 days before and after launch.

The table is broken down into three sections: “Pre-Launch”, “Post-Launch”, and “Impact”.

<Frame>
  <img alt="Impact Impact Chart" />
</Frame>

The Impact Table compares users who performed the launch event and those who did not. For both groups of users, Mixpanel calculates the average number of times per day that users performed the metric event before the launch, after the launch, and the difference between the two (the delta).

The average number of times that users performed the metric event before the launch is calculated by:

$group\,average\,value = average\left( (group\,metric\,event\,count \div group\,user\,count) \over (day\,count) \right)$

The average rate is calculated before the first day of the launch event, after the launch event, and the report also displays the difference between those rates. These values are reported in the three sections of the table.

A relative delta is also present in each section of the table.

### Pre-Launch

The Pre-Launch section contains columns for adopters, non-adopters, and the relative delta between them. Adopters are users who perform the launch event after launch, and non-adopters are users who do not perform the launch event after the selected launch date.

The relative delta is calculated using the equation:

$relative\,delta= { (adopter\,average - non\,adopter\,average) \over (non\,adopter\,average)}$

### Post-Launch

The Post-Launch section contains columns for actual adopters, non-adopters, unobserved counterfactuals of adopters, and the relative delta between them. Adopters are users who perform the launch event, and non-adopters are users who do not perform the launch event after the selected launch date.

The UCA value is the projected behavior of adopters if the launch event never happened. This calculation controls for any difference between the adopters and non-adopters that is not a result of the launch event. This value is calculated by the following, where NA is non-adopters, pre is pre-launch, and post is post-launch:

$UCA=\mu_{NA\,post} + ({\mu_{NA\,post}*\Delta_{relative\,pre})}$

The relative delta is calculated using the equation:

$relative\,delta= { (adopter\,average - non\,adopter\,average) \over (non\,adopter\,average)}$

### Impact

The Impact section of the table contains the final calculations that indicate if and by how much the launch event affected your impacted metrics. These calculations are the delta, the relative delta, and the confidence score.

The delta is the difference between the UCA and adopters in the post-launch period. The relative delta divides that value by the UCA.

Confidence indicates the statistical significance of the report calculations. [See below for details on the calculation of confidence](/docs/reports/apps/impact#confidence-calculation).

### Interpret the Results

In general, when the overall delta is positive and the confidence score is 95% or more, it indicates a successful launch. The most successful launches will see the rate at which adopters perform the metric event increase post-launch, while the same rate for the non-adopters remains relatively constant.

In the Impact Chart, look at the average gap in usage between the adopters and non-adopters. Typically, it is preferable for the increase in the gap to be mostly driven by an increase in the rate at which adopters perform the metric event, rather than a decrease in the rate at which non-adopters perform it.

### Confidence Calculation

Impact includes confidence to indicate the statistical significance of the report calculations. Interpret the confidence as the probability that the final delta is primarily caused by the launch event, as opposed to existing by chance.

The confidence is calculated as a confidence interval using a cumulative distribution function while assuming a normal distribution.

The confidence variables are as follows:

* **X** = The number of events per day performed by adopters in the pre-launch period.
* **Y** = The number of events per day performed by adopters in the post-launch period.
* **A** = The number of events per day performed by non-adopters in their pre-launch period.
* **B** = The number of events per day performed by non-adopters in their post-launch period.
* **Y - X** = The difference in the number of events per day performed by adopters between post-launch and pre-launch periods.
* **B - A** = The difference in the number of events per day performed by non-adopters between the post-launch and pre-launch periods.
* The mean of **Y - X** over time is denoted by:

$\mu_{Y-X}$

* The mean of B-**A** over time is denoted by:

$\mu_{B-A}$

* The standard deviation of **Y - X** over time is denoted by:

$\sigma_{Y-X}$

* The standard deviation of **B - A** over time is denoted by:

$\sigma_{B-A}$

With the variables assigned, the calculations for confidence are as follows:

$\mu_{final} = \mu_{Y-X} - \mu_{B-A}$

$\sigma_{final} =\sqrt{{\sigma_{Y-X}^2 \over N_{Y-X}} - {\sigma_{B-A}^2 \over N_{B-A}}}$

$z_{score} = \left|\mu_{final} \over \sigma_{final}\right|$

$p_{value} = 1-cdf(z_{score})$

$confidence = 1 - p_{value}$

### Causal Impact

Causal impact uses propensity score methods (a class of causal inference techniques) to refine Impact report results by controlling for self-selection bias. Self-selection bias refers to the tendency of active users to be likely to use your new feature and to perform the impacted metrics, independent of the launch.

Propensity score methods control for self-selection bias by simulating what would occur in a hypothetical, randomized A/B test.

Propensity scores are estimated using L2-regularized logistic regression. Features are selected via chi-square feature selection, zero-imputed for missing values, and users without any feature data are excluded.

To learn more about Causal Impact in detail, read this [Mixpanel Whitepaper](https://storage.googleapis.com/cdn-mxpnl-com/site_media/pdf/Mixpanel_Causal_Inference_Whitepaper.pdf).

Click **View Causal Impact** to use the propensity matching model.

<Frame>
  <img alt="Impact Causal Report" />
</Frame>

Please note that Causal Impact can take up to a few minutes to calculate results. Causal Impact requires at least 200 total samples and a minimum of 10 features. Each stratum must contain at least 3 treated (adopter) and 3 control (non-adopter) units.

### Propensity Score Stratification

Propensity score stratification addresses self-selection bias by comparing adopters and non-adopters who are equally as likely to perform the launch event.

Users are broken into 10 subclasses after the propensity matching model runs. The 10 subclasses are deciles based on the logit of the estimated propensity score, and weights across subclasses are based on subclass size. Each subclass contains adopters and non-adopters that have a similar likelihood of performing the launch event. Mixpanel determines the rate at which the adopters and non-adopters performed the impacted metric and calculates the difference for each subgroup.

Lastly, we average those values across all 10 subclasses to produce the Average Treatment Effect, or ATE. The ATE indicates, on average across all users, how many more or fewer times per day the newly launched feature led users to perform the impacted metric.

### Causal Impact Chart

The Causal Impact chart plots the ATE on each Impacted Metric. The dark line shows the ATE, and the surrounding box shows the 95% confidence interval bounds of the ATE.

When the confidence interval does not include 0, it indicates that the positive or negative effect of the launch event is statistically significant.

### Causal Impact Table

The Causal Impact Table provides additional detail on the treatment effects on the impacted metrics in each subclass.

For each impacted metric, the table displays the ATE, the ATT (the average treatment effect on the treated), the 95% confidence interval (CI) bounds for those, and the number of adopters and non-adopters in the calculation.

Click the caret to expand the impacted metric row into the 10 subclasses considered. For each subclass, Mixpanel displays the number of matched adopters in the subclass, the number of matched non-adopters in the subclass, and the [rates at which each performed the impacted metric](/docs/reports/apps/impact). The Delta column shows the difference between those rates.

Note that these values can differ from those reported in the Adoption and Impact Trends charts because Causal Impact only considers users who can be found to have a similar propensity to perform the launch event to other users.

### Interpret the Causal Impact Results

Mixpanel's causal model is confident that your new feature successfully changed the rate at which users perform the impacted metric if the ATE on any impacted metric is positive and the 95% confidence interval does not contain zero. This holds as long as there are no confounding factors outside of your event data.


# JQL
Source: https://docs.mixpanel.com/docs/reports/apps/jql

Create custom queries using Javascript code

> ❗️JQL is currently in maintenance mode. We recommend discontinuing use of JQL and using an [alternate method](/docs/export-methods) to get the data you need. Below are alternatives for common use cases and you need help deciding the best method for you, reach out to [support](https://mixpanel.com/contact-us/support).
>
> * Raw Event export: [Export API](/reference/raw-data-export-api) or [Data Pipelines](/docs/data-pipelines)
> * User Profile export: [Engage Query API](/reference/engage-query) or [Data Pipelines](/docs/data-pipelines)
> * Other reporting: [Query API](/reference/query-api) or in-app [Core Reports](/docs/reports)
>
> ❗️JQL is a self-serve tool. If you choose JQL, your developer team will be responsible to write and maintain the query logic.

The JQL JavaScript code must define a `main()` function. This JavaScript will be compiled, and the `main()` function will be executed by the query engine. The return value of `main()` must be a sequence of zero or more transformations applied to a collection of events, user records or joined records.<br />Events are retrieved by calling the `Events()` function.

For example, the following query counts the number of events that happened on one day in 2016:

```javascript theme={"system"}
function main() {
  return Events({
    from_date: "2016-01-04",
    to_date: "2016-01-04"
  }).reduce(mixpanel.reducer.count());
}
```

## Querying Events

The events collection is fetched by calling `Events()` with a single object argument that describes what events should be fetched.

```javascript theme={"system"}
function main() {
  // Get all signups and purchases by users with email addresses
  // from Yahoo or Gmail between January 1st and January 2nd
  return Events({
    from_date: '2016-01-01',
    to_date: '2016-01-02',
    event_selectors: [
        {event: 'signup', label: 'Signup'},
        {event: 'purchase', selector: '"yahoo" in properties["$email"]',
            label: 'Purchase (Yahoo)'},
        {event: 'purchase', selector: '"gmail" in properties["$email"]',
            label: 'Purchase (Gmail)'}
    ]
  })
}
```

## Event Object Specification

The event objects returned from `Events()` have the following attributes:

| Attribute            | Type                 | Description                                                                                                                                                                                                                                                    |
| :------------------- | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **name**             | <span>string</span>  | The name of the event.                                                                                                                                                                                                                                         |
| **distinct\_id**     | <span>string</span>  | The distinct\_id of the user associated with this event. If distinct\_id was not sent with the event, this will be undefined.                                                                                                                                  |
| **time**             | <span>integer</span> | The timestamp of the event, expressed as milliseconds since January 1, 1970 in your project's timezone, not UTC.                                                                                                                                               |
| **sampling\_factor** | <span>float</span>   | The rate at which this event was sampled (if you are using Mixpanel's sampling feature). 0.05 means the event is being sampled at 5%. This is important for getting accurate counts of sampled events. If you are not using sampling, this will always be 1.0. |
| **properties**       | <span>object</span>  | An object containing all of the properties of the event.                                                                                                                                                                                                       |

## Querying Profiles

Profile data is fetched by calling `People()`

| Argument            | Type                                          | Description                                                                                                                                                                                                                                                                                                                                                                                        |
| :------------------ | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **user\_selectors** | <span>array</span><br /><span>optional</span> | An optional list of \{selector: "Segmentation expression"} objects that restrict user records retrieved. A record is retrieved if it matches any of the expressions. Segmentation expression in user selectors expressions can only access user properties, not event properties. See also information on Segmentation expressions as [argument to Events()](/reference/segmentation-expressions). |

```javascript theme={"system"}
function main() {
  // get all users who signed up in 2016
  return People(
  ).filter(function(user){
    return user.properties.signup_date >= new Date("2016-01-01") &&
           user.properties.signup_date < new Date("2017-01-01");
  });
}
```

or, equivalently:

```javascript theme={"system"}
function main() {
  // get all users who signed up in 2016
  return People({
    user_selectors:[{selector:
        'has_prefix(string(user["signup_date"]), "2016")'}]
  });
}
```

## User Object Specification

The user objects returned from `People()` have the following attributes:

| Attribute        | Type                 | Description                                                                                                                                                 |
| :--------------- | :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **distinct\_id** | <span>string</span>  | The distinct\_id of the user.                                                                                                                               |
| **time**         | <span>integer</span> | The timestamp of the most recent user record update, expressed as milliseconds since January 1, 1970 in your project's timezone, not UTC.                   |
| **last\_seen**   | <span>integer</span> | The timestamp of the most recent user record update provided via Set() method, expressed as milliseconds since January 1, 1970, in your project's timezone. |
| **properties**   | <span>object</span>  | An object containing all of the properties of the user.                                                                                                     |

## Combining Events and Profiles

You can combine (join) events and profile data using `join(Events(), People())` expression.

Apart from joined collection, join() accepts an optional third argument: an object with join options:

| Argument      | Type                                           | Description                                                                                                                                                                                                                                                                                                                                                                                  |
| :------------ | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **type**      | <span>string</span><br /><span>optional</span> | Join type: full, left, right or inner. Default is a full join.                                                                                                                                                                                                                                                                                                                               |
| **selectors** | <span>string</span><br /><span>optional</span> | An optional list of \{event: "event name", selector: "Segmentation expression"} objects that restrict event/user pairs retrieved. A record is retrieved if it matches any of the selector objects. To learn more about selectors, refer to [Segmentation API](/reference/segmentation-expressions). Segmentation expressions in join() selectors can access both events and user properties. |

```javascript theme={"system"}
function main() {
  return join(
    Events({
      from_date: "2016-01-01",
      to_date: "2016-06-01",
    }),
    People(),
    // Fetch tuples that satisfy multiple conditions:
    // * They're both event and user records.
    // * Event is sent from US.
    // * User age is above thirty.
    {
      type:"inner",
      selectors:[{selector:
        'properties["country"] == "US" and user["age"] > 30'}]
    }
  );
}
```

## Joined Object Specification

The objects returned from `join()` have the following attributes:

| Attribute        | Type                | Description                                                                                                                                           |
| :--------------- | :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **distinct\_id** | <span>string</span> | The distinct\_id of both event and matching user.                                                                                                     |
| **event**        | <span>object</span> | Event object. For users with no events, this property is undefined                                                                                    |
| **user**         | <span>object</span> | User object with distinct\_id matching the event. For events without distinct id or when there's no matching user record, this property is undefined. |

## join() Operation Details

You cannot apply any transformations to the collections inside `join()`. For example, this is not legal: `join(Events(...).map(...)`, `People(...).filter())`

## Passing Parameters to a Query

The query engine creates and populates a `params` object inside the global context. The object is constructed from a JSON blob passed as the params argument to the JQL HTTP endpoint.

Query parameters allow you to write more flexible and reusable queries. We recommend populating Events `from_date/to_date` using params to make the query code reusable across different date ranges.

For example, you could pass these params:

```javascript theme={"system"}
params = {
  start_date: "2016-01-01",
  end_date: "2016-01-10",
  event: "View Blog"
}
```

to this query:

```javascript theme={"system"}
function main() {
  return Events({
    from_date: params.start_date,
    to_date: params.end_date,
  }).filter(function(event) { return event.name == params.event })
}
```

Alternatively, and more efficiently, you can pass multiple events as a list in a `params` object using `_.map`.

For example, you could pass these params:

```javascript theme={"system"}
params = {
  start_date: "2016-01-01",
  end_date: "2016-01-10",
  events: ["View Blog", "View Landing Page", "pageview"]
};
```

to this query:

```javascript theme={"system"}
function main() {
  return Events({
    from_date: params.start_date,
    to_date: params.end_date,
    event_selectors: _.map(params.events, event => ({event: event}))
  });
}
```

# Transformations

Transformations are applied to collections, taking one collection as input and producing another. A transformation takes a user-defined function (or a built-in function) that controls how the transformation works.

The JQL API provides the following set of transformations, which can be chained together to do complex analysis.

## filter(function(item) )

Filter the collection by calling the provided function on each of its elements. If the function evaluates to true, keep the element. Otherwise, discard it.

```javascript theme={"system"}
// filter for "login" events from users who signed up in January.
function main() {
  return join(
      Events({
        from_date: "2016-01-01",
        to_date: "2016-04-01"
      }),
      People())
  .filter(function(tuple) {
    return tuple.event && tuple.user &&
        tuple.event.name == "login" &&
        tuple.user.properties.signup_date >= new Date("2016-01-01") &&
        tuple.user.properties.signup_date <= new Date("2016-02-01");
  });
}
```

## map(function(item) )

Build a new collection by applying the provided function to each element of the input collection. The output collection contains the return value of the provided function for each element in the input collection, so an input collection of size N will result in an output collection of size N.

```javascript theme={"system"}
// Extract the email domain name for further analysis.
// The resulting collection contains strings.
function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-01-07"
  })
  .map(function(event) {
    var pos = event.properties.$email.indexOf("@");
    return event.properties.$email.slice(pos + 1);
  });
}
```

## reduce(\[reducer function(s)])

`reduce()` turns the input collection into just a single value.

It takes one argument - a reducer or list of reducer functions, which must implement the following signature:

```javascript theme={"system"}
function(accumulators, items) {
  // Combine previously-aggregated "accumulators"
  // with new "items" and return the result.
}
```

A reducer function accepts two arguments: an array of its previous results (accumulators), and an array of items to reduce. The first argument - accumulators - is used to break down the initial set of values into many calls of the reducer function. JQL runs the reduction in a hierarchical fashion, where some subsets of inputs are reduced to accumulator values first, and multiple accumulator values are combined subsequently. There are no guarantees on the order of input.

The example below is using a reduce function that counts elements up.

```javascript theme={"system"}
// Count events.

function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-01-07"
  })
  .reduce(function(previous_counts, events) {
    var count = events.length;
    for (var i = 0; i < previous_counts.length; i++) {
        count += previous_counts[i];
    }
    return count;
  });
}
```

Counting is a common use case, so JQL provides a built-in `mixpanel.reducer.count()` that could be used in place of the snippet above.

```javascript theme={"system"}
// Count events.

function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-01-07"
  })
  	.reduce(mixpanel.reducer.count());
}
```

While there are built-in reducer methods to address common use cases, a reducer function is flexible and can be used to aggregate inputs into a single value.  For example, returning the earliest timestamp and latest timestamp could be done using a reducer function.

```javascript theme={"system"}
// Return earliest timestamp and latest timestamp of events
function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-01-07"
  })
  .reduce(function(accumulators, items){
    var result = {
      earliest: null,
      latest: null
    };
    for (var i = 0; i < accumulators.length; i++) {
      result.earliest = minimum(result.earliest, accumulators[i].earliest);
      result.latest = Math.max(result.latest, accumulators[i].latest);
    }
    for (var j = 0; j < items.length; j++) {
      result.earliest = minimum(result.earliest,items[j].time);
      result.latest = Math.max(result.latest,items[j].time);
    }
    return result;
  });
}

// Helper function to return minimum value (ignoring null)
function minimum(x,y) {
  if (x === null) {
    return y;
  }
  if (y === null) {
    return x;
  }
  return Math.min(x,y);
}
```

## groupBy(\[keys], \[reducer function(s)])

Group the collection according to the provided list of keys, then apply the provided reducer function(s) to each group. The underlying action of `groupBy()` is similar to the one of `reduce()` - aggregating many input values into one. However, the output collection is different: while `reduce()` aggregates everything into a single value, `groupBy()` produces a collection with the following structure:

```json Result theme={"system"}
{
  "key": <composite group key>,
  "value": <return value of reducer function or list of values if composite reducer supplied>
}
```

The group key is computed from a key specification - the first argument of the `groupBy()` transformation. This argument is a list containing property names or functions that compute a key from a collection element.

If you use property names as keys, you can use dot notation (i.e., a ".") to access values inside nested objects. For example, if you had a list of objects that looked like

`{"item": "t-shirt", "info": {"size": "XL"}}`, you could group by

`["item", "info.size"]`

It is common to use dot notation to group on event properties. For example, in `Events(...).groupBy(['properties.$city', 'properties.$browser'], ...)`, each unique combination of City and Browser becomes a group, so the following groups may be output:

* \["New York", "Firefox"]
* \["San Francisco", "Firefox"]
* \["San Francisco", "Safari"]
* etc.

As with a list of keys, the `groupBy()` can accept a single reducer or a list of reducer functions. Each reducer supplied in this argument is then applied to each group key. When a list of reducer functions is provided, the value for each group key will be a list of the results from each function. Reducer functions can include both built-in and custom reducer functions. The signature of a reduce function provided to a `groupBy()` is:

```javascript theme={"system"}
function(accumulators, items) {
    // Analyze items, return accummulators
}
```

```javascript theme={"system"}
function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-02-01",
    event_selectors: [{event: "Change Plan"}],
  })
  .groupBy(
    [
      "properties.New Plan",
      "properties.Previous Plan",
      // use a function to dynamically calculate a day of the event.
      function(ev) {
        return (new Date(ev.time)).toDateString();
      }
    ],
    [
      mixpanel.reducer.count(),
      mixpanel.reducer.any()
    ]
  );
}
```

The group key can only include scalars - strings, numbers, booleans, nulls. If a group-by property evaluates to a list of multiple scalars, `groupBy()` can treat in two different ways:

Inline that list into group key (this is the default behavior). The following query computes, for every sequence of notification campaigns each user participated in, the total number of profiles that have that sequence:

```javascript theme={"system"}
function main() {
  return People().groupBy(["properties.$campaigns"],
                          mixpanel.reducer.count());
}
```

Create a different group key for each list element. The following query computes the number of users that participated in each campaign.

```javascript theme={"system"}
function main() {
  return People().groupBy(
        mixpanel.multiple_keys(["properties.$campaigns"]),
        mixpanel.reducer.count())
}
```

A single query can use both key treatments, even with the same property, like in a query below:

```javascript theme={"system"}
function main() {
  return People().groupBy([
          mixpanel.multiple_keys(["properties.$campaigns"]),
          "properties.$campaigns"],
        mixpanel.reducer.count());
}
```

## groupByUser(\[optional additional keys], \[reducer function(s)])

Group events by distinct\_id and, optionally, additional keys, then apply the provided reducer function(s) to each group.

This transformation is a specialization of `groupBy()` that guarantees that the reduce function(s) will process all events of a single user in temporal order.

This guarantee is reflected in the signature of the reduce function provided to `groupByUser()`:

```javascript theme={"system"}
function(state, events) {
    // Analyze events, aggregate in state. Return the new state.
}
```

Its first argument is a single accumulator or a list of accumulators, but not an array of accumulators as used in `groupBy()` and `reduce()` cases. The accumulator value is always the value of last call to the reduce function, with an initial value of Undefined.

The difference in signature means that reducer function implementations can not be used interchangeably between `groupByUser()` and `groupBy()/reduce()`. Built-in reducers, however, can be used in both contexts.

The output of `groupByUser()` is a collection of objects with the following structure:

```json theme={"system"}
{
  "key": [<user distinct_id>] + <optional additional keys>,
  "value": <return value of reducer function(s)>
}
```

`groupByUser()` can only be applied to the source data collection. This means it must be called either on the `Events()`, `People()` or `join()` collections directly, or on the collection returned by `Events({ ... }).filter(...) or People({ ... }).filter(...) or join( ... ).filter(...)`

A very common use-case for `groupByUser()` is to compute some property of each user based on their behavior. For example, the code below computes what events users typically perform after a "login" event.

**Frequencies of Events Following "Login":**

```javascript theme={"system"}
// For each user, find how often they perform each event
// after signing up.
function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-02-01"
  })
  .groupByUser(function(state, events) {
    state = state || { distribution: {} };
    if (events.length == 0) {
        return state;
    }
    for (var i = 0; i < events.length - 1; ++i) {
        if (events[i].name == "login") {
            state.distribution[events[i + 1].name] =
                state.distribution[events[i + 1].name] || 0;
            ++state.distribution[events[i + 1].name];
        }
    }
    // Previous call for this user may have contained
    // "login" as the last event.
    if (state.last_event_login) {
        state.distribution[events[0].name] =
            state.distribution[events[0].name] || 0;
        ++state.distribution[events[0].name];
    }
    // If last event is "login", next call should see that.
    if (events[events.length - 1].name == "login") {
        state.last_event_login = true;
    }
    return state;
  });
}
```

It is possible to compute more fine-grained aggregation with `groupByUser()` by providing a list of additional keys in the first argument. User distinct\_id always remains the implicit first key.

The following example computes, for each user and each day, when they did their first event on that day.

**Multiple Groups per User:**

```javascript theme={"system"}
// figure out the hour where the most users do something
// for the first time that day
function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-01-07"
  })
  // group the events for each user by day, then get
  // the first hour we saw them in each of those days.
  .groupByUser([getDay], function(first_hour, events) {
    if (first_hour === undefined) {
      first_hour = (new Date(events[0].time)).getHours();
    }
    return first_hour;
  })
}

function getDay(event) {
  return (new Date(event.time)).toISOString().split('T')[0];
}
```

`groupByUser()` places the same restriction on group keys as `groupBy()` does: a key can only include scalars, and list keys can be treated in two different ways depending on presence of the `mixpanel.multiple_keys()` decorator.

## flatten()

Flatten the collection by inlining array elements of the input collection. The contents of arrays in the input collection are placed into the output collection. Input elements that are not arrays are forwarded into the output collection without modification.

```javascript theme={"system"}
// Compute percentiles on counts for number
// of events each user has done.
function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-01-07"
  })
  // Compute the number of events for each user.
  .groupByUser(mixpanel.reducer.count())
  .reduce(mixpanel.reducer.numeric_percentiles('value',
      [10, 25, 50, 75, 90]))
  .flatten();
}
```

## sortAsc(accessor)

Sort the input collection by the provided sort key - either property name or a function. Sort key must be a scalar.

```javascript theme={"system"}
// Find the users who have used the product the least.
function main() {
    return Events({
      from_date: "2016-01-01",
      to_date: "2016-01-07"
    })
    .groupBy(['properties.$email'], mixpanel.reducer.count())
    .sortAsc('value');
}
```

## sortDesc(accessor)

Similar to `sortAsc()`, but sort in descending order.

```javascript theme={"system"}
// Find the most popular events.
function main() {
    return Events({
      from_date: "2016-01-01",
      to_date: "2016-01-07"
    })
    .groupBy(['name'], mixpanel.reducer.count())
    .sortDesc('value');
}
```

# Chained Aggregations

Chaining `groupBy()` operations in JQL can be used to compute complex statistics. The simplest case for chained aggregations is the query below that computes the number of unique users that had events from each country:

```javascript theme={"system"}
function main() {
  return Events({
    from_date:"2016-01-01",
    to_date:"2016-06-01",
  })
  .groupByUser(["properties.country"], mixpanel.reducer.null())
  .groupBy([mixpanel.slice("key", 1)], mixpanel.reducer.count());
}
```

The first `.groupByUser()` transformation results in a collection of objects with the following structure: `{key:[distinct_id, country], value: null}`.

The second aggregation instructs JQL to strip off position 0 of the key holding the distinct\_id, and aggregate again, counting results up. The result is going to be a number of unique users for each country.

`mixpanel.slice("key", <start>, <optional limit>)` is a built-in function that instructs JQL to strip away key components that don't fall into \[start, limit) interval, coalescing some groups and producing a more coarse grouping.

This approach can be extended for computing more complex statistics. For example, here is median over a maximum number of events users had in each country:

```javascript theme={"system"}
function main() {
  return Events({
    from_date:"2016-01-01",
    to_date:"2016-06-01",
  })
  .groupByUser(["properties.country"], mixpanel.reducer.count())
  .groupBy([mixpanel.slice("key", 1)], mixpanel.reducer.max("value"))
  .reduce(mixpanel.reducer.numeric_percentiles("value", 50));
}
```

<Note>
  **NOTE**

  An important note on data serialization: the query engine is sometimes forced to serialize and transfer collections during transformations using JSON. Complex data types such as functions and dates are not preserved, so you should avoid storing these types in accumulator objects.
</Note>

# JQL Builtins

We provide a set of useful helper functions for use with the `groupBy()`,` groupByUser()`, and `reduce()` transformations. These functions are provided by the query engine, so they are available with no extra work to you.

Some of built-in reducers, e.g. `avg()` or `sum()`, compute statistics over numeric collections. Each of the numeric built-in reducers accepts an optional first argument - an accessor - that instructs it how to convert the input object to a numeric value.

An accessor can be a JavaScript function, a string with a dot-separated property path, or a built-in mapper function, like `mixpanel.numeric_bucket()`.

For example, the following query computes the average age of your users:

```javascript theme={"system"}
function main() {
  return People().reduce(mixpanel.reducer.avg("properties.age"));
}
```

This example makes use of the property name accessor to `mixpanel.reducer.avg()` built-in. A custom function could be used too; in the example below, that function computes length of an array property:

```javascript theme={"system"}
function main() {
  return People().reduce(mixpanel.reducer.avg(
    function(u) { return u.properties.$campaigns.length; }));
}
```

## mixpanel.reducer.count()

Count the number of elements in the collection (or group, if passed to groupBy()). For example, you could use groupBy() and this reducer to implement Mixpanel's Segmentation report.

**Example:**

```javascript theme={"system"}
// count the number of events between two dates
function main() {
  return Events({
    from_date: "2015-08-01",
    to_date: "2015-08-30"
  }).reduce(mixpanel.reducer.count());
}
```

**Result**

```json theme={"system"}
// 15834 total events
[15834]
```

```javascript theme={"system"}
// count the number of people of each age
function main() {
  return People().groupBy(["properties.age"],
    mixpanel.reducer.count());
}
```

```json Result theme={"system"}
[
  {
    "key": [0],
    "value": 109
  },
  {
    "key": [1],
    "value": 120
  },
  ...
]
```

## mixpanel.reducer.sum(accessor)

Sum a collection of numeric values together.

| Argument     | Type                  | Description                                                              |
| :----------- | :-------------------- | :----------------------------------------------------------------------- |
| **accessor** | <span>function</span> | Optional property accessor to retrieve a numeric property from the item. |

```javascript theme={"system"}
// compute the total number of notification hits
function main() {
  return People()
    .reduce(mixpanel.reducer.sum(
      function(u) { return u.properties.$campaigns.length; }));
}
```

```json Result theme={"system"}
[11301]
```

## mixpanel.reducer.numeric\_summary(accessor)

Get a numeric summary of a collection. Returns the count, sum, sum of squares, average and standard deviation for a collection of numeric values.

| Argument     | Type                  | Description                                                              |
| :----------- | :-------------------- | :----------------------------------------------------------------------- |
| **accessor** | <span>function</span> | Optional property accessor to retrieve a numeric property from the item. |

```javascript theme={"system"}
// understand page load times
function main() {
  return Events({
    from_date: "2015-10-01",
    to_date: "2015-10-02",
    event_selectors: [{event: "pageview"}],
  })
  .reduce(mixpanel.reducer.numeric_summary('properties.load_time_ms'));
}
```

```json Result theme={"system"}
// count = 221 events
// sum(load time) == 32624 milliseconds
// sum squares = 9199564 ms^2
[{ "count": 221, "sum": 32624, "sum_squares": 9199564, "avg": 147.61991, "stddev": 140.838023 }]
```

## mixpanel.reducer.avg(accessor)

Compute the average of a numeric collection. `avg()` is a shortcut replacement for the two-step process: aggregate with `numeric_summary()`, and follow-up with a `.map()` step that computes average.

| Argument     | Type                  | Description                                                              |
| :----------- | :-------------------- | :----------------------------------------------------------------------- |
| **accessor** | <span>function</span> | Optional property accessor to retrieve a numeric property from the item. |

```javascript theme={"system"}
function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-06-01",
    event_selectors: [{event:"pageview"}]
  })
  .reduce(mixpanel.reducer.avg("properties.load_time_ms"));
}
```

```json Result theme={"system"}
[148.9087]
```

## mixpanel.reducer.numeric\_percentiles(accessor, percentiles spec)

Compute percentiles of a numeric collection. Note: this built-in samples the numeric stream; it's output will differ from exact percentile value up to a fixed error bound. The result may also fluctuate between runs.

| Argument       | Type                  | Description                                                               |
| :------------- | :-------------------- | :------------------------------------------------------------------------ |
| **accessor**   | <span>function</span> | name of a numeric property or a function that computes number from input. |
| **percentile** | <span>number</span>   | A percentile number, in (0, 100) interval (alternative 1).                |
| **percentile** | <span>array</span>    | Array of percentile numbers (alternative 2).                              |

```javascript theme={"system"}
// Find median page load time
function main() {
  return Events({
    from_date: "2015-06-01",
    to_date: "2016-06-01",
    event_selectors: [{event: "pageview"}],
  })
  .reduce(mixpanel.reducer.numeric_percentiles(
       "properties.load_time_ms", 50));
}
```

```json Result theme={"system"}
[118]
```

```javascript theme={"system"}
// Find 90th, 95th, 99th, 99.9th percentiles of page load time.
function main() {
  return Events({
    from_date: "2015-06-01",
    to_date: "2016-06-01",
    event_selectors: [{event: "pageview"}],
  })
  .reduce(mixpanel.reducer.numeric_percentiles(
       "properties.load_time_ms", [90, 95, 99, 99.9]));
}
```

```json Result theme={"system"}
[
 [
     {"percentile":90,"value":356},
     {"percentile":95,"value":468},
     {"percentile":99,"value":732},
     {"percentile":99.9,"value":1725}
 ]
]
```

## mixpanel.reducer.min(accessor)/max(accessor)

Compute minimum (or maximum) element in a numeric collection.

| Argument     | Type                  | Description                                                                  |
| :----------- | :-------------------- | :--------------------------------------------------------------------------- |
| **accessor** | <span>function</span> | Name of a numeric property, or a function that computes a number from input. |

```javascript theme={"system"}
// Find minimum page load time.
function main() {
  return Events({
    from_date: "2015-06-01",
    to_date: "2016-06-01",
    event_selectors: [{event: "pageview"}],
  })
  .reduce(mixpanel.reducer.min("properties.load_time_ms"));
}
```

```json Result theme={"system"}
[0]
```

## mixpanel.reducer.min\_by(accessor)/max\_by(accessor)

Find the element in a collection that gives the minimum (or maximum) value of a numeric property.

| Argument     | Type                  | Description                                                                  |
| :----------- | :-------------------- | :--------------------------------------------------------------------------- |
| **accessor** | <span>function</span> | Name of a numeric property, or a function that computes a number from input. |

```javascript theme={"system"}
// Find the pageview event with lowest load time.
function main() {
  return Events({
    from_date: "2015-06-01",
    to_date: "2016-06-01",
    event_selectors: [{event: "pageview"}],
  })
  .reduce(mixpanel.reducer.min_by("properties.load_time_ms"));
}
```

```json Result theme={"system"}
[
 {
     "name":"pageview",
     "distinct_id":"8bcf7259-5c6c-4b10-9b8a-34148607aa95",
     "time":1437541412000,
     "sampling_factor":1,
     "properties":{
         "$email":"Sylvia.Harper@outlookx.com",
         "$import":true,
         "country":"MX",
         "load_time_ms":0
     }
 }
]
```

## mixpanel.reducer.top(limit)

Limit the response to the top N values of a collection. This function expects the input collection to be of the `groupBy()` format: `{ "key": [...], "value": <numeric value> }`. The output of this function is a collection containing a single item, the list of the top N items.

| Argument  | Type                 | Description                   |
| :-------- | :------------------- | :---------------------------- |
| **limit** | <span>integer</span> | The number of items to return |

```javascript theme={"system"}
// get the top 3 countries sending any event
  function main() {
  return Events({
    from_date: "2015-06-01",
    to_date: "2016-06-01",
    event_selectors:[{event: "pageview"}]
  })
  .groupBy(["properties.country"], mixpanel.reducer.count())
  .reduce(mixpanel.reducer.top(3));
}
```

```json Result theme={"system"}
[
  [
    {
      "key": ["USA"],
      "value": 1234
    },
    {
      "key": ["MEX"],
      "value": 678
    },
    {
      "key": ["CAN"],
      "value": 345
    }
  ]
]
```

## mixpanel.reducer.applyGroupLimits(limit spec)/

Limit the response of each group to the top N values of a collection and optionally to the top N values of the entire collection. This function expects the input collection to be of the `groupBy()` format: `{ "key": [...], "value": <numeric value> }`. The output of this function is a collection with the following structure.

| Argument   | Type                | Description                                 |
| :--------- | :------------------ | :------------------------------------------ |
| **limits** | <span>array</span>  | Array of limits per group.                  |
| **global** | <span>number</span> | limit Maximum number of results to display. |

```javascript theme={"system"}
// Get the top events by user, by date, limited to the top 12 results
function main() {
  return Events({ // Collect our events
    from_date: '2016-01-01',
    to_date:   '2016-01-31',
  }) // Group the events by multiple keys
  .groupBy(["name","properties.$email","properties.signup_date"], mixpanel.reducer.count())
  // Sort the results in the desired order by the desired property
  .sortDesc('value')
  // Limit the results of each group displayed
  .applyGroupLimits([5,5,5], 12)
}
```

```json Result theme={"system"}
[
  {
    "key": [
      "login",
      "Ralph.Vargas@aolx.com",
      "2015-11-29T05:55:40"
    ],
    "value": 30
  },
  {
    "key": [
      "login",
      "Frances.Mendoza@gmailx.com",
      "2015-12-12T06:50:28"
    ],
    "value": 28
  }, ...
  {
    "key": [
      "View Blog",
      "Henry.Murray@gmailx.com",
      "2015-12-22T20:14:32"
    ],
    "value": 8
  }
]
```

## mixpanel.reducer.object\_merge()

Merge a collection of JavaScript objects into a single object. Numeric leaf values are summed.

```javascript theme={"system"}
// alternate way of calculating the same thing as
// mixpanel.reducer.numeric_summary()
function main() {
  return Events({
    from_date: "2015-10-01",
    to_date: "2015-10-02",
    event_selectors: [{event: "pageview"}],
  })
  .map(function(event) {
    var load_time_ms = event.properties.load_time_ms;
    return {
      count: 1,
      sum: load_time_ms,
      sum_squares: load_time_ms * load_time_ms
    }
  })
  .reduce(mixpanel.reducer.object_merge());
}
```

```json Result theme={"system"}
[{ "count": 221, "sum": 32624, "sum_squares": 9199564}]
```

## mixpanel.reducer.any()

```javascript theme={"system"}
function main() {
  return Events({
    from_date: "2015-10-01",
    to_date: "2015-10-02",
  })
  .filter(function(e) { return e.properties.country == "US"; })
  .reduce(mixpanel.reducer.any());
}
```

```json Result theme={"system"}
[
  {
    "name": "pageview",
    "distinct_id": "75a54352-33c9-4606-9d5f-c5eca9b77b5d",
    ...
  }
]
```

## mixpanel.reducer.null()

Always return null.

```javascript theme={"system"}
// Dump distinct ids of users who had events in January 2016.
function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-01-31",
  })
  .groupByUser(mixpanel.reducer.null())
}
```

```json Result theme={"system"}
[
   {"key": "1f83aed1-63c4-48ec-aa44-91b90fc1917d", "value": null},
   ...
]
```

## mixpanel.numeric\_bucket(accessor, buckets spec)

Bucketize a numeric value by normalizing it to the lower boundary of the bucket it falls into. It is commonly used to reduce the number of distinct keys when aggregating over numeric values.

| Argument | Type                | Description                                                                              |
| :------- | :------------------ | :--------------------------------------------------------------------------------------- |
| **spec** | <span>array</span>  | List of bucket boundaries (alternative 1).                                               |
| **spec** | <span>object</span> | with bucket\_size and offset fields specifying regular bucket intervals (alternative 2). |

```javascript theme={"system"}
// Bucketize all users into five age groups.
function main () {
  return People().groupBy(
     [mixpanel.numeric_bucket('properties.age', [0, 5, 18, 30, 60])],
     mixpanel.reducer.count());
 }
```

```json Result theme={"system"}
[
  {
    "key": [0],
    "value": 539
  },
  {
    "key": [5],
    "value": 1041
  },
  ...
]
```

```javascript theme={"system"}
// Bucketize all users into regular buckets by event count.
function main() {
  return Events({
    from_date: "2015-10-01",
    to_date: "2015-10-02",
  }).groupByUser(mixpanel.reducer.count())
    .groupBy(
      [mixpanel.numeric_bucket('value', {bucket_size: 10, offset:1})],
      mixpanel.reducer.count());
}
```

```json Result theme={"system"}
[
  {
    "key": [1],
    "value": 422
  },
  {
     "key": [11],
     "value": 15
  }
]
```

## mixpanel.to\_number(accessor)

Convert input into a number. mixpanel.to\_number() is commonly used when executing numeric aggregations over a collection of mixed non-numeric data. When unable to interpret input as a number, return undefined.

| Argument     | Type                  | Description                                             |
| :----------- | :-------------------- | :------------------------------------------------------ |
| **accessor** | <span>function</span> | Name of property to convert (or a javascript function). |

```javascript theme={"system"}
// Compute the distribution of signup times
function main() {
  return People()
    .reduce(mixpanel.reducer.numeric_summary(
      mixpanel.to_number('properties.signup_date')
    ));
}
```

```json Result theme={"system"}
[
  {
    "count": 4411,
    "sum": 6369278974417,
    "sum_squares": 9.1971e+21,
    "avg": 1443953519.477896,
    "stddev": 5988562.937055
  }
]
```

## mixpanel.numeric\_bucket()

`mixpanel.numeric_bucket()` can be used to segment events over calendar period, when applied to time property.

```javascript theme={"system"}
function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-01-30",
  }).groupBy([mixpanel.numeric_bucket('time', {bucket_size: 86400 * 1000})],
             mixpanel.reducer.count());
}
```

JQL defines several constants with bucket specs for widely used time bucket boundaries, when applied to milliseconds since Unix epoch.

* `mixpanel.daily_time_buckets` - buckets for calendar days
* `mixpanel.weekly_time_buckets` - buckets for calendar weeks, starting on Monday
* `mixpanel.monthly_time_buckets` - buckets for calendar months
* `mixpanel.quarterly_time_buckets` - buckets for calendar quarters: Jan - Mar, Apr - Jun, ...
* `mixpanel.annual_time_buckets` - buckets for calendar years

The following is an equivalent of the query above.

```javascript theme={"system"}
function main() {
  return Events({
    from_date: "2016-01-01",
    to_date: "2016-01-30",
  }).groupBy([
    mixpanel.numeric_bucket('time', mixpanel.daily_time_buckets)],
    mixpanel.reducer.count());
}
```


# Signal
Source: https://docs.mixpanel.com/docs/reports/apps/signal

Quantify correlation between two events

<Note>
  Users on an Enterprise plan can access the Signal report. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

## Overview

Signal measures the association between a correlation event and a goal event and quantifies the correlation between the two. This facilitates a deeper understanding of the behaviors that drive customer conversions and can help guide product decisions.

## Use Cases

Using a social media app as an example can highlight the value of quantifying correlations between events.

The customer may want to understand the correlation between top events and users who like a video on the app. Building this query in Signal would involve selecting the target users and how the "like video" goal event is correlated with the top events.

<Frame>
  <img alt="Impact3" />
</Frame>

Values are returned after running the correlation. “channel subscribe” could have a strong positive correlation with liking a video; most of the users who subscribed to a channel liked a video.

<Frame>
  <img alt="Impact Correlation Events" />
</Frame>

This information can be used in future product decisions. By knowing that those who subscribed to a channel are more likely to like a video, it is possible to build tools to encourage video liking and, in the end, lead to a dramatic increase in the number of users interacting with creators.

## Quick Start

<Frame>
  <iframe />
</Frame>

By default, Mixpanel will build a query to show how your top 50 events correlate with 2nd week retention in the last quarter for all users. This translates to, “How do the top events correlate with two-week retention in the last quarter for all users?"

To access **Signal**, go to the Applications section on the bottom left-side of the screen, and then select **Signal**.

<Frame>
  <img alt="Signal Access" />
</Frame>

Signal queries require a minimum of 60 days' worth of data. Queries with less data history than that will return a calculation error. Signal currently supports filtering only by event properties. Custom events with profile property filters will now be shown in the event dropdown.

1. Determine and specify the target users. “All Users” is the default.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.13.57_PM.png" />
</Frame>

2. Select any event performed by the target user by clicking the **+** sign.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.13.57_PM_copy.png" />
</Frame>

3. Further filter by property by clicking "**+ Filter**" and selecting any properties, as well as the frequency of occurrence.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.19.21_PM.png" />
</Frame>

4. Determine and select the Goal Event and its properties. The goal event can be a specific event with a frequency (users did Goal Event at least x number of times) or one of the default Signal retention events calculated by Mixpanel.

<Frame>
  <img alt="Signal Query Builder" />
</Frame>

The default retention events available in Signal include:

* 2nd week retention: Users doing a specific action or set of actions in your project and then returning to do anything within two weeks.
* 3rd week retention: Users doing a specific action or set of actions in your project and then returning to do anything within three weeks.
* 4th week retention: Users doing a specific action or set of actions in your project and then returning to do anything within four weeks.
* 2nd month retention: Users doing a specific action or set of actions in your project and then returning to do anything within two months.

5. Determine and select the Correlation Event and its properties. It is possible to add up to ten different correlation events by clicking the "**+**" button at the bottom of the query builder.

* The correlation event can be [broken down by property](/docs/reports#breakdowns). To do this, select "**+ Breakdown**" and select the property to break the data down by.
* The correlation event can be [filtered by property](/docs/reports#event-inline-filters). To do this, select "**+ Filter**" and select the property and property value you want to filter by.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.22.08_PM.png" />
</Frame>

6. Select the time frame for the query and the users who are to be evaluated. It’s important to select a long enough time frame that allows users to complete both the correlation event(s) and the goal event.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.24.59_PM.png" />
</Frame>

7. Click **Correlate**.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.22.08_PM.png" />
</Frame>

## Interpreting Results

### Summary View

Each correlation will be represented by one card in the summary view results. The list-view will display the optimal action, correlation with the goal event, and key findings about the event. Results can be sorted by correlation strength or by Mixpanel opportunity score.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.32.35_PM.png" />
</Frame>

### Scores

By default, the results will be sorted by Opportunity. “Opportunity” is Mixpanel’s proprietary calculation of how important a given correlation might be. The correlation strength is calculated using the phi coefficient. [See here](/docs/reports/apps/signal#correlation) for more details on how Opportunity and correlation strength are calculated.

### Key Findings

The key findings presented are rarity analysis results and conversion measurements. Rarity defines how common or uncommon it is for users to complete an individual event. The conversion measurements qualify how likely a given conversion is to be helpful.

**Rarity Analysis** can be broken down into:

* Rare in user group.
* Never performed in user group.
* Uncommon in user group.
* Common in user group.
* Majority of user group performed.

**Conversion Measures** can be broken down into:

* No users converted to goal.
* Unlikely to be useful.
* Associated almost perfectly with not converting.
* Associated almost perfectly with converting.

### Detailed view

To access the detailed view, click on a card in the summary view.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.33.37_PM.png" />
</Frame>

The detailed view provides the correlation calculations for each event evaluated. This view uses a heat map to show the strength of the correlation with the goal event.

The x-axis represents the velocity, or the number of days it took users to complete the event (up to 15 days), and the y-axis shows the frequency of the event, or the number of times the event was done, up to ten times.

<Frame>
  <img alt="/DetailedView.png" />
</Frame>

### Optimal Action

The optimal action will be highlighted in green on the heat map.

The optimal action tells you how many times and in how many days your customers should trigger the event in order to achieve your optimal correlation. Frequency labels are listed below the action and provide precise information, based on the correlation, about when your users should complete the event. For example, if you have a music streaming app and want to see how a “Play Song” event correlates with two-week retention, you might see something like “Play song once within ten days” as an optimal action.

### Supporting Statistics

For each combination, Mixpanel will provide supporting statistics for further analysis:

* **Precision**: Percent of users who convert to your goal among those who did this event at least x times within y days.
* **False omission rate**: Percent of users who convert to your goal among those who did this event fewer than x times within y days.
* **Recall**: Percent of converted users who did this event at least x times within y days.
* **Fall-out**: Percent of unconverted users who did this event at least x times within y days.
* **Correlation**: Association between performing this event at least x times in y days and converting to your goal.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.35.27_PM.png" />
</Frame>

To see the calculations of the optimal correlation data, hover over the ƒx in the upper right-hand corner of the chart at the bottom of the heat map.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.35.35_PM.png" />
</Frame>

### Key Findings

Signal also presents two key findings, rarity analysis results and conversion measurements. Rarity defines how common or uncommon it is for users to complete an individual event. The conversion measurements qualify how likely a given conversion is to be helpful. For example, if all users are converting because the application forces this by design, then the conversion measurement will flag this as "unlikely to be useful".

### CSV Download

To download the results to a CSV, click the **Download CSV** icon in the upper right-hand corner of the Summary Results view or the Detailed Results view after you have run your correlation.

<Frame>
  <img alt="/Screen_Shot_2022-07-13_at_10.37.09_PM.png" />
</Frame>

## Reference

### New Users vs All Users

New users are users who have completed their first event in the selected time frame.

All users will look at all users in your Mixpanel project who have completed the event in the selected time frame.

### Download Glossary

* **Frequency:** Number of times, up to 10, a user should complete the event for the correlation.
* **Intervals:** Number of days, up to 15, when a user should complete the event for the correlation.
* **True positive:** Number of positive correlations that are correctly identified.
* **True negative:** Number of negative correlations that are correctly identified.
* **False positive:** Number of positive correlations that are incorrectly identified.
* **False negative:** Number of negative correlations that are incorrectly identified.
* **Correlation:** The association between your event and your goal event.
* **Precision:** Percent of users who convert to your goal among those who did this event at least x times within y days
* **Fall-out:** Percent of unconverted users who did this event at least x times within y days.
* **Recall:** Percent of converted users who did this event at least x times within y days.
* **False Omission Rate:** Percent of users who convert to your goal among those who did this event fewer than x times within y days.
* **Phi max:** A single number between -1 and 1 that indicates how closely an event moves toward your goal event, where 1 means that 100% of all users who did your goal event also did the event you are evaluating, and -1 means the opposite - 0% of users who did your goal event also did the event you are evaluating.
* **Mixpanel Opportunity Score:** Mixpanel’s proprietary calculation of how important a given correlation might be.

### Calculations

Signal calculates correlation using a well-known statistical algorithm called the phi coefficient. In addition to correlation, Mixpanel calculates what is called an opportunity score and also presents a list of key findings.

#### Correlation

The phi coefficient is a single number between -1 and 1, and it indicates how closely an event moves with your goal event. 1 means that 100% of all users who did the goal event also did the correlation event. -1 means that 0% of users who did the goal event also did the correlation event.

#### Opportunity Score

“Opportunity” is Mixpanel’s proprietary calculation of how important a given correlation might be. Opportunity helps pare down results by eliminating false positives and highlighting weak correlations that may be actionable. Based on this assessment, which determines how much an event impacts conversion on your goal, Mixpanel will tell you if there is an opening to make a change in your product or not.

Once we correlate, the results on the summary page will display the optimal action, correlation with the goal event, and our key findings about that optimal action.

The optimal action tells you how many times and in how many days your customers should trigger the event in order to achieve your optimal correlation. Frequency labels are listed below the action and provide precise information, based on the correlation, about when your users should complete the event. For example, if you have a music streaming app and want to see how a “Play Song” event correlates with two-week retention, you might see something like “Play song once within ten days” as an optimal action.

**Frequency Labels** -- \*these will be supplemented with temporal labels, i.e. At least 4 times in 10 days.\*

* Many times
* Just once
* At least x times
* Always avoid
* As few times as possible
* No strong correlations found
* Is complex

The correlation with the goal event presents to you the optimal correlation for the event and tells you whether this indicates a strong or weak association with your goal. We calculate the association using a well-known statistical measure called the phi coefficient. The phi coefficient is a single number between -1 and 1 that indicates how closely an event moves with your goal event.

Finally, we will display the key findings. The key findings contain the rarity analyses and the impact on conversion. The rarity analyses define how common or uncommon it is for users in your user group to complete your event, and the impact to conversion explains how the event impacts conversion to your Goal event (i.e., retention). These help you interpret the correlations. A certain event may have a strong correlation to a goal event, but may not have been completed by many users in your group, and thus is unlikely to be useful. Below, we have listed the different messages you can see as a part of the rarity analysis and the impact on conversion.

**Rarity Analyses**

* Rare in user group
* Never performed in user group
* Uncommon in user group
* Common in user group
* Majority of user group performed

**Conversion Measures**

No users converted to goal.

* Example: None of the users analyzed converted to the goal in question.

Unlikely to be useful.

* Example: There may be no correlation (positive or negative) between the two events.

Associated almost perfectly with not converting. Something might be off here.

* Example: Users who trigger an “uninstall” event are not going to complete your Goal event.

Associated almost perfectly with converting. Too good to be true?

* Example: Users who trigger a Purchase event will always trigger an Add To Cart event. Add To Cart and Purchase will always have a high correlation.


# Flows
Source: https://docs.mixpanel.com/docs/reports/flows

See frequent paths taken by users to or from any event

## Overview

<Frame>
  <img alt="/flows_header.png" />
</Frame>

A Flows report identifies the most frequent paths taken by users to or from any event. Use Flows to understand how your users sequentially perform events in your product and analyze drop-offs or unsuccessful behavior.

Flows can be accessed from the left-side navigation by clicking the '+ Create New' button.

<Note>
  The Flows report is available on all free and paid subscription plans.
</Note>

## Use Cases

Here are some of the sample questions you can answer in Flows:

* What did users do immediately after signing up?
* What are the most common sets of actions taken after opening the app?
* What actions lead up to creating a channel?
* How do users navigate between account creation and sending their first message?

## Quick Start

<Frame>
  <iframe />
</Frame>

Building a Flows report follows the same high-level steps as building any other report. You can read about report-building basics [here](/docs/reports).

Building a report in Flows takes just a few clicks, and results arrive in seconds. Let's build a simple report together. Using a B2B messaging example, imagine you wanted to answer the following question:

> What are the top paths leading Chrome users from Landing Page to Sign Up?

### Step 1: Choose Events

Events are the basic building block of a Flow. In this case, since we want to know how users navigated from the landing page to signing up, we would add two events, "Landing Page" and "Sign Up", within the "Steps" section.

### Step 2: Choose Steps Before/After Events

Above and below your selected events, you can choose how many steps to show before and after each event, respectively. In this case, we're curious to see at least 3 steps after our first selected event, so we input "3" below "Landing Page." At this point, your query should look like this:

<Frame>
  <img alt="/Screen_Shot_2022-07-11_at_3.19.59_PM.png" />
</Frame>

### Step 3: Choose Filters

Filters exclude unwanted data. In this case, we only care about events performed by Chrome users. Therefore, add a "Browser" filter, where Browser equals "Chrome". At this point, your query should look like this:

<Frame>
  <img alt="/flows_3.png" />
</Frame>

### Step 4: Expand The Events

Transforms a high-level view of a certain flow step into a more granular, segmented analysis at any given point. However, if we wanted to see how the flow varies by city for a "Check Out" event, we could expand the "Check Out" event by "City", which can either be an event property or a user profile property.

### Step 5: Choose Breakdowns

The "Breakdown" feature in Mixpanel's Flows report helps you understand how the complete user journey differs for various segments of your audience. What it does: Instead of seeing one combined flow for all users, "Breakdown" separates the report into multiple, parallel flows. This lets you clearly compare the entire user journey (from entry to exit or drop-off) for specific groups, helping you identify where their paths diverge and where you might need to optimize for different audiences.

### Step 6: Analyze Results

Flows features two visualizations to help you view the results of your query in the clearest chart type. By default, Flows displays the User Flows chart, which uses a Sankey diagram to visually display multiple paths on the same chart. This visualization excels when trying to identify different variants of a similar path or following one particular trail.

User Flows displays a Sankey diagram where the height of the bar is proportional to the number of users who perform that specific event, and the height of the lines that connect bars is proportional to the number of users who perform the two events in sequence.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.14.37_PM.png" />
</Frame>

In the above example, more users moved from the A event “Exit Tutorial” to “Experiment Started” than any other path. This is graphically signified by the height of the line.

Hover over a stage of the diagram to highlight it and see details of that section. This includes the total number of unique users who moved between those two steps on that path, as well as the percentage.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.15.41_PM.png" />
</Frame>

Select any blue node representing an event on the Sankey chart to highlight the most popular paths that led to or from that node. The selected node is indicated in a lighter blue.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.16.15_PM.png" />
</Frame>

## Basic Features

### Viewing More Steps

By default, Flows shows you the first 3 events performed by users after the selected event. If you wish to see what users did further along in the path, you can adjust the number of steps directly in the Sankey visualization, as shown below.

Use the "+" icon on the right of the visualization to add steps after your selected events of interest to see what paths your users took following these key events.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.34.41_PM.png" />
</Frame>

The "+" on the left of the visualization will add steps before the events you've added in the query builder. This will allow you to see what paths your users took that led up to these events of interest.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.35.06_PM.png" />
</Frame>

To add steps in larger quantities, you can adjust the number of steps directly in the query builder section as well.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.40.10_PM.png" />
</Frame>

### Multiple Anchor Steps

You can add multiple steps in the query builder.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.51.32_PM.png" />
</Frame>

This allows you to examine flows between targeted events. The "+" on the left of the breakpoint line (marked with ≈) will show you the events that happened directly after the first anchored event.

In the following example, Flows is showing the event that happened right after 'App Open' before 'In-App Purchase'.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.52.07_PM.png" />
</Frame>

Use the "+" on the right of the breakpoint line (marked with ≈) to show you the events that happened right before the later anchored event.

As an example, below we see the event that happened directly before 'In-App Purchase', but only after the user did 'App Open'.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.53.04_PM.png" />
</Frame>

### Viewing More Event Flows

By default, Flows only show you the top 3 events performed by users, ordered by the number of users who performed them. Less common events performed by fewer users are combined into an "Other events" section. To view more events, simply right-click the 'Other events' node and `Add a row of events`.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.46.45_PM.png" />
</Frame>

To expand a large number of steps at the same time, you can select the number of rows you want directly in the advanced settings

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.47.31_PM.png" />
</Frame>

### Sankey Chart

#### Selected Events

These are significant moments in a user's lifecycle around which you would like to explore user behavior (for example, you may wish to view what users do after a Sign Up event). Selected events are picked in the query builder and are annotated with an alphabetical label (A, B, C) that is shown in the query builder and the sankey diagram.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.20.39_PM.png" />
</Frame>

In the above example, we picked two anchor events, "Exit Tutorial" and "Experiment Started", and are viewing the events that were performed by users between them.

#### Intermediate Events

Once an event is selected, Mixpanel calculates the most common events performed by users immediately before or after the selected event. These intermediate events can match either regularly tracked events OR the most used custom events in your project. The icon will let you know at a glance the type of event being displayed.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.27.00_PM.png" />
</Frame>

In the above example, Install or Open is a custom event, while Experiment Started is a regular event.

[Click here](/docs/reports/flows#custom-events-in-flows) to learn more about custom events in flows.

#### Other Events

At each step in the flow, Mixpanel by default displays the top 3 intermediate events performed by users, ordered by the number of users who performed them at that step. The rest of the events performed are grouped into a single bar called "Other events".

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.28.39_PM.png" />
</Frame>

#### Drop off

“Drop-off” represents users who did not do any further events in the next step during the time period specified in the report, and therefore dropped out of the flow. Users are considered dropped off at future anchor steps selected in the query builder if they do not perform that particular anchor in the time period.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.28.54_PM.png" />
</Frame>

### Conversion Criteria

#### Counting Method

Your selected counting method determines how many times Mixpanel will count a particular user's activity. Mixpanel Flows can be calculated by uniques, totals, or sessions, the same as the Funnels report.

By default, Flows calculations are based on **uniques**. To change to a different counting method, click on the word **Uniques** in the conversion criteria, and select between **totals or sessions** from the drop-down list.

<Frame>
  <img alt="/Screen_Shot_2021-12-15_at_10.16.00_AM.png" />
</Frame>

**Uniques:** counts a single entry per user (determined by distinct\_id). Each can do the first step only once, and this is on the first time they perform the Step A event in the date range. Even if a particular user completes the funnel multiple times in the date range, they will only be counted towards conversion once, and on the first time they entered in the span of the funnel.

**Totals:** counts multiple entries per user.  Users can restart the flow, and every time a user starts the flow, they are counted. Users may re-enter a totals flows only after they have exited their previous attempt. Users exit a flow in 3 ways:

1. They complete the last required step in the flow
2. They fail to get to the last required step in the conversion window and time out,
3. They are excluded from the current flow by an exclusion step.

**Sessions:** ensure every step in the flow is performed in the same session. Like totals flows, users will be allowed to restart the flow in subsequent sessions. Learn more about Sessions [here](/docs/features/sessions).

#### Conversion Window

The Conversion Window determines how much time a user has to finish the last required step in the flow. By default, all customers have 30 days to complete a flow from the timestamp they perform the Step A event. To adjust this conversion window, click on the words **30 days** in the conversion criteria. You will be able to adjust both the unit of time and the amount for Flows consisting of two or more events.

<Frame>
  <img alt="/Screen_Shot_2021-12-15_at_11.12.25_AM.png" />
</Frame>

The maximum amount of time you can choose for the conversion window is 366 days, or otherwise equivalent (12 months, 52 weeks, etc).

#### Hold Property Constant

Holding a property constant in flows requires that a user retain the same value of a given event property for an event to be considered part of the flow.

For example, let's say your product is an e-commerce retail site, and you want to see flows between Add to Cart -> Purchase as long as they purchased the same item - meaning they must be interacting with the same item in every step of the flow - you would hold the Item Name property constant.

The way this is calculated depends on whether you have selected a counting method that does not allow users to re-enter the flow ("Uniques") or allows re-entry ("Totals" or "Sessions).

* **Uniques:** When you select "Uniques" and hold a property constant, because users of this counting method only enter the flow once and on the first time they do the Step A event, Mixpanel will hold constant the property value from the first Step A event.
* **Totals or Sessions:** When you select "Totals" or "Sessions" and hold a property constant, since these counting methods allow users to re-enter the flow, Mixpanel will hold the property constant that is set with each new re-entry at the Step A event.

To add a property constant to your flows, select the **Holding property constant** button in the conversion criteria section.

<Frame>
  <img alt="/Screen_Shot_2021-12-15_at_11.10.42_AM.png" />
</Frame>

Some things to keep in mind are that you are only able to select event properties that apply to all of the required steps. Also, you can select multiple properties, but when you do, **all** must be kept constant.

## Advanced

### Top Paths

Another way to visualize your user flows is by "Top Paths", which condenses the flows down to unique paths on each row. This visualization is great for understanding the most common paths users take, though they may not be similar. In this case, since we want to understand the most common paths, we choose Top Paths. Your report should look like this:

In the top bar of the visualization, you will see the option to toggle between User Flows and Top Paths.

<Frame>
  <img alt="/Screen_Shot_2022-07-12_at_4.31.17_PM.png" />
</Frame>

Top paths will show the 50 most common event sequences of up to the number of steps you had selected in the User Flow sankey visualization.

<Frame>
  <img alt="/Screen_Shot_2022-07-12_at_4.32.15_PM.png" />
</Frame>

The total percentage of users who reached the ultimate destination of a flow is indicated on the top left, while the total number of users that reached a given step and the percentage of users who converted from the previous step are indicated on the bottom of each step.

<Frame>
  <img alt="image" />
</Frame>

### Expand Event by Property

You can choose to expand the results of your report by a particular property to see how that property may impact user flows. You can select multiple properties. For instance, what if I wanted to understand how the specific Purchase Type changes the most common flow that leads to a Purchase event?

Click the **Expand** button, select an event, and then select a property under that event.

<Frame>
  <img alt="Flows Expand Event Property" />
</Frame>

You can also expand on a specific event in the chart below by right-clicking on an event and selecting **Expand by property**.

<Frame>
  <img alt="Flows Expand Event Property2" />
</Frame>

### Breakdown and Compare by Cohorts

Beside the **Filter** button, select the **Breakdown** button to select one or more cohorts from the drop-down list. You will be shown both users in and not in the cohort.

<Frame>
  <img alt="Flows Breakdown Cohort" />
</Frame>

If you have selected multiple cohorts, the chart below will be broken down by those cohorts. Cohorts will appear in the chart in different colors, making it easy to follow the paths the cohorts took in your flows.

In the following example, the cohorts “Android Users” and “iPhone Users” are being compared. As shown in the Legend on the left of the chart, “iPhone Users” are indicated in purple, “Android Users” in orange.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_5.42.31_PM.png" />
</Frame>

To see the percentage breakdowns of these cohorts in more detail, click on a node to highlight the strongest path to that node. The box that pops up shows the percentage of each cohort that followed that path.

In the following example, of the users that reached this Exit Tutorial event, 22.2% of users are iPhone users, 77.8% of users are Android users.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_5.42.41_PM.png" />
</Frame>

### Hide Events

You can choose to hide events from the flows report to simplify and clarify the results. This is useful if you have common events that add noise because they are not relevant to the workflow you are examining.

Click the **Hide Events** button at the top of the chart and check any events you want to hide from the query, then click **Apply**.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_5.45.22_PM.png" />
</Frame>

You can also choose to hide a specific event from the flow by right-clicking on it in the Flows chart.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_5.45.58_PM.png" />
</Frame>

### Custom Events in Flows

#### Custom events as start/end events

You may pick custom events as the starting or ending events directly in the query. For custom events that are composed of multiple events, paths consisting of either event are combined into a single flow.

#### Custom events as intermediate events

Mixpanel automatically considers the most used and common custom events in your project, displaying them in intermediate steps instead of showing the underlying events. When a custom event is shown instead of the underlying event, it is annotated with the custom event icon to indicate that the event displayed is custom.

<Frame>
  <img alt="/Screen_Shot_2021-07-20_at_7.04.29_PM.png" />
</Frame>

Mixpanel uses the following criteria to decide which custom events are shown in user flows:

1. Custom events that are shared with all users in the projects are the only ones picked to be shown in flows right now
2. Only the 50 most frequently queried custom events in the project are used in Flows analysis.
3. If custom events have overlapping definitions (e.g., both custom events operate on the same event), we will choose the more frequently queried custom event to show in the report.

#### Expanding custom events

You may also expand custom events by event name to view the underlying events if required.

<Frame>
  <img alt="/Screen_Shot_2021-07-30_at_1.21.26_PM.png" />
</Frame>

#### Disabling custom events

You can disable custom events for flows by toggling the Show Custom Events in the dropdown menu below. Custom events that have been manually chosen as steps in the flow will continue to show up, but no other custom events will be shown.

<Frame>
  <img alt="/Screen_Shot_2021-10-29_at_10.48.22_AM__1_.png" />
</Frame>

### Exclusion Steps

You can add exclusion steps, which exclude users who did a particular step. This is useful for digging into a particular view, for example, to explore the 2nd most popular path taken.


# Funnels
Source: https://docs.mixpanel.com/docs/reports/funnels

Measure conversions through a series of events

Take a look at these pages to learn about our Funnels Report.

<CardGroup>
  <Card title="Overview" href="/docs/reports/funnels/funnels-overview" />

  <Card title="Quickstart" href="/docs/reports/funnels/funnels-quickstart" />

  <Card title="Advanced Concepts" href="/docs/reports/funnels/funnels-advanced" />

  <Card title="FAQ" href="/docs/reports/funnels/funnels-faq" />
</CardGroup>


# Funnels Advanced Concepts
Source: https://docs.mixpanel.com/docs/reports/funnels/funnels-advanced



## Overview

This page covers advanced concepts related to funnels, including how their metrics are measured and their various configurations.

## Conversion Criteria

<Frame>
  <iframe />
</Frame>

### Conversion Window

The Conversion Window determines how much time a user has to convert through all steps of the funnel after entering it.

By default, all customers have 7 days to complete a funnel from the timestamp they perform the Step 1 event. To adjust this conversion window, click on the words 7 **days** in the conversion criteria. You will be able to adjust both the unit of time and the amount.

<Frame>
  <img alt="/Screen_Shot_2021-12-15_at_11.12.25_AM.png" />
</Frame>

The maximum amount of time you can choose for the conversion window is 366 days, or otherwise equivalent (12 months, 52 weeks, etc). For session-based conversion windows, the maximum is 12 sessions.

Keep in mind that the conversion window starts on the first instance of the Step 1 event per funnel entry, and will not be updated by later instances of the same event in the same funnel entry.

For example, let's say a user tracks the following:

1. Event A at 1:00 pm
2. Event A at 1:30 pm
3. Event B at 1:45 pm
4. Event C at 2:15 pm

You create a Funnel looking at A → B → C, with a conversion window of 1 hour.

This user enters the funnel when they first track Event A at 1:00 pm. They convert through Event B at 1:45 pm, and then time out of the funnel. They do not show as converting through Event C since Event C took place more than 1 hour after the entry event at 1:00 pm.

The second instance of Event A at 1:30 pm does not reset the conversion window timer. Event B and Event C would need to be completed within 1 hour of Event A, and tracked for the user to be counted as converted.

### Optimized Re-entry

When **Optimized Re-entry** mode is enabled, we actively evaluate all funnel entry attempts - even if the user's previous funnel is still in progress. This allows us to capture potential conversions that might occur from subsequent entries, maximizing total conversions.

If any user funnel entries within the report date range result in a conversion, we count the user as converted.

<Frame>
  <img alt="image" />
</Frame>

**Scenario 1**

* Funnel Steps: A -> B
* Event Stream: A -> Conversion Window Ends for A Ends -> A^ -> B

**Default Mode**

Since event A occurred first and did not convert within its window, we count the user as not converted. This mode only considers the user’s first funnel entry.

**Optimized Reentry Mode**

We treat A^ → B as a valid conversion because A^ initiates a new funnel which converts within its active conversion window. Therefore, we count the user as converted.

**Scenario 2**

* Funnel: A -> B
* Event Stream: A -> A^ -> Conversion Window for A Ends -> B

**Default Mode**

Since A^ took place while the funnel entry triggered by A was still active, we ignore it. We only evaluate the first funnel entry (A), which did not convert. The conversion rate would be 0% from the drop-off for A since A^ is ignored.

**Optimized Reentry Mode**

We treat A^ as a new funnel entry and restart the funnel history. When B occurs, it completes the new funnel A^ → B, which we count as a conversion. The conversion rate would be 50% from the successful conversion for A^ and the drop-off for A. (A′^ / \[A + A^])

**PLEASE NOTE:**

1. For [Unique aggregation](/docs/reports/funnels/funnels-advanced#counting-methods) during a date range with multiple funnel conversions, we consider the first converted funnel only. For example, in scenario A → B → A^ → B^, there are 2 user funnels converted: A → B and A^ → B^. We only consider the first A → B as the user conversion.
2. In a multi-step funnel, we only consider the first step for re-entries. For every subsequent step, we pick the first instance of the step.
3. For the first step in a funnel, if there are multiple entries prior to step 2, we consider the most recent entry. For example, in scenario A → A^ → A^^ → B, where all actions happen within the conversion window, A^^ → B would be recorded as the funnel.
4. For all other counting types - [TTC](/docs/reports/funnels/funnels-advanced#time-to-convert), [Property Sum](/docs/reports/funnels/funnels-advanced#property-sum) - we compute these based on the funnels selected to optimize maximum conversions. For example, in scenario A → A^ → A^^ → B, where all actions happen within the conversion window, in the Optimized Reentry mode, TTC would be calculated for A^^ → B. However, in the Default mode, TTC would be calculated for A → B.

### Ordering

The order control determines how much flexibility there can be in the sequence of your user's actions to be counted as a conversion. By default, funnels are based on a specific order.

#### Specific Order

Specific Order Funnels require the user to complete each of the funnel steps in the order laid out to be counted as a conversion from one step to another. In other words, Step 1 must be completed before Step 2, which must be completed before Step 3, and so on. The user can engage in other actions in between funnel steps - including additional occurrences of the actions listed as funnel steps - but they will only be counted as converted if they complete all the funnel steps in order.

To illustrate with an example, let's say a specific order funnel has steps: A → B → C → D → E

1. The user does events A → B → C → D → E in exact order. Mixpanel counts this as a conversion.
2. The user does event A → B → **F** → C → D → E. Mixpanel counts this as a conversion. Users can do additional actions in between funnel steps and still convert.
3. The user does events A → B → **D** → C → D → E. Mixpanel counts this as a conversion. Even though the user did D before the first time they did C, they will continue to convert because they eventually did a D after C.
4. The user does events A → B → C → E. Mixpanel will not count this as a full conversion, and the customer will drop off after step C. The customer's completion of step E is excluded from the funnel because step D did not occur.

#### Any Order

In Any Order Funnels, users can complete unanchored funnel steps in any particular sequence and still convert. This type of funnel is most useful in situations where a user must complete all actions to be considered converted, but the exact order is not important.

A good example of this could be a job application flow, where a user must input multiple pieces of information (their name, email address, current job title, etc.) to complete the form and submit their application, but they can provide all the information in any order.

To switch to **Any Order**, expand the “Advanced” menu in the Conversion Criteria and toggle on “Any Order”.

When you switch to **Any Order,** you have the option to anchor specific steps in your funnel by clicking on the step number.

A step will either appear with a number beside it, indicating where it must fall in the funnel, or with an asterisk (\*), indicating that it can be performed in any order before the next anchored step.

If you have selected any order for your funnel steps, you have the option to select **Top paths** from the drop-down visualization list to view a [Sankey visualization](/docs/reports/flows#sankey-chart) of how your users are performing the steps in your funnel.

<Frame>
  <img alt="/funnels_any.png" />
</Frame>

### Hold Property Constant

Holding a property constant in a funnel requires that a user retain the same value for a given event property for each step to convert. In other words, a user must perform the funnel events in the order you specified with the same property value.

For example, let's say your product is an e-commerce retail site, and you have a three-step funnel of Browse → Add to Cart → Purchase. If you want to examine the conversion of users through this funnel who browse, add to cart, and purchase the same item - meaning that they cannot convert if they do not complete each step with the same item - you would hold the Item Name property constant.

Since all the events must have the property, you can only select event properties that apply to all of the events in your funnel. You can select multiple properties, but when you do, **all** of them must be kept constant. A maximum of 3 properties can be held constant at the same time.

The way entry values are determined when "Holding Property Constant" depends on the selected counting method:

* **Uniques:** With the “Uniques” counting method, users will only enter the funnel once, the first time they do Step 1. Mixpanel will hold the property value constant from the first Step 1 event.
* **Totals or Sessions:** “Totals” and “Sessions” counting methods allow users to re-enter the funnel. Mixpanel will hold the property constant that is set with each new re-entry at the Step 1 event. This means the user can enter multiple times with different property values.

To hold a property constant in your funnel, expand the “Advanced” menu and click “Holding property constant”.

<Frame>
  <img alt="/funnels_hold.png" />
</Frame>

## Exclusion Steps (Exclude users who did…)

Exclusion steps operate as a “did not do” filter for funnels. This provides the ability to create a funnel where users are excluded from converting if they track a specific event between the funnel steps.

A few things to note about exclusion steps:

1. An exclusion step can be placed between any steps in the funnel. It cannot be the first or last step. Example scenario: The user tracks (1) Event A → (2) Event A → (3) Event A → (4) Event B Totals conversion funnel looking at A → B, with Exclusion Step: Event A The user enters the funnel when they track (1). They then drop off when they track (2) since Event A is excluded. With the totals conversion criteria, the user will re-enter the funnel at (3) and then convert with (4). Overall, there will be two entries and one conversion. Example reports for reference from our demo dataset:

   * [User activity](https://mixpanel.com/s/2it5gE)
   * [Funnel](https://mixpanel.com/s/2CpCuq)
2. A user will qualify for each step in the funnel until they track the exclusion step. This means users who tracked the exclusion step are still able to enter the funnel and convert through the steps. Use a [cohort](/docs/users/cohorts) filter if you want users who did a particular event at any point to be excluded from entering the funnel.
3. There may be any number of exclusion events between steps.
4. Exclusion steps have the same two-second [grace period](/docs/reports/funnels/funnels-faq#how-does-the-funnel-handle-simultaneous-events) as other steps in the funnel.

As an example, let's say you want to understand if users who add additional products to their cart and check out are less likely to complete a purchase. To answer this question, you could create a funnel with four steps:

Step 1: Product Viewed

Step 2: Product Added

Step 3: Checkout Started

Step 4: Purchase Completed

You can exclude users who did another “Product Added” event between Step 2 and Step 3 to see how that affects your funnel's conversion rate.

To add an exclusion step in your funnel, expand the “Advanced” menu and click “Exclude users who did…”.

Select an event from the list and choose whether you would like the event to be excluded from all steps or between specific steps. Click the Filter icon beside the step to filter that event by an event or user profile property.

<Frame>
  <img alt="/exclude_2.png" />
</Frame>

## Saved Funnel Behaviors

You can save the Funnel Behavior you built and reuse it in other reports. This can be helpful when there is a sequence of events that you frequently analyze (such as sign-up flow), or if you want to analyze your Funnels Behavior alongside other metrics in an Insights report.

Select the "..." button in the top right corner of the metric, then click "Save Behavior". Note that saving a behavior and saving a metric are different; a saved behavior consists of the events/Funnels/Retention, while a saved metric consists of the saved behavior and the measurements of the behavior.

<Frame>
  <img alt="/saved-funnel-behavior1.png" />
</Frame>

Learn more about [Saved Metrics and Behaviors](/docs/features/saved-metrics-and-behaviors).

## Counting Methods and Measurements

You have a variety of options to measure your funnel behavior.

### Counting Methods

| Counting Method | Description                                                                                                                                                                                                                                                                                                                                                                         |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Uniques         | Users will enter the funnel the first time that they track Step 1 in the time period selected. When a breakdown is applied, they can enter up to once per segment.                                                                                                                                                                                                                  |
| Totals          | Users can re-enter a totals funnel after they have exited their previous attempt through the funnel. Users exit in three ways: successful conversion through the funnel, time out of the [conversion window](/docs/reports/funnels/funnels-advanced#conversion-window), or track an [exclusion step](/docs/reports/funnels/funnels-advanced#exclusion-steps-exclude-users-who-did). |
| Sessions        | Users can enter the funnel in each session that qualifies.                                                                                                                                                                                                                                                                                                                          |

### Measurements

| Measurements      | Description                                                                                                                                                                                                                                          | Counting Method                         |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| Conversion Rate   | The rate at which funnels are completed for the selected steps of the funnel.                                                                                                                                                                        | Uniques (default), Totals, or Sessions. |
| Unique Users      | The number of users who completed the selected steps of the funnel.                                                                                                                                                                                  | Uniques                                 |
| Total Conversions | The total number of funnels that have reached the selected step of the funnel.                                                                                                                                                                       | Totals                                  |
| Total Sessions    | The total number of unique users sessions that reached the selected step of the funnel                                                                                                                                                               | Sessions                                |
| Time to Convert   | Allows for selection of an aggregation: Average, Median, Percentile, Min and Max. Measures the aggregated time to convert for the selected steps of the funnel. See more [here](/docs/reports/funnels/funnels-advanced#time-to-convert-measurement). | Totals                                  |
| Property Sum      | Sums up a chosen property value for each step of the funnel, and measures the total amount of the property converted for the selected step of the funnel. See more [here](/docs/reports/funnels/funnels-advanced#property-sum).                      | Totals                                  |

### Step Selection

You can select which step of the funnel you would like to measure. By default, this is set to All Steps. To change your step selection, press “All Steps” and choose the desired range.

When measuring “Unique Users”, “Total Conversions”, or “Total Sessions”, you can select “Entering Funnel” in order to get a top-of-funnel count. Similarly, if you would like to get the bottom-of-funnel count, you can choose “All Steps”.

<Frame>
  <img alt="step selection" />
</Frame>

## Time to Convert

Time to Convert is a feature within the Funnels report that measures how long it takes users to move through the steps of a funnel, from the first event to the last (or between any two specific steps).

### Time to Convert Measurement

You can select a Time to Convert aggregation to see how quickly or slowly your funnel converts. You can see this as a summarized value by selecting “Metric” or “Bar” visualizations, or you can see it as a trend using the “Line” visualization. You can also see the time to convert for a particular chosen step selection. (Note: Our percentiles are calculated using an approximate algorithm, and when this algorithm is run on small/sparse datasets, the results can be non-deterministic, i.e., the results can differ by a small amount across runs.)

<Frame>
  <img alt="toc_measurement.png" />
</Frame>

### Time to Convert Breakdown

You can select the Time to Convert breakdown to see a distribution of the time users took across the funnel or  between any two steps. The steps selected in the breakdown are independent of the step of the metric you are measuring. For example, you can measure the overall conversion rate broken down by Time to Convert between Steps 1 and 2.

Time to Convert works like any other property in that you can filter to a specific range of times or customize the bucketing of the breakdown. You can't use it as an inline filter since it is used to filter funnels, which have been measured, rather than changing the per-step conversion window.

You can see a distribution of the conversion time to convert by using the 'Time to Convert' breakdown in combination with measuring total conversion. You can also use this to see how other metrics, such as conversion rate, are affected based on how quickly users convert on a particular step range.

<Frame>
  <img alt="toc_breakdown.png" />
</Frame>

## Property Sum

This measurement type allows you to visualize a numeric event property through a funnel. Instead of seeing how many users move through your flow, you can select an event property that exists on each step of the funnel. Mixpanel will sum up the total value of this property at each stage of the funnel and visualize the total amount converted, or the drop-off at each step if “Funnel Steps” visualization is selected. For example, this could be used to visualize the revenue across the funnel steps.

**Note**: For many e-commerce flows, you will want to pair the property sum with [hold property constant](/docs/reports/funnels/funnels-advanced#hold-property-constant) on item ID so you can track each individual item.

To use this property, select Property Sum from the measurement menu and select a numeric property.

<Frame>
  <img alt="funnels_property_sum.png" />
</Frame>

## Behavioral Properties

Behavioral properties allow you to use your user’s activity and use it as a property in your other analysis. Behavioral properties work like any other numeric property in that you can filter to a specific range of frequencies or customize how it is bucketed.

In funnels, the behavioral property is computed in the time range between 2 steps in your funnel. You can specify which steps in the funnel this applies to. The step selection is separate from the overall funnel measurement; for example, you can measure the overall conversion rate but break it down by the frequency of an event between Steps 1 and 2.

The behavioral properties will only count the events in the chosen range. The event that originally satisfied the funnel definition does not count towards the behavioral property between steps.

For example, if a user performs “Step 1 → Step 2”:

* Frequency: “0 times” — there is no extra “Step 1” event, so the frequency will be “0 times”

For example, if a user performs “Step 1 → Step 1 → Step 2”:

* Frequency: “1 time” — we will count the second “Step 1” event, so the frequency will be “1 time”

See [here](/docs/features/computed-properties#behavioral-properties) for more information about behavioral properties.

<Frame>
  <img alt="funnels_behavioral_props.png" />
</Frame>

### Frequency per User

Use the Frequency per User to see the number of times users performed an event between any two funnel steps. For example, see the number of times a user listened to a song between signing up and purchasing the song.

### Aggregate Property per User

Use 'Aggregate Property per User' to see the aggregation on an event property between steps. For example, you can see the sum of a purchase amount between steps.

## "Attributed by..." Breakdown

You can select this breakdown to attribute credit for the funnel to touchpoints along the user journey. The attribution is calculated on the first step of the funnel. See the [Attribution doc](/docs/features/computed-properties#attribution) for more information.

## Comparison Events

You can select multiple events at a particular step in a funnel, and Mixpanel will compute a segmented funnel that shows what percent of users reached each of these comparison events.

To do this, click on the ”…” menu and select “Event Comparison”

<Frame>
  <img alt="funnels_comparison.png" />
</Frame>

## Breakdowns

### User Count in Breakdown

Users will count in each breakdown segment in which they qualify. In order to qualify for a new segment, the user must have exited their previous funnel attempt unless the funnel is [holding a property constant](/docs/reports/funnels/funnels-advanced#hold-property-constant). The breakdown segment value is determined by the selected [property attribution](/docs/reports/funnels/funnels-advanced#property-attribution).

For example, let's say a user tracks the following:

1. Browse Product, item = shirt
2. Browse Product, item = jeans
3. Add to Cart
4. Browse Product, item = shoes

The funnel looks at Browse Product → Add to Cart, with a breakdown on "item" set to attribute the funnel on the value of "Step 1".

This user would enter the funnel when they first track "Browse Product" with "item = shirt". The second "Browse Product" event is not counted as a new entry since the user has not exited the current funnel attempt. They then convert on event 3, when they track "Add to Cart". With the breakdown applied to "item", they will re-enter the funnel when they track "Browse Product" with the new item value of "shoes".

Overall, the funnel would show two entries, "shirt" and "shoes", with one conversion on "shirt".

### Significance

Statistical significance in funnels validates an increase or decrease in conversion rate for a property or cohort segment. It attempts to identify random chance with respect to overall conversion. A p-value indicating statistical significance is calculated in the overview table when you choose a property or cohort to group by.

In statistical hypothesis testing, the p-value or probability value is the probability that the variation in a segment's conversion rate, compared to the overall conversion rate, is not driven by random chance. This value is shown for every segment by default. To learn more about how this is calculated, click [here](/docs/reports/funnels/funnels-faq#how-does-mixpanel-calculate-statistical-significance).

In order to clarify this statistical significance, the segmentation chart shows the confidence level of each segment. Confidence level is defined as 1 - p.

* \> 0.95 = statistically significant, indicated in green. This variation in conversion rate is likely **not** driven by random chance.
* \< 0.95 = not statistically significant, indicated in red. This variation in conversion rate is likely driven by random chance.

<Frame>
  <img alt="funnels_significance.png" />
</Frame>

Scrolling further down the table takes you to the statistically insignificant segments. If a segment has fewer than 30 samples, the p-value is not shown, as the sample size is too low to detect differences from the overall population. This is indicated by “Insufficient samples”.

The number of samples is the same as the count of entries into the funnel. If the funnel is looking at the unique count, this is the number of unique users who entered the funnel in that segment. If the funnel is looking at the total count, this is the total number of entries into the funnel in that segment.

You can choose to sort by any of the columns of the overall table in descending or ascending order by clicking on the header. If you sort by statistical significance, the secondary sorting is determined by the overall conversion rate for the funnel.

Click on the **dot** beside the statistical significance number to make that property value the Control value that the other property values are compared to. To return to the default view, click the **dot** beside “Overall”.

## Filters

### Inline Filtering (Pre-Query)

Inline filters allow you to apply event or user property filters to each step of your funnel. This adds granularity and specificity to your conversion criteria. In selecting an inline filter, you are tightening the parameters of events that qualify for conversion.

Inline filters are performed pre-query. Thus, these filters will impact your funnel's conversion by removing events that don't qualify from consideration of being included in a funnel calculation.

<Frame>
  <img alt="funnels_filter1.png" />
</Frame>

Let's illustrate this with some examples.

Consider a three-step funnel where a user must View Item → Add to Cart → Purchase, all within a one-hour conversion window.

As you can see in the activity feed below, this user's first "View Item" event happens more than one hour before they "Add to Cart", so they would drop off after the initial "View Item". As such, the funnel would show one entry with no conversions.

<Frame>
  <img alt="funnels_filter2.png" />
</Frame>

However, if you put an **inline filter on the "View Item" event with "Browser = Safari"**, then users will only enter the funnel with "View Item" events on Safari browsers.

Below we see the same user's activity stream, where their first "View Item" is with the Chrome browser, and thus this user's first "View Item" event **is not** included in a funnel's calculation.

They have a second "View Item" that is using Safari, and this event qualifies them to enter into the funnel. Each of their subsequent steps happens within the conversion window, and this user reaches full conversion at the end of the funnel.

<Frame>
  <img alt="funnels_filter3.png" />
</Frame>

If we were to take it further and place an inline filter on each and every step in this funnel, so that all steps must be completed with events where Browser = Safari, then this user would only convert to the second step of "Add to Cart". This is because the "Purchase" event doesn't have a browser set.

### Global Filtering (Post-Query)

Global filters apply your selected filters to the entire report after the Funnels query has been run. Since Funnels will calculate conversions first and then apply your global filters, entire conversions that do not meet the filter requirements will be excluded from the report's results. The filter value is determined based on the [property attribution](/docs/reports/funnels/funnels-advanced#property-attribution) selected.

For example, let's use the same three-step funnel where a user must View Item → Add to Cart → Purchase, all within a one-hour conversion window. This time, we apply a **global filter of "Browser = Safari", filtering on "First Step Defined".**

In the below example, the same user's funnel entry would be their first "View Item" event, with a "Browser = Chrome" since this is the first defined property value. When the global filter is applied, the entire entry is filtered out since it doesn't meet the filter criteria. This means the report would show no users entering the funnel at "View Item".

<Frame>
  <img alt="funnels_filter4.png" />
</Frame>

## Property Attribution

### First Step Defined vs Last Step Defined

Event property values can vary from step to step in your funnel. You can choose which step the value is derived from for breakdowns and filters.

To access this feature, filter or breakdown by a property in the funnel chart below the query builder. Click on **Step 1** to select either “Last Step Defined”, “First Step Defined”, or a specific step number. Your selected choice will determine which step of your funnel determines the property value for the whole funnel.

<Frame>
  <img alt="funnels_attribution1.png" />
</Frame>

### "First Step Defined" Attribution and Forwardfilling

By default, Mixpanel *forward-fills* [event properties](/docs/data-structure/events-and-properties) in instances where properties are sent in earlier steps of a Funnel but not sent in subsequent steps of the same funnel. This means that the property that is present in the early steps of a funnel is appended to the later steps of the funnel, where it was previously absent.

Select **First Step Defined** to attribute the first property value to the whole funnel, regardless of whether the property value changes in subsequent steps. First Step Defined is not the same as the first step of the funnel; it is the first time the property is given a non-null defined value.

For example, say that the user is shopping on your website and you want to track a funnel from Page View → View Item → Add to Cart → Checkout, with a breakdown on "color". With "First Step Defined", the first color will be applied to the entire funnel, in this case, "red" seen on View Item.

<Frame>
  <img alt="funnels_attribution2.png" />
</Frame>

### Last Step Defined Attribution

By default, Mixpanel “backfills” [event properties](/docs/data-structure/events-and-properties) in instances where properties are sent in later steps of a Funnel but not sent in the earlier steps of the same funnel. This means that the property that is present in later steps of a funnel is appended to the earlier steps of the funnel, where it was previously absent.

Select **Last Step Defined** to attribute the last property value to the whole funnel, regardless of the property value in previous steps. Last Step Defined is not the same as the last step of the funnel; it is the last time the property is given a non-null defined value.

For example, say that the user is shopping on your website and you want to track a funnel from Page View → View Item → Add to Cart → Checkout, with a breakdown on "color". With "Last Step Defined", the last defined color value will be applied to the entire funnel, in this case, "blue" seen on Add to Cart.

<Frame>
  <img alt="funnels_attribution3.png" />
</Frame>

### Per-Step Attribution

You can choose to attribute a property value from any step to the whole funnel by selecting the step number. Note that with this option, you may see an “undefined” null value for the property, as this option is not tied to when the property value was defined.

## View as Flow

You can click into any funnel step and select “View as Flow”. This takes you to the [flows](/docs/reports/flows) report and lets you see:

* What events did users do before or after converting?
* What events did the users who dropped off do instead?

For example, you might use this to discover that most users who dropped off are hitting a specific bug in your platform. You can then fix the bug and revisit your funnel to see if there's been an improvement.

## Rename a Step

Click on the “...” icon beside a step and click "Rename" to rename it.

<div>
  <div>
    <h2>
      Next: Frequently Asked Questions
    </h2>

    <p>
      Still got questions? Get answers to the most frequently asked Funnels questions below.
    </p>

    <br />

    <ExtendedButton title="Funnels FAQ" />
  </div>
</div>


# Funnels FAQ
Source: https://docs.mixpanel.com/docs/reports/funnels/funnels-faq



#### Why is my user shown as dropped off even though they've just completed the full funnel today?

Assuming that the user performed all actions in the funnel, on their first try, in the right sequence, within the conversion window, the user should be counted as converted. However, there is an ID Merge delay where it can take up to 24 hours for the anonymous and identified user activity to be linked together across Mixpanel. If you are looking at the Funnel report for today, the events may not be linked to one user if they are soon after ingestion. Once the identities are merged, the funnel should display the conversion if the user performs the steps in the funnel in the specified sequence.

#### Can users do other actions during the funnel?

Users can complete the steps you designate in your funnel in loose order. Loose order means that a customer can engage in other actions in between funnel steps, as long as they complete all the funnel steps in order. See the [Ordering](/docs/reports/funnels/funnels-advanced#ordering) section for more information.

#### Why do I get differing numbers when comparing Funnels and Insights?

Funnels and Insights are fundamentally different when it comes to counting events. A Funnels report expects users to convert through a series of events within a specified time period, with additional logic around re-entries and filtering. An Insight metric gives the actual count of users or events.

For example, let's say we are looking at a Funnel from Step 1 → Step 2. In the Funnel report, the user will need to enter the report at "Step 1" and then track "Step 2" within the conversion window. If they don't do both of those things, "Step 2" will not be counted in the report. An Insight metric, on the other hand, will count the "Step 2" event without those criteria being met.

In a "Totals" funnel, users will only re-enter after exiting their previous attempt. This means the count for "Step 1" in a funnel may not match the overall total number of events tracked for "Step 1". As an example, let"s say a user tracked Step 1 → Step 1 → Step 2. This user would only enter the funnel once when they first track "Step 1", but the "Total" count on an Insight report would show a count of 2 "Step 1" events.

#### Can multiple events count towards the same Funnel step?

Custom events allow multiple events to count towards the same step in the funnel. With custom events, you can essentially “combine” events into a single event so that you can create Funnels that measure the following:

**Step 1:** Event A OR Event B

**Step 2:** Event C

This allows users to make multiple paths to the same end goal. Learn more about creating custom events [here](/docs/features/custom-events).

#### Why are there only 200 segments in my Funnels breakdown report?

When breaking down a Funnel by a Property, only the top 200 property values will be returned. All other segments will be grouped into an "\$other" category.

If you would like to view all of the individual segments beyond the 200-property limit, you can export a CSV of the report. The export will contain up to 10k segments.

#### How does the Funnel handle simultaneous events?

Funnels include a built-in two-second grace period. This means any consecutive steps that have timestamps within two seconds of one another are interchangeable. This window allows for inconsistencies that arise with cross-platform tracking, batch event sending, mobile time tracking, or variations in connection speed.

What does this mean in terms of your funnel? In a funnel with step A → B, if a user completes event B first and then performs event A within two seconds, the Funnel will count this as a conversion from A → B or B → A.

#### What is the difference between Inline Filtering and Global Filtering?

You can use both inline and global filters to decide which users and events to include in a funnel. Inline filters apply pre-query to a specified step, while global filters apply post-query based on the [property attribution](/docs/reports/funnels/funnels-advanced#property-attribution) selected.

At a high level, an inline filter query will filter for the funnel entry for the user that meets the filter criteria. With a global filter, the user will enter the funnel the first time that they track Step 1. That entry will then be filtered based on the global filter criteria.

See the [Filters](/docs/reports/funnels/funnels-advanced#filters) for more information.

#### Why do the Line chart (by day) and Table (with a day breakdown) show different numbers for the same funnel?

The two visualizations calculate conversions differently. The Line chart runs a separate funnel for each day (based on the time interval) in your date range, so a user can enter the funnel on multiple days and be counted multiple times. The Table (with a day breakdown) runs a single funnel across the full date range, then segments the results by day afterward, so each user is only counted once.

#### How does Mixpanel calculate statistical significance?

This section is intended for users who want to understand the mathematics involved in statistical significance in depth.

To determine whether a particular segment's conversion rate is significantly different from the overall conversion rate, we use a hypergeometric distribution to calculate statistical significance. The hypergeometric distribution is used to model the probability of picking k items of a particular type in n attempts without replacement from a population of size N having K items of the same type.

For example, let's say we have a sock drawer with 20 socks, 10 blue and 10 red. If we randomly picked 10 socks one at a time from the drawer without putting them back between picks, and we wanted to know the probability of 9 of those socks being red and 1 of them being blue, we would use a hypergeometric distribution to calculate that.

This is applied to funnels by considering the total number of users who enter the funnel to be a finite population of size N, out of which a subset of users convert (K). We then estimate the probability of getting k conversions in a particular segment (given that there were n users who entered the funnel in that segment) if users in that particular segment were picked at random from the overall user set. The higher the probability, the higher the likelihood that variations we see in conversion rate are due to random chance.

To calculate the actual p-value, we estimate the hypergeometric cumulative distribution function (CDF) for N, K, n.

<Frame>
  <img alt="funnels_statsig.png" />
</Frame>

In the CDF, the value of any point (X) represents the probability that a random draw would result in fewer conversions, P(k \< X). 1 - P(k \< X) represents the probability that a random draw would result in more conversions, P(k >= X).

These two probabilities are used to represent the probability that the selected segment will either outperform (P(k \< X)) or underperform (P(k > X)) the overall set of users. Mixpanel takes the higher probability of the two and calculates the p-value as 1 - max(P(outperform), P(underperform)).


# Funnels
Source: https://docs.mixpanel.com/docs/reports/funnels/funnels-overview

Measure conversions through a series of events

## Overview

<Frame>
  <img alt="/funnels_result_header.png" />
</Frame>

Mixpanel's Funnels allows you to examine how end-users perform events in a series. Funnels calculate and display conversions from one event to another within a particular time window. This allows you to identify where your users drop off, what segments convert the most, and other important facets of the user journey.

Funnels can be accessed from the left-side navigation by clicking the '+ Create New' button.

<Note>
  The Funnels report is available on all free and paid subscription plans.
</Note>

## Use Cases

Imagine your product is a B2B messaging application. You might use Funnels to answer these questions:

* What percent of users converted through my signup funnel within 7 days?
* At what step of the signup funnel did most users drop off?
* How did my A/B test impact conversions in the signup funnel?
* How has the payment funnel conversion rate in the US changed over time?
* How long does it take most users to complete my payment funnel?
* What departments complete the payment funnel most often?
* Why did the successful users purchase?

<div>
  <div>
    <h2>
      Next: Build a Funnels Report
    </h2>

    <p>
      Build your first Funnels report using the Quickstart below.
    </p>

    <br />

    <ExtendedButton title="Funnels Quickstart" />
  </div>
</div>


# Funnels Quickstart
Source: https://docs.mixpanel.com/docs/reports/funnels/funnels-quickstart



<Frame>
  <iframe />
</Frame>

A funnel is a sequence of events done within a defined period of time. A converted user is one who triggers the funnel events, in the specified order, within the defined time period.

## Step 1: Define your Funnel Behavior

A Funnel Behavior is the basic building block of the Funnels report. A Funnel Behavior is a sequence of events done within a defined period of time.

For example,  let's say your signup flow contains five steps. Within the funnel definition, you can add one event for each step, in the following order: “Product Viewed” → “Product Added” → “Checkout Started” → “Purchase Completed”. At this point, your query should look like this.

<Frame>
  <img alt="/funnels_beta_1.png" />
</Frame>

You can save the Funnel Behavior you built and reuse it in other reports. Select the "..." button in the top right corner of the metric, then click "Save Behavior". Note that saving a behavior and saving a metric are different; a saved behavior consists of the events/Funnels/Retention, while a saved metric consists of the saved behavior and the measurements of the behavior.

Learn more about [Saved Metrics and Behaviors](/docs/features/saved-metrics-and-behaviors).

## Step 2: Choose your Measurement

After your Funnel Behavior is defined, you can choose how you want to measure the Funnel. By default, the Funnels report will select the unique conversion rate of the funnel as the measurement.

<Note>
  **Advanced** - See [Counting Method and Measurements](/docs/reports/funnels/funnels-advanced#counting-methods-and-measurements) section for more information on the measurements.
</Note>

<Frame>
  <img alt="/funnels_beta_2.png" />
</Frame>

Your Funnel Behavior combined with the measurement forms a Metric. You can save the Funnels Metric you built and reuse it in other reports (such as the Insights report). Select the "..." button in the top right corner of the metric, then click "Save Behavior". Note that saving a behavior and saving a metric are different; a saved behavior consists of the events/Funnels/Retention, while a saved metric consists of the saved behavior and the measurements of the behavior.

Learn more about [Saved Metrics and Behaviors](/docs/features/saved-metrics-and-behaviors).

## Step 3: Choose Filters

In this case, we only care about events performed on the iOS platform. Therefore, add a “Platform” filter, where Platform equals “iOS Native”. At this point, your query should look like this.

<Note>
  **Advanced** - See [Filter](/docs/reports/funnels/funnels-advanced#filters) section for more information on the filters.
</Note>

<Frame>
  <img alt="/funnels_beta_3.png" />
</Frame>

## Step 4: Choose Breakdowns

Breakdowns segment data into groups. In this case, we want to break our funnel down by marketing medium, tracked via UTM tags. Therefore, you can add a “UTM Medium” breakdown.

<Note>
  **Advanced** - See [Breakdowns](/docs/reports/funnels/funnels-advanced#breakdowns) section for more information on the breakdowns.
</Note>

<Frame>
  <img alt="/funnels_beta_4.png" />
</Frame>

## Step 5: Choose Visualization

You can visualize your metric in a variety of ways. Mixpanel allows you to choose how you would like to visualize your data. Select “Funnel Steps” in the top right to change your visualization. In Funnels, you can choose:

* Funnel Steps - see how users are progressing through the funnel
* Line - see how your metric is trending over time
* Bar - see a summary view of your metric
* Metric - see a summary view of your metric

<Frame>
  <img alt="/funnels_beta_5.png" />
</Frame>

<div>
  <div>
    <h2>
      Next: Advanced Funnels Concept
    </h2>

    <p>
      Explore how funnel metrics are measured and the various configuration options below.
    </p>

    <br />

    <ExtendedButton title="Funnels Advanced Concepts" />
  </div>
</div>


# Insights
Source: https://docs.mixpanel.com/docs/reports/insights

Visualize trends and compositions within your data

## Overview

<Frame>
  <img alt="Insights Overview Image" />
</Frame>

Insights is a powerful and flexible tool designed to visualize trends and compositions within your data. You can analyze events, cohorts, and user profiles, and display the data in a wide variety of chart types.

Advanced Insights features also allow you to create formulas, compare current data to past data, and generate custom events and properties for deeper analysis.

Insights can be accessed from the left-side navigation by clicking the '+ Create New' button.

<Note>
  The Insights report is available on all free and paid subscription plans.
</Note>

## Use Cases

Here are some of the sample questions you can answer in Insights:

* Product Analytics

  * How is my WAU changing over time? (unique users)
  * How often are my users getting value? (frequency analysis)
  * What is the distribution of my users across regions/devices etc? (property breakdown)
  * [Lifecycle analysis](https://mixpanel.com/blog/growth-through-segmentation-lifecycle-analysis-to-understand-your-users/)
* B2B (in this case, a messaging application)

  * How many messages were sent in the US in the past 30 days? (total events, filtered)
  * How many users had a mobile app session yesterday? (unique events)
  * How many messages are sent per session? (formulas)
  * How much revenue was generated on plans purchased in the past year? (property aggregation)
  * How has the power users cohort grown over the past 6 months? (cohort trends)
* Marketing

  * Which advertising campaigns generate the most checkouts? (property breakdown)

#### Frequency Analysis

It's important to know what's the natural frequency at which your users use your product and experience the core value proposition of your product--do the majority of your users use your product daily? Weekly? Monthly? A16Z wrote a great article about the [Power User Curve](https://www.reforge.com/blog/brief-understand-your-most-engaged-users-with-the-power-user-curve), and this [video](https://www.loom.com/share/0c05ac17742a4d49a4c6879c0fe9f0de) shows how you can reproduce that within Mixpanel.

## Quick Start

<Frame>
  <iframe />
</Frame>

### Step 1: Define your Behavior

Metrics are the basic building blocks of an Insights report, and consists of profiles (users, groups, Cohorts) or behaviors (events, Funnels behavior, or Retention behavior) along with a measurement of those entities. Press the "Select Metrics" button to add a metric.

To select an event and start with an event-based simple behavior metric, choose "Events" in the left column of the metrics menu, then select the events you want to measure. This creates a simple behavior.

<Frame>
  <img alt="Choose Events" />
</Frame>

You can save the behavior you built and reuse them in other reports. Learn more about [Saved Metrics and Behaviors](/docs/features/saved-metrics-and-behaviors).

### Step 2: Choose your Measurement

Once you've selected your behavior, you can choose how to measure that behavior. A behavior combined with a measurement forms a Metric.

Depending on the type of behavior selected, Insights will default to a different measurement. If you're measuring a Simple Behavior (events), Insights will default to measuring the number of unique users who have done that event.

<Frame>
  <img alt="Choose Measurement" />
</Frame>

You can save the metric you built and reuse it in other reports. Select the "..." button in the top right corner of the metric, then click "Save Metric". Note that saving a metric and saving a behavior are different; a saved behavior consists of the events/Funnels/Retention, while a saved metric consists of the saved behavior and the measurements of the behavior.

Learn more about [Saved Metrics and Behaviors](/docs/features/saved-metrics-and-behaviors).

### Step 3: Choose Filters

Filters exclude unwanted data. In this case, we only care about events performed on the iOS platform. Therefore, add an "Operating System" filter, where OS equals "iOS". At this point, your query should look like this:

<Frame>
  <img alt="Choose Filters" />
</Frame>

### Step 4: Choose Breakdowns

Breakdowns segment data into groups. In this case, we want to count sign-ups based on users in different cities. Therefore, add a "City" breakdown. At this point, your query should look like this:

<Frame>
  <img alt="Choose Breakdowns" />
</Frame>

### Step 5: Change Visualization

Choosing a different chart can help you visualize data better. Line charts help you see a trend, but other charts will help you see the aggregate value.

<Frame>
  <img alt="Change Visualization" />
</Frame>

### Step 6: Analyze Results

You now have a full analysis that you can use and add onto a Board, or use as a starting point to dig in further. This might mean adding more filters or breakdowns, or adding another metric and seeing if there's an interesting comparison to be made. You could also change the counting type or the chart type.

## Basic Features

### Metrics

Metrics are the basic building blocks of an Insights report, and consists of profiles (users, groups, Cohorts) or behaviors (events, Funnels behavior, or Retention behavior) along with a measurement of those entities. The table below outlines the types of Metrics that can be analyzed in the Insights report.

**Behavioral Metrics**

| Metric Type              | Description                                                                                                                                                                                                                            |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Simple Behavior (events) | A metric based off of an event or group of events. The metric could measure the total number of occurrences, unique users, or aggregates a property of this event.                                                                     |
| Funnel Behavior          | A metric based off a funnel behavior. You can select a saved funnel behavior or define a new funnel, then choose a measurement on that funnel to form a funnel metric. By default measures conversion rate on all steps of the funnel. |
| Retention Behavior       | A metric based off a retention behavior. You can select a saved retention behavior or define a new retention, then choose a measurement to form a retention metric. By default, measures retention rate.                               |

**Other Metrics**

| Metric Type | Description                                                                                                                                        |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Profile     | A metric based off of the user or group profiles. You can measure the number of profiles, or an aggregate on properties of the profiles.           |
| Cohort      | A metric based off of a defined cohort. Measures the number of users who are part of that cohort.                                                  |
| Formula     | A metric that is a function of other metrics. You can select a saved formula, or create a new formula based on the existing metrics in the report. |

#### Saving Metrics and Behaviors

You can save the metric and behaviors you built and reuse them in other analysis. Select the "..." button in the top right corner of the metric, then click "Save Metric" or "Save Behavior". Note that saving a metric and saving a behavior is different; a saved behavior consists of the events/Funnels/Retention, while a saved metrics consists of the behavior together with the measurements of the behavior.

Learn more about [Saved Metrics and Behavior](/docs/features/saved-metrics-and-behaviors).

<Frame>
  <img alt="Insights Saved Behaviors" />
</Frame>

#### Metric Limits

Insight reports are limited to 40 metric/behavior blocks. This includes all metric and behavior blocks, such as hidden metrics and formulas.

If you hit this limit, you can:

* Migrate some metrics to a new report.
* Use Saved Formulas if your report contains formulas. Learn more about [Saved Formulas](/docs/reports/insights#save-formulas-for-re-use).
* Combine multiple events into a behavior. Learn more about [Saved Behaviors](/docs/features/saved-metrics-and-behaviors#simple-behaviors).

### Charts

Insights feature multiple visualizations to help you view the query results in the clearest chart type. By default, Insights displays the results on the line chart, which helps you understand how metrics trend over time. However, another chart type might present the results with more clarity. In Insights, you can choose to get a metric calculated either across the entire time period selected in the date picker or on a time-segmented view of the metric (e.g. daily breakdown).

* Metric calculated across the entire time period

  * Bar chart
  * Stacked bar chart
  * Pie chart
  * Metric chart
  * Table chart
* Metric time-segmented

  * Line chart
  * Stacked line chart
  * Column chart
  * Stacked Column chart

### Rename an Event within a Report

Click on the "three dots" icon beside an event and click Rename to rename it. This will only affect the current report, and will not change the event's name in other reports.

### Sorting

#### Bar chart

When you view a bar chart, you have four different sorting options: A-Z Ascending, Z-A Descending, Value Ascending, or Value Descending. To switch the sorting view, select the **Events** or **property name** column header in the upper left hand of the results and then select which sorting order you would like to see.

<Frame>
  <img alt="Sorting Bar Chart" />
</Frame>

#### Line chart

Line charts in Insights are accompanied by a table of values that gives users another way to consume the trends information. This data table can also be sorted by clicking the column headers.

Click on a column header to sort by that column. Click the header again to reverse the sorting order. For example, the table below is sorted by event counts on August 2nd:

<Frame>
  <img alt="Sorting Line Chart" />
</Frame>

Results that are segmented (from one or more "group by" clauses in your query) have four different sorting options when you click on the "segment column" headers:

* Segment A-Z Ascending: sort by segment name in ascending order
* Segment Z-A Descending: sort by segment name in descending order
* Value Ascending: sort by segment value in ascending order
* Value Descending. sort by segment value in descending order

When sorting by segments, the sort is carried out from left to right.

<Frame>
  <img alt="Sorting Line Chart" />
</Frame>

Clicking on the "Average" data column performs a flat sort across all segments:

<Frame>
  <img alt="Sorting Line Chart" />
</Frame>

#### Table chart

Tables are useful to see the precise values of your data and to quickly scan multiple metrics per segment. In general, tables work similarly to the rest of Insights, with a few extra features.

##### Sort Order

You can configure how you want rows in the table to be sorted, with our global sorting control.

<Frame>
  <img alt="Sorting.gif" />
</Frame>

###### Grouped View vs Ungrouped View

The Ungrouped View removes all hierarchy and makes the table flat. Each combination of segment values is treated as a row, independently of the other rows.

<Frame>
  <img alt="image" />
</Frame>

The Grouped View preserves the hierarchy of breakdowns. It shows you segments within a breakdown as displayed below. This view is only applicable when you have 2 or more breakdowns

<Frame>
  <img alt="image" />
</Frame>

###### Alphabetical vs Value-Based Sorting

You can sort segments alphabetically or by the value of a particular metric. In the grouped view, sorting is configured on a per-breakdown level and respects the breakdown hierarchy.

In the below image, we sort Country *within* Item Category, which respects the hierarchy.

<Frame>
  <img alt="image" />
</Frame>

Hierarchy is defined by the breakdown order in the query panel.

##### Overall and Segment Sub-Totals

**Overall:** This refers to the value considering all the segments, independent of whether displayed or not based on your View N control; i.e changes to View N will not affect Overall numbers

<Frame>
  <img alt="image" />
</Frame>

**Sub-Totals:** In the grouped view, in addition to the Overall, segment sub-totals are also displayed. Similar to “Overall”, these values are independent of the View N control

<Frame>
  <img alt="image" />
</Frame>

##### Dynamic & Manual Segments

Dynamic Segments let you decide how many segments to display per breakdown in your report. With Dynamic Segments, the segments selected in the report will change based on your latest data and the current sort order. Manual Segments let you choose specific segments that will always display in the report, regardless of the data or sorting.

<Frame>
  <img alt="image" />
</Frame>

When using Dynamic Segments, you can select the number of segments to display from the column headers.

<Frame>
  <img alt="View_N_gif" />
</Frame>

In the ungrouped view, choose the number of rows to display:

<Frame>
  <img alt="image" />
</Frame>

In the grouped view, you can choose the number of rows you want to display for each breakdown:

<Frame>
  <img alt="image" />
</Frame>

<Frame>
  <img alt="image" />
</Frame>

**Notes about Dynamic Segments**

* View N only controls how many segments to display. To decide which segments to display i.e if it’s the top segments by value or bottom segments by value or alphabetical, please change the “Sort Order”.
* View N will show the minimum of N and how many segments are in your report. For example, if you set N=10 but you only have 7 segments, we will only show 7 rows.
* When selecting “Show All”, the maximum number of segments displayed in the UI will depend on the chart type.

## Advanced

### Formulas

Use Formulas to make calculations using simple arithmetic operators.

Mixpanel supports the following operators:

* \+ : Add
* * : Subtract
* \* : Multiply
* / : Divide
* () : Use parentheses to influence the order of operations

You can also use numbers as constants in a formula. Multiply a ratio by 100 to display as a percentage, for example. Divide a property value tracked in seconds by 3,600 to display the value in hours. You can rename a formula by selecting Rename in the overflow menu of the formula.

Click the **Metrics** button, then select Formula.. Each event in the query shows a letter next to it, which indicates its variable name. Use these letters in combination with the operators to calculate a more advanced query. For example, you can use the DAU, WAU, and MAU functions in Formulas to calculate the stickiness of your product:

<Frame>
  <img alt="Formulas 1" />
</Frame>

To note, you cannot nest a formula metric when constructing another formula.

#### Save formulas for re-use

<Note>
  Users on an Enterprise or Growth plan can save Formulas for reuse. Free users can create Formulas locally within a report but cannot save them. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Use existing events to create calculated formulas, like Bounce Rate & % Active Users, that can be saved and reused by others within the project.

<Frame>
  <img alt="saveformula.gif" />
</Frame>

Some nuances to note:

* Once you save a formula, A,B,C refer to what’s **within** the saved formula modal
* To edit a saved formula, expand the metric and edit inline, and then save
* When a saved metric is updated, it will update across all reports it’s being used in
* A saved formula can’t reference another formula

To access and re-use saved formulas, click on “+Formula”, and then see the list of saved formulas. You can also look at all the saved formulas in the Lexicon tab “Metrics”. Some callouts regarding permissions:

* All roles can create a saved formula, but only some roles can share them with the whole project for re-use
* You can only look at saved formulas created by you or shared with you

### Custom Bucketing

Insights will automatically group your high-cardinality segments into buckets. Buckets can be edited by using the "Custom Buckets" option in the overflow menu: You can choose "Even" to get buckets of uniform size, and you can choose "Varied" to get buckets of different sizes. This helps with organizing outliers, or with drilling deeper into particular ranges.

<Frame>
  <img alt="Bucketing" />
</Frame>

### Time Period Comparisons

Compare the current period of time to previous periods to track trends and growth in your product’s use. Compare traffic from a specific campaign period or event from one year to the next, or compare the success of that campaign to your normal traffic.

Note that if a data point for a previous year falls on a weekend, the data point is automatically moved to the next Monday to give a clearer picture of the data change from one year to the next.

Click on the **Compare to past** button at the top of your Insights graph and select the time period you wish to compare to. You can also select a custom date range.

<Frame>
  <img alt="Time Period Comparison" />
</Frame>

### Value Comparisons

When you have multiple metrics, or have broken down a metric by a property, you can compare them against each and the relative value. Click on **Compare** -> **Overall**. This works for all measurements. For a "totals" measurement, you can see the percentage that a particular segment makes up. For non-sumable aggregations, it compares the segment value to the whole, unsegmented value.

<Frame>
  <img alt="Value Setting" />
</Frame>

### Profile Analysis

Profile metrics allow you to access profile data and visualize your users with filters and breakdowns based on their profile properties. When exploring Profiles, you are always analyzing all user profiles. Select the [Measurement](/docs/reports/insights#measurements) you want to use to calculate results by clicking on **Total** and selecting an option from the drop-down. You can calculate based on users or profile property value.

[Link to Demo](https://www.loom.com/share/dc5e909f2d7f427ca962e493e87894ad)

### Annotations

To clarify the results in your Insights report, add detailed annotations directly to your time-series charts (such as line, stacked line, column, and stacked columns charts). Annotations are tied to a specific date on the chart, rather than a particular point of data on the chart.

Learn more about [Annotations](/docs/features/annotations).

### Measurements

[Link to Demo](https://www.loom.com/share/22d760d014234a1eb566f68dda79c58f)

Measurements in Mixpanel reports allow you to perform more complex calculations on your queries - this includes computing aggregate values of your event and property data, including totals, uniques, and averages.

The following measurements are only available in Insights, and are separated into groups based on what is being calculated: Total, Unique, Count users, aggregate property values, aggregate property values per user, and count sessions.

Select the measurement you want to use to calculate results by clicking on **Unique Users** and selecting an option from the drop-down. You can calculate based on events, users, event property value, event property value per user, and sessions.

<Frame>
  <img alt="Measurements 1" />
</Frame>

The following functions have additional aggregation options which you will be prompted to select:

| Function                    | Aggregation options                                                                                                                                                              |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Frequency per User          | Distribution<br />Average<br />Median<br />Percentiles (P25,P75,P90,Nth)<br />Minimum<br />Maximum                                                                               |
| Aggregate Property          | Sum<br />Average<br />Median<br />[Distinct Count](https://www.loom.com/share/7d0e42f847c24b3c8720d5b6a6bedeb4)<br />Percentiles (P25,P75,P90,P99,Nth)<br />Minimum<br />Maximum |
| Aggregate Property per User | Average<br />Sum<br />Distribution<br />Median<br />Percentiles (P25,P75,P90,Nth)<br />Minimum<br />Maximum                                                                      |

These functions provide additional aggregation options following the initial calculation because they are “per user” calculations. “Per user” calculations first calculate the value per user, which is an unhelpful query in its raw form, but becomes useful when you perform an aggregation on that calculation.

Selecting any of these functions gives you the option to choose different ways to aggregate this data. The default aggregation is **Average**, which you can click on to select a different option such as distribution, median, 25/75/90th percentiles, minimum, and maximum.

<Frame>
  <img alt="Measurements 2" />
</Frame>

If the measurement you select calculates based on property (“Event Property Values” or “Event Property Values Per User”), you will be prompted to select an event property. You can find more information about each measurement and how they are calculated below:

#### Events

| Function Name      | Events Calculation                                                                                                                                                                   | Profiles Calculation |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
| Total Events       | Total count of \[event] performed.<br />Example: How many times did my users watch a video?                                                                                          | N/A                  |
| Frequency per User | The number of events performed per user.<br />Example: How many videos were watched per user?<br />Aggregation options: Average, distribution, median, percentiles, minimum, maximum | N/A                  |

#### Users

This can refer to measuring the total number of user profiles, as well as the number of unique users that performed an event. DAU, WAU, and MAU are accessed through the advanced settings of unique users. Select the > arrow to choose any XAU options.

If you select the DAU, WAU, or MAU function for a date range that includes the current day, the query will take the end of the current day as the end of the query’s time segment (even though it’s in the future). For example, today is April 25th, and it’s 4:22 PM. If you make a query to show WAU and you select “current day” as your date range, the query will return the count of unique users between April 19 at 12:00:00 AM and April 25 at 11:59:59.

<Frame>
  <img alt="Measurements 3" />
</Frame>

| Function Name              | Events Calculation                                                                                                                                           | Profiles Calculation                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| Total                      | N/A                                                                                                                                                          | Total count of user profiles. <br /><br />**Example**: What's my total number of users? |
| Unique Users               | The number of users who performed \[event] or are a part of the cohort.<br /><br />**Example**: What's the count of users who watched a video?               | N/A                                                                                     |
| Daily Active Users (DAU)   | The number of users who performed \[event] within the last 24 hours.<br /><br />**Example**: What's the count of users who watched a video on the last day?  | N/A                                                                                     |
| Weekly Active Users (WAU)  | The number of users who performed \[event] within the last 7 days.<br /><br />**Example**: What's the count of users who watched a video in the week?        | N/A                                                                                     |
| Monthly Active Users (MAU) | The number of users who performed \[event] within the last 30 days.<br /><br />**Example**: What's the count of users who watched a video in the last month? | N/A                                                                                     |

**Example of MAU**

Assuming we would like to find the MAU of the last 6 months (e.g. Jul 5, 2023 to Jan 1, 2024)

* If the time interval is "Month": [https://mixpanel.com/s/3LC8ll](https://mixpanel.com/s/3LC8ll)

  * For each month, we will look at the last date in the time frame, and count 30 days back from that.
  * So for the month of Dec, we will count the total number of active users from Dec 2 to Dec 31
  * As long as the user watches video once, anytime between Dec 2 to Dec 31, they will be counted as part of the MAU for Dec
* If the time interval is "Day": [https://mixpanel.com/s/47YhnE](https://mixpanel.com/s/47YhnE)

  * For each day, we will look at the last date in the time frame, and count 30 days back from that.
  * So for Nov 1, we will count the total number of active users from Oct 3 to Nov 1
  * As long as the user watches video once, anytime between Oct 3 to Nov 1, they will be counted as part of the MAU for Nov 1
* If the time interval is "Week": [https://mixpanel.com/s/dA5BK](https://mixpanel.com/s/dA5BK)

  * For each week, we will look at the last date in the time frame, and count 30 days back from that.
  * So for the week of Nov 27 to Dec 3, we will count the total number of active users from Nov 4 to Dec 3
  * As long as the user watches video once, anytime between Nov 4 to Dec 3, they will be counted as part of the MAU for Nov 27 to Dec 3.

**How do breakdowns work with Uniques?**

When you apply a breakdown to a metric, by default, Mixpanel tells you how many unique users contributed to each segment. For example, in the image below, you can see there were a total of 2441 unique users, while the sum of individual segments is more than 3000. This is correct. That is because one user could have seen both a Home Page and a Shop Page, so they get counted as a user towards both segments.

By default, Mixpanel answers the question: per segment, tell me the number of unique users, DON'T tell me how the 2441 users are distributed across the various pages with a user being counted only towards one segment, which will require assigning a user to one segment even if they contributed towards multiple segments.

<Frame>
  <img alt="image" />
</Frame>

There are some cases though, where you want to know how the 2441 users are distributed, generally either by their first or last action. For example, based on the last page (segment) a user saw, tell me the distribution of users. You can enable this now via the advanced control for Uniques, by choosing which segment to associate a user to: either the first segment or the last segment in the chart date range (7D in the below image)

<Frame>
  <img alt="image" />
</Frame>

To note - in a line chart, there are two concepts of time period: chart date range (3M below) and time interval (weekly interval below). When advanced controls are used in a line chart, it assigns a segment based on the first/last segment for each time interval, NOT across all time intervals in the chart range.

#### Aggregate Property

| Function Name             | Events Calculation                                                                                                                                                                 | Profiles Calculation                                                                                                                                  |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sum                       | The total of a numeric property value across all instances of \[event].<br /><br />**Example**: What's the total number of minutes of videos watched?                              | The total of a numeric property value across all user profiles.<br />Example: What's the total revenue across all users?                              |
| Average                   | Average of a numeric property value across all instances of \[event].<br /><br />**Example**: What's the average number of minutes per video watched?                              | Average of a numeric property value across all user profiles.<br />Example: What's the average revenue across all users?                              |
| Distinct count            | Calculates the unique count of property values across all instances of \[event].<br /><br />**Example**: How many unique songs were played in the last 30 days?                    | Calculates the unique count of property values across all profiles.<br />Example: How many unique countries were our video watchers from?             |
| Median                    | Median of a numeric property value across all instances of \[event].<br /><br />**Example**: What's the median number of minutes per video watched?                                | Median of a numeric property value across all user profiles.<br />Example: What's the median revenue across all users?                                |
| Percentiles (25/75/90/99) | The 25/75/90/99th percentile of a numeric property value across all instances of \[event].<br /><br />**Example**: What's the 25th percentile number of minutes of videos watched? | The 25/75/90/99th percentile of a numeric property value across all user profiles.<br />Example: What's the 25th percentile revenue across all users? |
| Minimum                   | Minimum of a numeric property value across all instances of \[event].<br /><br />**Example**: What's the minimum number of minutes per video watched?                              | Minimum of a numeric property value across all user profiles.<br />Example: What's the minimum revenue across all users?                              |
| Maximum                   | Maximum of a numeric property value across all instances of \[event].<br /><br />**Example**: What's the maximum number of minutes per video watched?                              | Maximum of a numeric property value across all user profiles.<br />Example: What's the maximum revenue across all users?                              |

#### Aggregate Property per User

| Function Name  | Events Calculation                                                                                                                                                                                                                                               | Profiles Calculation |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| Sum            | The total of a numeric property value across all instances of \[event] per user.<br /><br />**Example**: What's the total number of hours of videos watched per user?<br />**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A                  |
| Average        | Average of a numeric property value across all instances of \[event] per user.<br /><br />**Example**: What's the average number of hours of videos watched per user?<br />**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A                  |
| Distinct count | The number of distinct property values per user.<br /><br />**Example**: How many different videos did each user watch?<br />**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum                                               | N/A                  |
| Minimum        | Minimum of a numeric property value across all instances of \[event] per user.<br /><br />**Example**: What's the minimum number of hours of videos watched per user?<br />**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A                  |
| Maximum        | Maximum of a numeric property value across all instances of \[event] per user.<br /><br />**Example**: What's the maximum number of hours of videos watched per user?<br />**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A                  |

#### Total Sessions

| Function Name       | Events Calculation                                                                                                                        | Profiles Calculation |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| Sessions with event | The number of sessions that contain \[event].<br /><br />**Example**: What's the total number of sessions in which users watched a video? | N/A                  |

#### Additional Aggregation Option Examples

| Measurement                              | Average                                                            | Distribution                                                                         | Median                                                           | Percentiles (25/75/90)                                                         | Minimum/Maximum                                                       |
| ---------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| Total per user                           | What's the average number of songs played per user?                | What is the distribution of my users by the number of songs played?                  | What's the median number of songs played per user?               | How many songs did the 90th percentile user listen to?                         | How many songs did my least/most active user listen to?               |
| Sum of property value count per user     | What's the average cumulative watch time per user?                 | What's the distribution of my users by the cumulative minutes of content watched?    | What's the median of the cumulative watch time per user?         | How many cumulative minutes has the 90th percentile user watched?              | How much has the lowest/highest spender spent?                        |
| Average of property value count per user | What's the average of the average cart value for each rider?       | What's the distribution of my users by the average cart value per user?              | What's the median of the average cart value per user?            | What's the average cart value for the 90th percentile user?                    | What's the minimum/maximum average cart value?                        |
| Distinct property value count per user   | What's the average number of unique song titles heard by my users? | What's the distribution of my users by the number of unique song titles listened to? | How many unique songs does the median user listen to?            | How many unique songs does the 90th percentile user listen to?                 | What's the minimum/maximum number of unique songs my users listen to? |
| Minimum property value count per user    | What's the average of the minimum ratings provided per user?       | What's the distribution of my users by the minimum rating provided?                  | What's the median of the minimum ratings provided by users?      | What's the minimum rating provided by the 90th percentile user?                | What's the minimum rating across all ratings??                        |
| Maximum property value count per user    | What's the average of the maximum gaming session length per user?  | What's the distribution of my users by the maximum gaming session length?            | What's the median of the maximum gaming session length per user? | What's the maximum gaming session length provided by the 90th percentile user? | How long has the longest gaming session lasted across our users?      |

Here's a quick overview on "Distinct count" of property values, and how that differs from "Distinct count" of property values per user:

Here are some use cases that are now possible with "Distinct count" of property values:

* How many **unique items** were added to cart yesterday?
* How many **unique songs/videos** were played in the last 30 days?
* How many **unique files** were worked on in the last week?

### Analysis Settings

Allows you to change the metric being measured. Access by going into the advanced section of the measurement menu.

<Frame>
  <img alt="Rolling and Cumulative" />
</Frame>

* **Rolling Average:** Rolling analysis calculates the rolling average of the data set. A rolling average curve is a series of averages from subsets of data. Use rolling average analysis to remove noise or spikes from data and smooth out trends over time. Mixpanel calculates the rolling average based on the selected time interval (hour, day, week, month, or quarter) for each data point in the graph.<br />For example, if you make a rolling analysis query for the past 30 days, Mixpanel calculates the rolling 7-day average by default. The value reported on each day in the line graph is the average of the values from the 7 days leading to that day. In the case of the first 6 days in your selected time period, the 7-day-average calculation will include days before the selected time period.
* **Cumulative:** Adds up the values of each point on the graph as it goes along, so the height of the line will increase over time.

[Link to Demo](https://www.loom.com/share/4d49fe9a64e24fb2b6cac44f86839fd2)

### View Users

Click a segment in an Insights report to see the list of users that underlie that data point. This helps see a representative sample of users from any analysis, so you can drill into anomalies or simply get to know your users. You can also save this user list as a cohort to either export or use for message targeting.

See this [video walkthrough](https://www.loom.com/share/5568e266532b4804a1c2d36d678eb1a2) for examples of how View Users can help you understand users contributing to a specific metric.

### View Events

Click on a chart segment in Insights and view the raw events that made up that metric. You will be redirected to the Events page.

<Frame>
  <img alt="Reports View Events" title="Reports View Events" />
</Frame>

### View Sample Events

If you hover over any event and click "View Sample Events" in the context panel, it redirects you to the Events page with the 100 most-recent samples of that hovered event. You can see a few samples of an event to help you decide whether that's the right event you want for your analysis, or which property you should use for filters/breakdowns.

<Frame>
  <img alt="Reports View Sample Events" />
</Frame>

### Date Range Guardrails

To ensure a smooth self-serve experience and fast query performance, certain date-range guardrails apply depending on the type of report you create:

* **Hourly granularity reports** can include a maximum date range of 31 days.
* **Daily granularity reports** can include a maximum date range of 12 months.
* **Reports using All Events** can include a maximum date range of 93 days (approximately 3 months).
* **Reports using cohorts** can include up to 93 time intervals—for example, 93 weeks or 93 days. This allows queries such as “the last 3 months at daily granularity.


# Retention
Source: https://docs.mixpanel.com/docs/reports/retention

Measure engagement over time

## Overview

<Frame>
  <img alt="/Screen_Shot_2021-05-27_at_7.49.12_AM.png" />
</Frame>

The Retention report in Mixpanel is designed to assess user engagement over a specified period of time. Retention of your users is critical to achieving product-market fit and sustainable long-term growth, and this report will help you understand how long users continue to come back and find value from your product.

Retention can be accessed from the left-side navigation by clicking the '+ Create New' button.

<Note>
  The Retention report is available on all free and paid subscription plans.
</Note>

## Use Cases

Here are some of the sample questions you can answer in Retention:

* On average, how many users are still active after two weeks of signing up?
* What percent of all users are still sending messages after seven days?
* How has my 7-day messaging retention changed over time?
* What percent of users sent messages in 2, 3, or 4 distinct hours of the day?

## Quick Start

<Frame>
  <iframe />
</Frame>

Building a Retention report follows the same high-level steps as building any other report. You can read about report-building basics [here](/docs/reports).

### Step 1: Define your Retention Behavior

The Retention Behavior is the basic building block of a Retention report. A Retention Behavior is doing an event and then coming back to do another event. In this case, since we want to know retention after signup, choose "Sign Up Completed" in the first event slot. Then, we want to know if users are coming back and using the product, so we choose "Any Event" in the second event slot. At this point, your query should look like this:

<Frame>
  <img alt="/retention_beta_1.png" />
</Frame>

You can save the Retention Behavior you built and reuse it in other reports. Select the "..." button in the top right corner of the metric, then click "Save Behavior". Note that saving a behavior and saving a metric are different: a saved behavior consists of the events/Funnels/Retention, while a saved metric consists of the saved behavior and the measurements of the behavior.

Learn more about [Saved Metrics and Behaviors](/docs/features/saved-metrics-and-behaviors).

### Step 2: Choose your Measurement

After your retention behavior is defined, you can choose how you want to measure it. By default, the Retention report will select retention rate as the measurement.

There are 4 types of measurement

* Retention Rate: Percentage of users retained within the window.
* Unique Users: Absolute number of users retained within the window.
* Property Sum: Total sum of property within a window (eg, total video watch duration).
* Property Average: Average across users of the sum of properties within the window (e.g., average watch time per user).

<Frame>
  <img alt="/Updated_retention_measurements.png" />
</Frame>

Your Retention Behavior, combined with the measurement, forms a Metric, which you can also save like a Retention Metric.

### Step 3: Choose Filters

Filters exclude unwanted data. In this case, we only care about events performed on the "Chrome" browser. Therefore, add a "Browser" filter, where Browser equals "Chrome". At this point, your query should look like this:

<Frame>
  <img alt="/Retention_Filter.png" />
</Frame>

### Step 4: Choose Breakdowns

Breakdowns segment data into groups. In this case, we want to break our report down based on the browser version they are using to Sign Up. Therefore, add a "Browser Version" breakdown. At this point, your query should look like this:

<Frame>
  <img alt="/Retention_Breakdown.png" />
</Frame>

### Step 5: Choose Visualization

You can visualize your metric in a variety of ways. Mixpanel allows you to choose how you would like to visualize your data. Select "Retention Curve" in the top right to change your visualization. In Retention, you can choose:

* Retention Curve - see how users are retaining over time. Users are bucketed based on when they initially entered the product.
* Line - see how your metric is trending over time. Used to see if a particular retention group rate is trending over time.
* Metric - see a summary view of your metric

<Frame>
  <img alt="/retention_beta_5.png" />
</Frame>

## Basic Features

### Retention Curve

<Frame>
  <iframe />
</Frame>

The retention curve chart displays retention data as both a line chart and a table. Data is identical between the two. The line chart provides a visual representation of users becoming inactive over time, while the table provides a heat map to show which groups have the best retention.

<Frame>
  <img alt="/Screen_Shot_2021-05-27_at_7.49.12_AM.png" />
</Frame>

**Incomplete Buckets:** Boxes with an asterisk (\*) indicate that the data is still in flux and not set yet because the time is still ongoing. Hover over a box to see when the last qualifying date for that bucket will occur.

**Color Mapping:** Each box within a row is assigned a shade of purple. The shading gets darker the higher the retention percentage. It's important to note that the scale is relative to each cohort row.

### Line chart

<Frame>
  <img alt="/Retention Line Chart" />
</Frame>

Select **Line** from the visualization drop-down list to see how your retention metrics are changing over time. You can see how your retention rate or number of users retained is trending. You can see this trend for any of the retention time unit buckets. You can change between the different time unit buckets (i.e., \< 1 Day, Day 1, Day 2, ...) to see if your retention metrics are improving or declining along your retention curve.

### User Cohort Buckets

Retention counts users, not event totals. In other words, each of the user cohort buckets will include every unique user that met the "A event" criteria in that time window, starting at 0:00 of the first day of the bucket and ending at midnight of the last day. A customer can only be counted once per bucket, but can be included in more than one bucket.

The first column (Date) indicates the day/week/month when the user performed the "A event". The Size column indicates the number of users who performed the "A event" within the time period.

For example, if you are bucketing based on your "Item Purchased" event and creating weekly buckets, a customer who purchased at least one item each week will be in every bucket, not just the bucket of their first purchase.

## Advanced

### Retention Criteria

<Frame>
  <img alt="/Updated_retention_criteria.png" />
</Frame>

#### 'On or After' time interval

"On or After" Retention calculates the percentage of users who come back on a specific time unit (e.g., day, week, month) **or any time unit afterward**. A user can fulfill the "came back and did B criteria" on a specific time unit or any time in the future to be counted as retained in "On or After" Retention.

"On or After" Retention gives you a better sense of how long you are holding on to your users in an absolute sense. It will tell you how many users used your app and then ever returned to find more value. In other words, it's the opposite of the overall churn of your user base.

We think "On or After" retention is a better fit for most businesses, and it is the default calculation for the Retention report. This is because it’s more common that a product doesn’t require users to come back in each time unit to achieve the product’s value proposition, and more often than not, when doing retention analysis, we don’t only value the user coming back in a specific time unit as long as they eventually do. However, if this is important to you and your business, please utilize "On" Retention.

#### 'On' time interval

"On" Retention calculates the percentage of users who come back on a specific time unit (e.g., day, week, month).

After a user completes the “A criteria”, they will belong to a time unit cohort that corresponds with when they did the "A event", and the Retention report will start the clock counting from the time that particular user performed that "A event". When using "On" Retention, that same user must return to fulfill the “came back and did B criteria” on a specific and exact time unit relative to when they did the A criteria to be counted as retained.

For example, day 5 retention is the percentage of users who “came back and did B” exactly on the fifth day after they did the A event.

"On" retention is useful to understand high-level usage patterns.  We also recommend using "on" retention when your product relies on users returning on every time unit.

#### 'On or Before' time interval

“On or Before” is a retention criterion most commonly used with a measurement type of property sum or average. It looks at the total activity done during the period between the start and end events.

For example, if you want to look at the 30-day LTV (lifetime value) of e-commerce users, you would look at the total money spent on purchases from sign-up for 30 Days. This includes looking at revenue spent from Day 0, Day 1, ..., to Day 30, where revenue is a property on the event purchase.  Similarly, if you want to look  at 30-day ARPU (average revenue per user), you would look at averaging the total revenue spent per user within the first 30 days.

#### 'Streak mode'

“Streak mode” is mostly meant to count unique users doing consecutive actions across time intervals. If the birth event and retention event are the same, the birth event will count towards the streak.

For example, played a game for 5 consecutive days since sign-up, or visited the doctor for 8 consecutive months since registering for a clinic.

#### Advanced Use-Cases

These use-cases use a combination of different retention criteria & measurement types

<Frame>
  <iframe />
</Frame>

* What is the total revenue (or LTV) for new users in the first 7 days? How has this changed over time

  * Retention Criteria: On or Before
  * Measurement: Property Sum; 7 Days
* What is the average video watch-time for a new subscriber in their first 30 days since subscription? How has this changed over time?

  * Retention Criteria: On or Before
  * Measurement: Property Average; 30 Days
* How many new users have a Wordle streak for 5 days or 10 days?

  * Retention Criteria: Streak Mode
  * Measurement: Unique Users; 5 days

### Custom Retention Brackets

Not all retention analysis can be done with a set, repeated cadence, and it is not always important to measure how a user came back relative to each and every particular time unit.

Custom bracket retention gives you the flexibility to split up your retention buckets into customized intervals of multiple days, weeks, or months to create meaningful touchpoints as you see fit.

#### Use Cases

For example, let's answer an important mobile gaming question: How often do my users come back and play a game between 15 and 30 days after signing up to represent mid-term players?

In mobile gaming, industry-standard intervals typically examine retention for users who came back and play a game on Day \< 1, Days 1-3, Days 4-7, Days 8-14, and Days 15-30.

Typical "exact day" retention buckets don't quite solve for this use case because users should be able to play a game on any day between day 15 and 30 and be counted in a single bucket to understand how many users were retained in that entire period. Exact day retention will log users in each day bucket (15, 16, 17, ..., 30), which, while more granular, doesn't give a retention percentage for the entire interval. Instead, we want to know how many users played a game at all in any of the days 15-30.

**Free trials:** If you want to understand how many users come back to use the product during a 7-day free trial, and also who came back and kept using the product in the 30 days after the free trial is up, you could do something like this:

<Frame>
  <img alt="Retention 7 30" />
</Frame>

**In between cadences:** Are you somewhere between a DAU or WAU product? You can group daily buckets to understand how your users retain every 3 days (bi-weekly).

<Frame>
  <img alt="Retention 3 3" />
</Frame>

#### Setting Custom Brackets

First, go into the time unit drop-down in the Retention query builder and select **Custom.**

<Frame>
  <img alt="Setting Custom Buckets" />
</Frame>

Then, select the size of each bracket for the given time unit and click "Apply". In this example, we are selecting the number of days that are in each custom bracket.

<Frame>
  <img alt="Retention 3 3" />
</Frame>

Each of these intervals is its own retention bucket, and if the user does the "come back and did B" event anytime inside that bucket, they are counted as retained. Now I will be able to understand what percent of users come back to play at least one game on any day between day 15 and day 30 from signing up.

#### Calendar Retention Mode

You can go into the advanced menu under Retention Criteria to switch the retention mode from the default rolling time windows to calendar-defined time windows. This aligns the retention calculation so that all users entering within a time bucket get calculated together.

<Frame>
  <img alt="/13599603833876.png" />
</Frame>

This may be useful in scenarios where you want to check engagement on a strict day basis, OR if you want to check retention of your user base for the entire month, and when they return, regardless of when in the month they first entered or when in the next month they returned.

<Frame>
  <img alt="/13599765981076.png" />
</Frame>

In the above example, we're looking at retention on a calendar week basis.

* In the \< Week 1 bucket, 6 users did "Sign Up" at any point of the week of Dec 23 - Dec 30, and returned to do "Post Content" in that same week of Dec 23 - Dec 30.
* In the Week 1 bucket, 10 users did "Sign Up" in the same Dec 23 - Dec 30 interval, but returned to do "Post Content" only sometime between Dec 30 - Jan 6.

##### How is this different than the basic retention mode?

This [Loom video](https://www.loom.com/share/5484c7bdd61a4332818ceef20f475176) should provide an overview of what calendar interval retention is and how it works vs the default rolling window retention

**\[Basic] Rolling interval retention** - Considers time intervals based on the user’s time of birth; i.e:

* Day 1 retention = 24-48 hrs since person’s birth
* Week 1 retention = 7-14 days since person’s birth
* Month 1 retention = 30-60 days since person’s birth

**\[Advanced] Calendar interval retention** - Considers time intervals based on ‘calendar’ time; i.e:

* Day 1 retention = next ‘calendar’ day since person’s birth. If a person did an activity at 8 pm on Monday and then 6 am on Tuesday, the person is counted under Day 1 retention even though it’s just 10 hrs later
* Week 1 retention = next ‘calendar’ week since person’s birth. If a person did an activity on Friday and then Monday, the person is counted under Week 1 retention even though it’s just 3 days, since the ‘calendar’ week changed
* Month 1 retention = next ‘calendar’ month since person’s birth. Similarly, if a person made a purchase on 25th Feb and then again on 3rd March, the person will be counted under Month 1 retention metrics

NOTE — All the above cases would NOT qualify under Day 1, Week 1, or Month 1 rolling interval retention.

**When should you use the calendar vs rolling interval retention mode?**

Both modes are extremely useful. It totally depends on the use-case you’re trying to answer. Some examples -

| Use-Case                                                                                                         | Which mode to use? |
| ---------------------------------------------------------------------------------------------------------------- | ------------------ |
| Day 1 retention for apps focused on “daily engagement” like music, meditation, or workout apps                   | Calendar-interval  |
| How many users come back after month 1 (30 days)? How many come back after 3 months (90 days)?                   | Rolling-interval   |
| Understanding the effect of a marketing promotion, how many people came back the week after the promotion ended? | Calendar-interval  |
| What’s Mixpanel's quarterly revenue retention? How were gross and net retention in Q4 vs Q3?                     | Calendar-interval  |
| How many users renewed their Netflix subscription? To note, renewals happen 30 days after the last payment       | Rolling-interval   |

Above said, the general expectation is that product use-cases which focus on user stickiness are likely to use rolling interval mode. Marketing & Revenue teams that focus on calendar dates for their activities are likely to use the calendar interval model.

### Saved Retention Behaviors

You can save the Funnel Behavior you built and reuse it in other reports. This can be helpful when there is a sequence of events that you frequently analyze (such as sign-up flow), or if you want to analyze your Funnels Behavior alongside other metrics in an Insights report.

Select the "..." button in the top right corner of the metric, then click "Save Behavior".<br />Learn more about [Saved Metrics and Behaviors](/docs/features/saved-metrics-and-behaviors).

### Frequency View

<Frame>
  <iframe />
</Frame>

You can use the Frequency report to learn how frequently users return to use your product or service.

To generate Frequency reports, click **Reports**, **Retention**, and select the **Frequency** option under the toggle for retention.

<Frame>
  <img alt="/Screen_Shot_2022-07-05_at_4.41.04_PM.png" />
</Frame>

Mixpanel groups unique users in time-incremented buckets when they first complete an action, and then groups those same users in subsequent buckets when they return and perform the same or different actions.

The buckets measure the number of unique time buckets in which a user was active. Depending on the interval chosen, this will be one of:

* unique hours in a day
* unique days in a week
* unique days in a month

This will show how engaged users are with an action.

#### Frequency Criteria

**Cumulative Frequency**: calculates the number of users who did the event **in at least** X unique intervals. This shows overall engagement up to each frequency interval.

**Non-cumulative Frequency**: calculates the number of users who did the event in **exactly** X unique intervals. This is useful for determining exact engagement and for further investigating specific groups of engaged users.

## FAQ

**1. Retention reports do not extend beyond 60 days. How can I look beyond the 60-day mark?**

Currently, when using "Day" retention, Retention reports are limited to 60 days. One way to extend it would be to switch "Each Day" to "Each Week/Month" under the Retention Criteria.

**2.How is Retention calculated?**

When you create an unsegmented retention query (i.e., a retention query that is not segmented by a property or cohort), Mixpanel will automatically intervalize the retention calculation.

In other words, we will calculate the retention of each and every cohort based upon the selected birth interval unit (day/week/month cadence that the user performed the A action) and then summarize it into one line by taking the average of all complete buckets. You can see the retention of each interval by expanding the Average Retention column:

<Frame>
  <img alt="/intervalized_retention.png" />
</Frame>

Segmented queries are now calculated with that same intervalized average method, but for each particular property value or cohort segment. You can now expand any particular segment's name in a retention query to see the retention of each day, week, or month interval within that segment:

<Frame>
  <img alt="/segemented_intervalized_retention.png" />
</Frame>

Intervalized averages to segmented retention queries have two key advantages:

* **Not including users in incomplete periods:** The non-intervalized method did not give all users an equal chance to qualify for the later retention buckets. Newer, more recent users to come into the query towards the end of your date range would not have enough time to pass to have the opportunity to be retained in the later date buckets. This would sandbag the last retention buckets in your query. With intervalized retention, Mixpanel only counts the completed time periods into the Average Retention calculation so that all users have the same opportunity to be retained.
* **More granular analysis:** Users are now able to see how the individual birth interval cohorts are performing within a particular segment. This unlocks the ability to get more answers and dive deeper into particular cohorts of interest.

**3. How is the "Average" row for Retention reports calculated?**

Mixpanel calculates the "Average" row values by taking the average of all the completed buckets, **weighted** by the number of users who enter. Let's walk through an example using this sample data:

| Date    | Total Profile(s) | Day 1 Retained Users |
| ------- | ---------------- | -------------------- |
| March 1 | 1000             | 500                  |
| March 2 | 500              | 400                  |
| March 3 | 700              | 10 (incomplete)      |

From our sample data, the average value for day-1 retained users is calculated as follows:

**When examining a Retention report in the % / Retention Rate view:**

C\_March 1 = 500 (count retained for March 1)

C\_March 2 = 400 (count retained for March 2)

W\_March 1 = 1000 / 1500 (weight for March 1)

W\_March 2 = 500 / 1500 (weight for March 2)

P\_March 1 = 1000 (total profiles for March 1)

P\_March 2 = 500 (total profiles for March 2)

\*\*Weighted Average of Retained Users = C\_March 1 \* W\_March 1 + C\_March 2 \* W\_March 2

In our sample data, this computes to: ( 500 \* 0.66 ) + ( 400 \* 0.33 ) = 466.66

Next, we have to get the weighted average of the total profiles that were eligible for being retained.

\*\*Weighted Average of Total Users = P\_March 1 \* W\_March 1 + P\_March 2 \* W\_March 2

In our sample data, this computes to: ( 1000 \* 0.66 ) + ( 500 \* 0.33 ) = 825.00

Finally,

\*\*Weighted Average of Retention Rate = Weighted Average of Retained Users / Weighted Average of Total Users

In our sample data, this computes to: 466.66/833.33 \* 100% = 56%

**When examining a Retention report in # / Absolute view:**

C\_March 1 = 500 (count retained for March 1)

C\_March 2 = 400 (count retained for March 2)

W\_March 1 = 1000 / 1500 (weight for March 1)

W\_March 2 = 500 / 1500 (weight for March 2)

\*\*Weighted Average = C\_March 1 \* W\_March 1 + C\_March 2 \* W\_March 2

In our sample data, this computes to:(500 \* (1000 / 1500)) + (400 \* (500 / 1500)) = 466.67

**4. What does the Metric view in the Retention Trends report show?**

The Metric view in the Retention Trends Report shows the ***overall value*** for the retention trend for that time period.  There is a `Cohortize` option under the `Advanced` menu that, when enabled, will show the ***weighted average bucket*** for that retention trend.


# Response Times
Source: https://docs.mixpanel.com/docs/response-times



Mixpanel Support Engineers are always ready to lend their product expertise and share tips to help you get the most out of your Mixpanel experience. This article will cover:

1. Contacting Mixpanel Support
2. Support Offerings and Response Times

## Contacting Mixpanel Support

1. If you're logged in to Mixpanel, click on “Contact Support” in the Help Menu:

   <Frame>
     <img alt="Screenshot 2026 06 25 At 12 38 38 PM" title="Screenshot 2026 06 25 At 12 38 38 PM" />
   </Frame>
2. If you aren't logged in, you can access the same form by going to: [mixpanel.com/get-support](https://mixpanel.com/get-support)

## Support Offerings & First Response Times

Our Support Engineers are located all over the world – in San Francisco, Barcelona, London, Singapore, Bangalore and Tel Aviv – and we strive to respond to support issues as quickly as possible. Support offerings vary depending on your Mixpanel plan.

| Plan                | Critical FRT\* | Normal FRT\* | Hours of Operation |
| ------------------- | -------------- | ------------ | ------------------ |
| Premium Plus\*\*    | 1 hour         | 4 hours      | 24 x 7             |
| Premium Support\*\* | 4 hours        | 8 hours      | 24 x 5             |
| Enterprise          | 8 hours        | 24 hours     | 24 x 5             |
| Growth              | 24 hours       | 48 hours     | 24 x 5             |
| Free                | 48 hours       | N/A          | 24 x 5             |

* FRT: First Response Time (within the Hours of Operation). First response times are response times within the Hours of Operation and represent target response times except for critical issues for customers on Premium Support packages.

\*\* Add-on Support Plans are available for purchase with the Enterprise plan.

### AI Help Chat

If you're logged into Mixpanel, you can access the AI Help Chat via the Help Menu. This allows you to open a ticket with Mixpanel Support (FRTs apply) or troubleshoot your issue with the AI Help Chat agent directly. As opposed to the [Mixpanel Agent](/docs/mixpanel-agent), the AI Help Chat does not have access to your reports and data. The AI Help Chat can assist in troubleshooting most issues and escalate to Mixpanel Support if necessary.

## Ticket Priority Definitions

If you’re experiencing a persistent, widespread issue or cannot access your account, we'll prioritize your ticket as Critical. General product questions like how to use a feature, help understanding a report, or submitting a feature request will be categorized as Normal priority.

To see if there are any incidents affecting Mixpanel services, visit Mixpanel’s [Status Page](https://www.mixpanelstatus.com/) (or subscribe to receive notifications of future status updates). For all other issues, we’ll do our best to respond according to the table above and the severity of the issue. In the meantime, feel free to review our other resources:

* [Mixpanel Slack Community](https://www.mixpanel.com/community-slack): Crowd-source Mixpanel solutions and submit product ideas
* [Mixpanel Docs](/): Best practices, user guides, and frequently asked questions
* [Mixpanel API Reference](/reference/overview): API integration tutorials
* [Mixpanel Status Page](https://www.mixpanelstatus.com/): Updates on Mixpanel incidents to view or subscribe


# Root Cause Analysis
Source: https://docs.mixpanel.com/docs/root-cause-analysis

AI-generated explanations for why your metrics changed

## Overview

Investigating anomalies or trends in your data is extremely manual. Teams spend hours each week running the same repetitive process (picking properties, running breakdowns, eyeballing segments) to figure out what drove a change in a metric.

Mixpanel's **AI-Powered Root Cause Analysis (RCA)** feature does that work for you. Launch RCA from any Insights report, a fired alert, or the Mixpanel Agent and an AI agent automatically diagnoses what changed: it validates the anomaly, runs the relevant breakdowns, ranks the dimensions that contributed most, and writes up an interpretation with a confidence level and suggested next steps — all delivered as a Board you and your team can keep working from.

## How it works

When you run an RCA, Mixpanel immediately launches a new Board and exposes the agent's reasoning as it works:

1. **Validates the anomaly.** Confirms there's a real change to explain before going further. RCA compares your flagged point against a baseline window that ends right before it, sized automatically from your chart's time grain (hourly uses roughly the prior 24 hours, daily \~14 days, weekly \~9 weeks, monthly \~6 months); if your chart shows a longer range than that, RCA uses your range instead. It then measures how many standard deviations your point sits from that window's average (the z-score), with 2 or more being the bar for a real anomaly rather than routine noise. A seasonality check compares like-for-like periods (same weekday for daily data, same hour-of-day for hourly) so normal recurring patterns don't get flagged.
2. **Selects properties to analyze.** An LLM agent picks which properties to break down on, combining properties Mixpanel suggests for the event with any you've prioritized in [Custom RCA Settings](#custom-rca-settings). It spreads picks across plausible cause categories (acquisition, audience, platform, data quality, user identity), filters out high-cardinality identifiers and near-duplicates, and factors in your project's business context.
3. **Runs breakdowns.** Executes the chosen breakdowns to see which segments actually moved.
4. **Writes an interpretation.** Fills the Board with contribution factor analysis (each segment's share of the total change), ranked dimensions, an AI-written explanation of the likely cause, a confidence level, and suggested next steps.

Cards stream into the Board as each step completes, with a live progress banner at the top while the agent is still working.

<Info>
  **What the numbers mean.** The percentage change (sometimes called "lift") compares the data point you flagged against a baseline, which is the average of the periods just before it: `(flagged value - baseline) / baseline`, so +30% means it came in 30% above the recent norm and a negative number means below. Each segment's contribution percentage is its share of the total change: `(how much the segment moved) / (how much the whole metric moved)`, so if a metric dropped by 500 overall and one country accounts for 400 of that, it shows an 80% contribution. Confidence works differently: it's not a calculated number but a label ("High," "Medium," or "Low") the AI assigns to each finding based on how unusual the change is versus normal fluctuation (the z-score) and how cleanly a single segment explains it, so a big, clear change driven by one segment earns higher confidence than a small change spread across many segments or one that looks seasonal.
</Info>

## Where to launch RCA

<Steps>
  <Step title="From an Insights report">
    Open any Insights chart, hover over a data point that looks unexpected, and choose **Root Cause Analysis** from the popover. RCA launches scoped to that event and time window, and picks up any breakdown or segment already applied to the report so it analyzes the same slice you're looking at.
  </Step>

  <Step title="From a fired alert">
    When an alert fires, the notification (Slack, email, or webhook) includes a link that runs Root Cause Analysis and generates a Board for that alert. See [Alerts](/docs/features/alerts#root-cause-analysis) for how RCA fits into alerting.
  </Step>

  <Step title="From the Mixpanel Agent">
    Ask the [Mixpanel Agent](/docs/mixpanel-agent) to investigate a change (for example, *"explain this spike in signups"*) and it can kick off Root Cause Analysis for you. The analysis runs right in your Agent chat and produces the same RCA Board you can open and keep working from.
  </Step>
</Steps>

## The RCA Board

Because RCA generates a standard Mixpanel Board, it inherits all the capabilities of our typical Boards:

* **Anyone in your project can open it.** RCA Boards are project-shared by default, so teammates can pick up the analysis where you left off.
* **You can edit it like any Board.** Add cards, rearrange, annotate, or duplicate it if you want a private working copy.
* **Cards include contribution factor analysis.** Each ranked dimension lands as its own card with the breakdown, contribution percentage, and supporting context. You can edit this as needed before sharing.
* **The interpretation card summarizes findings.** The AI's written explanation, confidence level, and suggested next steps live at the top of the Board so anyone scanning the results gets the punchline first.

<Note>
  RCA only surfaces data the person running it already has permission to see. It won't expose personal information (PII) that wouldn't otherwise be visible to that user.
</Note>

## Re-run with added context

RCA doesn't always land the right answer on the first pass. It might miss a property that matters, or go down a path you already know isn't the real story. Instead of accepting the result or starting over, you can tell RCA what to do differently and re-run it in place.

Every RCA Board has an entry point at the top to dig deeper with the [Mixpanel Agent](/docs/mixpanel-agent). Describe what you want changed in plain English, for example:

* *"Go deeper on Android."*
* *"This isn't the main cause, try looking at plan type instead."*
* *"Ignore the bot traffic and re-check acquisition channels."*

RCA re-runs on top of the original inputs, applying your feedback, and updates the same Board in place. Prior iterations stay accessible from a dropdown on the Board, so you can compare runs or go back to an earlier one.

<Info>
  Each re-run counts as a run against your project's daily RCA cap. See [Limits](#limits).
</Info>

## Custom RCA Settings

Oftentimes, customers know which properties matter for their business and want to direct the root cause analysis to focus there first.

In the AI Settings tab of your Project Settings, you can specify which event properties RCA should prioritize during analysis. For example, a marketing team that knows anomalies usually trace back to `utm_campaign_id` can point RCA at that dimension so it's always considered first. Properties you prioritize are combined with Mixpanel's automatic suggestions, so you never lose the agent's broader view — you just guide it toward the dimensions you care most about.

<Info>
  These settings only influence which properties RCA prioritizes. They don't control RCA's analysis sequencing or methodology — regardless of the instructions you provide, the agent still validates the anomaly, runs its breakdowns, ranks contributing dimensions, and writes up its interpretation the same way.
</Info>

## Feedback

If RCA missed the mark, the fastest fix is to [re-run it with added context](#re-run-with-added-context) and tell the agent what to do differently.

Every generated Board also has a thumbs-up / thumbs-down feedback widget. We use this signal to evaluate RCA quality and improve future runs, so please rate it either way. It's the most direct way to influence what we work on next.

## Limits

* Daily RCA runs per project are capped by plan: Enterprise 300/day, Growth 70/day, Free 10/day. Re-runs count toward this cap.
* RCA today reasons over events and properties. Adjacent context like annotations, session replays, experiments, and metric trees aren't included in the V0 agent's reasoning.


# Session Replay
Source: https://docs.mixpanel.com/docs/session-replay

Watch playbacks of user digital experiences

Mixpanel Session Replay provides the fastest way to gain a comprehensive understanding of your customers and make informed product decisions by combining both quantitative and qualitative insights.

While analyzing customer journeys using Mixpanel's analytics, you can identify **where** customers drop off. Now, with Mixpanel Session Replay, you can quickly follow up by exploring **why** customers drop off.

## Plan Availability

Session Replay is available for customers on Free, Growth, and Enterprise plans. Customers must be on the latest Mixpanel plans to access free replays. Free replays reset monthly, and do not rollover to subsequent months.

| Plan       | Replay Allowance           | How to Access                                                                                                                                                                                                                                                                                             |
| ---------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Free       | 10k free Replays per month | Switch to the latest Free plan (includes 1M monthly events + 10k replays) via the [pricing page](https://mixpanel.com/pricing/).                                                                                                                                                                          |
| Growth     | 20k free Replays per month | You're on the latest plan if you purchased or edited your plan after April 2024. If you are not sure if your organization is using the latest plan, you confirm on our [pricing page](https://mixpanel.com/pricing/) - if you see "Make the Switch" on the Growth plan, then you are on an older version. |
| Enterprise | 20k free Replays per month | Contact your Account Manager to determine your plan status.                                                                                                                                                                                                                                               |

## Implementation

Session Replay is supported on four primary platforms: Web, iOS, Android, and React Native. You can use Session Replay with CDPs (e.g., Segment and mParticle) on both Web and Mobile. We also support Electron desktop apps.

See our developer guides on implementing Session Replay for these platforms below:

<CardGroup>
  <Card title="Web" href="/docs/tracking-methods/sdks/javascript/javascript-replay" />

  <Card title="iOS" href="/docs/tracking-methods/sdks/swift/swift-replay" />

  <Card title="Android" href="/docs/tracking-methods/sdks/android/android-replay" />

  <Card title="React Native" href="/docs/tracking-methods/sdks/react-native/react-native-replay" />
</CardGroup>

## UI Controls

<Note>
  UI Controls is currently available for Web, iOS, and Android. Support for React Native and Flutter is coming soon.
</Note>

With UI Controls, teams can manage Session Replay sampling directly from the Mixpanel UI — no code changes or redeployment required. This is available exclusively to customers with the paid Session Replay Add-On. **Changes take effect within an hour.**

<Frame>
  <img alt="remoteSettingsTab" />
</Frame>

### Prerequisites

To use UI Controls, your project must meet the following requirements:

* **Paid Session Replay Add-On**: UI Controls is available exclusively to customers who have purchased additional Session Replays beyond [the free Replay allowance](/docs/session-replay#plan-availability).
* **Remote configuration enabled in your SDK**: Your SDK must have remote configuration enabled so it can receive sampling updates from the UI. See the platform-specific guides for setup instructions:

  * [JavaScript](/docs/tracking-methods/sdks/javascript/javascript-replay#remote-configuration)
  * [Android](/docs/tracking-methods/sdks/android/android-replay#remote-configuration)
  * [iOS](/docs/tracking-methods/sdks/swift/swift-replay#remote-configuration)

### Baseline Sampling Rate

Set a global sampling rate that applies to all SDK initializations. This is the default capture rate before any conditional rules are applied. For example, you might set a baseline of 1% to capture a small portion of all traffic.

<Frame>
  <img alt="remoteSettingsGlobal" />
</Frame>

### Conditional Rules

Layer rules on top of the baseline rate using any event, property, or URL you're already tracking. Conditional rules are **additive only**: if a session isn't being captured, a matching rule can start capturing it; if a session is already being captured, rules have no additional effect.

For example, you can sample 1% of all sessions globally, but capture 100% of SDK initializations where `checkout_error` fires or where users land on your pricing page.

<Note>
  URL-based rules are evaluated using page view events (`$mp_web_page_view`) emitted while heatmap capture is active. These page views are **exempt from event and MTU billing**, so adding URL conditions does not increase your billable event volume. See [Heatmaps for Web](/docs/session-replay/heatmaps) for related click-exemption rules.
</Note>

<Frame>
  <img alt="remoteSettingsConditional" />
</Frame>

## Entry Points

<Note>
  By default, replays are stored for 30 days after the time of ingestion. Once a replay is expired, there is no way to view that replay. Enterprise plan customers with the paid session replay add-on can customize this retention period between 7 days and 360 days. For more information, reach out to your Account Manager or our sales team.
</Note>

Session Replay is particularly valuable for understanding user frustration and identifying problematic user experiences. To find relevant replays, you can focus on interesting users (power users, purchases), interesting trends (KPIs spikes or dips), or replays where certain events or sentiment signals (like [dead clicks](/docs/tracking-methods/autocapture#dead-clicks)/[rage clicks](/docs/tracking-methods/autocapture#rage-clicks)) occur.

There are several ways to find and watch replays in Mixpanel:

1. From the Session Replay home
2. From Mixpanel reports
3. From User profile pages

### From the Session Replay Home

Select **Session Replay** from the side navigation in your Mixpanel project. Here, you'll see your most recent replays and can easily filter them by events, properties, or custom time ranges to focus on the replays that matter most to you. Pro tip: when getting started with implementing Session Replay, you can use this view to check if replays are coming in as expected.

### From Mixpanel Reports

<Note>
  Reports entry point is currently supported for Event, Funnel, and User Profile metrics only.
</Note>

Click any point on a chart for Event, Funnel, and User Profile, and select "View Replays" to view replays that show that event being fired. From here, you will be taken to our Replay Player.

<Frame>
  <img alt="replayReportEntry" />
</Frame>

### From User Profile Page

In any user's profile page, Click the "View Replays" button to watch replays from that user. From here, you will be taken to our Replay Player.

<Frame>
  <img alt="replayProfileEntry" />
</Frame>

## Watching Replays

<Frame>
  <img alt="replayPlayer" />
</Frame>

The Replay Player has three main areas: the Replay Feed, the Player Area, and the Details Panel.

### Replay Feed

The Replay Feed on the left side of the player lets you browse and find replays. It works out of the box with the Mixpanel events and properties you already track (including server-side events) — no extra setup required. Each cell represents a single user journey: a group of replays for a specific user that happened within \~30 minutes of each other. A single journey can contain several replays.

The replay feed allows you to:

* Filter by any event, property, or time period
* Search by user name/email, replay date, user ID, or event name
* Sort by recency, activity, or duration
* Hover over replay cells to reveal more details

### Player Area

The Player Area is the central area where you watch replays. It includes the following controls:

* Expand the player to full-screen
* Copy a URL (with or without a timestamp) to share with your teammates
* Change the playback speed
* Automatically skip periods of the replay where user is inactive
* See events in the replay timeline
* Jump to different parts of the replay by clicking in the timeline
* Bookmark a replay to save it for later
* Enable server-side stitching (revealing replays and events for the same user that were not captured with the same SDK that captured the replay. This is particularly useful for discovering replays, as well as moments of those replays where important events you track server-side or via data warehouse occur, like purchase events or sign-up events.)

### Details Panel

The Details Panel on the right side of the player provides deeper context about the selected replay. It contains three tabs: Details, Activity Feed, and AI Summary.

#### Details

The Details tab shows metadata and properties for the selected replay, including user information, session properties, and device details.

#### Activity Feed

The Activity Feed tab shows a chronological feed of all events that occurred during the session, including Mixpanel track events, console logs, and network calls. You can search and filter events by type, and click any event to see its details and jump the replay to that moment.

##### Console Logs

Console logs, warnings, and errors are captured during a session and displayed in the Activity Feed timeline. Use the filters to toggle visibility of Errors, Warnings, and Logs. Click any console event to view the full message and stack trace (when available).

Console recording is enabled by default. To configure, see the [JavaScript SDK guide](/docs/tracking-methods/sdks/javascript/javascript-replay).

##### Network Calls

Network calls made during a session are captured and displayed in the Activity Feed. Use the filters to toggle visibility of Fetch, XHR, and Other request types. Click any network event to inspect headers, request payload, and response details, along with status codes and duration.

<Note>
  Network recording is disabled by default and requires SDK configuration. Request and response headers and bodies also require additional setup. See the [Network Recording guide](/docs/tracking-methods/sdks/javascript/javascript-replay#network-recording) for instructions.
</Note>

#### AI Summary

The AI Summary tab provides an AI-generated summary of the session, highlighting key moments and summarizing user behavior so you can quickly understand what happened without watching the entire replay. Summaries are powered by your governed event data for accuracy.

## Magic Playlists

Magic Playlists allow you to save playlists of replays based on events or properties, making it easy to revisit groups of replays that matter to you over time. A playlist stores your filter criteria (events, recording properties, date range, sort order) and can also hold up to 200 individually bookmarked replays. Key capabilities include:

* **Dynamic playlists**: Create playlists based on your Mixpanel events and properties that automatically update as new replays meet your criteria
* **Bookmarked replays**: Pin specific replays to a playlist so you can easily return to them later
* **AI-powered insights**: Get AI text summaries that identify key patterns and insights across numerous replays at once

<Note>
  AI summaries for Magic Playlists are currently in beta and publicly available for all customers using Magic Playlists.
</Note>

### Creating a Playlist

1. Access Session Replay from the side navigation in your Mixpanel project
2. Apply filters based on events, properties, or custom time ranges
3. Click **Save Playlist** in the header and add a name
4. Click **Save**

<Frame>
  <img alt="Save Playlist button" />
</Frame>

Once saved, your Magic Playlist will appear as a playlist card on your selected board. Any time new replays meet your saved criteria, they will automatically appear in your playlist. Modifying filters after saving shows unsaved changes — you can **Save** to update or **Save as New** to create a variant.

### Bookmarking Replays

Bookmarking pins a specific replay to the current playlist. You can bookmark replays in two ways:

* **From the player**: Use the bookmark icon in the player's top control bar to toggle bookmark status
* **From the playlist row**: Click the bookmark badge on any replay row

A playlist must be saved before you can bookmark replays — the bookmark button is disabled until a playlist is active.

### Viewing Bookmarked Replays

Use the bookmark filter toggle in the playlist header to show only bookmarked replays. When this filter is active, other filters are disabled. Bookmarked replays appear in a dedicated section at the top of the playlist.

Expired bookmarked replays appear in a separate **Expired Journeys** section. You can remove expired bookmarks, but expired replay content can no longer be played. Bookmark lookback searches up to 365 days.

## Best Practices

Session Replay is a powerful way to understand and debug user behavior by showing exactly what users see on their screens. This visibility is core to its value—but also introduces inherent privacy and security risks, especially when sensitive information appears in the UI.

Mobile platforms add some unique challenges:

* SDKs are installed directly on end-user devices, making them harder to roll back or patch quickly.
* Android’s fragmented ecosystem demands broader testing across different devices and OS versions.

These risks are common across all session replay tools, but well-established industry practices exist to help mitigate them. With careful planning and the right safeguards, teams can more confidently use session replay to improve their products.

### Key Considerations

| **Key Considerations**         | **Why It Matters**                                                                       |
| ------------------------------ | ---------------------------------------------------------------------------------------- |
| **Industries**                 | Apps in healthcare, fintech, or other regulated spaces carry higher compliance risk.     |
| **Sensitive Screens**          | Checkout, payment, and profile screens often contain sensitive user data.                |
| **Embedded Webviews**          | Embedded web views may require additional review to ensure expected behavior.            |
| **Uncommon App Architectures** | Custom or non-standard implementations may require additional testing and configuration. |

***

To ensure successful implementation, we recommend:

* Defensive programming, including safe initialization, graceful error handling (try/catch), and sensible fallback behavior
* Thorough QA, including testing across device types and sensitive screens
* Staged roll out, using feature flags to safely test and enable or disable Session Replay as needed

Session Replay is a powerful feature that should be implemented with care. Following best practices can help you gain valuable insights into user behavior. We recommend thorough testing in your development environment before deploying to production.

### Performance Considerations

Our Session Replay SDKs are designed with performance in mind, utilizing optimized capture algorithms that reduce CPU and memory usage. However, as with any SDK integration, there may still be some risk of performance impacts. We recommend thorough testing and monitoring your app's performance during initial deployment.

### Incident Handling

If you encounter an unexpected or urgent issue, please reach out to our support team promptly so we can help resolve it as quickly as possible. Examples of situations that require immediate attention include:

* Performance / stability issues with the SR SDK
* Accidental ingestion of sensitive user data

For these cases, [submit a request to our Support team](https://mixpanel.com/get-support) and include the following information:

If you're experiencing performance / stability issues with the SR SDK:

* Whether your issue is with Web, iOS, Android, or multiple platforms
* Your Session Replay (SR) code snippet
* Where you initialize the Session Replay SDK
* Any relevant logs or performance metrics

If you accidentally ingested sensitive user data:

* Whether your issue is with Web, iOS, Android, or multiple platforms
* Affected user IDs (if known)
* Time range of the incident (if known)

Our team will prioritize and address these issues as quickly as possible.

## FAQ

#### What happens when I reach my Session Replay limit?

Customers who have purchased the Session Replay add-on will be billed for replays ingested beyond the purchased amount at your per-unit rate. Customers using Session Replay without purchasing the add-on (e.g., those using complimentary replays included with the Free, Growth, or Enterprise plans) will be unable to view replays once they reach the data allowance, unless they upgrade. We will send email notifications to [organization Owners and Billing Admins](/docs/orgs-and-projects/roles-and-permissions#organization-roles) as your projects approaches the data allowance of your subscription plan.

Mixpanel reserves the right to stop ingesting replays once a customer collects replays beyond their purchased/allocated amount. To minimize disruption to your team, we recommend monitoring your data usage in the organization settings and working with your Account Manager (if applicable) to ensure you have the right plan for your needs.

#### How soon are Replays available for viewing after a session begins?

Replays are available for viewing in Mixpanel \~1 minute after the recording is captured.

#### What defines a single replay?

A replay is a continuous recording of a single user's activity.

On the web, a replay ends after 30 minutes of inactivity (a new replay begins automatically when the user is active again) or once it reaches a maximum length of 24 hours, whichever comes first. Both thresholds are configurable via the `record_idle_timeout_ms` (default 30 minutes) and `record_max_ms` (default 24 hours) [JavaScript init options](/docs/tracking-methods/sdks/javascript/javascript-replay#init-options). On the web, a replay is scoped to a single browser tab or window. Recording continues across page loads and navigations within that same tab (SDK v2.61.0+), but each additional tab or window is recorded as its own replay, as is activity in a different browser or on a different device. A single user's activity across multiple tabs, browsers, or devices is therefore captured as multiple replays, not one.

On our mobile SDKs (iOS, Android, and React Native), you control capture with a sampling rate and by starting or stopping recording manually, just as you can on the web. A replay ends when the user leaves the app.

#### How long are replays stored?

By default, replays are stored for 30 days after the time of ingestion. Once a replay is expired, there is no way to view that replay. Enterprise plan customers with the paid session replay add-on can customize this retention period between 7 days and 360 days. For more information, reach out to your Account Manager or our sales team.

<Note>
  Purchasing a custom retention period does not change your retention period automatically. Once the entitlement is provisioned, an org Owner or Admin needs to set the desired retention period from the Session Replay settings in the UI.
</Note>

#### Why does it say the player failed to load?

To maintain a high level of security, Mixpanel runs your session replays in an isolated domain through an iframe. Occasionally, this domain may be blocked by an ad blocker or specific browser settings. We recommend disabling any ad blockers, or whitelisting the Mixpanel domain.

For extensions like uBlock, go to "My Filters" in the extension settings and add the following custom filter:

```text theme={"system"}
@@||mxpnl.com^$domain=mxpnl.com
```

#### Why can't I see the "View Replays" button in the UI?

You will not see the "View Replays" button if your organization is on an older plan. You will need to update to the latest plan to use Session Replay (see [here](/docs/session-replay#plan-availability) for details).

#### Can I use Session Replay with a CDP?

You can use Session Replay with CDPs (e.g., Segment and mParticle) on both web and mobile.

| Platform | Guidance                                                                                                                                                                                                      |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Web      | Your app must include the Mixpanel Javascript SDK, with Session Replay enabled. Learn more in the developer guide [here](/docs/tracking-methods/sdks/javascript/javascript-replay#session-replay-with-a-cdp). |
| iOS      | Works with CDPs, but you must install the Mixpanel Session Replay SDK in your app. Read more in our [iOS implementation guide](/docs/tracking-methods/sdks/swift/swift-replay).                               |
| Android  | Works with CDPs, but you must install the Mixpanel Session Replay SDK in your app. Read more in our [Android implementation guide](/docs/tracking-methods/sdks/android/android-replay).                       |

#### How does Session Replay work differently on web versus mobile?

Session Replay works differently on web versus mobile in Mixpanel:

* **Web**: Captures DOM changes to reconstruct user interactions, tracking elements, clicks, and navigation. This provides an event-based replay of user activity.
* **Mobile**: Captures actual screen pixels since native apps don't use a DOM. This visual approach records all on-screen activity as it appears to users, including scrolls, carousels, and auto-scrolling elements.

#### How can I estimate how many Replays I will generate?

If you already use Mixpanel, the [Session Start events](/docs/features/sessions) are a way to estimate the rough amount of replays you might expect. This is especially true if you use timeout-based query sessions. However, because our sessions are defined at query time, we cannot guarantee these metrics will be directly correlated.

When you enable Session Replay, use the above proxy metric to determine a starting sampling percentage, which will determine how many replays will be sent. You can always adjust this as you go to calibrate to the right level.

#### Am I able to sample our Session Replay collection rate?

Yes, you can configure the percentage of total replays that our SDK will capture as a sampling rate or manually trigger/end replay capture.

#### Can I record cross-origin iframes within my page?

Yes, Session Replay supports recording cross-origin iframes embedded within your page (Web only, SDK v2.77.0+). Both the parent page and child iframe must have the Mixpanel SDK initialized with `record_allowed_iframe_origins` configured to include each other's origins. For detailed setup instructions, see [Cross-Origin Iframe Recording](/docs/tracking-methods/sdks/javascript/javascript-replay#cross-origin-iframe-recording).


# Heatmaps for Web
Source: https://docs.mixpanel.com/docs/session-replay/heatmaps



## Overview

Heatmaps help you visualize user interactions on your web application, showing where users click the most. This feature enables teams to quickly identify areas of high engagement and friction, helping to optimize user experiences and improve conversion rates.

We offer two types of heatmaps:

1. **Click Maps**: These track clicks on individual site elements, providing precise insights into which modals, dropdowns, or features that users engage with the most. This element-level tracking helps you understand specific component usage.
2. **Traditional Heatmaps**: These overlay general activity on a page based on X,Y coordinates, giving you a broader view of user interaction patterns across the entire page layout.

<Note>
  Note: Traditional heatmaps may show some inaccuracies on modern websites due to dynamic elements like modals, dropdowns, fixed elements, and cookie banners that change the page layout. Click maps can be used to confirm and clarify these interactions by showing exactly which elements users are engaging with.
</Note>

Future versions of heatmaps may also include hovers and other interaction types.

Enabling Heatmaps does not affect billing. They are included with the Session Replay add-on and do not generate additional billable events.

### How It Works

Heatmaps are powered by Session Replay data and automatically capture click interactions when enabled. Users can generate a Heatmap for specific pages to gain deeper insights into user engagement.

To function, Heatmaps require Session Replay to be enabled, as they rely on session replay data to track and visualize user clicks.

Heatmaps only capture data during sessions with recorded replays. If a page has limited replay coverage, the Heatmap may not offer meaningful insights.

<Warning>
  When clicks occur very close to page navigation events, the heatmap may occasionally show clicks on the wrong page. This happens because the timing between page changes and click events may not align perfectly. If you notice clicks appearing on the wrong page, try using a different [UI State](#ui-states) to find the correct page state.
</Warning>

### Implementation

Ensure you have Session Replay set up using our Javascript SDK (see [developer guide on implementing Session Replay](/docs/tracking-methods/sdks/javascript/javascript-replay)), with the `record_heatmap_data` set to `true`.

Clicks recorded using `record_heatmap_data` will only capture clicks while an a session recording is in progress. Events generated by `record_heatmap_data` are free only when a session recording is taking place.\*\* These clicks are sent as `$mp_click` and will not be counted against your plan data allowance. Page view events (`$mp_web_page_view`) emitted while a session recording is in progress are also exempt from your plan data allowance and MTU billing.

Currently, heatmaps are not available on our Mobile Session Replay SDKs.

**Example Usage**

```javascript Javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
  record_sessions_percent: 1, // Session Replay enabled, recording 1% of all sessions
  record_heatmap_data: true   // Enable Heatmap data collection
});
```

If you currently use [Autocapture](/docs/tracking-methods/autocapture) to track clicks, you can leverage these clicks to populate the Heatmaps without the `record_heatmap_data` init option.

Clicks captured by Autocapture are billable events that are counted against your plan data allowance.

**Example Usage**

```javascript Javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
  autocapture: {
    pageview: "full-url",
    click: true, // click tracking enabled
    input: true,
    scroll: true,
    submit: true,
    capture_text_content: false,
  },
  record_sessions_percent: 1 // Session Replay enabled, recording 1% of all sessions
});
```

<Note>
  Clicks generated by `record_heatmap_data` are exempt from your plan data allowance only when a session recording is taking place. Page view events (`$mp_web_page_view`) emitted during a recording are likewise exempt from event and MTU billing. Clicks generated by [Autocapture](/docs/tracking-methods/autocapture) are billable events.
</Note>

### Using Heatmaps

1. From the Home page, find the Heatmaps section.

<Frame>
  <img alt="heatmap_home.png" />
</Frame>

2. Choose a URL where you want to analyze user interactions and generate a Heatmap.

<Note>
  You can use wildcard selectors (\*) in your URL to group multiple pages into a single heatmap. For example, if your URLs contain unique IDs like `/products/123` and `/products/456`, you can use `/products/*` to analyze all product pages together.
</Note>

3. To easily navigate back to a created Heatmap, you can click the title to rename the Heatmap.

<Frame>
  <img alt="heatmap_rename.png" />
</Frame>

4. Rotate through UI States to view different states of your application for the same URL.

<Frame>
  <img alt="UI States view" />
</Frame>

5. Use the Click Map and Heatmap toggles to show or hide each view. Click Maps help you see exactly which elements users click, which can clarify any inaccuracies in traditional heatmaps caused by dynamic page elements.
6. Click on any element in the Click Map to open a selection menu with three options:

* **View Events**: View all click events recorded for this element
* **View Users**: See a list of users who clicked this specific element
* **Review Replays**: Watch session replays of users interacting with this element

<Frame>
  <img alt="heatmap_selection_menu.png" />
</Frame>

### Goal Mode

Goal Mode helps you see which UI elements actually drive conversions for any event goal, not just raw clicks. While traditional heatmaps show where users click, Goal Mode reveals whether those clicks lead to meaningful outcomes like signups, purchases, or feature adoption.

To enable Goal Mode, click the **Goal** button in any heatmap. You'll be prompted to configure:

* **Conversion Goal**: A user action deemed valuable to your business, such as a "Purchase" or "Sign Up" event. Select any Mixpanel event as your goal.
* **Conversion Weight Property (Optional)**: An optional numeric property that is used to weight conversions, such as a "Purchase Amount" or "Order Value" property. This allows you to prioritize higher-value conversions.

Once enabled, Goal Mode highlights the UI elements driving the most conversions, giving you a true aggregate visual of how your UI affects your core metrics. For example, you might discover whether a case study on your landing page is generating signups, or just a lot of clicks that don't convert.

<Note>
  Goal Mode works with any of your existing events and properties directly out of the box—no additional setup required.
</Note>

### UI States

UI States are snapshots of your application in various states (such as a modal open, a menu expanded, or different page layouts). UI States are pulled from session replays that match the URL you're analyzing, helping you understand how different views or UI states affect user interactions.

UI States are subject to the same retention policies as your session replays. Once a session replay expires, it can no longer be used as a UI State. If you don't see enough UI States (or can't find the specific view or state you're looking for), consider increasing your session replay sampling rate to capture a wider set of application states.

<Warning>
  Heatmaps only track scrolling on the main page (window). If your site scrolls inside a nested container (like a div with its own scrollbar), heatmaps and interactive mode may not display data correctly. The interactive UI States feature lets you customize your UI State, but click positions within nested scrollable elements will still not be fully reflected.
</Warning>

## Scrollmaps

Scrollmaps visualize how far down a page users scroll, helping you understand how much of your content is actually seen and where users drop off. Like Click Maps and Traditional Heatmaps, Scrollmaps are part of the Heatmaps and Session Replay feature set.

<Note>
  Scrollmaps are currently available for web only. They are not yet available on our Mobile Session Replay SDKs.
</Note>

### Requirements

To collect Scrollmap data, your implementation must meet the following requirements:

* Mixpanel JavaScript SDK **v2.71 or higher**
* Session Replay enabled
* `record_heatmap_data` set to `true` in your Session Replay configuration

Setting `record_heatmap_data: true` is what captures the Page Leave data that the scroll fold line is derived from, so it is required for Scrollmaps.

**Example Usage**

```javascript Javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
  record_sessions_percent: 1, // Session Replay enabled, recording 1% of all sessions
  record_heatmap_data: true   // Enable Heatmap and Scrollmap data collection
});
```

### Average Fold Line

Scrollmaps include an **Average Fold Line**, which marks the average point on the page where content falls below the fold (below the initially visible portion of the viewport). This value is derived from the `[Auto] Page Leave - Fold Line Percentage` property.


# Session Replay Privacy Controls
Source: https://docs.mixpanel.com/docs/session-replay/session-replay-privacy-controls



**Last updated January 21st, 2026**

## Introduction to Session Replay

Mixpanel offers a privacy-first approach to Session Replay, including features such as data masking. Mixpanel's Session Replay privacy controls were designed to assist customers in protecting end user privacy.

Data privacy regulations are rapidly evolving and vary considerably across states and countries. A consistent requirement across many data privacy regulations for website operators is disclosing to end users that their personal information is being collected, often in a privacy notice. Before implementing Session Replay on your website, a best practice is to review your privacy notice with legal counsel to ensure it remains accurate and compliant with data privacy laws.

## How does Session Replay work?

Session Replay for Web captures the Document Object Model (DOM) structure and changes to it. Mixpanel then reconstructs the web page, applying recorded events at the time an end user completed them. Within Mixpanel’s platform, you can view a reconstruction of your end user’s screen as they navigate your website. However, Session Replay for Web is not a video recording of your end user’s screen and end user actions are not literally video-recorded.

## How does masking and blocking work? What are the high-level technical details?

Masking and blocking are slightly different.

Masked data is suppressed client-side, meaning it is not collected in its original form by Mixpanel’s SDK, and the data is not stored on Mixpanel servers. Masked elements have their text replaced with asterisks of the same length \[\*\*\*\*].

Blocked data is similarly suppressed client-side, meaning it is not collected in its original form by Mixpanel’s SDK, and the data is not stored on Mixpanel servers. However, blocked elements will be rendered with a placeholder element (e.g., an empty box of similar size).

Note: interactions (such as mouse-clicks) with blocked and masked elements are still captured by Session Replay for Web.

<div>
  <Frame>
    <img alt="Masking vs Blocking" />
  </Frame>
</div>

## Configuring Privacy Controls

By default, Mixpanel masks and/or blocks the most common elements that contain content like input text, non-input text, images, and videos. However, Mixpanel also offers its customers a range of privacy controls to choose to unmask / unblock elements as needed, which are detailed further on this page.

| Element Type      | Default State                                                                                                                                                                                                                         | Customizable                                                                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Inputs            | Mixpanel masks all user input text by default. When a user enters text into an input field, Mixpanel captures \[\*\*\*\*] in place of text.                                                                                           | Yes. You can selectively unmask specific inputs using `record_unmask_input_selector`. However, certain [sensitive input types](#always-masked-inputs) cannot be unmasked for security reasons.     |
| Text              | By default, Mixpanel masks all non-input text on your webpage. This masked content on your webpage is replaced with \[\*\*\*\*].                                                                                                      | Yes. You can selectively unmask text elements using `record_unmask_text_selector`, or set `record_mask_all_text: false` to unmask all text by default and then selectively mask specific elements. |
| Videos and Images | By default, Mixpanel blocks videos and images. These elements will be rendered with a placeholder element (i.e., an empty box of similar size). Note: interactions with blocked elements will still be captured (e.g., mouse-clicks). | Yes. Mixpanel empowers its customers to decide to record images and videos as-is.                                                                                                                  |

Other elements not listed in this table are captured by default, and can be blocked at your discretion. You can specify a CSS selector under the config option `record_block_selector` to block all elements which match the selector.

### Text Masking vs Input Masking

Text masking and input masking are two separate pipelines that are configured independently. Text masking handles visible text inside any HTML element (`<p>`, `<h1>`, `<span>`, `<label>`, `<button>`, etc.), while input masking handles values typed into `<input>`, `<textarea>`, and `<select>` elements.

This means you can configure them independently. For example, you could unmask form labels while keeping input values masked — the label "Full Name" would be visible but the typed value "John Smith" would show as `****`.

<div>
  <Frame>
    <img alt="Text vs Input Masking" />
  </Frame>
</div>

## Text Masking Configuration

Mixpanel provides flexible options for controlling which text elements are masked in your replays.

### Configuration Options

| Option                        | Type                 | Default             | Description                                                                                                            |
| ----------------------------- | -------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `record_mask_all_text`        | `boolean`            | `true`              | When `true`, all text is masked by default. Use `record_unmask_text_selector` to selectively reveal specific elements. |
| `record_mask_text_selector`   | `string \| string[]` | `undefined`         | CSS selector(s) for elements to mask. Only applies when `record_mask_all_text` is `false`.                             |
| `record_unmask_text_selector` | `string \| string[]` | `undefined`         | CSS selector(s) for elements to unmask. Only applies when `record_mask_all_text` is `true`.                            |
| `record_mask_text_class`      | `string \| RegExp`   | Common mask classes | CSS class name or regex for elements to mask. Included for backward compatibility.                                     |

<Note>
  Selector options accept either a single CSS selector string or an array of selectors. Arrays are joined with commas internally, so `['.header', '.footer']` is equivalent to `'.header, .footer'`.
</Note>

### Mask All Text (Default Behavior)

By default, `record_mask_all_text` is `true`, meaning all text on the page is masked. To selectively unmask specific elements, use `record_unmask_text_selector`:

```javascript theme={"system"}
// All text masked by default, except navigation and footer
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 100,
    record_unmask_text_selector: ['.navigation', '.footer', '#public-content']
});
```

### Unmask All Text

To show all text by default and selectively mask sensitive areas, set `record_mask_all_text` to `false` and use `record_mask_text_selector`:

```javascript theme={"system"}
// All text visible by default, mask only sensitive areas
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 100,
    record_mask_all_text: false,
    record_mask_text_selector: ['.user-data', '.account-info', '#billing-section']
});
```

### Using CSS Classes

You can also mask elements using the `.mp-mask` CSS class directly in your HTML:

```html theme={"system"}
<div class="mp-mask">This text will be masked</div>
<p>This text follows regular masking rules</p>
```

## Input Masking Configuration

Input masking follows a similar pattern to text masking, with additional security protections for sensitive input types.

### Configuration Options

| Option                         | Type                 | Default     | Description                                                                                                              |
| ------------------------------ | -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| `record_mask_all_inputs`       | `boolean`            | `true`      | When `true`, all inputs are masked by default. Use `record_unmask_input_selector` to selectively reveal specific inputs. |
| `record_mask_input_selector`   | `string \| string[]` | `undefined` | CSS selector(s) for inputs to mask. Only applies when `record_mask_all_inputs` is `false`.                               |
| `record_unmask_input_selector` | `string \| string[]` | `undefined` | CSS selector(s) for inputs to unmask. Only applies when `record_mask_all_inputs` is `true`.                              |

### Selectively Unmask Inputs

To unmask specific input fields while keeping others masked:

```javascript theme={"system"}
// All inputs masked by default, except search and quantity fields
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 100,
    record_unmask_input_selector: ['#search-box', '.quantity-input', '[data-public="true"]']
});
```

### Always Masked Inputs

<Warning>
  Certain input types are **always masked** regardless of your configuration settings. This is a security measure that cannot be overridden.
</Warning>

The following inputs will always be masked:

| Input Type                                     | Reason                                                                                                                                                                                |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type="password"`                              | Contains authentication credentials                                                                                                                                                   |
| `type="email"`                                 | Contains personally identifiable information                                                                                                                                          |
| `type="tel"`                                   | Contains phone numbers                                                                                                                                                                |
| `type="hidden"`                                | May contain sensitive tokens or data                                                                                                                                                  |
| Inputs with non-empty `autocomplete` attribute | The [autocomplete attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete) is primarily used for PII fields (name, address, credit card, etc.) |
| Inputs with `data-rr-is-password` attribute    | Used internally when password inputs are transformed (e.g., "Show Password" functionality)                                                                                            |

Additionally, Mixpanel applies heuristic detection to identify inputs that may contain sensitive data based on their `name` or `id` attributes. Inputs matching patterns associated with credit cards, passwords, social security numbers, and similar sensitive data will be masked.

## Blocking Elements

To block elements entirely (replacing them with placeholder boxes), use the blocking configuration:

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 100,
    record_block_selector: '.sensitive-data'
});
```

```html theme={"system"}
<img src="https://example.com/photo.jpg" class="mp-block"/>
```

## Configuring Privacy Options via GTM

If you're using the Mixpanel GTM template, privacy options like `record_mask_all_text` and `record_block_selector` should be set using a **Custom JavaScript variable** rather than the template's "Set options manually" interface.

The manual interface can pass empty strings or whitespace for selector fields, which are not valid CSS selectors and will cause a runtime error (`Failed to execute 'matches' on 'Element'`). Using a Custom JavaScript variable gives you full control over the config object passed to the SDK.

### Setup

In GTM, create a new **Variable → Custom JavaScript** and return your privacy configuration alongside your other init options:

```javascript theme={"system"}
function() {
  return {
    record_sessions_percent: 100,
    record_mask_all_text: false,       // show all text by default
    record_block_selector: undefined   // uses default: 'img, video, audio'
  };
}
```

Then set **Initialization Options** in your Mixpanel init tag to use this variable.

### Common GTM privacy configurations

**Show all text, block nothing extra (testing/low-sensitivity sites)**

```javascript theme={"system"}
function() {
  return {
    record_sessions_percent: 100,
    record_mask_all_text: false,
    record_block_selector: undefined
  };
}
```

**Mask everything except specific elements (default-private approach)**

```javascript theme={"system"}
function() {
  return {
    record_sessions_percent: 100,
    record_mask_all_text: true,
    record_unmask_text_selector: '.public-content, nav, footer',
    record_block_selector: 'img, video, audio, .sensitive-widget'
  };
}
```

**Show all text, selectively mask sensitive areas**

```javascript theme={"system"}
function() {
  return {
    record_sessions_percent: 100,
    record_mask_all_text: false,
    record_mask_text_selector: '.user-data, .account-info, #billing-section',
    record_block_selector: 'img, video, audio'
  };
}
```

> **Important:** Do not pass `""` or `[]` for selector options — both resolve to an empty string, which is an invalid CSS selector. Pass `undefined` to use the SDK default, or omit the key entirely.

For the full list of available privacy options, see the sections above.

## How Nesting and Inheritance Works

Both masking and unmasking selectors propagate through the DOM tree. When checking if an element should be masked, the SDK checks the **element itself and all of its ancestors**.

**Masking propagates to children:** If a parent element matches a masking selector, all descendants are also masked — even deeply nested ones.

**Unmasking overrides ancestor masking:** When `record_mask_all_text` is `true`, adding `record_unmask_text_selector` on a container will unmask that container and all its children, even though the rest of the page remains masked.

<Warning>
  **Blocking does NOT support unblocking children.** When an element is blocked, the entire subtree is removed during DOM serialization. The recording engine never traverses inside a blocked element, so children cannot opt out. There is no unblock selector or class.
</Warning>

<div>
  <Frame>
    <img alt="Nesting and Inheritance" />
  </Frame>
</div>

## Quick Reference: Which Config Do I Use?

<div>
  <Frame>
    <img alt="Configuration Recipes" />
  </Frame>
</div>

## Disabling Replay Collection

Once enabled, Session Replay runs on your website/app until either:

* The user leaves your website/app
* The user is inactive for more than 30 minutes
* You call manually stop a session recording using an SDK method.

Call `mixpanel.stop_session_recording()` before a user navigates to a restricted area of your site to disable replay collection while the user is in that area. To restart replay collection, call `mixpanel.start_session_recording()` to re-add the plugin.

## Additional Considerations

WebComponents that utilize HTML attributes may be ingested and stored by Session Replay for Web, regardless of whether they are displayed in an individual recording as text. Customers should utilize the block functionality outlined above to the extent specific areas of a webpage should not be ingested.

## User Opt-Out

Session Replay follows [standard SDK opt-out setting](/docs/privacy/end-user-data-management#opt-out-users). If a user is opted out of regular SDK tracking, they will also be opted out of Session Replay recording.

## Data Deletion

Deletion requests for Session Replay for Web use Mixpanel's standard end user management process for events documented [here](/docs/privacy/end-user-data-management).

## Data Retention

Mixpanel retains Session Replays for 30 days from the date the replay is ingested and becomes available for viewing within Mixpanel.


# Tracking Best Practices
Source: https://docs.mixpanel.com/docs/tracking-best-practices



Take a look at any of these pages for more information about best practices on Mixpanel tracking.

## General Solutions

<CardGroup>
  <Card title="Tracking Plan" href="/docs/tracking-best-practices/tracking-plan" />

  <Card title="Server-side Best Practices" href="/docs/tracking-best-practices/server-side-best-practices" />

  <Card title="Debugging" href="/docs/tracking-best-practices/debugging" />
</CardGroup>

## Specific Solutions

<CardGroup>
  <Card title="Bot Traffic" href="/docs/tracking-best-practices/bot-traffic" />

  <Card title="Developer Environments" href="/docs/tracking-best-practices/developer-environments" />

  <Card title="Geolocation" href="/docs/tracking-best-practices/geolocation" />

  <Card title="Hot Shard Limits" href="/docs/tracking-best-practices/hot-shard-limits" />

  <Card title="Traffic Attribution" href="/docs/tracking-best-practices/traffic-attribution" />
</CardGroup>


# Block Unwanted Traffic
Source: https://docs.mixpanel.com/docs/tracking-best-practices/bot-traffic



In this guide, we describe how to avoid bot traffic from affecting your tracking.

At its core, blocking unwanted traffic relies on the reserved event property `$ignore` to drop unwanted traffic. Anytime our ingestion API detects the `$ignore` property on an event, it drops that event from ingestion.

## Exclude Bot Traffic From Javascript SDK

By default, the following bots are filtered out by the Mixpanel JavaScript library:

* Yahoo! Slurp
* bingbot/2.0
* Googlebot/2.1
* Baiduspider/2.0
* YandexBot/3.0

You can find the exact list on our [GitHub](https://github.com/mixpanel/mixpanel-js/blob/8ac526e5cb8563d11e2206046ab986c6491ac6d7/src/utils.js#L900C1-L925C3)

Any other bot hitting your site will affect your Mixpanel data. That being said, it’s possible to set up some code to filter out these users:

1. Find the user agent information of the individual accessing the site.
2. Look for the word “bot” anywhere in the user agent information.
3. If you find “bot,” set the `$ignore` property to `true`.

If you can, identify a common pattern in the bots to block them all in one shot by filtering out any interaction with your site that comes from a web framework that is not a consumer-facing browser. As an example, for GTM bots, this code would look like this:

```js theme={"system"}
var userAgentBotTest = navigator.userAgent;
mixpanel.register({"User Agent": userAgentBotTest});
if (/(Mozilla\/4.0)/i.test(userAgentBotTest)) {
     mixpanel.register({"$ignore": true});
}
```

If you implement this code, you will block all userAgents with "Mozilla/4.0" in the userAgent. This does include some older browsers, but modern browsers such as Chrome, Safari, and Firefox will never include this in their userAgent strings. See a [common list of bot userAgents](https://www.useragentstring.com/pages/useragentstring.php?typ=Crawler) and [common bot browsers](https://www.useragentstring.com/pages/useragentstring.php?typ=Browser).

If this does not work, you can start tracking this userAgent going forward so you can find the common pattern among all of the bots crawling your site.

Note: `$ignore` must have a string or at least be set to true, or else the event will fire. For example, if I have `'$ignore': ''`, the event will still fire since it's an empty string. `'$ignore': false` will also fire the event.

## Remove Bot Traffic Historically

Events in Mixpanel are immutable, which means they cannot be removed. However, they can be filtered out. If there are some events that have been sent in with bots and you can identify those events based on some property value (eg: the device type or location), we recommend creating a [custom event](/docs/features/custom-events) that applies that filter.  You can also [hide](/docs/data-governance/lexicon#hide-events-and-properties) the original event. That way, when you use the custom event, all bot traffic will automatically be filtered out.

## Block Internal or IP-Based Traffic

The same `$ignore` approach used above for bot traffic can also be applied to filter out internal traffic. (ex: events generated by your own team during testing, QA, or traffic originating from specific IP addresses you own).

### Filtering by IP Address

If you want to exclude traffic from known IP addresses (such as your office network or a VPN), you can resolve the user's IP and conditionally set `$ignore`. Since the browser doesn't expose the client IP directly, you'll need a lightweight server-side endpoint or third-party service to retrieve it:

```javascript Javascript theme={"system"}
fetch("https://api.ipify.org?format=json")
  .then((res) => res.json())
  .then((data) => {
    const blockedIPs = ["203.0.113.50", "198.51.100.27"]; // your internal IPs
    if (blockedIPs.includes(data.ip)) {
      mixpanel.register({ $ignore: true });
    }
  });
```

### Filtering by Internal Email Domain

If your team members are identified in Mixpanel, you can also suppress events based on an internal email domain or user property:

```javascript Javascript theme={"system"}
//After identifying the user and knowing their email
var userEmail = getCurrentUserEmail(); // your own helper
if (/@yourcompany\.com$/.test(userEmail)) {
  mixpanel.register({ $ignore: true });
}
```

### Server-Side Filtering

If you are sending events from a server-side method, you can apply the same logic before the event is sent. Attach `$ignore: true` as an event property whenever the request originates from an internal IP range or an internal service account:

```python Python theme={"system"}
import ipaddress

internal_networks = [
    ipaddress.ip_network("10.0.0.0/8"),
    ipaddress.ip_network("192.168.1.0/24"),
]

def is_internal(ip):
    addr = ipaddress.ip_address(ip)
    return any(addr in network for network in internal_networks)

if is_internal(request_ip):
    mp.track(user_id, "Page View", {"$ignore": True})
```

As with bot filtering, remember that `$ignore` must be set to `true` (or a non-empty string) to suppress the event. An empty string or false will not prevent the event from being recorded. If internal traffic has already been recorded, you can retroactively filter it out using a custom event as described in Remove Bot Traffic Historically.


# Debugging
Source: https://docs.mixpanel.com/docs/tracking-best-practices/debugging

Validate your data and troubleshoot your implementation

This document walks through best practices for data validation and debugging your Mixpanel implementation.

## Before You Debug

### Create a Test Project

Mixpanel recommends that you create a [separate development Mixpanel project](/docs/best-practices/developer-environments#separate-development-data) to validate your event data. This ensures that your testing data does not contaminate your production environment.

### Send Events

Mixpanel doesn't receive any data until you start sending events. If you haven't started sending data to Mixpanel, check out our quickstart guides for [JavaScript](/docs/quickstart/connect-your-data?sdk=javascript), [Server](/docs/quickstart/connect-your-data?sdk=python), and [Mobile](/docs/quickstart/connect-your-data?sdk=ios). We have a simple [HTTP API](/docs/quickstart/connect-your-data?sdk=httpapi) for any languages we don't support.

🎉 Congratulations, you're ready to debug! Theres are two primary places to inspect your raw events as they flow into your Mixpanel project: Events and User Profiles.

### Debugging with Events

Use the [Events](https://mixpanel.com/report/events) view (formerly called "Live View") to confirm that events are arriving to your Mixpanel project, so you can troubleshoot your Mixpanel setup quickly. To access the Events view, expand the "Data" tab from the left-hand navigation of the UI and select "Events".

With Events, you can see a feed of events along with all of their properties coming into Mixpanel.

### Find Yourself

The next step to validating your events is to manually trigger some of those events on your own device. After you have fired some events, navigate to Events and search or filter using any user-level information you know is available in the event's raw payload. Search by `$user_id`, `$device_id`, `distinct_id`, or user property values. If you are using Mixpanel's JavaScript SDK, you can use [`mixpanel.get_distinct_id`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelget_distinct_id) to return your own distinct\_id in your browser console and copy the distinct\_id value into the Events search bar.

<Frame>
  <img alt="Events Filter" />
</Frame>

Once you have identified one of your own events in Events, you can inspect all of the properties that were sent with your event by clicking on > to expand it. Toggle between the *Your Properties* and *Mixpanel Properties* tabs to determine which properties are custom to your Mixpanel implementation and which are sent default by Mixpanel. Toggle *JSON mode* to view the complete JSON object Mixpanel received from the calls you sent. We recommend checking that:

1. Events are triggered as expected and requests are successful.
2. Events contain all of the expected properties and event property values, including distinct\_id. Keep in mind that event properties should reflect the value **at the time of the event,** whereas user properties reflect the most recent value.
3. Property values are sent with the expected data type.
4. Event and property names are in the correct taxonomy and casing **(Mixpanel is CaSe Sensitive)**

To locate your User Profile from Events, click the User icon on the left to view your User Profile.

<Frame>
  <img alt="View User Profile in Events" />
</Frame>

### Debugging with User Profiles

User Profiles allow you to see the events feed and all user properties for a specific user. The Activity Feed displays a user's entire event history. The most recent activity appears at the top of the list. By reviewing User Profiles, you can validate:

1. User Properties set on the profile correctly. Keep in mind that user properties should reflect **the most recent value** of the property, unlike event properties which reflect the value at the time of the event.
2. Whether the expected events are appearing in the Activity Feed correctly and in order. For example, if you only trigger an event onces but two instances of the event appear in the event stream, you should check your initialization and the logic triggering the event for errors.
3. If user property names are in the correct taxonomy and casing **(Mixpanel is CaSe Sensitive)**

<Frame>
  <img alt="User Profile" />
</Frame>

## Missing or Incomplete Events

### Enable Debug Mode

If you are using one of Mixpanel's client-side SDKs, you can enable debug mode to confirm that requests are sending to Mixpanel:

* [JavaScript Debug Mode](/docs/tracking-methods/sdks/javascript#debug-mode)
* [iOS - Objective-C Debugging and Logging](/docs/tracking-methods/sdks/ios#debugging-and-logging)
* [iOS - Swift Debugging and Logging](/docs/tracking-methods/sdks/swift#debugging-and-logging)
* [Android - Debugging and Logging](/docs/tracking-methods/sdks/android#debugging-and-logging)
* [React Native - Debugging and Logging](/docs/tracking-methods/sdks/react-native#debugging-and-logging)
* [Flutter - Debugging and Logging](/docs/tracking-methods/sdks/flutter#debugging-and-logging)

### Debugging with the Browser Console (Web)

If you're using Mixpanel in a web application, you can use your browser's developer console to view Mixpanel API calls being made from each page.

1. On your website, [enable debug mode](/docs/tracking-methods/sdks/javascript#debug-mode).
2. Open your browser's developer console and navigate to the Network > Fetch/XHR tab.
3. Perform an action that triggers the `mixpanel.track` call.
4. Look for requests to the Mixpanel API and troubleshoot any error messages.

   * If your project has US Data Residency, look for a request triggered to `api.mixpanel.com/track`.
   * If your project has [EU Data Residency](/docs/privacy/eu-residency), look for a request triggered to  `api-eu.mixpanel.com/track`.
   * If your project has [India Data Residency](/docs/privacy/in-residency), look for a request triggered to  `api-in.mixpanel.com/track`.
5. If the request is successful, check that the "token" in the data payload matches the token in your [Project Settings](/docs/orgs-and-projects/managing-projects#access-keys). From here, you can then validate that the event was directed to the right project token and using Events, and confirm that the data is arriving correctly in Mixpanel.

### Ensure you are using the API host that matches your project's data residency

If you are using a Mixpanel SDK, you *must* configure it to talk to the correct api host depending on your project's data residency. Refer to the SDK documentation for how to configure the API host.

| Data Residency                                     | API Host                     |
| -------------------------------------------------- | ---------------------------- |
| US Data Residency                                  | `api.mixpanel.com` (default) |
| [EU Data Residency](/docs/privacy/eu-residency)    | `api-eu.mixpanel.com`        |
| [India Data Residency](/docs/privacy/in-residency) | `api-in.mixpanel.com`        |

**⚠️ Important:** Projects with EU or India Data Residency must configure their SDK with the matching regional host (`api-eu.mixpanel.com` or `api-in.mixpanel.com`). Events sent to the wrong host will not be ingested in your Mixpanel project.

### Customize Flush Interval (Mobile)

Both the Mixpanel iOS and Android libraries employ queueing to optimize battery and data use on the end user’s device. Calling track does not send the event immediately, Events and User data sent to Mixpanel gets queued and flushed at certain intervals by default. This interval can be adjusted to flush more or less frequently.

#### iOS

On iOS, data gets flushed every time the user backgrounds the app or every 60 seconds.

Shorten or lengthen the flush interval to send data to Mixpanel on a more or less frequent basis by changing the value of `self.mixpanel.flushInterval`. You can also explicitly call [flush()](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/flush) to send the phone's queue immediately after having collected key events (such as sign up).

#### Android

On Android, both Event and People calls are put into a queue that gets flushed to Mixpanel according to either time or size. If the bulk upload limit of 40 records is not reached, the default flush interval is 60 seconds.

You can also flush manually with public [`void flush()`](http://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#flush\(\)). One common use case is to call flush before the application is completely shut down to ensure that all of Events are sent to Mixpanel.

#### Unity

On Unity, you can configure the interval at which data is flushed to Mixpanel. The default time is that data gets flushed every 60 seconds.

You can also flush manually with public `void flush()`.

### Check for Hidden Events and Properties

#### Hidden in Lexicon

Project Owner and Admin users can hide events, event properties, and user profile properties in your [Mixpanel project through Lexicon](/docs/data-governance/lexicon#hide-events-and-properties). Check Lexicon to review if the event or property may be hidden.

#### Inactive Events and Properties

Mixpanel’s report dropdown menus hide events that have not been fired within the last 30 days. The only exception are events that have been modified via the Lexicon interface, eg: by adding a description, hiding the event, changing the display name, etc. The events will still be available in the project's raw data, but will not be visible in the UI. We do this to reduce clutter from events that are no longer firing. Event properties and property values that have not been sent to your project in the last 28 days will also be hidden from dropdowns.

To have an imported event, event property, or property value that’s older than 30 days show in the dropdowns, you can fire a single instance of that event, property, or property value and the data will resurface it in the UI. If you know the name of the event, you can also search for it by typing the name in the dropdown menu (case sensitive).

In addition to events and properties that haven't fired recently, Mixpanel also caches property names and property values to help dropdown menus load quickly.

If you've just implemented a new property or a new value for an existing property and don't see it appear in a report's dropdown, the cache may not have refreshed yet.

To manually refresh the dropdown cache:

1. Open the property dropdown menu
2. Type any string into the search box, e.g. "Refreshing Cache" (this doesn't need to match an actual property — it just triggers the dropdown's search state).
3. A **Refresh** option will appear in the dropdown.
4. Click **Refresh** to refresh the cache of property names and values for that dropdown.

Your new property or value should now appear without having to wait for it to automatically resurface in the UI.

<Frame>
  <img alt="Image" />
</Frame>

### Understanding CORS Errors

**CORS** stands for **Cross-Origin Resource Sharing**, and it is a security feature implemented by web browsers to prevent potentially harmful interactions between websites (or apps) from different domains (origins).

An "origin" refers to the combination of the protocol (HTTP or HTTPS), domain (example.com), and port (8080, for example). When a webpage from one origin tries to make requests (like loading data or interacting with a server) to a different origin, that is a cross-origin request.

#### Why do CORS errors happen?

By default, browsers block web pages from making requests to a different domain, protocol, or port than the one the page originated from (this is called the **same-origin policy**). This helps protect users from **cross-site scripting (XSS)** and other malicious attacks.

However, there are legitimate scenarios where a website might need to request resources from another domain. For example:

* A front-end app (like a React or Angular app) might need to get data from an API hosted on a different domain.
* A website might want to load images or resources hosted elsewhere.

In such cases, the server from the other domain has to explicitly allow these requests through a process called **CORS**.

#### Fixing Common Cases of CORS Errors

1. CORS Configuration

Ensure your proxy is properly configured to handle CORS. This includes adding the appropriate Access-Control-Allow-Headers, such as Authorization, in the preflight response. Verify that Access-Control-Allow-Origin is set to allow requests from your client’s domain.

2. Proxy Adjustments

Reconfigure your proxy to forward all necessary headers, including Authorization, Content-Type, and Content-Encoding, to the /record endpoint. If you’re encountering a 415 Unsupported Media Type error, it’s likely the Content-Type and Content-Encoding headers are being blocked or not forwarded correctly.

3. Initialization Setup

Make sure you’re initializing Mixpanel correctly for session replay by including the recommended options in your mixpanel.init() call, such as track\_pageview and persistence.

4. Content Security Policy (CSP)

Verify that your Content Security Policy allows connections to all required Mixpanel domains. Update it to include the necessary URLs if needed.

5. Fallback Option

If possible, switching back to the default Mixpanel endpoints could resolve these issues, as they are pre-configured to handle CORS correctly. However, we understand this might not be ideal if you rely on your proxy to avoid ad blockers.

6. Debugging Tips

Use your browser’s developer tools to inspect network requests to the record endpoint. Look for errors like CORS rejections or HTTP status codes (e.g., 415). Compare successful requests to the default Mixpanel endpoints with those sent through your proxy to identify any discrepancies.

## Data Discrepancies

### Discrepancies in Mixpanel Reports

Mixpanel reports calculate data in different ways. While the Insights report may be counting the total event count ('Total Events'), the funnel report may be counting based on unique user count ('Uniques'). So if you are seeing discrepancies between a Funnel and an Insights report, take a step back and look at the filtering for the events. It's important to note that the 'totals' in Funnels show total conversions, not total event count.

With discrepancies within the Mixpanel interface, it's important to look out for:

* Comparisons between unique user count vs. total event count? In funnels; Are you using unique, total conversions or session conversions?
* Differences in properties - E.g. event property vs. user property vs. custom property

If you took a screenshot of a report a while ago and the data has changed since then, you can check if any user properties have been used in the report as they change over time, while event properties hold constant. You can also check if you have imported data or if data was ingested later by breaking down a report by the property mp\_processing\_time\_ms.

A good way to start is to remove all filtering from the reports to check if the underlying data is the same, then re-add them and see when the discrepancy occurs. Likely the culprit will be a filter or a breakdown.

### Discrepancies between Mixpanel and other sources

Two systems will always track data differently due to their nature. It might very likely be that the systems will never track exactly the same data. However, it is important to get to the bottom of what's causing the discrepancy so you can establish trust in your data. Below is a list of common causes of discrepancies between Mixpanel and other sources:

### Ad Blockers and Do Not Track Settings

Client-Side Tracking can be unreliable, you may lose events for 30-50% of your users. You can resolve this by [sending events through a proxy](/docs/tracking-methods/sdks/javascript), but it requires a bit more effort. We [recommend](/docs/debugging/overview#client-side-vs-server-side-tracking) server-side tracking, since it is more reliable and easier to maintain than web/mobile tracking.

### Different Timezones

Mixpanel records all events in Coordinated Universal Time (UTC) at intake. By default, Mixpanel displays events times in US Pacific Time but this is adjustable in [Project Settings](/docs/orgs-and-projects/managing-projects#manage-timezones-for-projects). Navigate to your Project Settings to determine what timezone your Mixpanel events are displayed in.

* Are event timezones tracked in the same way?

### Different Queries

* Are both systems looking at the same event and the same time frame?
* Are any filters applied to the query? Does the discrepancy persist if you remove them?
* Are you looking at event or user properties?

### Different Calculations

* Some of our reports have calculations applied, such as Funnels or Retention. Does the same calculation apply to the data in your other source?

### Client-Side vs. Server-Side Tracking

* Client-side integrations are more vulnerable to data tracking issues due to ad blockers and DNT settings
* Mixpanel's SDKs needs to be loaded to trigger the first event

### Different Triggers to Track Data

* Are both systems using the same triggers to track events? For example, the First App Open event in Mixpanel will trigger when our SDK has loaded, other systems might trigger a comparable event earlier.
* The event definitions might be different - Think of a button click on the client-side triggering the event in one system vs. an API call triggering the event in the other system.

### Delayed Ingestion

* Mixpanel accepts data that has been triggered a while ago, either via mobile SDKs or event import. You can check the \$import property and the mp\_processing\_time\_ms to confirm when data has been ingested.
* Mixpanel events older than 5 days sent to our /track endpoint will not be ingested, but other systems might accept these events (e.g. Firebase). Check how old an event was at point of ingestion in the other system to confirm.
* If the same report with the same date range returns different metrics from one day to the next, this typically indicates that late-arriving data were not yet ingested at the time of the previous view. This can occur when data are imported retroactively or when other ingestion delays occur.

### Cohort Export

A cohort might show more in Mixpanel than what is actually being exported to the partner. You can find out more about [troubleshooting this here](/docs/cohort-sync/webhooks).

### Debugging Discrepancies

To debug, please make sure that you are looking at data in both systems like this:

* data that is triggered at the same point of the user journey
* at the same time frame and timezone
* with the same filtering for the query of the data
* at the same unit (unique user count, total event count or session count)

Once you have established this, we recommend drilling down into the data, for example into one day that shows the biggest discrepancies. You can also drill down into specific segments such as country to identify users that have been tracked in one system, but not the other. The goal is to confirm which users are present in one system but not the other, to understand a pattern.

You can also compare the total event count versus the unique user count in the affected systems. If the totals match, but the unique user count shows discrepancies, it likely points to an ID management issue.

A 'last resort' to get to the bottom of things is to implement your own server-side tracking of the data. This will be more reliable as it’s less prone to issues and is independent of Mixpanel and other systems. It would give you a source of truth to compare any other system to and go from there. While this is resource-intense, it’s a good way to get to a source of truth.

### Discrepancies with Segment

The first step here would be to check if you are tracking with a cloud-mode or device-mode integration.

If the discrepancy is between Mixpanel and another source, but you're tracking via Segment in cloud-mode, you can do the following to troubleshoot:

* If Segment and Mixpanel show the same data, we recommend reaching out to Segment Support, as this likely points to an issue with Segment tracking.
* If Mixpanel and Segment don’t show the same data, and both have a discrepancy with a third source, we also recommend reaching out to Segment Support to troubleshoot the discrepancy between the 3rd party and Segment. In Mixpanel, you can check for specific distinct\_ids that should have events in Mixpanel, or specific events that should be in Mixpanel but might’ve been ingested with a different distinct\_id.

If the discrepancy is between Segment and Mixpanel only, keep in mind that device-mode tracking will send the data to Mixpanel directly. If there are discrepancies, you can check for data by searching for specific events, or specific distinct\_ids, depending on what you have available from Segment, as it might be that the data has been ingested but allocated to the wrong distinct\_id.

If you are tracking via cloud-mode, data will be sent from Segment to Mixpanel. It would basically be the same approach as above, whereas you’d need information from Segment Support when data has been sent. If in cloud-mode, then the issue is the communication between the two systems and Segment would need to provide information on when and how data has been sent.


# Developer Environments
Source: https://docs.mixpanel.com/docs/tracking-best-practices/developer-environments



## Separate Development Data

We recommend that you set up a separate project for your development environment. Keeping your development data separate is important to maintain the integrity of your Mixpanel data. It's easy to prevent development data from cluttering your production project, but hard to detangle in later stages of a project.

To set up separate environments:

1. Create two separate Mixpanel projects for development and production. Mixpanel doesn't limit the number of projects you can use. If you are on an MTU plan, keep in mind that an organization is charged based on the total number of MTUs across all projects. This means that if a user performs a qualifying event in multiple projects, they are counted once per project. Once you have tested thoroughly in your development environment, stop sending data to your development project to avoid double-counting MTUs across projects.
2. Use the logic in the code snippet below to switch automatically between the two project tokens when you're in development or when you're ready to push data to production.
3. Specify your production domain and project tokens.

Dynamically changing project tokens ensure your testing data does not contaminate your production environment. It allows you to easily build reports from true user data. Plus, it removes the need to swap out tokens before every push to production.

Remember, use this solution only if your development environment uses a different hostname, such as development.yourdomain.com.

```javascript theme={"system"}
var productionHost = 'Your production Domain'; 
var devToken = 'Development Token'; 
var prodToken = 'Production Token'; 

//If the hostname is anything other than your production domain, initialize the Mixpanel library with your Development Token 

if (window.location.hostname.toLowerCase().search(productionHost) < 0) { mixpanel.init(devToken);
 } else { mixpanel.init(prodToken); } 
```

## When to Use Multiple Production Projects

You can choose to send production data from multiple sources (for example, your website and mobile app) to the same Mixpanel project or to two separate projects. It’s up to you to determine which is best for your business, but here are a few tips to help you decide:

### Factors to Consider

**Do you want to track and study cross-platform user behavior?**

* For example, do you foresee leveraging either platform to convert users to another platform or contributing to the other platform's retention? Or is it common for users to begin a flow on your web app and complete that flow on your mobile app?
* If so, then you probably do want to study behavior cross-platform and should send the data to the same project. Sending data to two different projects means you won’t be able to easily compare any behavior from the app to the website or vice versa.

**Do your app and website offer fundamentally different functionality?**

* If the purpose and features of your data sources vary widely, you might consider using two different projects and analyzing each separately.
* Sending both types of data to the same project could clutter your analytics for both mobile and web, as having a many unique event and property names from different platforms can clutter the UI and dropdown menus in your Mixpanel project.

**Note** An organization is charged based on data across all projects. This means that if the same event is being sent to multiple projects, it will count against your data allowance once per each project.

### Best Practices for Cross-Platform Tracking

Generally speaking, Mixpanel users have more flexibility and get more valuable insights when combining the tracking of multiple platforms into a single project to study their overall user experience across platforms.

While we generally recommend sending data from all platforms to a single project, it’s also best practice to create separate development and production projects to avoid cluttering production data with test data, regardless of platform. If you send events from all platforms to one project, you can still differentiate actions taken on your app vs. website via segmentation and filtering using the Operating System property (the Mixpanel JavaScript, iOS, and Android libraries store the Operating System property by default).

If you decide to send events from multiple platforms to the same Mixpanel projects, follow these guidelines for the best results:

* Make sure events that are the same across platforms are named the same way. For example, you wouldn’t want to create an Event on your website called Sign in and an Event on your app called Log in if they represent the same user action.
* Capitalization matters: calling one event “Purchase” and one “purchase” will show as two different events in your report dropdowns!
* Ensure you’re handling user identity properly so that you can track users across platforms without counting them as a different user on each platform. Learn more about [identifying users](/docs/tracking-methods/id-management/identifying-users).
* Advanced tip: You can initialize multiple instances of Mixpanel on the same app to send certain events to their own, different project. This would allow you to send some events to a different project if you have some different functionality on certain platforms and want to analyze that activity separately.

## Send Data to Multiple Projects

You can initialize separate Mixpanel objects with different tokens to send event and property updates to separate projects.

This separation is useful when you want certain events to appear in one project and others events to appear in a different project.

### Web

Sending event data from a single website to multiple different Mixpanel projects is possible by using the JavaScript library and modifying the mixpanel.init call.

The optional library\_name parameter in the mixpanel.init function allows you to specify which library to write to in all tracking calls.

For example, suppose you have project A with a token of "123abc" and project B with a token of "456def."

After your initial Project A init call (with 123abc), you could set up a second instance of the initialization like this:

```javascript theme={"system"}
// Replace 456def with your project B token
mixpanel.init("456def", {}, "project_b")
```

You would then send any project B calls like this:

```javascript theme={"system"}
mixpanel.project_b.track("event name")
```

Any standard track calls without a specified project name would go to the initial Mixpanel project.

### iOS

You can create multiple instances of the Mixpanel API and switch back and forth between two projects by using the initWithToken method.

You can specify your second project token in this method.

Note that codeless events and A/B testing will always apply to the instance with sharedInstanceWithToken.

For example:

```objc theme={"system"}
Mixpanel *master = [Mixpanel sharedInstanceWithToken:MASTER_TOKEN];

Mixpanel *publisher = [[Mixpanel alloc] initWithToken:PUBLISHER_TOKEN andFlushInterval: 60];

[master track:@"..."];

[publisher track:@"..."];
```

### Android

To initialize multiple instances of Mixpanel on Android, construct separate Mixpanel objects.

For example:

```java theme={"system"}
public class MainActivity extends AppCompatActivity {
    public MixpanelAPI mixpanel;
    public MixpanelAPI mMixpanel;

    private static final String projectToken = "TOKEN 1";
    private static final String projectToken_t = "TOKEN 2";
    private static Context context;

    @Override
    protected void onCreate(Bundle savedInstanceState) {

        super.onCreate(savedInstanceState);


        setContentView(R.layout.activity_main);

        mixpanel = MixpanelAPI.getInstance(this, projectToken);
        mMixpanel = MixpanelAPI.getInstance(this, projectToken_t);
        mixpanel.identify(mixpanel.getDistinctId());
        mMixpanel.identify(mMixpanel.getDistinctId());


        try {
            JSONObject props = new JSONObject();
            props.put("Screen", "MainActivity");
            mixpanel.track("Viewed Screen", props);
            mMixpanel.track("Viewed Screen", props);
        } catch (JSONException e) {
            Log.e("MYAPP", "Unable to add properties to JSONObject", e);
        }
    }
}
```


# Geolocation
Source: https://docs.mixpanel.com/docs/tracking-best-practices/geolocation

IP address and location properties

## Overview

Mixpanel automatically appends geolocation to your events and profiles. Geolocation consists of the following properties:

* `$region`
* `$city`
* `mp_country_code` (for event data)
* `$country_code` (for profile data)

These geolocation properties are [Default Properties](/docs/data-structure/property-reference#default-properties) of [Mixpanel's Ingestion APIs](/reference/ingestion-api) and [Client-side SDKs](/docs/tracking-methods/choosing-the-right-method#client-side-tracking).

They are also Reserved Properties that Mixpanel uses for special processing or for specific system features. These properties, when populated, will affect the way Mixpanel processes your data (e.g., appearing in the special areas in the UI).

## Default Geolocation Tracking

By default, geolocation properties are set using the IP address of the location where the request was made.

For **event data**, the geolocation event properties are derived from the IP address of the client-device or server that sent the event [track/import request](/reference/import-events). (e.g. calling [.track()](/docs/tracking-methods/sdks/javascript#track-events))

For **profile data**, the geolocation profile properties are derived from the IP address of the client-device or server that sent the [profile update request](/reference/profile-set). (e.g., calling [.people.set()](/docs/tracking-methods/sdks/javascript#setting-profile-properties))

<Note>
  Every time you set profile properties, the geolocation properties are overwritten with the location of the profile set request. Learn how to ignore geolocation when setting profile properties [here](/docs/tracking-best-practices/geolocation#ignore-ip-address).
</Note>

### IP address Parsing

While the IP address is used to generate the geolocation properties, the IP address values themselves are not stored. Under the hood, we take the IP address of the request and parse it through [Maxmind](https://www.maxmind.com/en/geoip-demo) to generate the Country, Region, and City values. Afterward, these geolocation values are attached to your data, and the IP address value is discarded from the payload prior to ingestion into your project.

In summary, here is the order of operations:

1. Our ingestion API receives a request to ingest an event or update a profile.
2. We extract the IP address from the request location, then check it against Maxmind's database.
3. Maxmind returns the country, region, and city information associated with the IP address.
4. The country, region, and city are attached to the event/profile payload as geolocation properties.
5. The IP address value is discarded from the payload.
6. The payload, which includes the geolocation properties without the IP address, enters the queue for ingestion into the project.

<Note>
  IP address is an approximation of location. For more granular precision, [set your location using latitude and longitude](/docs/tracking-best-practices/geolocation#define-latitude-and-longitude).
</Note>

<Frame>
  <img alt="geolocation_parsing.png" />
</Frame>

## Manual Geolocation Tracking

It is possible to override the default geolocation tracking behavior of our ingestion APIs. This is helpful in certain scenarios, for example:

* **Server-side implementation**: Since the default geolocation is derived from the IP address of the request, data sent from the server-side will appear with geolocation set to the location of the server instead of the location of your users.
* **Precise Location**: IP address is an approximation of location. Some use cases require additional precision.
* **Geolocation information already exists**: If you have a database of your users' locations, you may want to leverage your database as a source of truth instead of relying on the geolocation parsing mechanism.

There are 3 ways to manually set the geolocation properties in your Mixpanel payloads: define the geolocation properties, define the Latitude/Longitude, or define the IP address.

### Define Geolocation Properties

You can manually define the country, city, and region geolocation properties in your event and profile payloads. The manually defined geolocation properties will be prioritized over the location derived from the IP address.

**Example Event**

```json theme={"system"}
// set event location to San Francisco, California, USA
{
    "event": "Signed Up",
    "properties": {
        "distinct_id": "13793",
        "token": "project_token",
        "mp_country_code": "US",
        "$city": "San Francisco",
        "$region": "California",
        "someProperty": "someValue"
    }
}
```

**Example Profile**

```json theme={"system"}
//set profile location to San Francisco, California, USA
{
    "$token": "project_token",
    "$distinct_id": "13793",
    "$set": {
        "my_property": "my_value",
        "$country_code": "US",
        "$region": "California",
        "$city": "San Francisco"
    }
}
```

### Define Latitude and Longitude

If you have access to Latitude and Longitude information, you can specify `$latitude` and `$longitude` in the payload so that Mixpanel will use these properties (instead of the IP address) to infer the closest city.

**Example Event**

On events, the event properties must be named `$latitude` and `$longitude`, and the values should be in floating-point decimal degrees.

```json theme={"system"}
{
    "event": "Signed Up",
    "properties": {
        "distinct_id": "13793",
        "token": "mytoken",
        "$latitude": 37.77,
        "$longitude": -122.42
    }
}
```

**Example Profile**

On user profile updates, the data must be named `$latitude` and `$longitude`, and the values should be in floating-point decimal degrees.

You would also need to set `$latitude` and `$longitude` outside of the `$set` dictionary.

You will see the `$geo_source=reverse_geocoding` profile property in the Profile UI if location properties were determined through `$latitude` and `$longitude`.

<Note>
  Reverse geocoding for user profiles is not supported via client-side SDKs.
</Note>

```json theme={"system"}
{
    "$token": "mytoken",
    "$distinct_id": "13793",
    "$latitude": 37.77,
    "$longitude": -122.42,
    "$set": {
        "My_property": "my_value"
    }
}
```

### Define IP Address

You can manually define the IP address value of your payloads and Mixpanel will parse for the geolocation using your IP address value instead of the IP address of the request location. The IP address is dropped prior to ingestion, so if you are looking to track the IP address as a property inside Mixpanel, name the property something else.

<Note>
  Note that `ip` is used for event payloads, and `$ip` is used for profile payloads.
</Note>

If you're tracking from your servers, you need to set the `ip` property of the events to the *client's* IP address. Most server frameworks provide this out of the box.

* [Django](https://docs.djangoproject.com/en/4.1/ref/request-response/#django.http.HttpRequest.META) exposes this in the request object with `request.META['REMOTE_ADDR']`.
* [Flask](https://flask.palletsprojects.com/en/2.2.x/api/?highlight=remote_addr#flask.Request.remote_addr) exposes this as `request.remote_addr`.
* [Go](https://pkg.go.dev/net/http#Request) exposes this as the `RemoteAddr` field on the http.Request struct.
* [Nginx](http://nginx.org/en/docs/http/ngx_http_log_module.html) exposes this as `$remote_addr`.

**Events**

```json theme={"system"}
//manually set the IP address of the event to 136.24.0.114
{
    "event": "Signed Up",
    "properties": {
        "distinct_id": "13793",
        "token": "mytoken",
        "ip": "136.24.0.114"
    }
}
```

**Users**

```json theme={"system"}
// set location of the profile to 136.24.0.114
// note that $ip is outside of the $set object
{
    "$token": "mytoken",
    "$distinct_id": "13793",
    "$ip": "136.24.0.114",
    "$set": {
        "My_property": "my_value"
    }
}
```

#### Ignore IP Address

As all server-side requests originate from the same IP, such as the IP of your server, it can have the unintended effect of setting the location of all of your users to the location of your data center. To prevent the Engage API from updating your profile geolocation using the IP address of the incoming request, you can set the \$ip to 0 in your payload.

```json theme={"system"}
// $ip set to 0
// Engage API will ignore the IP address
// Geolocation will not be updated
{
    "$token": "mytoken",
    "$distinct_id": "13793",
    "$ip": "0",
    "$set": {
        "My_property": "my_value"
    }
}
```

You can set append `ip=0` to your request URL to set \$ip to 0 for all your Engage requests.

```text theme={"system"}
api.mixpanel.com/engage?verbose=1&ip=0
```

## FAQ

**1. Why is my user's profile geolocation different from the geolocation of their events?**

Profile geolocation properties and event geolocation properties are set at different times. Profile geolocation is updated every time profile properties are set, and event geolocation is parsed at the time the event is tracked. For this reason, the geolocation of the profile may not necessarily match all of the events by that same user.

For example, your user may log in to your app in the US, which sets the profile geolocation to the US. Then they may travel to Germany and track many events using your app without updating any profile properties since they are already logged in. In this case, we will see some events stemming from Germany despite the user profile location being in the US.

**2. I know for a fact that one of my users is located in a certain country, but they are appearing in an entirely different continent in Mixpanel. What's wrong?**

This can happen for a variety of reasons. Some users may have privacy settings or VPNs that mask their true location. Mixpanel uses the IP address of the request for geolocation parsing, so if a user is masking their location, we would have no way of distinguishing it. If you know the geolocation of your users, consider [manually defining the geolocation properties in your data](/docs/tracking-best-practices/geolocation#manual-geolocation-tracking).


# Hot Shard Limits
Source: https://docs.mixpanel.com/docs/tracking-best-practices/hot-shard-limits



In order to maintain fast queries and catch implementation mistakes, we set a limit on the number of events sent to a particular identifier in a given time window. This threshold has been established for a project as:

* 200K events per `distinct_id` per event date in the project's user analytics.
* 1M events per `group identifier` per event date (still represented as distinct\_id in the rest of this doc) in each of the project's [analytic groups](/docs/data-structure/advanced/group-analytics).

## What is a hot shard?

Whenever a project goes above the threshold described above, it generates an imbalance when storing events across distinct\_ids, where one distinct\_id's events grows larger than the rest, impacting storage and query systems which in-turn results in high query latencies (slower reports) for the end user.

Since we distribute events across shards, this imbalance is called a **hot shard**.

Group analytics has a different storage sharding of events separate from the user analytics. A hot shard that appears in an analytic group may or may not not appear in user analytics.

## What happens when we detect a hot shard?

Once a given entry crosses the threshold, all subsequent matching events (same `distinct_id` and calendar day) will have the following transformations applied to them:

* `event` will be changed to `$hotshard_events` (display name is `Hotshard Events`).  The original event name will be preserved under a property called `mp_original_event_name` (display name is `Hotshard Original Event Name`). Changing the name removes the bad events from being selected for analysis yet remain accessible for debugging.
* `distinct_id` is changed to `""`\[^1]. The original value will be preserved under a property called `mp_original_distinct_id` (display name is `Hotshard Original Distinct ID`). Removing the distinct\_id allows Mixpanel backend to distribute these events evenly across shards ensuring that performance is not adversely affected while keeping the data accessible for debugging.
* If the hot shard comes from a `group identifier`, these transformed events would show up when you analyze by the respect `Group` in Insights report.

Original Event -

```json theme={"system"}
{
  "event": "Signed up",
  "properties": {
    "time": 1618716477000,
    "distinct_id": "hotshard@mixpanel.com",
    "$insert_id": "36a92782-cd7d-41a0-93af-8c23ec6c4191",
  }
}
```

Updated Event -

```json theme={"system"}
{
  "event": "$hotshard_events",
  "properties": {
    "time": 1618716477000,
    "distinct_id": "",
    "mp_original_event_name": "Signed up",
    "mp_original_distinct_id": "hotshard@mixpanel.com",
    "$insert_id": "36a92782-cd7d-41a0-93af-8c23ec6c4191",
  }
}
```

These events can be queried from the dashboard just like any other events. An email is sent to organization owners and the specific project's owners to alert them of the hot shard. In addition, a monthly report (per project) is sent as well for hot shards that were detected and remediated in the past month.

Starting in June 2024, we are also limitedly emitting a new type of events called `$hotshard_record`. The purpose is to keep track of all user-analytics and group-analytics hotshard remediation history that has happened inside your project in a central event type.

```json theme={"system"}
{
  "event": "$hotshard_record",
  "properties": {
    "time": 1618716477000,
    "hotshard_distinct_id": "hotshard@mixpanel.com",
    "hotshard_group_key": "group_key",
    "hotshard_group_display_name": "group_display_name",
  }
}
```

## Recovering from a hot shard

The process can be broken down into 3 main steps:

* Reviewing the hot shard events in your project to identify which events, and `distinct_id` or (analytics groups and `group identifier`) values are involved
* Change the implementation to avoid further instances of the hot shard
* (Optionally) Fix historical data via exporting, transforming and re-importing the data

### Reviewing hot shard data in your project

A great starting point for the analysis would be to create a copy of [this board](https://mixpanel.com/s/15L5fh) from our demo project into the affected project. As you open the board linked above, you will see instructions to click on "Use this board" to transfer it over to your project and to edit the default date range. Only projects with US residency will be able to copy the board directly. Projects with EU and IN residency will need to recreate the reports manually.

<Frame>
  <img alt="Screenshot use this board" />
</Frame>

The board eases the process of identifying the data marked as coming from a hot shard. Essentially, it helps you create reports to break down that data by the main `distinct_id` values affected as well as the event names. For example, you can see reports pointing to the main `distinct_id` values (by volume) generating the hot shard.

<Frame>
  <img alt="Sample hot shard report" />
</Frame>

### Changing your implementation

Once you have identified the cluster of `distinct_id` values related to the issue, it would be time to review your implementation and inspect the reason why a set of these IDs are getting a higher than usual number of events. In general terms, you will often find these main scenarios:

#### Events that are non-attributable to users but marked with a specific ID

In some instances, your project will have events that should not be attributed to a specific user or group, like some automated tests being tracked, or perhaps ad-spend data you're importing; it may be that when implementing, a specific ID was arbitrarily chosen for those events, say the string `"0"`, `"spend_data"` or perhaps even the name of the pod/server the data is coming from. This can lead to hundreds of thousands of events with the same ID causing this issue.

If your use case is similar to this, and the event **should not be attributed to specific users or groups**, you can change your implementation to send those events with an empty string value `""`. Upon ingestion, Mixpanel will randomly store these events in different shards so you will not incur a performance hit if this is your intended use case.

#### ID management issue

Throughout the user journey, a given user might trigger events under multiple `distinct_id` values; the most frequent use case being a user initially being anonymous and then authenticating. When a user authenticates, generally, we advice changing the ID of the user to the authenticated one and for projects with ID merge enabled, and this is done through the `identify` function. Ideally this function should receive the user's authenticated ID to link it to the anonymous activity, but sometimes there can be implementation issues; as an example, the implementation may provide a static string for all users instead of the new user ID, like this:

```javascript theme={"system"}
function authenticate_user(user_id){
	mixpanel.identify('user_id');
	mixpanel.track('user_authenticated');
}
```

Although the code above looks almost like it should work, it could be easy to miss a static string is being passed to the function instead of the dynamic value for each user. This would mean that after this function runs, all users would actually send events with the same id value: `user_id`.

You will want to fix the implementation to identify users correctly and avoid new users being impacted. You can find more information on [identifying users in this doc](/docs/tracking-methods/id-management/identifying-users).

In case you've identified the problematic set of ID values, but you have not been able to identify the root cause in the implementation. Reach out to our [support team](https://mixpanel.com/get-support) and provide the details you've uncovered so far; providing your copy of the board and any details on the investigation in your code will be of great assistance helping you identify the issue.

#### Group Analytics implementation issue

Adding users to groups causes the group\_key and group\_id to send as a property key and value for all events triggered by that user on the device.

```javascript theme={"system"}
mixpanel.set_group(“company”, [“Company”])
}
```

Similar to the issue above, it is also easy to pass a static string to this function. After this runs, all events sent would include the group identifier: `Company`.

### Fix historical data not involving Groups Analytics

Before re-importing, verify newly imported events will no longer create hot shards and the original issue has been solved.

Once the implementation has been changed, you can still have a situation in which some of your metrics might be temporarily down since they were tracked with a different event name (`$hotshard_events` instead of the original name) and without a distinct\_id (which can make unique counts go down, although this is usually less of an impact).

The great news is that since the events are still in your project, you can export them, transform them and re-import them.

Below you will find an example script leveraging [our python module](https://github.com/mixpanel/mixpanel-utils) to export the `$hotshard_events` by day to a folder, transform them (in this case replace the event name with the original name the events had) and re-import them. This script is meant as a template for you to review and adjust. You will want to pay special attention to the `transform_event` function in which you can remap properties as needed for the final event to be imported. You can find the configuration options towards the start of the script within the `SETTINGS` variable.

```python theme={"system"}
import glob
import gzip
import json
from mixpanel_utils import MixpanelUtils

SETTINGS = {
    "PROJECT_ID": "<REPLACE YOUR PROJECT ID>",
    "TOKEN": "<REPLACE PROJECT TOKEN>",
    "SA_USERNAME": "<REPLACE SERVICE ACCOUNT USERNAME>",
    "SA_PASSWORD": "<REPLACE SERVICE ACCOUNT PASSWORD>",
    "EU": False, # set to TRUE if your project is in the EU
    "EXPORT_FOLDER": "exported_files", # make sure to create the folder if it does not exist
    "FROM": "2023-09-01",
    "TO": "2023-09-15",
}
mputils = MixpanelUtils(SETTINGS["SA_PASSWORD"],token=SETTINGS["TOKEN"],service_account_username=SETTINGS["SA_USERNAME"], eu=SETTINGS["EU"], project_id=SETTINGS["PROJECT_ID"])

def flush_events(events):
    global mputils
    if(len(events) == 0):
        return False
    mputils.import_events(events,timezone_offset=0)
    return True

def transform_event(event):
    try:
        data = json.loads(event)
        data["event"] = data["properties"]["mp_original_event_name"]
        del data["properties"]["mp_original_event_name"]
        del data["properties"]["mp_original_distinct_id"]

        # example if you wanted to remap the value from $user_id to distinct_id
        # if("$user_id" in data["properties"]):
        #     data["properties"]["distinct_id"] = data["properties"]["$user_id"]

        return data
    except:
        return False
#export hotshard events
mputils.export_events(f'{SETTINGS["EXPORT_FOLDER"]}/events.json',{
    "from_date": SETTINGS["FROM"],
    "to_date": SETTINGS["TO"],
    "event": '["$hotshard_events"]'
}, add_gzip_header=True, request_per_day=True, raw_stream=True)

exported_files = glob.glob(f'{SETTINGS["EXPORT_FOLDER"]}/*.json.gz')
for file_name in exported_files:
    events = []
    event_queue_max = 50_000 # arbitrary max length before sending in batches
    with gzip.open(file_name,'rt') as file:
        for line in file:
            event = transform_event(line)
            if(event == False):
                continue
            events.append(event)
            if(len(events) >= event_queue_max):
                flush_events(events)
                events = []
        
        #flush remaining events
        if(len(events) > 0):
            flush_events(events)
            events = []
```

### Fix historical data involving Groups Analytics

Just like the strategy above, before re-importing, verify newly imported events will no longer create hot shards and the original issue has been solved.

Since hot shards involving Groups Analytics are more complicated, we would need a different strategy of fixing historical data here. As of right now, our recommendation would require you to export all events related to the hot group ID (not just \`\$hotshard\_events), contact our [support team](https://mixpanel.com/get-support) to delete these events from Mixpanel, and reimport the fixed events.

Below are two sample scripts leveraging[our python module](https://github.com/mixpanel/mixpanel-utils) to export all events related to recent hot shard `group identifiers` by day to a folder. The idea would be to:

* Export the data and verify you store it to re-import it later. When you run the script to export, make sure to note the selector and date range generated by the script
* Reach out to our [support team](https://mixpanel.com/get-support) asking  for a deletion to remediate the hot shard issue. Provide the selector and date ranges from the previous script to make sure it aligns with the data you exported.
* Once the deletion has been confirmed by our support team (do note it can take about 1 week after the deletion is scheduled), use the second sample script to clean and re-import the data. Please note that the remediation strategy here will blank-out that group identifier for the day it's remediated.

#### Export all events related to the group hot shard

First step script below would download all events related to the group hot shards, leveraging the convenient `$hotshard_record` events for history-reading purpose. Notice the selector used below would include a time-threshold to bound both the export and deletion later to be the same set of events.

```python theme={"system"}
import glob
import gzip
import json
import shlex
import tempfile
import os
import time
from mixpanel_utils import MixpanelUtils

SETTINGS = {
    "PROJECT_ID": "<REPLACE YOUR PROJECT ID>",
    "TOKEN": "<REPLACE PROJECT TOKEN>",
    "SA_USERNAME": "<REPLACE SERVICE ACCOUNT USERNAME>",
    "SA_PASSWORD": "<REPLACE SERVICE ACCOUNT PASSWORD>",
    "EU": False, # set to TRUE if your project is in the EU
    "EXPORT_FOLDER": "exported_files", # make sure to create the folder if it does not exist
    "FROM": "2023-09-01",
    "TO": "2023-09-15",
}

mputils = MixpanelUtils(SETTINGS["SA_PASSWORD"],token=SETTINGS["TOKEN"],service_account_username=SETTINGS["SA_USERNAME"], eu=SETTINGS["EU"], project_id=SETTINGS["PROJECT_ID"])

def generate_individual_selector(hotshard_group_id, group_key):
    return (
        f"""((defined (properties["{group_key}"])) AND
        (
            (any(X, properties["{group_key}"], X="{hotshard_group_id}")) OR
            (string(properties["{group_key}"], "undefined") == "{hotshard_group_id}")
        ))"""
    )

def generate_selector(hotshard_key_group_id_tuples, time_threshold):
    return " OR ".join(
        [
            generate_individual_selector(hotshard_group_id, group_key)
            for hotshard_group_id, group_key in hotshard_key_group_id_tuples
        ]
    ) + f""" AND (number(properties["mp_processing_time_ms"]) < {time_threshold})"""

def hotshard_group_tuple(event):
    try:
        data = json.loads(event)
        hotshard_group_id = data.get("properties", {}).get("hotshard_distinct_id", "")
        group_key = data.get("properties", {}).get("hotshard_group_key", "")
        if group_key == "":
            return False
        return (hotshard_group_id, group_key)

    except:
        return False


unique_tuples = set()
# Find unique hot shard records
with tempfile.TemporaryDirectory() as temp_dir:
    file_path = os.path.join(temp_dir, "hotshard_records_events.json")
    mputils.export_events(file_path,
  {
        "from_date": SETTINGS["FROM"],
        "to_date": SETTINGS["TO"],
        "event": '["$hotshard_record"]' ,
    }, add_gzip_header=True, raw_stream=True)

    with gzip.open(file_path + ".gz",'rt') as file:
        for line in file:
            tupl = hotshard_group_tuple(line)
            if(tupl== False):
                continue

            unique_tuples.add(tupl)
    if len(unique_tuples) == 0:
        print("No hotshard records found")
        exit(0)
    print("UNIQUE_HOTSHARD_GROUP_TUPLES=", list(unique_tuples))

TIME_THRESHOLD = int(time.time() * 1000)
print("TIME_THRESHOLD=", TIME_THRESHOLD)
SELECTOR = generate_selector(unique_tuples, TIME_THRESHOLD)
print("SELECTOR=", shlex.quote(SELECTOR))

#Export all events related to hotshard groups
mputils.export_events(f'{SETTINGS["EXPORT_FOLDER"]}/events.json',{
    "from_date": SETTINGS["FROM"],
    "to_date": SETTINGS["TO"],
    "where": SELECTOR,
}, add_gzip_header=True, request_per_day=True, raw_stream=True)
```

#### Delete and re-import

Reach out to our [support team](https://mixpanel.com/get-support) for a deletion requests on events related to the group hot shards above. Include the `SELECTOR`, `FROM`, `TO` settings above so Mixpanel support team can get a clear understanding on the deletion criteria.

After hard-delete went through, use the below template script to fix the exported data kept from above, and re-import them.

```python theme={"system"}
import glob
import gzip
import json
import shlex
import tempfile
import os
import time
from mixpanel_utils import MixpanelUtils

SETTINGS = {
    "PROJECT_ID": "<REPLACE YOUR PROJECT ID>",
    "TOKEN": "<REPLACE PROJECT TOKEN>",
    "SA_USERNAME": "<REPLACE SERVICE ACCOUNT USERNAME>",
    "SA_PASSWORD": "<REPLACE SERVICE ACCOUNT PASSWORD>",
    "EU": False, # set to TRUE if your project is in the EU
    "EXPORT_FOLDER": "exported_files", # make sure to create the folder if it does not exist
    "FROM": "2023-09-01",
    "TO": "2023-09-15",
    # unique tuples acquired from export script run
    "UNIQUE_HOTSHARD_GROUP_TUPLES": [
        ("test_hot_shard_group_test_key_A", "test_key"),
        ("test_hot_shard_group_test_key_B", "test_key_2"),
    ],
}

mputils = MixpanelUtils(SETTINGS["SA_PASSWORD"],token=SETTINGS["TOKEN"],service_account_username=SETTINGS["SA_USERNAME"], eu=SETTINGS["EU"], project_id=SETTINGS["PROJECT_ID"])

def flush_events(events):
    global mputils
    if len(events) == 0:
        return False
    mputils.import_events(events, timezone_offset=0)
    return True


def transform_event(event):
    try:
        data = json.loads(event)
        if data["event"] == "$hotshard_events":
            data["event"] = data["properties"]["mp_original_event_name"]
            del data["properties"]["mp_original_event_name"]
            del data["properties"]["mp_original_distinct_id"]

        # example remediation you wanted to blank out the hot shard in groups
        for hotshard_group_id, group_key in SETTINGS["UNIQUE_HOTSHARD_GROUP_TUPLES"]:
            if group_key not in data["properties"]:
                continue

            if data["properties"][group_key] == hotshard_group_id:
                data["properties"][group_key] = ""
            elif hotshard_group_id in data["properties"][group_key]:
                data["properties"][group_key] = [
                    "" if x == hotshard_group_id else x for x in data["properties"][group_key]
                ]

        return data
    except:
        return False


# Work on exported files from export script run
exported_files = glob.glob(f'{SETTINGS["EXPORT_FOLDER"]}/*.json.gz')
for file_name in exported_files:
    events = []
    event_queue_max = 50_000  # arbitrary max length before sending in batches
    with gzip.open(file_name, "rt") as file:
        for line in file:
            event = transform_event(line)
            if event == False:
                continue
            events.append(event)
            if len(events) >= event_queue_max:
                flush_events(events)
                events = []

        # flush remaining events
        if len(events) > 0:
            flush_events(events)
            events = []
```

## Hot Shard FAQ

#### How does hot shard detection work?

The detection step runs in the ingestion pipeline. A counter of events is maintained for each `distinct_id` and `event_date` combination. The counter is best-effort as a result of the underlying systems used to maintain such a large key space.

Once a pre-defined threshold is crossed, the `distinct_id` is marked as contributing to a hot shard and all subsequent events for this `distinct_id` and `event_date` are updated to even the load across shards. Historical events prior to the hotshard detection for the same `distinct_id` are not updated.

#### I received an email about a hot shard but I don't see users with more than 200K events, why?

Since the detection is done at ingestion, duplicates (potentially as a result of client-side tracking retries) are also counted as part of the hotshard threshold (roughly > 200K event volume). This means you might see \<200K events in Mixpanel reports as being remediated for certain distinct\_id which were only deduplicated post-ingesting these events.

1. Due to a side-effect on how events are serialized, some remediated entries were initially saved with a numeric distinct\_id (instead of ""). This value can safely be ignored.


# Server-Side Best Practices
Source: https://docs.mixpanel.com/docs/tracking-best-practices/server-side-best-practices



This document gives tips for implementing scalable, maintainable server-side tracking. If you're just getting started, check out the [quickstart](/docs/quickstart/connect-your-data).

## Tracking Browser, Device, and OS

Mixpanel's Web and Mobile SDKs parse `User-Agent` into a set of properties about the user's browser, device, and OS. This doesn't happen automatically with server-side tracking, but it's easy to add these properties yourself.

`User-Agent` is a header sent on all requests to your server. Most server frameworks provide a way to access your headers:

* [Django](https://docs.djangoproject.com/en/4.1/ref/request-response/#django.http.HttpRequest.headers) exposes this as `request.headers["User-Agent"]`.
* [Flask](https://flask.palletsprojects.com/en/2.2.x/api/#flask.Request.headers) exposes this as `request.headers["User-Agent"]`.
* [Go](https://pkg.go.dev/net/http#Request) exposes this in `Headers["User-Agent"]` on the http.Request struct.
* [Nginx](http://nginx.org/en/docs/http/ngx_http_log_module.html) exposes this as `$http_user_agent`.

Parse the user agent using a library for your language and send the browser, device, and OS properties to Mixpanel. Here's an example using Python and [uaparser](https://github.com/ua-parser/uap-python):

```python theme={"system"}
from mixpanel import Mixpanel
from ua_parser import user_agent_parser

mp = mixpanel.init("YOUR_TOKEN")

def track_to_mp(request, event_name, properties):
  parsed = user_agent_parser.Parse(request.headers["User-Agent"])

  # Set parsed values as properties.
  # You can also parse out the browser/device/os versions.
  properties.update({
    "$browser": parsed["user_agent"]["family"],
    "$device": parsed["device"]["family"],
    "$os": parsed["os"]["family"],
  })

  properties["ip"] = request.remote_addr
  mp.track(request.user_id, event_name, properties)

def handle_signup(request):
  # ... logic to process the signup ...

  track_to_mp(request, "Signed Up", {"Signup Type": request.form["type"]})

  return "Signup successful!"
```

## Tracking UTMs and Referrer

Mixpanel's Web SDK parses UTM parameters from the current URL and obtains referrer information from the browser's `document.referrer` property to enable easy marketing analytics. Since this is not automatic for server-side implementations, these properties will need to be added manually to tracked events. Below is an example in Python:

```python theme={"system"}
from urllib.parse import urlparse

from mixpanel import Mixpanel

mp = mixpanel.init("YOUR_TOKEN")

def track_to_mp(request, event_name, properties):

  # ... handle additional event properties such as $browser, $device, and $os ...

  if "Referrer" in request.headers:
    properties.update({
      "$referrer": request.headers["referrer"]
      "$referring_domain": urlparse(request.headers["Referrer"]).hostname
    })

  # assumes query parameters are available as Flask request.args dict
  utm_keys = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"]
  utm_values = {key: request.args[key] for key in utm_keys if request.args.get(key)}
  properties.update(utm_values)

  properties["ip"] = request.remote_addr
  mp.track(request.user_id, event_name, properties)
```

## Tracking Geolocation (Server-side)

By default, Mixpanel uses the IP address of the request to set geolocation properties. If you're tracking from your server, you need to override the IP property of your events and profile updates from your server's IP address to the client's IP address.

Read our full guide on [managing geolocation](/docs/tracking-best-practices/geolocation).

## Tracking Page Views

Page view tracking must be done manually for server-side implementations. Here are some general guidelines for tracking page views.

* Track page views as a single event type by using a constant `event_name`
* Track different pages as an event property and not as different events for better analysis
* Plan ahead for handling page views from anonymous users, identified users, and connecting them to merge a user's journey

  * Get started below with [Identifying Users](#identifying-users)
* Fire page view events only on successful responses to the client
* Parse headers and the request URL for common web analytics properties such as referrer and UTM parameters

  * See above for [parsing user agent](#tracking-browser-device-and-os) and [marketing attribution properties](#tracking-utms-and-referrer)

## Identifying Users

Mixpanel's server-side SDKs and HTTP API do not generate IDs automatically, meaning your server is responsible for generating IDs and maintaining ID persistence.

Read our full guide on [Server-side ID Management](/docs/tracking-methods/id-management/identifying-users-simplified#server-side-identity-management).


# Create A Tracking Plan
Source: https://docs.mixpanel.com/docs/tracking-best-practices/tracking-plan



<Note>
  Read the detailed [guide on creating a tracking plan](/guides/plan/tracking-strategy).
</Note>

## Overview

Mixpanel recommends creating a tracking plan based on the key business goals identified from your analytics strategy. It should:

* Be a centralized document that should serve as the source of truth on your Mixpanel implementation
* Define your business goals / KPIs and analytics strategy metrics
* Outline the events, event properties, and user profile properties aligned to your metrics
* Be treated as a living and shared document that is continuously updated with any implementation changes
* Include notes that are referenced across teams (product, marketing, data science, tech / dev teams, etc.)

This will be important for team members who are involved in defining use cases to be implemented in Mixpanel as well as, tech teams involved in the actual implementation of the codes.

## Tracking Plan Methodology

Be intentional with your data. Prioritize the most critical data you'll need based on your analytics strategy and KPIs, then iterate. Tracking everything and anything your user can do in your product can lead to unnecessary development effort and unused data.

### Define and prioritize KPIs

Define the top KPIs and metrics that will help measure success and inform decisions about your product.

### Map KPIs to User Flows

Map each KPI / metric to the steps or actions that users take to influence each KPI / metric. For example, sign up flow will be important when measuring KPIs related to new user acquisition. Consider also the different paths that users can take to achieve the same outcomes.

### Translate Flows into Events / Properties

Breakdown your user flows into events (actions) and properties (context of these actions) in your tracking plan. This will ensure that you have scoped out the data you need to achieve your KPIs / metrics in Mixpanel.

Mixpanel provides the following templates for vertical-specific tracking plans:

* [Retail and E-commerce](https://docs.google.com/spreadsheets/d/1Kyys37m_GEL79_1BKKEnU5KxK91NF04kY-L_bFfcfqE/#gid=1641519238)
* [Media and Entertainment](https://docs.google.com/spreadsheets/d/1K9t53kJJjaBG36kCIbZn_qKjXR9Iy306zYZAqDrv_AM/#gid=1641519238)
* [SaaS](https://docs.google.com/spreadsheets/d/1A5wm5MKzRfSOZfUfCAg8YpePiz8Jn3Ar_u8KBo5lD6g/#gid=1641519238)
* [Financial Services](https://docs.google.com/spreadsheets/d/1oGv6vbIFiYbima9IX4ItpBJvuChs-zzh83MRt_dSPgg/#gid=1641519238)

You can also access a copy of a [blank Tracking Plan from here](https://docs.google.com/spreadsheets/d/1ZdOZ6TMtRPxy7qRxiLsvH9HWcHJM6nZydWKoThRxFKc/edit#gid=1641519238). Save a copy to your device to get started on your tracking plan.


# Traffic Attribution
Source: https://docs.mixpanel.com/docs/tracking-best-practices/traffic-attribution

Analyze your marketing channels

## Web Attribution

When setting up your Mixpanel implementation, one issue of particular interest is tracking users by their original source of traffic. By default, Mixpanel does some of this tracking for you on the web in the form of several [default properties](/docs/data-structure/property-reference/default-properties).

### UTM Properties

Mixpanel's JavaScript library tracks all [UTM tags](/docs/tracking-methods/sdks/javascript#track-utm-tags) by default. This allows you to segment key actions by relevant campaign information using [attribution models](/docs/features/computed-properties#attribution), so that you can quantify the effectiveness of specific campaigns.

Mixpanel's JavaScript library will also track initial\_utm\_parameters as a profile property, based on the first-ever visit. This is helpful because knowing which acquisition channel originally brought a user to your site allows you to attribute purchases or other key events accurately.

* utm\_source: source where traffic is coming from, including a website or advertiser
* utm\_medium: advertising medium, including email and banner ads
* utm\_campaign: campaign name associated with the traffic
* utm\_content: specific link within an ad that a user clicked
* utm\_term: keywords associated with campaigns
* utm\_id / utm\_campaign\_id: unique identifier of a campaign
* utm\_source\_platform: marketing platform responsible for directing traffic
* utm\_creative\_format: a type of ad creative, for example: display, native, video, search
* utm\_marketing\_tactic: targeting criteria applied to a campaign, for example: remarketing, prospecting
* Initial UTM: tracks the first time a user reaches any of the above parameters

UTM parameters are by default persisted across events as [Super Properties](/docs/tracking-methods/sdks/javascript#setting-super-properties). To opt in to the recommended modern behavior most compatible with our [attribution models](/docs/features/computed-properties#attribution), use the SDK initialization option `{stop_utm_persistence: true}` to disable UTM param persistence (refer to our [Release Notes](https://github.com/mixpanel/mixpanel-js/releases/tag/v2.52.0) in GitHub).

#### Organic Traffic

If a user arrives at your landing page organically, no UTM tags will be parsed because the URL does not contain them. As a result, the UTM property will be absent from the events and will appear as "(not set)" when used as a breakdown in a report. You can interpret a "(not set)" value for any UTM property as indicating organic or direct traffic.

Learn more about falsy values [here](/docs/data-structure/property-reference/data-type#undefined-and-null).

### Initial Referrer and Initial Referring Domain Properties

Mixpanel's JavaScript library will track Initial Referrer and Initial Referring Domain and append them as a property to any event that a user completes. These properties are stored in the Mixpanel cookie the first time a user comes to your site and will not change on future site visits as long as the cookie is not cleared.

If a user comes to your site from [www.google.com](http://www.google.com) for the first time, for example, then the initial referring domain is equal to [www.google.com](http://www.google.com) and the initial referrer is the URL that they first came from. This information will be stored in the Mixpanel cookie and sent with all future events.

Having this information allows you to build reports to see how users from different initial referrers convert through an application.

#### \$direct

An initial referrer is equal to `$direct` when a user first lands on a site without being referred by another website. The user may have typed the website address directly, clicked a bookmark, clicked a link from an email, or might have security settings in their browser that prevent referrer data from being passed.

## Mobile Attribution

Mobile attribution, or tracking campaign sources for app installs/uninstalls/downloads on mobile devices, can be more complex than the web due to the way mobile devices store attribution information.

For Android, Google provides a [Play Install Referrer Library](https://developer.android.com/google/play/installreferrer/library) so you know where your installations came from. You can use the [getInstallReferrer ( )](https://developer.android.com/reference/com/android/installreferrer/api/ReferrerDetails#getinstallreferrer) method to retrieve the referrer URL string, parse it, and send that data to Mixpanel as properties in events.

For iOS, users enter the Apple App Store carrying data about where they came from, but the App Store strips that data once the user arrives in the store. Therefore, users who download your application don’t come with any data showing where they were before arriving at the App Store.

To track channel attribution on iOS, you'll need to use a [mobile attribution tool](/docs/tracking-methods/integrations/mobile-attribution-tracking). You can see a list of the partners we integrate with on our [tech partners page](https://mixpanel.com/partners/integrations?categories=attribution-deep-linking).

## Server-Side Attribution

Unlike web tracking, server-side implementations generally don't have access to global contexts or variables that can provide attribution data. This means these data, such as UTM parameters and referrer information, need to be extracted manually from the request. Below is an example of how this can be done using Python:

```python theme={"system"}
from urllib.parse import urlparse

from mixpanel import Mixpanel

mp = mixpanel.init("YOUR_TOKEN")

def track_to_mp(request, event_name, properties):

  # ... handle additional event properties such as $browser, $device, and $os ...

  if "Referer" in request.headers:
    properties.update({
      "$referrer": request.headers["Referer"]
      "$referring_domain": urlparse(request.headers["Referer"]).hostname
    })

  # assumes query parameters are available as Flask request.args dict
  utm_keys = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term"]
  utm_values = {key: request.args[key] for key in utm_keys if request.args.get(key)}
  properties.update(utm_values)

  properties["ip"] = request.remote_addr
  mp.track(request.user_id, event_name, properties)
```


# Warehouse Best Practices
Source: https://docs.mixpanel.com/docs/tracking-best-practices/warehouse-best-practices



<Note>
  Warehouse Connector is a paid add-on available to organizations on a Growth or Enterprise plan. Learn more on our [pricing page](https://mixpanel.com/pricing/).
</Note>

In this page, we describe best practices for implementing [Warehouse Connectors](http://mixpanel.com/docs/tracking-methods/warehouse-connectors), which allow you to seamlessly integrate your existing data warehouse with Mixpanel's powerful analytics platform, unlocking deeper insights while maintaining your existing trusted data infrastructure and workflows.

## Hub & Spoke Data Governance Model

To provide a clean, trusted dataset for your analytics needs we recommend implementing a structured hub & spoke rollout method prior to importing your data. In an effort to maintain high quality, trusted events and properties optimized for self-serve metrics, a central hub team will own core strategy and defined rollout rules, and the spoke teams operate within their verticals to define the metrics they care most about, owning the socialization and standardization of key reports and dashboards.

### Central Hub Responsibilities

Appoint a hub data governance owner who is in charge of enforcing data validation rules, reviewing event transformations before import, and monitoring quality standards.

* Responsible for: approving new data requests, enforcing naming conventions, requirements on any global property values, designating a canonical identifier for users, what constitutes as PII, and data retention, etc.

### Spoke Team Responsibilities

Designate spoke data governance owners for each underlying team that contributes data to Mixpanel. These spoke owners must regularly collaborate with the hub data governance owner to ensure alignment with data governance policies and best practices.

* Responsible for: logging new data requests, defining the business need behind the data request, driving ongoing enablement & adoption on their teams data, etc.

## Phased Implementation Approach

Always start by importing a smaller time period of data for quality assurance testing. Ensure the spoke data governance owner signs off, confirming that their team can access the insights they need before proceeding with the full dataset import.

## Change Management Process

Ongoing Change Management: All changes to data tables must be documented. The hub data governance owner is required to record the rationale behind changes and inform the relevant stakeholders.

* We've seen success with distributed teams using a [data request template](https://docs.google.com/spreadsheets/d/1Bx0LpGi5JoyWVCLU3UlmEBpvy09wFrLNH1HWHPnTe6A/edit?gid=0#gid=0) to organize the urgency and need for new data sets that need to be brought in.

## Learn More

For more information about warehouse connectors, check out these resources:

* [Warehouse Connectors Help Docs](http://mixpanel.com/docs/tracking-methods/warehouse-connectors)
* [Warehouse Billing FAQ](http://mixpanel.com/docs/tracking-methods/warehouse-connectors#billing-faq)
* [General Warehouse FAQ](http://mixpanel.com/docs/tracking-methods/warehouse-connectors#faq)


# Tracking Methods
Source: https://docs.mixpanel.com/docs/tracking-methods



Take a look at any of these pages for more information about our tracking methods.

<CardGroup>
  <Card title="Choosing the Right Method" href="/docs/tracking-methods/choosing-the-right-method" />

  <Card title="List of Supported SDKs" href="/docs/tracking-methods/sdks" />

  <Card title="Data Warehouse" href="/docs/tracking-methods/warehouse-connectors" />

  <Card title="List of Integrations with Tracking" href="/docs/tracking-methods/integrations" />

  <Card title="All about Identity Management" href="/docs/tracking-methods/id-management" />
</CardGroup>


# Autocapture
Source: https://docs.mixpanel.com/docs/tracking-methods/autocapture



## What is Autocapture?

Autocapture allows you to capture information about your website with minimal setup. Once enabled via SDK, Autocapture automatically captures frontend events like page views, button clicks, and form interactions.

## Availability

Autocapture is available on all plans. Autocapture is currently available for web only via Mixpanel’s [JavaScript SDK](/docs/tracking-methods/sdks/javascript). To turn it on, ensure you have the config `{autocapture: true}` set in the SDK.

## Autocapture events

By default, Autocapture will automatically collect the following predefined events with minimal engineering:

* Pageviews
* Page scrolls
* Form interactions (e.g., form submitted)
* Element interactions, including clicks and changes on page elements
* Attribution
* Dead clicks
* Rage clicks

When you enable Autocapture, you will start collecting these predefined events and property types, and they will appear for your use in analysis in your Mixpanel instance. Within your Mixpanel instance, these events will be displayed using preset labels such as “\[Auto] Page View” and “\[Auto] Element Click”.

Autocapture events will all be tracked as events that start with `$mp_`  and will start with \[Auto] as a prefix in Mixpanel, so if used in combination with other tracking and ingestion methods, you will be able to tell the difference.

### Dead Clicks

A dead click is when a user clicks an interactive element, but the click produces no visible response within a certain timeframe. Dead clicks often indicate broken functionality, unresponsive UI elements, or poor user experience. Dead clicks are tracked as `[Auto] Dead Click` events.

By default, Mixpanel considers a click on an interactive element to be a dead click if no responses are within 0.5 seconds. You can configure these qualifying criteria to something that best suits your application by overriding the defaults in the [Javascript SDK](/docs/tracking-methods/sdks/javascript).

### Rage Clicks

A rage click is when a user clicks on the same spot on your webpage in quick succession. It happens because the user expects something to happen, but nothing does, so they click again and again, showing they are frustrated. Rage clicks are tracked as `[Auto] Rage Click` events.

By default, Mixpanel considers 4 clicks within a second and between 30 pixels apart as a rage click. You can configure these qualifying criteria to something that best suits your application by overriding the defaults in the [Javascript SDK](/docs/tracking-methods/sdks/javascript).

## Autocapture vs Precision Tracking

There are two ways to capture events:

* Autocapture allows you to automatically collect a predefined set of events and properties. It is the best option for getting started quickly.
* Precision tracking allows you to instrument events and properties specific to your business needs and desired analyses. This is the best option when you want to perform deeper and more customized analyses.

Autocapture can coexist with more precise tracking — you can both enable Autocapture and instrument-specific events. You don’t have to choose one solution over the other.

## Configuring Autocapture

If you subscribe to automatic SDK updates, please note that these updates will not change your Autocapture configuration.

<Note>
  Before permanently implementing Autocapture, we recommend thoroughly testing the feature in a sandbox project to evaluate its impact on your data consumption and confirm that it meets your use case.
</Note>

Customers adding the JavaScript SDK with a snippet that contains an enabled autocapture config will turn on autocapture. **If this config is not present in the snippet, Autocapture will not be enabled.** Our documentation on how to configure the JavaScript SDK, including changing your Autocapture configuration, can be found [here](/docs/tracking-methods/sdks/javascript).

### Disabling Autocapture

You can disable Autocapture by setting the config in the JavaScript SDK. Disabling Autocapture does not disable session recording, which is [configured separately](/docs/tracking-methods/sdks/javascript#session-replay) in the JavaScript SDK. Learn more about detailed configuration [here](/docs/tracking-methods/sdks/javascript).

### Manage your event volume

Mixpanel recommends monitoring your event volume (in Organization Settings > Plan Details & Billing) as you make changes to ensure it matches your expectations.

At any time, you can change your configuration to only capture clicks on specified elements (or elements with certain classes), track on specific pages, or turn click tracking off while still taking advantage of other Autocapture data (pageviews, submits, etc.). Learn more about detailed configuration [here](/docs/tracking-methods/sdks/javascript).

## Privacy and security

The default configuration of Autocapture is designed to strike a balance between automatically capturing meaningful events while excluding potentially sensitive data. At the same time, the technical design of your website, your industry, the purpose of your website, and compliance requirements across jurisdictions can vary greatly. As a result, your close review of the data derived from Autocapture is always recommended. **Because there is no one-size-fits-all approach to event analytics, it's our customers' responsibility to ensure the configuration of Mixpanel on their website complies with applicable data privacy laws and regulations and their Mixpanel Services Agreement.**

In certain contexts, a flexible configuration of Autocapture or turning off Autocapture may be appropriate to enable your company's privacy and compliance requirements. **In particular, if the purpose of your website involves the capture of highly sensitive data like Protected Health Information (PHI), we do not recommend using Autocapture. If you have entered into a BAA (Business Associate Agreement) with Mixpanel, we do not recommend using Autocapture.**

As an analytics provider, Mixpanel is committed to designing features to facilitate data privacy for our customers and their end-users.  While it's our customers' responsibility to ensure use of Mixpanel complies with data privacy law, we offer a privacy-first approach to autocapture, including default omission of input elements, designed to help you complete data minimization and comply with data privacy law. We’ve additionally provided you with the following tools and resources to help you adhere to applicable data privacy legislation.

### Default protections

Autocapture's default settings also include the following privacy and security considerations:

* Sensitive elements — such as end-user text inputs, selects, and textarea elements - are default-excluded from tracking. You can view our default configurations and options [here](/docs/tracking-methods/sdks/javascript).
* By default, Autocapture will not collect sensitive input fields like passwords or form fields — it will only capture a limited set of HTML attributes like class, name, aria-label, role, title, and type attribute values. No content populated by an end user will be collected.
* By default, Autocapture will not capture the text that your website or app displays (`textContent` and its children).
* Mixpanel also provides flexibility to define the class pages of your website for which you configure Autocapture by using `block_selectors` and `block_url_regexes`.

To change these default settings, you can customize what is collected through your [SDK configuration](/docs/tracking-methods/sdks/javascript).

### Additional privacy and security options

For any element on your website/web application you do not want to track, there are built-in selector options to omit it. You can add any element to the `.mp-no-track` class to omit it. You can also opt an individual element out of being included in any tracking (including the 'elements' prop of another target's event) using `.mp-sensitive`.

Alternatively, you can update your Autocapture configuration using different blocking options, including blocking tracking of certain classes or certain URLs. You can read more about this [here](/docs/tracking-methods/sdks/javascript).


# Choosing the Right Method
Source: https://docs.mixpanel.com/docs/tracking-methods/choosing-the-right-method



If you use our SDKs, there are two general approaches to track events: client-side and server-side. The approach you choose has implications on the quality and comprehensiveness of your data.

We recommend tracking everything you possibly can via your servers, and only supplementing that with client-side tracking when necessary.

Note: If you already track events via a CDP, Tag Manager, or via your DWH using something like Snowplow, you can route those events to Mixpanel with our native integrations. See the [Segment](https://segment.com/docs/connections/destinations/catalog/actions-mixpanel/), [Rudderstack](https://rudderstack.com/integration/mixpanel/), or [GTM](https://github.com/mixpanel/mixpanel-gtm-template#readme) docs for a walkthrough. We can also load data directly from data warehouses like [Snowflake](/docs/data-pipelines/integrations/snowflake) and [BigQuery](/docs/data-pipelines/integrations/bigquery).

<Frame>
  <img alt="client-side vs server-side" />
</Frame>

## Server-Side Tracking

In this method, you send events from your servers to Mixpanel. For example, when a user loads a web page, a request is made to your web application server. In the code that handles the request, you can create a "Page Loaded" event and send it to Mixpanel. You can use one of our server SDKs (eg: Python) or send events to our [HTTP API](/reference/track-event) directly. Please see [this article](/docs/best-practices/server-side-best-practices) on best practices for server-side tracking.

**Pros**

* Reliable, not susceptible to ad-blockers
* Data is consistent across platforms
* Easier to fix integration mistakes quickly

**Cons**

* Harder to track user interactions that only happen on the client
* Requires some custom code to track anonymous (non-logged in) users across requests

**Server-Side SDKs**

* [Python](/docs/tracking-methods/sdks/python)
* [Node.js](/docs/tracking-methods/sdks/nodejs)
* [PHP](/docs/tracking-methods/sdks/php)
* [Go](/docs/tracking-methods/sdks/go)
* [Java](/docs/tracking-methods/sdks/java)

## Client-Side Tracking

In this method, events are generated on the client device and sent to the Mixpanel API. There are two types of client-side tracking: web (Javascript) and mobile.

**Pros**

* Easy to track client-side actions and state
* Easy to track anonymous (non-logged in) user data

**Cons**

* Unreliable, due to ad-blockers. You may lose events for 30-50% of your users. You can resolve this by sending events through a proxy, but it requires a bit more effort
* Difficult to keep metrics consistent across web, iOS, and Android since each requires its own tracking
* Difficult to fix integration mistakes quickly (particularly on mobile applications)
* Tracking will diverge over time due to old mobile clients

**Client-Side SDKs**

* [Javascript](/docs/tracking-methods/sdks/javascript)
* [React Native](/docs/tracking-methods/sdks/react-native)
* [Android](/docs/tracking-methods/sdks/android)
* [Objective C](/docs/tracking-methods/sdks/ios)
* [Swift](/docs/tracking-methods/sdks/swift)
* [Flutter](/docs/tracking-methods/sdks/flutter)
* [Unity](/docs/tracking-methods/sdks/unity)

> Note: Mixpanel client-side SDK uses [/track API endpoint](/reference/track-event#limits) which by default only ingests events in the last 5 days.

### Client-Side Tracking via a Proxy

A proxy is helpful in a client-side web setting to [reduce the likelihood of ad-blockers impacting your tracking](https://www.youtube.com/watch?v=8Pv6tmRfqr8). Please see [this article](/docs/tracking-methods/sdks/javascript#tracking-via-proxy) on how to set up a proxy.


# Mixpanel Data Inspector
Source: https://docs.mixpanel.com/docs/tracking-methods/data-inspector



## Overview

The Mixpanel Data Inspector is a browser extension that provides real-time visibility into events being sent to Mixpanel from your web application. This tool helps developers and analysts validate tracking implementation, debug data issues, and ensure data quality during development and testing.

## Key Features

**View SDK Events**

* Monitor events sent from the Mixpanel SDK in real-time
* See events as they're transmitted to Mixpanel servers
* Track both successful and failed event calls

**JSON Payload Inspection**

* View complete JSON payload for each event
* Copy JSON payload to clipboard for analysis
* Examine event structure and data formatting

**Event and Property Search**

* Search through event payloads to find specific properties
* Filter away noisy events to find desired information efficiently
* Inspect registered super properties and other event metadata

## Installation

### Chrome Web Store

1. Visit the [Chrome Web Store](https://chromewebstore.google.com/detail/camknfenboildigjgpmhojlcnejppooh)
2. Search for "Mixpanel Data Inspector"
3. Click **Add to Chrome**
4. Confirm installation in the pop-up dialog

### Firefox Add-ons

1. Navigate to [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/mixpanel-data-inspector/)
2. Search for "Mixpanel Data Inspector"
3. Click **Add to Firefox**
4. Follow the installation prompts

## Usage

### Getting Started

1. **Install the extension** from your browser's extension store
2. **Navigate to your website** where Mixpanel tracking is implemented
3. **Open the extension** by clicking the Mixpanel icon in your browser toolbar
4. **Interact with your site** to trigger events and see them appear in real-time
5. **Debug continuously** by opening the extension as a devtool window on Chrome through Inspect Element

## Common Use Cases & Best Practices

### Implementation Validation

**Use Cases:**

* Verify events are being sent correctly from your Mixpanel SDK
* Check that all expected properties are included in event payloads
* Confirm event timing and sequencing

**Best Practices:**

* Keep the Data Inspector open while implementing new tracking
* Use the copy feature to document expected payload structures
* Search for critical properties to ensure consistent naming

### Debugging and Troubleshooting

**Use Cases:**

* Identify missing or malformed event properties
* Debug tracking issues before they reach production
* Validate A/B test or feature flag implementations

**Best Practices:**

* Start by checking if events appear in the extension
* Use JSON view to examine payload structure and values
* Search for specific properties that may be causing issues

### Quality Assurance & Testing

**Use Cases:**

* Examine complete event structure and nested properties
* Compare expected vs. actual event data
* Understand property naming conventions and values

**Best Practices:**

* Validate tracking across different user flows
* Copy and compare payloads between different test scenarios
* Use search to verify that required properties are present

### Property Discovery & Analysis

**Use Cases:**

* Search for specific properties across multiple events
* Copy JSON payloads for further analysis or documentation
* Identify inconsistencies in property implementation

**Best Practices:**

* Use search functionality to locate properties of interest quickly
* Copy payloads to share with team members or include in documentation
* Regularly review property naming and value consistency

***

## Troubleshooting

### Events Not Appearing

* **Verify SDK implementation:** Ensure Mixpanel SDK is properly installed and configured. See [JavaScript SDK documentation](/docs/tracking-methods/sdks/javascript) for installation methods.
* **Check browser console:** Look for JavaScript errors that might prevent tracking
* **Refresh the page:** Some events only fire during page initialization
* **Disable ad blockers:** Ad blockers may prevent events from being sent to Mixpanel servers

### Support

For technical support or feature requests:

* Report issues through your standard Mixpanel support channels
* Include browser version and extension version in reports
* Provide specific JSON payload examples when reporting data issues


# Identity Management Overview
Source: https://docs.mixpanel.com/docs/tracking-methods/id-management



<Note>
  Already familiar with the concept of identity management? Click [here](/docs/tracking-methods/id-management/identifying-users-simplified) for a detailed implementation guide for Mixpanel ID management.
</Note>

## Overview

Identity management is the process of assigning IDs and maintaining ID mappings to ensure data are attributed to your users accurately. Mixpanel uses the **Distinct ID** property to identify your users and determine their uniqueness.

## Distinct ID

Distinct ID is Mixpanel's identifier used to uniquely track a user in the system. Every event data and profile update sent to Mixpanel should have a distinct\_id property associated with it (except in the case of preventing [hot shards](/docs/debugging/distinct-id-limits)). The Distinct ID value tells Mixpanel which user to attach your events and profile property updates.

The purpose of Distinct ID is to provide a single, unified identifier for a user across devices and sessions. When two events have the same value of `distinct_id`, they are considered as being performed by one unique user. If the Distinct ID on two events are two different values, they will be considered as coming from two separate users.

<Warning>
  Note that the Distinct ID property is `distinct_id` for event payload, and `$distinct_id` for profile update payloads. Learn more about the [Import Events API](/reference/import-events) and [Engage API](/reference/profile-set).
</Warning>

### Role of Distinct ID in Mixpanel

Below are examples of Distinct ID's role in Mixpanel:

**Insights report** - Distinct IDs are used to determine uniqueness, which is crucial for aggregation methods like Uniques and Average per User.

**Funnels report** - Distinct IDs are used to follow a user through a conversion journey. If a user tracks events with inconsistent Distinct IDs between steps, they will be counted as a drop-off.

**User report** - Distinct IDs are used to index individual users. User Profiles with 2 different Distinct IDs from the same user would end up with 2 different profiles.

## Identity Management in Action

Let's walk through how identity management affects your implementation using an example flow. Imagine you have a product that can be accessed from a website and a mobile app:

### Without ID Management

<Frame>
  <img alt="no_id_management" />
</Frame>

1. A user accesses your product on the website through a computer. The Javascript SDK automatically generates a Distinct ID for them, with the value of `123`.
2. Later in the day, the same user accesses your product again, this time on their smartphone. The Android SDK automatically generates a Distinct ID for them, with the value of `ABC`.
3. This single user would appear as two separate users in your Mixpanel project; once for their access through the website, and another for their access through your app.

Without identity management, a user who accesses your product from multiple devices is incorrectly counted as two separate users.

### With ID Management

<Frame>
  <img alt="with_id_management" />
</Frame>

1. A user accesses your product on the website through a computer. The Javascript SDK automatically generates a Distinct ID for them, with the value of `123`.
2. When the user registers for an account, your implementation makes an identify call, using their login `charlie` as the User ID. This triggers an ID merge, resulting in an ID cluster containing both `charlie` and `123`, which will map to the same user in Mixpanel.
3. Later in the day, the same user accesses your product again, this time on their smartphone. The Android SDK automatically generates a Distinct ID for them, with the value of `ABC`.
4. When the user logs in to your product using the account they registered earlier, your implementation calls identify again using the same User ID. This triggers another merge, adding `ABC` to the existing ID cluster. Now `ABC`, `123`, and `charlie` are all in one cluster and map to one user in Mixpanel.

With identity management, a user who accesses your product from multiple devices is accurately resolved to a single user.

## Identity Merge APIs

<Warning>
  You cannot switch between the two APIs if your project already contains data in it.
</Warning>

Mixpanel supports 2 versions of the ID Merge API:

* Simplified ID Merge
* Original ID Merge.

Simplified ID Merge API is the default for new organizations created from April 2024. Although it is not directly possible to switch from Original ID Merge (for a project that already has data) to Simplified ID Merge, both APIs will remain supported.

### Switching Between Simplified and Original API

You can set the default Identity Merge API version for your projects in the Organization Settings:

<Frame>
  <img alt="Untitled" />
</Frame>

For new projects without any data in it, you can switch the Identity Merge API version for the project in the Project Settings:

<Frame>
  <img alt="Untitled" />
</Frame>

Once there are any data in your project, your Identity API version cannot be changed.

<Note>
  Learn more about migrating to Simplified API [here](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system).
</Note>

### Simplified vs Original API Key Differences

**Simplified API**

* Distinct IDs are determined using `$user_id`/`$device_id` in events.
* The `$user_id` is always set as the distinct\_id for the user.
* There is no limit on the number of `$device_id`s that can be merged into a single `$user_id`.
* Any IDs in the cluster can be used for ingestion.

**Original API**

* Distinct IDs are determined using the `$identify`, `$merge`, and `$create_alias` events.
* The distinct\_id is automatically determined by Mixpanel using one of the IDs in the cluster and is not user-configurable. Any IDs in the cluster can be used for ingestion.
* There is a limit of 500 IDs that can be merged into a single ID cluster.

### Third-Party Integration Support

Customer Data Platform (CDP) integrations may require some configuration to work the Simplified API:

* Segment works out of the box with both the Simplified and Original APIs with no special configurations.
* Rudderstack has a [connection setting](https://www.rudderstack.com/docs/destinations/streaming-destinations/mixpanel/#connection-settings) that should match the API version configured on your Mixpanel project.
* mParticle works out of the box with both the Original API, and the Simplified API; when using the Simplified API (for new projects) ensure the "Simplified ID Merge" option is checked in mParticle's connection details

Most other integrations are unaffected by this API change. These integrations are not involved in identity management, they send data to the ID they are given and will work the same way on the Simplified API as they do on the Original API.

#### ID Merge Not Enabled

If your project is not ID Merge enabled, please refer to [this documentation](https://github.com/mixpanel/docs-legacy/blob/main/legacy/aliases.md) for identity management using our legacy ID management version.


# Identifying Users (Simplified)
Source: https://docs.mixpanel.com/docs/tracking-methods/id-management/identifying-users-simplified



<div>
  <Warning>
    The information on this page is for projects on the **Simplified ID Merge API**. [Learn more here](/docs/tracking-methods/id-management/identifying-users-simplified#overview).
  </Warning>
</div>

## Overview

<Warning>
  **Check your project's ID management version**

  The information on this page is for projects using the **Simplified ID Merge API**. You can check your Identity Merge API by navigating to [your project settings](https://mixpanel.com/settings/project/id-management).

  For projects using Original ID Merge API, please refer to this documentation [here](/docs/tracking-methods/id-management/identifying-users-original).

  Learn more about the different ID Merge APIs [here](/docs/tracking-methods/id-management#identity-merge-apis).
</Warning>

Mixpanel supports stitching user behavior pre-login (eg: traffic from your website, docs, blog) and post-login (once the user has signed up). This helps answer questions like:

* What % of site visitors end up signing up?
* How much of my Purchase revenue can I attribute to a particular campaign?
* What is the conversion rate of reading a particular blog post -> signing up?

This system is called ID Merge. In this guide, we walk through how to identify users in projects using the **Simplified ID Merge API** and exactly how it works under the hood.

## Mechanism

The **Simplified ID Merge API** uses the `$device_id` and `$user_id` event properties to determine the `distinct_id` that is set for your events.

### distinct\_id

The `distinct_id` property (learn more [here](/docs/tracking-methods/id-management#distinct-id) ) is the identifier property that Mixpanel uses to determine the uniqueness of your users.

### \$device\_id

The `$device_id` event property is automatically generated by our client-side SDK and then attached to all of the user's events. All client-side events should contain a `$device_id`.

If an event contains a `$device_id` without a `$user_id`, the value of the `$device_id` will be set as the `distinct_id` for that event.

We can consider the `$device_id` as the anonymous ID for the user.

### \$user\_id

Calling `identify(<user_id>)` sets the `user_id` value passed to the identify function as the `$user_id` event property for the user's events moving forward.

If an event contains a `$user_id`, the value of the `$user_id` will be set as the `distinct_id` for that event.

**When a `$user_id` and `$device_id` are present in the same event for the first time, a mapping is created to merge the `$user_id` and `$device_id` values together, forming an identity cluster.** Any data sent with a `distinct_id` set to any of the values in an ID cluster will be attributed back to the same user in Mixpanel.

## Client-side Identity Management

If using our Web/Mobile SDKs or a CDP like Segment or Rudderstack, there are only 2 steps to identity management:

1. Call `.identify(<user_id>)` when a user signs up or logs in, passing in the user's known identifier (eg: their ID from your database).
2. Send at least one event after the `.identify()` call. This is necessary to get the `$user_id` and `$device_id` to merge. Learn more about [the merge mechanism above](/docs/tracking-methods/id-management/identifying-users-simplified#mechanism).
3. Call `.reset()` when a user logs out.

* Any events prior to calling `.identify()` are considered anonymous events. Mixpanel's SDKs will generate a `$device_id` to associate these events to the same anonymous user. By calling `.identify(<user_id>)` when a user signs up or logs in, you're telling Mixpanel that `$device_id` belongs to a known user with ID `user_id`.
* Under the hood, Mixpanel will stitch the event streams of those users together. This works even if a user has multiple anonymous sessions (eg: on desktop and mobile). As long as you always call `.identify` when the user logs in, all of that activity will be stitched together.
* Calling `.reset` will clear the local storage (which contains the `$user_id` and `$device_id`), and generate a new `$device_id` for the session. It is recommended to call `.reset` when a user logout or times out of an authenticated session to prevent the unintentional merging of multiple users sharing one device.

## Canonical Distinct ID

Once a user has been identified via the `.identify(user_id)` method, their `$device_id` prior to identification will be combined with the `$user_id` to form an identity cluster containing both IDs, as well as any other IDs previously merged with the `$user_id`. For projects using the Simplified ID Merge API, the canonical `distinct_id` is always set to the `$user_id`.

You can use any of the IDs in the cluster for ingestion, but only the canonical `distinct_id` can be used in queries and exports.

## Example User Flows

Let's walk through a few user flows where ID Merge is useful, and when to call `.identify()` and `.reset()` to use ID Merge properly.

### New User Signup

1. A user lands in your product on a new device and interacts with your product before signing up. Our SDK will assign the user a random `$device_id` and persist it. All events tracked at this point will send only a `$device_id`.

   | Event | \$device\_id | \$user\_id | distinct\_id (set by Mixpanel) | Notes |
   | ----- | ------------ | ---------- | ------------------------------ | ----- |
   | 1     | D1           |            | \$device:D1                    |       |
   | 2     | D1           |            | \$device:D1                    |       |
2. The user returns later and signs up for your product. You call `.identify(U1)`. All events sent after this point are tracked with both the original `$device_id` and the new `$user_id`. Mixpanel will retroactively set the `$user_id` on any prior events with the user’s `$device_id` so that both event streams are joined.

   | Event | \$device\_id | \$user\_id | distinct\_id (set by Mixpanel) | Notes                                              |
   | ----- | ------------ | ---------- | ------------------------------ | -------------------------------------------------- |
   | 1     | D1           |            | *~~\$device:D1~~* ⇒ **U1**     | Retroactively updated                              |
   | 2     | D1           |            | *~~\$device:D1~~* ⇒ **U1**     | Retroactively updated                              |
   | 3     | D1           | U1         | U1                             | Links D1 ⇒ U1, D1 and U1 are inside one ID cluster |

### Returning User

1. The user from the previous flow returns, but is on a new device and has not logged in yet.

   | Event | \$device\_id | \$user\_id | distinct\_id (set by Mixpanel) | Notes         |
   | ----- | ------------ | ---------- | ------------------------------ | ------------- |
   | 1     | D1           |            | *~~\$device:D1~~* ⇒ **U1**     |               |
   | 2     | D1           |            | *~~\$device:D1~~* ⇒ **U1**     |               |
   | 3     | D1           | U1         | U1                             | Links D1 ⇒ U1 |
   | 4     | D2           |            | \$device:D2                    | New device D2 |
   | 5     | D2           |            | \$device:D2                    |               |
2. The user logs in. Call `.identify(U1)` to tell us that the user on this device is the same `$user_id` we have seen before.

   | Event | \$device\_id | \$user\_id | distinct\_id (set by Mixpanel) | Notes                                                   |
   | ----- | ------------ | ---------- | ------------------------------ | ------------------------------------------------------- |
   | 1     | D1           |            | *~~\$device:D1~~* ⇒ **U1**     |                                                         |
   | 2     | D1           |            | *~~\$device:D1~~* ⇒ **U1**     |                                                         |
   | 3     | D1           | U1         | U1                             | Links D1 ⇒ U1                                           |
   | 4     | D2           |            | *~~\$device:D2~~* ⇒ **U1**     | Retroactively updated                                   |
   | 5     | D2           |            | *~~\$device:D2~~* ⇒ **U1**     | Retroactively updated                                   |
   | 6     | D2           | U1         | U1                             | Links D2 ⇒ U1, D1, D2, and U1 are inside one ID cluster |

### Multiple Users, One Device

1. A first user begins using a new device.

   | Event | \$device\_id | \$user\_id | distinct\_id (set by Mixpanel) | Notes |
   | ----- | ------------ | ---------- | ------------------------------ | ----- |
   | 1     | D1           |            | \$device:D1                    |       |
2. The user logs in. Call `.identify(U1)`, which links the `$device_id` to their `$user_id`.

   | Event | \$device\_id | \$user\_id | distinct\_id (set by Mixpanel) | Notes                                              |
   | ----- | ------------ | ---------- | ------------------------------ | -------------------------------------------------- |
   | 1     | D1           |            | *~~\$device:D1~~* ⇒ **U1**     | Retroactively updated                              |
   | 2     | D1           | U1         | U1                             | Links D1 ⇒ U1, D1 and U1 are inside one ID cluster |
3. The user logs out. At this point, you should call `.reset()`, or manually generate a new `$device_id` if you are managing it yourself. A new user shows up and tracks events using this new `$device_id`.

   | Event | \$device\_id | \$user\_id | distinct\_id (set by Mixpanel) | Notes                      |
   | ----- | ------------ | ---------- | ------------------------------ | -------------------------- |
   | 1     | D1           |            | *~~\$device:D1~~* ⇒ **U1**     |                            |
   | 2     | D1           | U1         | U1                             | Links D1 ⇒ U1              |
   | 3     | D2           |            | \$device:D2                    | Reset generated new ID: D2 |
   | 4     | D2           |            | \$device:D2                    |                            |
4. This new user (U2) now logs in. Call `.identify(U2)`.

   | Event | \$device\_id | \$user\_id | distinct\_id (set by Mixpanel) | Notes                                                   |
   | ----- | ------------ | ---------- | ------------------------------ | ------------------------------------------------------- |
   | 1     | D1           |            | *~~\$device:D1~~* ⇒ **U1**     |                                                         |
   | 2     | D1           | U1         | U1                             | Links D1 ⇒ U1                                           |
   | 3     | D2           |            | *~~\$device:D2~~* ⇒ **U2**     | Retroactively updated                                   |
   | 4     | D2           |            | *~~\$device:D2~~* ⇒ **U2**     | Retroactively updated                                   |
   | 5     | D2           | U2         | U2                             | Links D2 ⇒ U2, D1, D2, and U1 are inside one ID cluster |

## Server-side Identity Management

Our server libraries normally require that you specify the `distinct_id` value for each event. If you don't know the user's identity at the time the event is tracked, then they're an anonymous user.

When using our Web or Mobile SDKs, Mixpanel will automatically generate an `$device_id` that's local to that user's device, and set that value as the `distinct_id` for the event. This ID will persist on all events tracked by that user on that device, until you call `identify()` or `reset()`.

If you're tracking from servers, you'll need to generate and manage the IDs yourself. We recommend not setting the `distinct_id` directly; instead you should set the `$device_id` and `$user_id` and have our API determine the `distinct_id` for you.

### Step 1 - Generate an Anonymous ID

The key is to have an ID that is unique to each user and persists during that user's session. We recommend generating a UUID and storing that value in a cookie. All common server frameworks provide a simple way to set and retrieve cookies per request.

### Step 2 - Leverage Anonymous ID for anonymous events

Set the `$device_id` event property to the anonymous ID you generated. You do not need to set the `distinct_id` property since it will be assumed to `$device_id` if there is no `$user_id` present in the event.

### Step 3 - Set the Authenticated ID once users log in

Once the user logs in, you know their true ID, you should leverage the new ID for the user.

Set the `$user_id` property to the Authenticated ID and continue setting `$device_id` to the Anonymous ID generated in step 1, including both the `$user_id` and `$device_id` in your events moving forward.

If Mixpanel receives an event with both `$device_id` and `$user_id` set, it will merge the two IDs together. This is essential to track pre-login and post-login behavior accurately. The `distinct_id` will be assumed to the `$user_id`.

If you choose to manually define the `distinct_id` property, it should be the same value as the `$user_id`.

#### Example Python

Here's a pseudocode example using Django's cookies and authentication. It assumes the client is setting and sending cookies:

```python theme={"system"}
import uuid

def track_to_mp(request, event_name, properties):
  # This assumes you've previously set a cookie called "SESSION_ID" that is local to the user's session
  # Set `$device_id` to that cookie's value
  properties["$device_id"] = request.cookies.get('SESSION_ID')

  # Set $user_id if the user is authenticated (logged in).
  if request.user.is_authenticated():
    properties["$user_id"] = request.user.username

  # Note: leave the first argument blank here, since we're passing $device_id and $user_id as properties.
  mp.track("", event_name, properties)
```

## Best Practices

**Call `.identify` upon a registration/login or when an app is re-opened in a logged-in state**

By calling `.identify()` at these specific points in user journeys, you would be able to link the pre and post-login events to the same user on Mixpanel. Besides, calling `.identify` when the users re-open the app in a logged-in state ensures that all events in the session are tracked with the user's identifier such as user id.

**Call `.reset` upon logout or when an app leaves an authenticated-state**

By calling `.reset()` at logout or when a user enters an unauthenticated-state (such as timing out), you generate a new `$device_id` for your user, ensuring that multiple users that are sharing a single device would not be incorrect considered as a single user tracking events with the same IDs.

**Track the unique identifier as a super property and user property to assist in troubleshooting**

You can track the user's unique identifier as a super property via `.register()` and user property via `.people.set()` as soon as it is available in the app i.e. on a successful sign-up / login or when an app is re-opened in a logged in state. In the cases when ID Merge is not implemented properly, you can rely on these properties for troubleshooting purposes.

See the SDK reference on [registering super properties](/docs/tracking-methods/sdks/javascript#super-properties) and [setting profile properties](/docs/tracking-methods/sdks/javascript#setting-profile-properties).

**Avoid creating profiles for anonymous users**

Avoid creating profiles for anonymous users. If possible, cache user profile properties update in cookie or local storage and only send them to Mixpanel after the user is identified (ie logged-in state).

**QA your ID management implementation during the development phase**

Here are a few things to look out for:

* Ensure that cross-platform, pre and post-registration events are linked to the same user on Mixpanel.
* Ensure that no duplicate profiles are created as the users go through the onboarding, registration, login, and cross-platform user journey.
* Ensure that all the user’s identifiers are stored in the same Identity Cluster and that all their events are displayed on a single profile on Mixpanel.

**Keep a record of your ID management implementation**

We encourage you to document your implementation (or create a diagram of the implementation). This will come in handy when you need to re-implement this on a new platform or troubleshoot ID management issue.

## FAQ

**What does Mixpanel recommend using as the `$user_id`?**

We recommend using an ID that is unique to each user and does not change, for example, a database ID. While using an identifier like email may be more convenient, keep in mind that you cannot merge 2 `$user_ids` or change a `$user_id`, so if the user changes their email, they will count as a separate user.

**How long does it take for the `$device_id` -> `$user_id` mapping to take effect?**

For debugging purposes, the Activity Feed view of a single user is updated in real-time (less than 1 minute delay). You can get to the Activity Feed by navigating to [Users](/docs/users) and selecting a given user.

It may take up to 24 hours for this mapping to propagate to all other parts of the system. This means that, in some cases, when analyzing a funnel that spans pre-login and post-login behavior in real-time, some may be shown as dropped-off, even though they've performed the conversion event.

**How does this relate to User Profiles?**

[User Profiles](/docs/data-structure/user-profiles) are set directly on `$distinct_id`s, not on `$user_id`s or `$device_id`s. We recommend waiting until after a user is identified before setting user profile properties.

It is possible to set user profile properties for unidentified users by sending the profile updates to `$distinct_id=$device:<device-id>`. However, user profile properties are not preserved when `$device_id`s are linked to `$user_id`s, so any properties set before the IDs became linked will need to be set again using `$distinct_id=<user-id>` once the user is identified.

**Is it possible to merge two `$user_id`s?**

It is not possible to merge 2 `$user_id`s together using the Simplified API. We don't recommend doing this in general, as it adds complexity to your identity resolution strategy. Instead, we recommend having a single, unchanging `$user_id` for each user and pointing all other IDs for that user to that single `$user_id`.

**How should I link identified IDs from 3rd-party systems?**

Attribution providers (like Appsflyer, Adjust, and Branch) use Mixpanel's SDK properly to set `$device_id` to whichever ID they use for attribution.

For cohort syncs out to 3rd-party systems, we recommend designating a user property with the identifier of the user in that third-party system. More details are in our [integrations docs](/docs/cohort-sync/integrations); for example, see our [doc on exporting cohorts to Braze](/docs/cohort-sync/integrations/braze#matching-mixpanel-and-braze-users). If those integrations are bidirectional (eg: they send events back to Mixpanel), it's best to ensure that the user ID in both Mixpanel and the 3rd-party system is the same so that those events are sent to the correct user.

**What is the status of Mixpanel's legacy `alias` method?**

Prior to March 2020, the only way to connect users together was the `.alias()` method. This was very limited and was not retroactive; this meant that if a user used two devices and then logged in, you would lose activity for the user from one of the devices.

If you set up Mixpanel prior to 2020, you may have implemented using the `.alias()` method. Alias is still supported in its original state and we have preserved its documentation [here](https://github.com/mixpanel/docs-legacy/blob/main/legacy/aliases.md), but if you want to revisit your identity management strategy, we recommend setting up a new Mixpanel project and using the best practices outlined in this guide.


# Migrating to Simplified ID Merge
Source: https://docs.mixpanel.com/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system



## Overview

Mixpanel currently has three versions of ID management:

* Prior to March 2020, we only had 1 version that merges a user's very first anonymous state to the identified state (typically on sign-up when a User ID is created).  We will refer to this as **Legacy ID Management** (or Legacy for short).
* In March 2020, we released **Original ID Merge** (formerly known as just "ID Merge"), which supports retroactive identity merging, enabling the merging of multiple anonymous states to an identified state across multiple devices and platforms.
* In March 2023, we released **Simplified ID Merge** to remove the complexities of having to rely on different [identity methods](/reference/create-identity) (i.e. \$identify, \$create\_alias, \$merge) for different merging scenarios. This also removed the need to cap Distinct IDs at 500 in an ID cluster.

To determine your current ID Management version, navigate to <b>Identity Merge</b> setting under your [Organization Settings](https://mixpanel.com/settings/org/id-management) (for Organization Owners/Admins) or [Project Settings](https://mixpanel.com/settings/project/id-management) (for Project Owners/Admins).

The Organization Settings for Identity Merge determines the default identity management for every new project created:

* **Disabled**: Legacy ID Management
* **Original API**: Original ID Merge
* **Simplified API**: Simplified ID Merge

<Frame>
  <img alt="image" />
</Frame>

<br />

You can change the identity management version for a specific project (without affecting other projects) via Project Settings, provided no data has been ingested into the project. For new projects, we recommend setting the Simplified ID Merge (<b>Simplified API</b>) option as it is a generally more straightforward, simpler way of managing your users' identity in Mixpanel.

<Frame>
  <img alt="image" />
</Frame>

## Deciding to Migrate

It is currently not possible to automatically convert an existing project, already populated with data, from Legacy or Original ID Merge to Simplified ID Merge. This is because Simplified ID Merge has a very different backend architecture. <b>To adopt Simplified ID Merge, you would need to set up a new empty Mixpanel project</b>.

This guide assists you in evaluating whether a migration to Simplified ID Merge will benefit your tracking based on your current identity management requirements and future product plans. We'll outline the pros and cons of each ID Management version and guide you through key considerations to make an informed decision. We'll also provide details on the resources required on your end should you decide to proceed with the migration.

### On Legacy ID Management

The main limitation of Legacy ID Management was that anonymous user states could become orphaned. This happens when an anonymous user was initially tracked on one platform or device, signs up as a user, and later on moved to another platform or device, triggering various anonymous events before logging in. The anonymous events on the second platform would be orphaned, resulting in duplicated users on Mixpanel.

Aliasing on Legacy ID Management can only be done once. Once a User ID is aliased to an Anonymous ID (typically on the 1st device where they started using your product), subsequent attempts to alias the same User ID to a different Anonymous ID (generated from a different platform or device) will fail. Here’s a diagram illustrating how a typical user journey on different devices ends up creating an orphaned user.

<Frame>
  <img alt="image" />
</Frame>

<br />

The lack of a retroactive identity merging feature means that orphaned users are created whenever new Anonymous IDs are introduced during user interactions across multiple sessions, devices, and platforms. This prevents you from getting a holistic view of the user's journey.

> <b>Staying on Legacy ID Management</b> <br /> Note: If you are only tracking authenticated users (i.e. don't track events while the user is anonymous), you don't need the retroactive identity merging feature in Simplified ID Merge and should not consider the migration. We have preserved the documentation on the Legacy ID Management [here](https://github.com/mixpanel/docs-legacy/blob/main/legacy/aliases.md).

### On Original ID Merge

While retroactive identity merging is supported on Original ID Merge, the main limitation is that each user's ID cluster is limited to a maximum of 500 Distinct IDs. Upon reaching this limit, any new Distinct ID can no longer be merged into the same ID cluster. They will then become orphaned (duplicate users on Mixpanel), preventing you from getting a holistic view of the user's journey.

Reaching the 500 Distinct IDs per ID cluster limit is possible when the process of generating new Anonymous IDs through the `reset()` call on logout, and adding them to the ID cluster repeats 500 times. The `reset()` call is typically implemented in products where multiple users are sharing the same device. This ensures that anonymous events post logout are linked to the next user who logins in, rather than the last user who logout. If some of your users are approaching this cluster limit, you should revisit your implementation and consider removing the `reset()` call, unless there is a compelling use case where the benefits outweigh the implications of reaching the ID cluster limit.

Also, if you are considering Simplified ID Merge, it's important to note that it does not support multiple identified IDs (i.e. User IDs) per ID cluster. This is supported on Original ID Merge via special events such as \$merge and \$create\_alias but they are not supported on Simplified ID Merge as the approach to identity management is completely different, more details [here](/docs/tracking-methods/id-management/identifying-users-simplified#example-user-flows).

> <b>Staying on Original ID Merge</b>
>
> * If you don’t generally support multiple users sharing the same device, and don’t have a compelling use case requiring `reset()` calls on logout (or if you are implementing via server-side and do not generate new anonymous IDs for the same user), you are unlikely to run into the limit of 500 IDs per ID cluster, and should not consider the migration.
> * You have ID management requirements that are not supported in Simplified ID Merge (e.g. the need to support multiple identified IDs per user)

## Understanding Simplified ID Merge

Unlike Legacy ID Management, which requires an explicit alias call to connect anonymous to identified state, or Original ID Merge, which requires special identity events (i.e. \$identify, \$create\_alias, and \$merge) to initiate identity merging; <b>Simplified ID Merge only requires including reserved event properties `$device_id` and `$user_id` on the events for identity merging to take place</b>. You can learn more about Simplified ID Merge [here](/docs/tracking-methods/id-management/identifying-users). Here’s a quick example to illustrate:

1. When a user is anonymous, the events should include a `$device_id` property that stores the Anonymous ID.

```json theme={"system"}
{
  "event": "View Anonymous Page",
  "properties": {
    "token": "{{token}}",
    "$device_id": "anonymous111" 		
  }
}
```

2. As soon as the user is identified (i.e. logged in), the events should include both `$device_id` (user's Anonymous ID) and `$user_id` (user's User ID) properties. A single instance of such event is adequate to trigger identity merging which merges “anonymous111” and “charlie”. Subsequent events can continue to have the same `$device_id` and `$user_id` properties or minimally just the `$user_id` property.

```json theme={"system"}
{
  "event": "Sign Up",
  "properties": {
    "token": "{{token}}",
    "$device_id": "anonymous111", 
    "$user_id": "charlie"
  }
}
```

3. Upon user logging out, you can generate a new Anonymous ID for `$device_id` to temporarily store the anonymous events, and then later merge them with the next user who logs in (could be the same user, or a different user sharing the same device). Unlike Original ID Merge, Simplified ID Merge does not have a limit on the number of identifiers allowed in an ID cluster.

```json theme={"system"}
//after user logout 
{
  "event": "View Anonymous Page",
  "properties": {
    "token": "{{token}}",
    "$device_id": "anonymous222"		
  }
}
```

4. Upon user (re)identification, send events containing both the `$device_id` and `$user_id` properties to trigger identity merging.

```json theme={"system"}
//same user 
{
  "event": "Sign In",
  "properties": {
    "token": "{{token}}",
    "$device_id": "anonymous222", 
    "$user_id": "charlie"
  }
}
```

```json theme={"system"}
//different user sharing the same device 
{
  "event": "Sign In",
  "properties": {
    "token": "{{token}}",
    "$device_id": "anonymous222", 
    "$user_id": "taylor"
  }
}
```

Simplified ID Merge can retroactively merge an unlimited number of anonymous IDs (`$device_id`) to a user (`$user_id`). This ensures that anonymous events across multiple platforms, devices, or sessions can always be merged to the respective user. The implementation above results in the following ID cluster if **charlie** is the one who re-logged in.

<Frame>
  <img alt="image" />
</Frame>

* Any ID provided as `$device_id` will be prefixed with `$device:` in the ID cluster.
* You can merge unlimited number of `$device_id` into a `$user_id`
* `distinct_id` is optional on events because Mixpanel automatically updates or overrides it whenever `$user_id` or `$device_id` is present on the events. It takes the value of `$user_id` if present; otherwise, it takes `$device_id` and prefixes it with `$device:`

<br />

<b>Example 1:</b>

```json theme={"system"}
//Triggered event 
{
  "event": "Sign Up",
  "properties": {
    "token": "{{token}}",
    "$device_id": "anonymous111", 
    "$user_id": "charlie"
  }
}
```

```json theme={"system"}
//distinct_id set by Mixpanel 
{
  "event": "Sign Up",
  "properties": {
    "token": "{{token}}",
    "$device_id": "anonymous111", 
    "$user_id": "charlie",
    "distinct_id": "charlie"
  }
}
```

<b>Example 2:</b>

```json theme={"system"}
//Triggered event 
{
  "event": "View Anonymous Page",
  "properties": {
    "token": "{{token}}",
    "$device_id": "anonymous111" 		
  }
}
```

```json theme={"system"}
//distinct_id set by Mixpanel 
{
  "event": "View Anonymous Page",
  "properties": {
    "token": "{{token}}",
    "$device_id": "anonymous111", 		
    "distinct_id": "$device:anonymous111"
  }
}
```

## Considerations when Migrating

Take note of the following details when planning for the migration from Legacy ID Management or Original ID Merge to Simplified ID Merge:

1. Simplified ID Merge supports only one User ID (`$user_id`) per ID cluster, and this User ID will serve as the user's canonical Distinct ID. If you need an ID management solution that supports multiple User IDs per user, such as both a email address and a phone number, it’s recommended to remain on Legacy ID Management or Original ID Merge which provide methods such as \$create\_alias or \$merge to merge multiple User IDs.

   * For example, here’s an attempt to merge `+6512345678` (additional User ID) with `charlie` on Simplified ID Merge:

   ```json theme={"system"}
   {
     "event": "Add phone number as user ID",
     "properties": {
       "token": "{{token}}",
       "$device_id": "+6512345678", 
       "$user_id": "charlie"
     }
   }
   ```

   * This results to phone number `+6512345678` being treated as one of the Anonymous IDs and prefixed with `$device:`. As such, if you subsequently send events with `$user_id` as `+6512345678` it will not be associated to `charlie` and would result to creating a completely different new ID cluster where `+6512345678` is the main User ID.

     <Frame>
       <img alt="image" />
     </Frame>

     <br />
2. If you are sending events via third-party integrations, ensure that they are compatible with Simplified ID Merge by having reserved properties, `$device_id` and `$user_id` on the events.

   For backward compatibility, Simplified ID Merge still supports events that are only sent with `distinct_id` property (i.e. no `$device_id` and `$user_id` properties):

   * `distinct_id` values prefixed with a `$device:` will be used as `$device_id`, while
   * `distinct_id` values without the `$device:` prefix will be used as `$user_id`

   Ensure that the `distinct_id` value of an anonymous user's events are always prefixed with `$device:` if this approach is used.

   <br />

   <b>Example 1:</b>

   ```json theme={"system"}
   //Triggered event 
   {
       "event": "Message Sent",
       "properties": {
           "token": "{{token}}",
           "distinct_id": "charlie"
       }
   }    
   ```

   ```json theme={"system"}
   //$user_id is set by Mixpanel 
   {
       "event": "Message Sent",
       "properties": {
           "token": "{{token}}",
           "distinct_id": "charlie", 
           "$user_id": "charlie"
       }
   }
   ```

   <b>Example 2:</b>

   ```json theme={"system"}
   //Triggered event 
   {
       "event": "App Install",
       "properties": {
           "token": "{{token}}",
           "distinct_id": "$device:anonymous111"
       }
   }        
   ```

   ```json theme={"system"}
   //$device_id is set by Mixpanel 
   {
       "event": "App Install",
       "properties": {
           "token": "{{token}}",
           "distinct_id": "$device:anonymous111",
           "$device_id": "anonymous111"
       }
   }
   ```
3. If you have Mixpanel in your mobile apps, you’ll need to ship a new version of the app with the updated ID management implementation, and the new project’s token as part of the migration process. Without a forced app update, it may take awhile for all users to upgrade to the latest app version. During this period, some events will still be tracked to the old project. Be prepared for data backfilling if you want these events, as well as the historical data to be included in the new project.
4. With the introduction of the retroactive identity merging feature in Original and Simplified ID Merge, it may take up to 24 hours for identity merging (merging 2 unique users into 1 unique user) to be fully reflected in all Mixpanel reports. More details [here](/docs/tracking-methods/id-management/identifying-users-simplified#faq).
5. All Mixpanel [Client-Side SDKs](/docs/tracking-methods/choosing-the-right-method#client-side-tracking) support Simplified ID Merge except for [Unity SDK](/docs/tracking-methods/sdks/unity).

## Migrating to Simplified ID Merge

The following guide outlines the steps required to set up the new Mixpanel project and populate it with data compatible with Simplified ID Merge. This will help you estimate the time and resources required on your end to complete the migration.

### Set Up a New Mixpanel Project

> <b>Note: You need to set up a new Mixpanel project and enable Simplified ID Merge as none of the configurations from any existing project(s) can be carried over.</b>

1. Create a new Mixpanel project in your existing organization by navigating to <b>Projects</b> setting under [Organization Settings](https://mixpanel.com/settings/org/projects). You can refer to [Creating Projects](/docs/orgs-and-projects/managing-projects#creating-projects) section in our documentation.
2. Enable <b>Simplified API</b> in the new project by navigating to <b>Identity Merge</b> setting under this new Project's Settings. Refer to [this](/docs/tracking-methods/id-management#switching-between-simplified-and-original-api) section in our documentation.

   Please note that the new project follows the organization’s default (Legacy or Original ID Merge). You have to switch the project to Simplified ID Merge <b><i>before</i></b> sending any data to the project. Make sure to override the default selection in every newly created project.

<Frame>
  <img alt="image" />
</Frame>

3. Continue to set up the new project by following the guide [here](/docs/best-practices/project-setup). Configure the new project's settings by referring to your existing project’s settings. Some of the setup tasks may include:

   * [Inviting users](/docs/orgs-and-projects/roles-and-permissions#invite-users-to-a-project) to the project and granting them [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions#permissions)
   * Creating [Teams](/docs/orgs-and-projects/roles-and-permissions#teams) and adding users to them
   * Adding [group keys](/docs/data-structure/group-analytics#group-keys-in-project-settings) from Group Analytics
   * Creating [data views](/docs/data-governance/data-views-and-classification#create-data-view) and adding users or teams to them
   * Creating or granting [service accounts](/reference/service-accounts) access to this project
   * Configuring [session settings](/docs/features/sessions)

   Note that the new project comes with newly generated project token, API secret, and new sets of service account credentials (if you had created new service account in the new project). Replace the project token in your implementations with the new ones to start sending data to this new project. Ensure that any backend scripts using API secret or service accounts are updated as well.

### Populating Data into New Project

This process typically involves populating both the live data and historical data into the new project. Coming from Legacy or Original ID Merge, you will find that the implementation for Simplified ID Merge is generally more straightforward and robust. It’s important to review and modify your ID management implementation to get the expected result in terms of user identity merging.

#### Sending Live Data

Update your tech stack with the new project’s token, API secret, and service accounts credentials to redirect data to the new project.

1. Mixpanel <b>[Client-Side SDK](/docs/tracking-methods/choosing-the-right-method#client-side-tracking)</b> integration:

   * Upgrade to the latest SDK version supporting Simplified ID Merge and initialize the SDK with new project’s token:

     * [Javascript ≥ v2.46.0](https://github.com/mixpanel/mixpanel-js/releases/tag/v2.46.0)
     * [Android ≥ v7.3.0](https://github.com/mixpanel/mixpanel-android/releases/tag/v7.3.0)
     * [iOS (Objective-C) ≥ v5.0.2](https://github.com/mixpanel/mixpanel-iphone/releases/tag/v5.0.2)
     * [Swift ≥ v4.0.5](https://github.com/mixpanel/mixpanel-swift/releases/tag/v4.0.5)
     * [React Native ≥ v2.2.0](https://github.com/mixpanel/mixpanel-react-native/releases/tag/v2.2.0)
     * [Flutter ≥ v2.1.0](https://github.com/mixpanel/mixpanel-flutter/releases/tag/v2.1.0)

     <b>Note: Mixpanel [Unity](/docs/tracking-methods/sdks/unity) SDK currently does not support Simplified ID Merge.</b>
   * Refer to the implementation guide [here](/docs/tracking-methods/id-management/identifying-users-simplified#client-side-identity-management). You only need to call `identify` and `reset` methods at specific points in the user journeys as the SDK will automatically add the reserved properties `$device_id` and `$user_id` to the events before sending them to Mixpanel.
   * You should not call `alias`, as this method will not trigger identity merging in a Simplified ID Merge project. It is only provided as a backward-compatible solution for users who are on Legacy / Original ID Merge.

<br />

2. Mixpanel <b>API / [Server-Side SDK](/docs/tracking-methods/choosing-the-right-method#server-side-tracking)</b> integration:

   * If you are sending data from server via Mixpanel's [Import API](/reference/import-events), update the project token or service account to point to the new project.
   * You should not send \$identify, \$create\_alias, and \$merge events since they will be ignored in Simplified ID Merge projects and will not trigger identity merging.
   * Update your Import API payload to include `$device_id` and `$user_id` properties in the events. A single instance of such event is adequate to trigger identity merging. You can learn more about Simplified ID Merge in this [section](#understanding-simplified-id-merge).
   * If it's not feasible to include both `$device_id` and `$user_id` in events triggered typically from a user interacting with your product; you can still trigger identity merging by sending a dummy event that includes both `$device_id` and `$user_id` at the point when user is switching from anonymous to identified state. You can choose any name for the dummy event (e.g. login) except for \$identify, \$create\_alias, and \$merge.

<br />

3. <b>Customer Data Platform (CDP)</b> integration:

   * Ensure that your CDP is updated with new Mixpanel project token or API secret.
   * Check the CDP's support for Simplified ID Merge [here](/docs/tracking-methods/id-management#third-party-integration-support).

<br />

4. Other <b>3rd-party Platforms</b> integration:

   If you are sending events from 3rd-party platforms (i.e. attribution and messaging tools), make sure to update the Mixpanel project token (or API secret) and ensure that 3rd-party events sent to Mixpanel are compatible with Simplified ID Merge. Refer to this [section](/docs/tracking-methods/id-management/identifying-users#how-should-i-link-identified-ids-from-3rd-party-systems) for more information.

<br />

5. <b>Data Warehouse</b> integration:

   Consider using our [Mixpanel Warehouse Connector](/docs/tracking-methods/warehouse-connectors) which supports Simplified ID Merge. Make sure that events from the data warehouse contains information that can be mapped to the reserved properties `$device_id` and `$user_id` before setting up the connector in Mixpanel.

For mobile apps, adoption of the latest app version may take some time. This means that users who have upgraded to the latest app version will start sending data to the new project (with Simplified ID Merge), whereas users on the older apps will continue to send data to the old project. To capture the full data, consider migrating the residual data in the old project to the new one, and repeat the process until the app adoption reaches a satisfactory level. You can find additional information about backfilling and key considerations in the [next section](#backfilling-historical-data).

#### Backfilling Historical Data

> Note: This is an optional step. If your existing project did not have that much data and you don’t mind starting your analysis from scratch, you can skip this section on backfilling.

<br />

Before starting the backfilling process, it’s important to have a discussion internally to determine the volume of historical data that needs to be migrated. It’s advisable to migrate only what you need (i.e. recent data actively queried by the team) as this is more manageable and resource-efficient. Note that backfilling historical data can have significant impact on your billing. Refer to [this section](/docs/pricing#are-monthly-events-calculated-based-on-ingestion-time-or-event-timestamp) for more details.

* Mixpanel Client-Side SDKs, by default, use the /track API endpoint which accepts events up to 5 days old, so it is advisable to initiate the backfill process only after the data for a given day has stabilized to avoid the need for multiple backfills.
* If waiting data to stabilize is not feasible, consider using `mp_processing_time_ms` property (UTC timestamp of when the event was processed by our servers) to identify late-arriving events and selectively backfill them into the new project.
* To prevent data duplication caused by backfilling, ensure that each imported event includes a [`$insert_id`](/reference/import-events#propertiesinsert_id) which provides a unique identifier for the event and is used for deduplication.

<br />

Depending on where you data resides, there are different ways to backfill historical data into the new project:

1. <b>Mixpanel APIs</b> - if Mixpanel is your single source of truth, export data from the existing project using [Raw Export API](/reference/raw-event-export) and then import it into the new project via [Import API](/reference/import-events). Ensure that the data is compatible with Simplified ID Merge before importing it to Mixpanel.

   * You can use Engage API to migrate user data (APIs for both [user export](/reference/engage-query) and batched [user import](/reference/profile-batch-update) are available).
   * Consider incorporating the export and import functions from [Mixpanel-utils open source library](https://github.com/mixpanel/mixpanel-utils) in your migration script.
2. <b>Mixpanel Warehouse Connector</b> - if you’ve been storing your data in a data warehouse, you can import them into Mixpanel using [Warehouse Connector](/docs/tracking-methods/warehouse-connectors) which supports both events and user data.
3. <b>Customer Data Platform (CDP)</b> - replay the historical data from CDP to Mixpanel.

Please make sure that the historical data is properly formatted before backfilling it to a new project via any of the methods mentioned above. Familiarize yourself with the Simplified ID Merge implementation in this [section](#understanding-simplified-id-merge) to plan out the required data transformation tasks for your historical data.

If your historical events do not include both `$device_id` and `$user_id` that are required in Simplified ID Merge for identity merging, check if you can retrieve this ID mapping information from your system through other means. Instrument a dummy event that includes both `$device_id` and `$user_id` based on your ID mappings and send that to the new project to enable identity merging. You can choose any name for the dummy event except for \$identify, \$create\_alias, and \$merge.

##### Legacy ID Management

If you had implemented using Mixpanel Client-Side SDKs (except for Unity) and have been making alias calls to link Anonymous ID to User ID, the Client-Side SDKs should have already populated `$device_id` and `$user_id` on your events (please verify this in your existing Mixpanel project). These historical events can be directly imported into the new Simplified ID Merge project as they include reserved properties required for identity merging.

However, in the case of a custom implementation without the reserved properties `$device_id` and `$user_id` present on your events (e.g. server-side implementation), it’s necessary to transform these events before backfilling it to the new project. For example, you can derive the reserved properties from other relevant properties on the events or from ID mappings maintained in your system.

##### Original ID Merge

If you had implemented using Mixpanel Client-Side SDKs (except for Unity) and have been calling identify to merge pre and post-login states, the SDK should have already populated `$device_id` and `$user_id` on your events (please verify this in your existing Mixpanel project). These historical events can be directly imported into the new Simplified ID Merge project as they include reserved properties required for identity merging.

If you are also calling alias or merge (using special events, \$create\_alias or \$merge) to merge multiple user IDs per user, it's important to note that this functionality is not supported in Simplified ID Merge. Additional details can be found in this [section](#considerations-when-migrating).

#### Validating Identity Management

As you migrate your data (both live and historical) into the new Simplified ID Merge project, it's important to check if identity merging is working properly.

* Verify that users who are using your product across multiple platforms, devices, or sessions are being merged correctly and reserved properties `$user_id` and `$device_id` are being populated.
* Sample a couple of key users and compare their events and user profiles between existing and new project to check for any missing events / user profiles or events being merged to the wrong user.

#### Data Migration Approach

Discuss internally and decide on the best data migration approach with minimal interruption to the analysis activities on Mixpanel.

1. Test both live and historical backfilled data thoroughly in a development environment before deploying to production. For historical data, you only need a subset of them in the new project for testing and verification purposes.
2. Prepare for the official transition to the new project as soon as live data is re-directed there. Make sure that your project is well-setup by then.

   * If data delays or incomplete data are expected in the new project, clearly communicate this to your Mixpanel users as their analysis will be impacted. For example, having a data backfilling plan in place and sharing details such as “X months of data will be available in new project within Y hours”. This proactive approach will help manage expectations with your Mixpanel users and ensure a seamless transition.
   * Do check the [cost implication](/docs/pricing) of having overlapping data across multiple projects. If you have any questions, do reach out to our [Mixpanel Support](/docs/response-times#contacting-mixpanel-support) team for assistance.
3. In cases of a more intricate migration, involving larger data volumes coming from different sources that potentially pose a higher risk to Mixpanel users' experience, you might want to consider doing historical backfilling before updating the live implementation. This approach enables you to have ample time to configure your new project, replicate existing reports and non-data entities into the new project, and test them against the backfilled data. While this may require multiple backfills, you have the option to only deploy the live data implementation when you are ready.

### Migrating Reports and Non-Data Entities

As part of creating the new Simplified ID Merge project, you would also need to migrate existing boards, reports, and non-data entities (e.g. cohorts, custom events, custom properties, lookup tables, etc.) into the new project. Below is a recommended approach on how to go about doing this work:

1. <b>Cohorts, Custom Events, and Custom Properties</b>

   Manual Recreation: This involves manually copying and pasting / replicating the logic from the existing project into the new project's [cohorts](/docs/users/cohorts#creating-cohorts), [custom events](/docs/features/custom-events#create-a-custom-event), and [custom properties](/docs/features/custom-properties#creating-a-custom-property) definitions.

   For example for custom properties, follow steps to [Creating a Custom Property](/docs/features/custom-properties#creating-a-custom-property) and copy over the definition from the old project.

<br />

2. <b>Lookup Tables</b>

   Manual Recreation: If your existing project is heavily reliant on [Lookup Tables](/docs/data-structure/lookup-tables) for reports, manually [re-upload](/docs/data-structure/lookup-tables#how-do-i-upload-a-lookup-table) the lookup tables to the new project via Lexicon and map them to the relevant event / user properties.

<br />

3. <b>Boards & Reports</b>

   Move Board: Mixpanel provides a [Move Board](/docs/boards/move-boards) feature that allows you to directly [transfer Boards between projects](/changelogs/2023-07-27-move) preserving reports, filters, and text annotations.

   Before you move any Board, it's important to note the following:

   * Duplicate the existing Board and move the new copy into the new project. This would minimize impact where users are still using Boards and reports in the old project.
   * Any saved cohorts, custom events, custom properties, lookup tables would need to be created first as they don't get automatically moved as part of the Move Board.
   * You may need to replicate the permissions for the moved Board should you have very specific [sharing permissions](/docs/boards/sharing-and-permission) set in the existing project.
   * Double check that all reports (especially those that use cohorts, custom events, custom properties, lookup tables) are working properly.

<br />

1. <b>Lexicon</b>

   Schemas API or CSV Export/Import: Migrate the Lexicon schema definitions (i.e. display name, descriptions, etc.) of your events, event properties, and user properties from the existing project to the new project using either the [Lexicon Schemas API](/reference/lexicon-schemas-api) or [Lexicon CSV Export/Import](/docs/data-governance/lexicon#export-and-import-lexicon-data).

   Make sure that the events, event properties, and user properties that you're migrating are still relevant to your new project. You may want to take this opportunity to clean up your schema and remove any unused or deprecated elements before executing the import.

***If you have any questions or encounter any issues along the way, do reach out to our [Mixpanel Support](/docs/response-times#contacting-mixpanel-support) team for assistance.***


# Tracking Integrations
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations

Ingest data from a third-party tool into Mixpanel

These integrations allow you to send your tracking data to Mixpanel. You may review our complete integrations directory [here](https://mixpanel.com/partners/integrations). If you don't see what you're looking for [reach out to us](https://mixpanel.com/get-support).

### Featured Integrations

<CardGroup>
  <Card title="Segment" href="/docs/tracking-methods/integrations/segment" />

  <Card title="Google Tag Manager" href="/docs/tracking-methods/integrations/google-tag-manager" />
</CardGroup>

### All Integrations

<CardGroup>
  <Card title="Ad Spend" href="/docs/tracking-methods/integrations/ad-spend" />

  <Card title="Amazon S3" href="/docs/tracking-methods/integrations/amazon-s3" />

  <Card title="Amazon Kafka" href="/docs/tracking-methods/integrations/aws-kafka" />

  <Card title="CMS & E-Commerce" href="/docs/tracking-methods/integrations/cms-ecommerce" />

  <Card title="Customer.io" href="https://customer.io/docs/cdp/destinations/connections/mixpanel?utm_source=mixpanel&utm_medium=partner" />

  <Card title="Freshpaint" href="/docs/tracking-methods/integrations/freshpaint" />

  <Card title="Google Cloud Storage" href="/docs/tracking-methods/integrations/google-cloud-storage" />

  <Card title="Google Pubsub" href="/docs/tracking-methods/integrations/google-pubsub" />

  <Card title="Google Sheets" href="/docs/tracking-methods/integrations/google-sheets" />

  <Card title="Langfuse" href="/docs/tracking-methods/integrations/langfuse" />

  <Card title="LaunchDarkly" href="/docs/tracking-methods/integrations/launchdarkly" />

  <Card title="mParticle" href="/docs/tracking-methods/integrations/mparticle" />

  <Card title="Next.js" href="/docs/tracking-methods/integrations/nextjs" />

  <Card title="Mobile Attribution Tracking" href="/docs/tracking-methods/integrations/mobile-attribution-tracking" />

  <Card title="Rudderstack" href="/docs/tracking-methods/integrations/rudderstack" />

  <Card title="Shopify" href="/docs/tracking-methods/integrations/shopify" />

  <Card title="Vendo for Shopify" href="https://apps.shopify.com/vendo?utm_source=mixpanel&utm_medium=partner" />

  <Card title="Snowplow" href="/docs/tracking-methods/integrations/snowplow" />

  <Card title="Stripe" href="/docs/tracking-methods/integrations/stripe" />

  <Card title="Tealium" href="/docs/tracking-methods/integrations/tealium" />

  <Card title="Vendo" href="/docs/tracking-methods/integrations/vendo" />
</CardGroup>


# Ad Spend
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/ad-spend



Mixpanel’s event-based data model enables you to represent and analyze any type of data, including ad campaign performance. This guide shows you how to track this data to Mixpanel. The end result is a report that looks like this.

In this doc, we give step-by-step guidance on how to bring your advertising network data into Mixpanel to look at metrics such as ROAS (Return on Ad Spend), CPC (Cost per click) in the context of in-product conversions. We also provide detailed guides for Google and Facebook Ads. The end result should look like this:

<Frame>
  <img alt="" />
</Frame>

**NOTE:** If you are a Marketer reading this, we encourage you to share this with your dev team to get this one-time setup done. This should not take more than a couple of hours.

<Note>
  If you prefer not to build and maintain your data pipelines, consider using [Vendo](/docs/tracking-methods/integrations/vendo). The Vendo integration with Mixpanel allows seamless integration of advertising data from Google, Meta, and other ad platforms into Mixpanel without the need for custom development. Learn more [here](https://www.vendodata.com/integrations/mixpanel).
</Note>

## Importing via Warehouse Connectors

If your ad spend data is already in a data warehouse, you can bring it into Mixpanel using [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors) — no custom code or cloud functions required.

### Using the Ad Spend Template

[Link to Demo](https://www.loom.com/share/69dbc98ffeca415aafb10ede7a52b925)

The Ad Spend template provides a streamlined setup for mapping your warehouse table to Mixpanel's ad spend data model.

1. Connect your warehouse in **Project Settings → Warehouse Sources**.
2. Select a table or view that contains your ad metrics and choose the **Ad Spend** template.
3. Map columns for required Mixpanel fields (event name, timestamp) and ad metrics like `cost`, `clicks`, and `impressions`.
4. Set a sync schedule (e.g. hourly or daily). Mixpanel will sync rows from your table and turn each one into an event you can analyze in Insights and other reports.

## Importing via APIs

The sections below walk through building custom API pipelines to pull data directly from ad networks and send it to Mixpanel. This approach gives you full control but requires writing and hosting code.

### Understanding the Data Model

Events are the core of Mixpanel's data model. Fundamentally, an event is a row of data with a name, a timestamp, and a set of properties. This is how we can represent Ad Data as events.

```jsx theme={"system"}
{
	event: 'Ad Data',
	properties: {
		time: 1680307200000,
		source: 'Google',
		campaign_id: 12345,

		// Cost of this campaign in USD for this day
		cost: 37.19,
		// The total clicks of this ad campaign for this day
		clicks: 11,
		// The total impressions of this ad campaign for this day
		impressions: 482,

		// metadata about the campaign; matches client side events
		utm_source: "google",
		utm_medium: "newsletter",
		utm_campaign: "Launch Commercial US",
		utm_content: "ad-text-or-variant",
		utm_term: "ad-keywords"
	}
}
```

The crux of this How To guide is turning the data exported by Ad Networks into events that look like the above.

**Best Practices**

* **Only include base metrics** cost, clicks, and impressions. We don’t need to send derived metrics like Cost-per-click, because Mixpanel’s [Custom Properties](/docs/features/custom-properties) and Formulas allow us to calculate and alter derived metrics on the fly.
* **Matching client side properties:** if you are using a Mixpanel client-side SDK to track user behaviors, you will want to model additional campaign metadata (source, medium, campaign, etc...) as `utm_source`, `utm_medium` etc... this matches the way mixpanel's SDKs [capture UTM params by default](/docs/tracking-methods/sdks/javascript#tracking-utm-parameters)
* **No Distinct ID:** You’ll notice that our event has no Distinct ID. This is because ad performance data isn’t tied to any particular user. **This is the key difference from behavioral events.** By omitting it, we are ensuring that these events do not get erroneously included in reporting that intend to analyze user behavior such as Funnels, Retentions, Flows, unique user counts, “did not do” cohorts, etc.
* **Event properties are aggregated:** You’ll notice the Ad-Data event in this example is scheduled to trigger only once a day. Properties are aggregated counts of all clicks through the day, all impressions through the day, all ad-spend through the day. Reason for this is ad-networks only export data at an aggregate level (without user details) and at fixed intervals (lowest granularity is generally a day)
* **Include an Insert ID:** It’s recommended to include the Insert ID property for these kinds of events. This allows you to send the campaign data to Mixpanel more than once for a particular segment without duplicating the data in reports.

The Insert ID should be made up of unique attributes in the event that separate it from other performance data. Using our above event example, the uniquely identifiable properties are:

* The ad network name
* The date of the performance data
* The campaign ID

If we were to send this data more than once to Mixpanel, we know that these 3 properties will always be constant. We can build an Insert ID from that information:

```jsx theme={"system"}
// "G" = Google Ads
// "2023-04-01" = The date of our data
// "12345" = The specific campaign ID

$insert_id = `G-2023-04-01-12345`;
```

Note: Keep in mind the [Insert ID length limitations](/reference/import-events#propertiesinsert_id). If your ad network has long campaign IDs or other unique properties to use, you should use MD5 or another hashing algorithm to shorten your Insert ID.

### Gathering Data from Ad Networks

Different ad networks provide different ways to access their raw data. Some allow you to manually download a CSV export that can be transformed into the above format and sent to Mixpanel. Most networks also have APIs that allow you to automate exporting the metrics that you’re interested in.

> 💡 Note: Some of these APIs require registration and permissions with the underlying platform, please read their docs to set this up.

* **Google Ads** provides a Reporting API that can be used to extract performance data: [https://developers.google.com/google-ads/api/docs/reporting/overview](https://developers.google.com/google-ads/api/docs/reporting/overview)
* Facebook provides a Marketing Insights API for ad performance metrics: [https://developers.facebook.com/docs/marketing-api/insights](https://developers.facebook.com/docs/marketing-api/insights)
* LinkedIn provides a Marketing Reporting API for ad performance data: [https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/getting-started](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/getting-started)
* Twitter provides an Ads Analytics API that can be used to extract performance data: [https://developer.twitter.com/en/docs/twitter-ads-api/analytics/overview](https://developer.twitter.com/en/docs/twitter-ads-api/analytics/overview)

## Detailed Guides

Below are detailed guides for Google and Facebook Ad Networks. The same general process described in these two guides can be followed for any other ad network as well by using their export APIs and pushing the data to Mixpanel.

### Google

This guide will go through setting up a serverless Google Cloud Function that will export individual ad campaign performance data from Google Ads, transform them into Mixpanel events, and send them to your Mixpanel project every day.

#### Prerequisites

In order to follow this guide, you will need:

* Mixpanel project token (can be found in Mixpanel project settings)
* Mixpanel secret token (can be found in Mixpanel project settings)

  * This is required to track back-dated events
* [Google Ads Developer Token](https://developers.google.com/google-ads/api/docs/first-call/dev-token)
* An account with [Google Ads](https://ads.google.com/) access to your ad campaigns
* A Google Cloud Platform project

#### Accessing Google Ads API

Our Google Cloud Function will use the [Google Ads API](https://developers.google.com/google-ads/api/docs/start) to extract relevant campaign performance data for the previous day. To access their API, we will need to create a new Google API Credential that has access to the Google Ads API.

##### Creating your Credentials

* In your Google Cloud Platform project, navigate to the [Credentials](https://console.cloud.google.com/apis/credentials) screen
* From the ************************************Create credentials************************************ dropdown, create a new ******************************OAuth client ID******************************
* For **********************************Application type**********************************, select ******************************Web application******************************
* Add an ************************************************Authorized redirect URIs************************************************ entry for `https://developers.google.com/oauthplayground`

  * This is only for the next step and can be removed afterwards
* ************Create************ the credential

After creating your credential, it will show you its ********************Client ID******************** and **************************Client secret**************************. Take note of those as we will need them for the next step and to access the Google Ads API.

##### Enabling Google Ads API access

We need to allow our new credential to access the Google Ads API by enabling it.

* Navigate to the [Enabled APIs & services](https://console.cloud.google.com/apis/dashboard) page in Google Cloud
* Click ********************************************Enable APIs and services********************************************
* Find [****************************Google Ads API****************************](https://console.cloud.google.com/apis/library/googleads.googleapis.com), and press ************Enable************

##### Generating a Refresh Token

The credential you created allows Google to track access to the Google Ads API, but it doesn’t specify which Google user its acting on behalf of to retrieve the correct ad performance data. We will need to give the credential access to your Google Ads account so that it can export metrics on your behalf.

* Go to the [Google OAuth Playground](https://developers.google.com/oauthplayground#step1\&scopes=https%3A//www.googleapis.com/auth/adwords\&url=https%3A//\&content_type=application/json\&http_method=GET\&useDefaultOauthCred=checked\&oauthEndpointSelect=Google\&oauthAuthEndpointValue=https%3A//accounts.google.com/o/oauth2/v2/auth\&oauthTokenEndpointValue=https%3A//oauth2.googleapis.com/token\&includeCredentials=unchecked\&accessTokenType=bearer\&autoRefreshToken=unchecked\&accessType=offline\&forceAprovalPrompt=checked\&response_type=code)
* Click the Settings cog in the upper right corner

  * Set **********************OAuth flow********************** to **********************Server-side**********************
  * For **********************Access type**********************, select **************Offline**************

    * This will ensure we get a refresh token, and not just a short-lived access token
  * Check the ************************************************************Use your own OAuth credentials************************************************************ checkbox
  * Fill in the ********************Client ID******************** and ****************************Client Secret**************************** from the credential that you created earlier
* In the left hand side, find ****************************Google Ads API****************************, and select it

Once you click the ******************************Authorize APIs****************************** button, it will ask you to sign in with your Google account. Make sure to sign in with the one that has access to your Google Ads account.

It will ask you to allow the credential to ****************************************************************Manage your Google Ads Campaigns****************************************************************. Click ************Accept************.

Once it generates an Authorization code, click the button that says **Exchange authorization code for tokens**.

Take note of the **************************Refresh token************************** that it generates, your function will need this to access the Google Ads API.

##### Get the customer client ID

The last piece of information we will need is the Client Customer ID. It is the ID of your Google Ads user account, which we will need to know where to pull campaign data from.

Log into [Google Ads](https://ads.google.com/), and note the numbers at the top right of the screen under your display name.

<Frame>
  <img alt="Untitled" />
</Frame>

It should look something like: `123-456-7890`.

#### Creating the function

Now that we have all of the information we need, we can create our Google Cloud Function.

The function will run once a day, export the previous day’s campaign metrics, transform them into Mixpanel events, and import them our Mixpanel project.

* Go to the [Google Cloud Functions](https://console.cloud.google.com/functions/) page
* Click ******************************Create function******************************
* In the **********************Environment********************** dropdown, select **************2nd gen**************
* For ****************************Function name****************************, choose something informative like `mixpanel-ads-google`
* Open ********************************Runtime, build, connections and security settings******************************** and increase the **********************************Memory allocated********************************** and ********CPUs******** from the defaults

  * Depending on your ad network volume, you might want to play with these settings to process all of your data. You can always change these after creation.
* Press ********Next********
* Select **********************Node.js 18********************** as the **************Runtime**************
* For ************************Entry point************************, set it to `handler`

We will need to specify the dependencies for the function to use. Open the Inline Editor for **************************package.json************************** by clicking on it in the left navigation, and replace the contents with this:

```json theme={"system"}
{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0",
    "mixpanel": "^0.17.0",
		"google-ads-api": "^13.0.0"
  }
}
```

> 💡 Google doesn’t provide a first-party Ads API client for Node.js. The one we are using is third-party. More information can be found [here](https://www.npmjs.com/package/google-ads-api).

For the function’s code, select ****************index.js**************** in the file tree and replace its contents with this snippet:

```jsx theme={"system"}
const functions = require('@google-cloud/functions-framework');
const { GoogleAdsApi } = require('google-ads-api');
const Mixpanel = require('mixpanel');

// Configuration:
// It's recommended to pass these values through Environment Variables to your function via Secret Manager

const MIXPANEL_TOKEN = 'YOUR MIXPANEL TOKEN';
const MIXPANEL_SECRET = 'YOUR MIXPANEL SECRET';
// For US Data Residency (default):
const MIXPANEL_HOST = 'api.mixpanel.com';
// For EU Data Residency:
// const MIXPANEL_HOST = 'api-eu.mixpanel.com';
// For India Data Residency:
// const MIXPANEL_HOST = 'api-in.mixpanel.com';

const GOOGLE_CLIENT_ID = 'YOUR GOOGLE CREDENTIAL CLIENT ID';
const GOOGLE_CLIENT_SECRET = 'YOUR GOOGLE CREDENTIAL CLIENT SECRET';
const GOOGLE_CLIENT_REFRESH_TOKEN = 'YOUR REFRESH TOKEN FOR YOUR GOOGLE CREDENTIAL';
const GOOGLE_ADS_DEVELOPER_TOKEN = 'YOUR GOOGLE ADS DEVELOPER TOKEN';
const GOOGLE_ADS_CUSTOMER_ID = 'YOUR GOOGLE CUSTOMER CLIENT ID WITHOUT HYPHENS'; // ex. 1234567890

// End of Configuration

const mixpanel = Mixpanel.init(MIXPANEL_TOKEN, {host: MIXPANEL_HOST, secret: MIXPANEL_SECRET});

const client = new GoogleAdsApi({
    client_id: GOOGLE_CLIENT_ID,
    client_secret: GOOGLE_CLIENT_SECRET,
    developer_token: GOOGLE_ADS_DEVELOPER_TOKEN
});

/**
 * Gets campaign data from Google Ads.
 */
function fetchGoogleAdsCampaigns() {
    const customer = client.Customer({
        customer_id: GOOGLE_ADS_CUSTOMER_ID,
        refresh_token: GOOGLE_CLIENT_REFRESH_TOKEN
    });

		// Find metrics for all Google Ads campaigns that ran yesterday
    return customer.query(`
        SELECT
            segments.date,
            campaign.id,
            campaign.name,
            metrics.cost_micros,
            metrics.clicks,
            metrics.impressions
        FROM
            campaign
        WHERE
            metrics.cost_micros > 0
        AND
            segments.date DURING YESTERDAY
    `);
}

/**
 * Turns a Google Ads campaign result into a Mixpanel event.
 */
function transformCampaignToEvent(campaign) {
    return {
        event: 'Ad Data',
        properties: {
            $insert_id: `G-${campaign.segments.date}-${campaign.campaign.id}`,
						// We need to turn the date into a Unix timestamp
            time: new Date(campaign.segments.date).getTime(),
            source: 'Google',
            campaign_id: campaign.campaign.id,

            // metadata about the campaign; matches client side events
            utm_source: "google",
            utm_campaign: campaign.campaign.name,

            // Google's cost metric is 1 millionth of the fundamental currency specified by your Ads Account.
            cost: campaign.metrics.cost_micros / 1_000_000,
            impressions: campaign.metrics.impressions,
            clicks: campaign.metrics.clicks
        }
    };
}

/**
 * Our function's handler.
 */
functions.http('handler', async (req, res) => {
  try {
		// Get the raw campaign metrics
    const campaigns = await fetchGoogleAdsCampaigns();

    // Transform our raw metrics into Mixpanel events
    const events = campaigns.map(transformCampaignToEvent);

    // send them to Mixpanel
    mixpanel.import_batch(events, (err) => {
        if (err) {
					throw err;
				}

				res.status(200).send(`Imported ${events.length} events.`);
    });
	} catch (err) {
		res.status(500).send(err);
	}
});
```

Change the variables at the top of the snippet to use the information we collected earlier and press ************Deploy************.

After deployment, you will see a ******URL****** at the top of the **********************************Function details********************************** screen. Save that for the next step.

Your function is now ready! When it’s triggered, it will pull your Google Ad network data and send it to Mixpanel.

#### Schedule your function

We want the function to run by itself every day so we can regularly inspect the data in Mixpanel. We’ll do this by using Google Cloud Scheduler to run our Google Cloud Function every morning at 8 AM UTC.

* Navigate to the [Google Cloud Schedule](https://console.cloud.google.com/cloudscheduler) page in your project
* Click ********************Create job******************** at the top of the page
* For ********Name********, choose something descriptive such as `gcf-mixpanel-ads-google-daily`
* In ******Frequency******, put `0 8 * * *`

  * This is a unix-cron expression that means to run every day at the 8th hour (8:00 AM)
  * [Google Ads has a short delay](https://support.google.com/google-ads/answer/2544985?hl=en#:~:text=In%20most%20cases%2C%20your%20account%20statistics%20\(such%20as%20clicks%2C%20conversions%2C%20and%20impressions\)%20are%20delayed%20by%20less%20than%203%20hours) before metrics are available. Choosing a time sufficiently later than midnight ensures that the data will be ready for us to retrieve.
* Select ******************************************************************Coordinated Universal Time (UTC)****************************************************************** as the ****************Timezone****************

  * This can also be your local time if you prefer
* Press ****************Continue****************
* Select **********HTTP********** as the **********************Target type**********************
* In ********URL********, paste the URL that you got from your Cloud Function
* Set the **********************HTTP method********************** to ******GET******
* In the **********************Auth header********************** dropdown, choose Add OIDC token
* Select the service account that has access to your Google Cloud Function in the Service account dropdown

  * This gives Cloud Scheduler the access required to invoke your function on your behalf
* Press ************Create************ to create your new schedule

#### Wrapping up

That’s it! We’ve made a Google Cloud Function that syncs Google Ads data to Mixpanel every morning.

### Facebook

This guide will go through setting up a serverless Google Cloud Function that will export individual ad campaign performance data from Facebook, transform them into Mixpanel events, and send them to your Mixpanel project every day.

#### Prerequisites

We'll be using Facebook's [Marketing API](https://developers.facebook.com/docs/marketing-apis/get-started) to retrieve ad data from your ads account.

In order to follow this guide, you will need:

* Mixpanel project token (can be found in Mixpanel project settings)
* Mixpanel secret token (can be found in Mixpanel project settings)

  * This is required to track back-dated events
* [Facebook App Access Token](https://developers.facebook.com/docs/facebook-login/guides/access-tokens#apptokens) with the `ads_read` permission
* Facebook Ad Account ID

  * You can get this from the Ad account dropdown at the top of [Facebook Ads Manager](https://adsmanager.facebook.com/adsmanager/manage)
* A Google Cloud Platform project

#### Creating the function

The function will run once a day, export the previous day’s campaign metrics, transform them into Mixpanel events, and import them our Mixpanel project.

* Go to the [Google Cloud Functions](https://console.cloud.google.com/functions/) page
* Click ******************************Create function******************************
* In the **********************Environment********************** dropdown, select **************2nd gen**************
* For ****************************Function name****************************, choose something informative like `mixpanel-ads-facebook`
* Open ********************************Runtime, build, connections and security settings******************************** and increase the **********************************Memory allocated********************************** and ********CPUs******** from the defaults

  * Depending on your ad network volume, you might want to play with these settings to process all of your data. You can always change these after creation.
* Press ********Next********
* Select **********************Node.js 18********************** as the **************Runtime**************
* For ************************Entry point************************, set it to `handler`

We will need to specify the dependencies for the function to use. Open the Inline Editor for **************************package.json************************** by clicking on it in the left navigation, and replace the contents with this:

```json theme={"system"}
{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0",
    "mixpanel": "^0.17.0",
		"facebook-nodejs-business-sdk": "^16.0.2"
  }
}
```

For the function’s code, select ****************index.js**************** in the file tree and replace its contents with this snippet:

```jsx theme={"system"}
const functions = require('@google-cloud/functions-framework');
const adsSdk = require('facebook-nodejs-business-sdk');
const Mixpanel = require('mixpanel');

// Configuration:
// It's recommended to pass these values through Environment Variables to your function via Secret Manager

const MIXPANEL_TOKEN = 'YOUR MIXPANEL TOKEN';
const MIXPANEL_SECRET = 'YOUR MIXPANEL SECRET';
// For US Data Residency (default):
const MIXPANEL_HOST = 'api.mixpanel.com';
// For EU Data Residency:
// const MIXPANEL_HOST = 'api-eu.mixpanel.com';
// For India Data Residency:
// const MIXPANEL_HOST = 'api-in.mixpanel.com';
const FACEBOOK_TOKEN = 'YOUR FACEBOOK DEVELOPER APP TOKEN';
const FACEBOOK_AD_ACCOUNT_ID = 123456789012345; // Your Facebook Ad account ID here. e.g. 123456789012345
const FACEBOOK_AD_API_ACCOUNT = 'act_' + FACEBOOK_AD_ACCOUNT_ID;

// End of Configuration

const mixpanel = Mixpanel.init(MIXPANEL_TOKEN, {
    host: MIXPANEL_HOST,
    secret: MIXPANEL_SECRET
});

adsSdk.FacebookAdsApi.init(FACEBOOK_TOKEN);

/**
 * Gets campaign data from Facebook.
 */
function fetchFacebookCampaigns() {
    const account = new adsSdk.AdAccount(FACEBOOK_AD_API_ACCOUNT);

		// Find metrics for all Facebook Ads campaigns that ran yesterday
    return account.getInsights([
        'campaign_id',
        'campaign_name',
        'spend',
        'impressions',
        'clicks'
    ], {
        level: 'campaign',
        date_preset: 'yesterday',
        filtering: [
            {
                field: 'spend',
                operator: 'GREATER_THAN',
                value: 0
            }
        ]
    });
}

/**
 * Turns a Facebook campaign result into a Mixpanel event.
 */
function transformCampaignToEvent(campaign) {
    return {
        event: 'Ad Data',
        properties: {
            $insert_id: `FB-${campaign.date_start}-${campaign.campaign_id}`,
            time: new Date(campaign.date_start).getTime(),
            source: 'Facebook',
            campaign_id: campaign.campaign_id,
            // metadata about the campaign; matches client side events
            utm_source: "facebook",
            utm_campaign: campaign.campaign_name,

            cost: campaign.spend,
            impressions: campaign.impressions,
            clicks: campaign.clicks
        }
    };
}

/**
 * Our function's handler.
 */
functions.http('handler', async (req, res) => {
  try {
		// Get the raw campaign metrics
    const campaigns = await fetchFacebookCampaigns();

    // Transform our raw metrics into Mixpanel events
    const events = campaigns.map(transformCampaignToEvent);

    // send them to Mixpanel
    mixpanel.import_batch(events, (err) => {
        if (err) {
					throw err;
				}

				res.status(200).send(`Imported ${events.length} events.`);
    });
	} catch (err) {
		res.status(500).send(err);
	}
});
```

Change the variables at the top of the snippet to use the information we collected earlier and press ************Deploy************.

After deployment, you will see a ******URL****** at the top of the **********************************Function details********************************** screen. Save that for the next step.

Your function is now ready! When it’s triggered, it will pull your Facebook Ad network data and send it to Mixpanel.

#### Schedule your function

We want the function to run by itself every day so we can regularly inspect the data in Mixpanel. We’ll do this by using Google Cloud Scheduler to run our Google Cloud Function every morning at 8 AM UTC.

* Navigate to the [Google Cloud Schedule](https://console.cloud.google.com/cloudscheduler) page in your project
* Click ********************Create job******************** at the top of the page
* For ********Name********, choose something descriptive such as `gcf-mixpanel-ads-facebook-daily`
* In ******Frequency******, put `0 8 * * *`

  * This is a unix-cron expression that means to run every day at the 8th hour (8:00 AM)
  * Some ad networks may have a delay before metrics are available. Choosing a time sufficiently later than midnight ensures that the data will be ready for us to retrieve.
* Select ******************************************************************Coordinated Universal Time (UTC)****************************************************************** as the ****************Timezone****************

  * This can also be your local time if you prefer
* Press ****************Continue****************
* Select **********HTTP********** as the **********************Target type**********************
* In ********URL********, paste the URL that you got from your Cloud Function
* Set the **********************HTTP method********************** to ******GET******
* In the **********************Auth header********************** dropdown, choose Add OIDC token
* Select the service account that has access to your Google Cloud Function in the Service account dropdown

  * This gives Cloud Scheduler the access required to invoke your function on your behalf
* Press ************Create************ to create your new schedule

#### Wrapping up

That’s it! We’ve made a Google Cloud Function that syncs Facebook Ads data to Mixpanel every morning.


# Amazon S3
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/amazon-s3



This guide demonstrates how to set up a serverless ingest pipeline from an AWS S3 bucket into Mixpanel. Once this is set up, you can simply upload files containing events into the designated S3 bucket and the events will be ingested into Mixpanel, both one-time and on a recurring basis. Setup should take \~5-10 minutes.

<Frame>
  <img alt="image" />
</Frame>

Note: This guide assumes you are running in Amazon Web Services, and have the necessary IAM Access to have AWS Lambda read from S3.

## Step 1: Create an S3 Bucket

[Create a dedicated S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) for this integration. We recommend including `mixpanel-import` in the name to make it explicit and avoid any accidental data sharing.

You can create the bucket in any region, though it will need to be in the same region as your AWS Lambda function.

## Step 2: Setup Import Config

### Step 2a: Setup the Lambda Function

Create a [new Lambda Function](https://docs.aws.amazon.com/lambda/latest/dg/getting-started-create-function.html).

* Select `Author From Scratch`.
* Select a Python runtime.
* Select  `Create Function`.

<Frame>
  <img alt="image" />
</Frame>

### Step 2b: Write the Lambda Function

Change the filename from `lambda_function.py` to `main.py` and edit the `runtime settings` handler to `main.Handler`. Paste the code below for `main.py`.

<Frame>
  <img alt="image" />
</Frame>

```python main.py theme={"system"}

from datetime import date
from io import TextIOWrapper
import gzip
import json
import random
import time
import urllib.parse
import os

import boto3
import requests


# Fill this out with your Project Token
PROJECT_TOKEN = ""

# Flush a batch once these limits are hit
EVENTS_PER_BATCH = 2000
BYTES_PER_BATCH = 2 * 1024 * 1024


# Adjust event timestamps of test data so that it appears recent in Mixpanel.
# NOTE: THIS IS JUST FOR DEMO PURPOSES.
# REPLACE THIS WITH YOUR OWN TRANSFORMS IN PRODUCTION.
def transform_to_event(line):
    """Convert a line of the file to a json string in Mixpanel's format."""
    event = json.loads(line)
    event["properties"]["time"] = int(date.today().strftime("%s"))
    return json.dumps(event)
  

def flush(batch):
    payload = gzip.compress("\n".join(batch).encode("utf-8"))
    tries = 0
    while True:
        resp = requests.post(
            "https://api.mixpanel.com/import",
            params={"strict": "1"},
            headers={
                "Content-Type": "application/x-ndjson",
                "Content-Encoding": "gzip",
                "User-Agent": "mixpanel-s3"
            },
            auth=(PROJECT_TOKEN, ""),
            data=payload,
        )
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(min(2 ** tries, 60) + random.randint(1, 5))
            tries += 1
            continue
        return resp


def Handler(event, context):
    s3 = boto3.client('s3')

    bucket =  event['Records'][0]['s3']['bucket']['name']
    key = urllib.parse.unquote_plus(event['Records'][0]['s3']['object']['key'], encoding='utf-8')

    blob = s3.get_object(Bucket=bucket, Key=key)
    if blob['ResponseMetadata']['HTTPHeaders']['content-type'] == 'application/x-gzip':
        gzipped = gzip.GzipFile(None, 'rb', fileobj=blob['Body'])
        data = TextIOWrapper(gzipped).read()
    else:
        data = blob['Body'].read().decode('utf-8').splitlines()

    error = None
    batch, batch_bytes = [], 0
    
    for line in data:
        # Here we assume each line is valid JSON representing a single Mixpanel event
        # If lines are not in Mixpanel's format, apply any transformations here.
        line = transform_to_event(line)
  
        batch.append(line)
        batch_bytes += len(line)
    
    
        if len(batch) == EVENTS_PER_BATCH or batch_bytes >= BYTES_PER_BATCH:
            resp = flush(batch)
            batch, batch_bytes = [], 0
    
            if resp.status_code != 200:
                error = resp.json()
                break

    # Flush final batch
    if batch and not error:
        resp = flush(batch)
        if resp.status_code != 200:
            error = resp.json()
    

    print(
        json.dumps(
            {
                "message": "Import complete",
                "request": event,
                "success": error is None,
                "first_error": error,
                "severity": "INFO",
            }
        )
    )
```

### Step 2c: Add Trigger

Add a trigger so that your Lambda function runs whenever a new object is added to your bucket by selecting `Add trigger` under `Function Overview`. You will want to use the bucket created in Step 2 and select `All object create events`.

<Frame>
  <img alt="image" />
</Frame>

### Step 2d: Update Configurations and Deploy

Select `Configuration` > `General Configuration` > `Edit`.

* Change `Memory` to `1024 MB`.
* Change `Timeout` to `5 minutes`.

<Frame>
  <img alt="image" />
</Frame>

Click `Versions` > `Publish New Version` to deploy the function. At this point, any file you upload to the bucket will trigger an invocation of the function and an import into Mixpanel. Let's test it out!

## Step 3: Test with sample data and watch the logs

Let's test the connection with some [sample events](https://storage.googleapis.com/mixpanel-sample-data/10-events.json). Run the following to copy them to your bucket, which will trigger the import:

`gsutil cp cp gs://mixpanel-sample-data/10-events.json s3://your-s3-bucket/example.json`

Monitor the logs of your Lambda Function; you should see an `Import Complete` log line within a minute.

<Frame>
  <img alt="image" />
</Frame>

If you navigate to CloudWatch logs, you will see a more detailed log that includes the filename being imported and the first error encountered (if any).

<Frame>
  <img alt="image" />
</Frame>

Finally, let's confirm that the events made it into Mixpanel. Head to the [Events](https://mixpanel.com/report/live) page, pick `test_event` in the event picker, and you should see the events you just imported.

<Frame>
  <img alt="image" />
</Frame>

## Step 4: Import more data

We're now ready for an import of your own data. If your data is not already in the Mixpanel format, this is a good time to write a transformation step to run as part of the Lambda. We recommend testing locally as you iterate on your data transformation logic, as it's much quicker than redeploying the Lambda. The [Overview](/docs/quickstart/connect-your-data?sdk=httpapi) page has sample code and data to test locally.

Once you're ready and have tested with a few small files, you can upload all the files for your import to your S3 bucket, and the import will kick off. This pipeline can be made recurring by uploading files to the S3 bucket periodically.

We recommend partitioning files in S3 to \~200MB of JSON for optimal performance.


# Kafka
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/aws-kafka



This guide demonstrates how to plug Mixpanel into an event collection pipeline by AWS Kafka. Once set up, your events will route to Mixpanel and be available in real-time for analytics. This approach is serverless and open-source, and takes \~5 minutes to set up.

To read messages from a Kafka topic and send them to Mixpanel, you'll need to use the confluent-kafka library for Kafka and the mixpanel library for Mixpanel.

### Here's a sample Python code snippet:

```python main.py theme={"system"}
from confluent_kafka import Consumer, KafkaError
from mixpanel import Mixpanel

# Kafka setup
kafka_config = {
    'bootstrap.servers': 'localhost:9092',
    'group.id': 'my-group',
    'auto.offset.reset': 'earliest'
}
consumer = Consumer(kafka_config)
consumer.subscribe(['my_topic'])

# Mixpanel setup
mp = Mixpanel('YOUR_MIXPANEL_TOKEN')

try:
    while True:
        msg = consumer.poll(1)

        if msg is None:
            continue
        if msg.error():
            if msg.error().code() == KafkaError._PARTITION_EOF:
                continue
            else:
                print(msg.error())
                break

        # Send to Mixpanel
        # The event_data contains the entire event. Consider extracting parsing the event for properties and explicitly assigning them instead.
        event_data = msg.value().decode('utf-8')
        mp.track('some_user_id', 'My Event', {'message': event_data})

finally:
    consumer.close()
```

To run this code:

1. Install Kafka and start a Kafka broker.
2. Install necessary Python packages:

   * pip install confluent-kafka
   * pip install mixpanel
3. Replace 'YOUR\_MIXPANEL\_TOKEN' with your actual Mixpanel token.
4. Run the code.

Google has a [great reference](https://cloud.google.com/pubsub/docs/handling-failures) on best practices for handling both retryable and non-retryable errors.


# CMS & E-Commerce
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/cms-ecommerce



It's easy to integrate Mixpanel in CMS or E-Commerce sites with minimal code. Most approaches require adding our [Javascript snippet](/docs/quickstart/connect-your-data), which will automatically track all pageviews, and then customizing with additional `.track()` calls to track custom events.

## Wordpress

Though Mixpanel does not have an official plugin to support WordPress, there are plenty of options for getting Mixpanel set up on your WordPress site.

There are a variety of third-party options available that will automatically send data from your WordPress blog to your Mixpanel implementation. Some popular options include [third-party plugins](https://wordpress.org/plugins/tags/mixpanel/). Most of these third-party plugins essentially just track page loads, which means you would be tracking some data, but not really fully utilizing the potential of Mixpanel. Though none are officially supported by Mixpanel, they might be worth checking out if you’re looking for a quick and simple solution.

However, to really exercise the power of Mixpanel, you can do a custom implementation, integrating Mixpanel the same way as any other platform by following the [JavaScript API integration steps](/docs/tracking-methods/sdks/javascript).

[One option is to build a child theme in WordPress](https://codex.wordpress.org/Child_Themes) to be able to track events beyond page views. For example, if you have a plugin for a contact form in the page, you could modify the plugin to add the JavaScript specific to the Event within the form.

## Shopify

<CardGroup>
  <Card title="Integration Guide" href="/docs/tracking-methods/integrations/shopify" />
</CardGroup>

Even though the integration process is largely the same as the regular [JavaScript API Integration](/docs/tracking-methods/sdks/javascript), there are a few things specific to Shopify that you’ll want to account for.

To start, add the Mixpanel JavaScript snippet into the tag of your theme.liquid page. Then, once the library has been successfully loaded, implement `mixpanel.track()` calls wherever you see fit.

Mixpanel users who have successfully implemented on a Shopify site [have some great recommendations and tips on key locations to place mixpanel.track() calls](https://stackoverflow.com/questions/28160415/shopify-mixpanel-integration/34442476#34442476).

While Shopify is strict about preventing arbitrary scripts from running in the checkout flow, you can easily capture customer events and conversions by integrating the Mixpanel Javascript SDK with the Shopify Web Pixel API.

Reference our [Guide to Integrating Mixpanel Javascript SDK with Shopify](/docs/tracking-methods/integrations/shopify) for a detailed walkthrough.

If you are looking for a no-code solution, check out the [Vendo app by Growth Analytics Marketing](https://mixpanel.com/partners/integrations/vendo) (a Mixpanel solution and technology partner), available in the Shopify app store. Vendo automatically sends data from your Shopify store front-end and back-end to your Mixpanel project. Vendo offers a 30-day free trial and a free plan.

## PrestaShop

To get up and running with Mixpanel on a PrestaShop site, paste the [Mixpanel JavaScript snippet](/docs/tracking-methods/sdks/javascript) in the header.tpl file between `{literal} {/literal}` tags. Once you’ve successfully initialized the Mixpanel library, add mixpanel.track calls per the standard JavaScript integration documentation.


# Freshpaint
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/freshpaint



Freshpaint is a data platform that lets you to track events from your website into Mixpanel without writing any code. Freshpaint does a great job of helping teams faced by implementation challenges free up developer bandwidth through a hybrid approach to data collection.

Follow [this guide](https://documentation.freshpaint.io/destinations/apps/mixpanel) to quickly start tracking events to Mixpanel via Freshpaint.


# Google Cloud Storage
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/google-cloud-storage



This guide demonstrates how to set up a serverless ingest pipeline from a Google Cloud Storage bucket into Mixpanel. Once this is set up, you can simply upload files containing events into the designated GCS bucket and the events will be ingested into Mixpanel, both one-time and on a recurring basis. Setup should take \~10 minutes.

<Frame>
  <img alt="image" />
</Frame>

Note: This guide assumes you are running in Google Cloud Platform, and have the necessary IAM Access to have Cloud Functions read from GCS.

## Step 1: Create a GCS Bucket

[Create a dedicated Cloud Storage bucket](https://console.cloud.google.com/storage/create-bucket) for this integration. We recommend including `mixpanel-import` in the name to make it explicit and avoid any accidental data sharing.

You can create the bucket in any region, though we recommend `us-central` for highest throughput.

## Step 2: Setup Import Config

### Step 2a: Setup the Cloud Function

Create a [new Cloud Function](https://console.cloud.google.com/functions/add).

* Set the trigger to `Cloud Storage`, the Event Type to `Finalize/Create` and the bucket name to the bucket created in step 2. This means that any object uploaded to this bucket will trigger an invocation of this Cloud Function.
* Set Memory to 1GiB, Timeout to 300, and Instances to 20

<Frame>
  <img alt="image" />
</Frame>

### Step 2b: Write the Cloud Function

Switch the runtime to `Python3.9` and change the entrypoint from `hello_gcs` to `main`. Paste the code below for `main.py` and `requirements.txt`.

<Frame>
  <img alt="image" />
</Frame>

```python main.py theme={"system"}
from datetime import date
import gzip
import json
import random
import time

from google.cloud import storage
import requests

# Fill this out.
PROJECT_TOKEN = ""

# Flush a batch once these limits are hit
EVENTS_PER_BATCH = 2000
BYTES_PER_BATCH = 2 * 1024 * 1024


# Adjust event timestamps of test data so that it appears recent in Mixpanel.
# NOTE: THIS IS JUST FOR DEMO PURPOSES.
# REPLACE THIS WITH YOUR OWN TRANSFORMS IN PRODUCTION.
def transform_to_event(line):
    """Convert a line of the file to a json string in Mixpanel's format."""
    event = json.loads(line)
    event["properties"]["time"] = int(date.today().strftime("%s"))
    return json.dumps(event)


def flush(batch):
    payload = gzip.compress("\n".join(batch).encode("utf-8"))
    tries = 0
    while True:
        resp = requests.post(
            "https://api.mixpanel.com/import",
            params={"strict": "1"},
            headers={
                "Content-Type": "application/x-ndjson",
                "Content-Encoding": "gzip",
                "User-Agent": "mixpanel-gcs"
            },
            auth=(PROJECT_TOKEN, ""),
            data=payload,
        )
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(min(2 ** tries, 60) + random.randint(1, 5))
            tries += 1
            continue
        return resp


def main(request, context):
    gcs = storage.Client()
    bucket = gcs.get_bucket(request["bucket"])
    blob = bucket.get_blob(request["name"])
    
    compressed = request["name"].endswith(".gz")

    error = None
    batch, batch_bytes = [], 0
    
    # As a convenience, check for files ending with .gz
    f = blob.open("rb")
    if request["name"].endswith(".gz") and request.get("contentEncoding") != "gzip":
        f = gzip.open(f)
    
    for line in f:
        # Here we assume each line is valid JSON representing a single Mixpanel event
        # If lines are not in Mixpanel's format, apply any transformations here.
        line = transform_to_event(line)

        batch.append(line)
        batch_bytes += len(line)

        if len(batch) == EVENTS_PER_BATCH or batch_bytes >= BYTES_PER_BATCH:
            resp = flush(batch)
            batch, batch_bytes = [], 0

            if resp.status_code != 200:
                error = resp.json()
                break

    # Flush final batch
    if batch and not error:
        resp = flush(batch)
        if resp.status_code != 200:
            error = resp.json()

    f.close()
    print(
        json.dumps(
            {
                "message": "Import complete",
                "request": request,
                "success": error is None,
                "first_error": error,
                "severity": "INFO",
            }
        )
    )
```

```text requirements.txt theme={"system"}
google-cloud-storage
requests
```

This code will be triggered whenever a new object is added to your bucket. It streams over the newly added object, assuming each line is newline delimited JSON in Mixpanel's event format. It then forms batches and hits our /import API, retrying any retryable errors. It logs a single message on completion. If it fails due to a validation error, this log includes the first non-retryable error encountered.

Click `Deploy` to deploy the function. At this point, any file you upload to the bucket will trigger an invocation of the function and an import into Mixpanel. Let's test it out!

## Step 3: Test with sample data and watch the logs

Let's test the connection with some [sample events](https://storage.googleapis.com/mixpanel-sample-data/10-events.json). Run the following to copy them to your bucket, which will trigger the import:

`gsutil cp gs://mixpanel-sample-data/10-events.json gs://<YOUR-BUCKET>/`

Monitor the logs of your Cloud Function; you should see an `Import Complete` log line within a minute.

<Frame>
  <img alt="image" />
</Frame>

If you navigate to Stackdriver logs, you will see a more detailed log that includes the filename being imported and the first error encountered (if any).

<Frame>
  <img alt="image" />
</Frame>

Finally, let's confirm that the events made it into Mixpanel. Head to the [Events](https://mixpanel.com/report/live) page, pick `test_event` in the event picker, and you should see the events you just imported.

<Frame>
  <img alt="image" />
</Frame>

## Step 4: Import more data

We're now ready for an import of your own data. If your data is not already in the Mixpanel format, this is a good time to write a transformation step to run as part of the Cloud Function. We recommend testing locally as you iterate on your data transformation logic, as it's much quicker than redeploying the Cloud Function. The [Overview](/docs/quickstart/connect-your-data?sdk=httpapi) page has sample code and data to test locally.

Once you're ready and have tested with a few small files, you can upload all the files for your import to your GCS bucket, and the import will kick off. This pipeline can be made recurring by uploading files to the GCS bucket periodically.

We recommend partitioning files in GCS to \~200MB of JSON for optimal performance.


# Google Pubsub
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/google-pubsub



This guide demonstrates how to plug Mixpanel into an event collection pipeline hosted in Google Cloud. Once set up, your events will route to Mixpanel and be available in real-time for analytics. This approach is serverless and open-source, and takes \~5 minutes to set up.

> Note: if you are on AWS, this approach is very similar using Kinesis and AWS Lambda.

<Frame>
  <img alt="image" />
</Frame>

## Step 1: Create a Cloud Pub/Sub Topic

(You can skip this step if you already have a Pub/Sub topic with events flowing through it.)

Create a [new Pub/Sub Topic](https://console.cloud.google.com/cloudpubsub/topic). All events that will ultimately route to Mixpanel will flow through this Pub/Sub topic.

<Frame>
  <img alt="image" />
</Frame>

### Step 2a: Add a Cloud Function Trigger to your Pub/Sub Topic

In this step, we set up a Cloud Function to trigger whenever events are pushed to your Pub/Sub topic. [Google's documentation](https://cloud.google.com/functions/docs/calling/pubsub) goes into full detail on how this trigger works.

From your newly created topic, click `+Trigger Cloud Function`. Give the Cloud Function a name and Save.

<Frame>
  <img alt="image" />
</Frame>

<Frame>
  <img alt="image" />
</Frame>

### Step 2b: Write the Cloud Function

Switch the runtime to `Python3.9` and change the entrypoint from `hello_pubsub` to `main`. Paste the code below for main.py and requirements.txt.

```python main.py theme={"system"}
import base64
from datetime import date
import gzip
import json
import random
import time

import requests

# Fill this out.
PROJECT_TOKEN = ""


def main(event, context):
    # Assumes the message consists of lines of JSON, each in Mixpanel's format
    msg = base64.b64decode(event["data"]).decode("utf-8")
    events = [json.loads(line) for line in msg.split("\n") if len(line) > 0]

    # Adjust the timestamps of each of the sample events so that
    # they appear recent. Note: this is just for this demo, do not
    # do this in production.
    for e in events:
        e["properties"]["time"] = int(date.today().strftime("%s"))

    # Send to Mixpanel
    tries = 0
    payload = gzip.compress(json.dumps(events).encode("utf-8"))
    while True:
        resp = requests.post(
            "https://api.mixpanel.com/import",
            params={"strict": "1"},
            auth=(PROJECT_TOKEN, ""),
            headers={"Content-Type": "application/json", "Content-Encoding": "gzip", "User-Agent": "mixpanel-pubsub"},
            data=payload,
        )
        if resp.status_code == 429 or resp.status_code >= 500:
            # Retryable errors, use exponential backoff
            tries += 1
            time.sleep(min(2 ** tries, 60) + random.randint(1, 5))
            continue
        else:
            break

    if resp.status_code != 200:
        # Log failures. In production, write to a dead-letter queue
        print({"message": "Import failed", "error": resp.json(), "severity": "WARN"})
    else:
        # Log success for debugging. Remove in production.
        print(
            {
                "message": "Import succeeded",
                "count": resp.json()["num_records_imported"],
                "severity": "INFO",
            }
        )
```

```text requirements.txt theme={"system"}
requests
```

This code does a very simple passthrough of events from the incoming Pubsub message into Mixpanel's [Import API](/reference/import-events). You can use this function to transform events from your Pub/Sub topic into Mixpanel's format before sending them to our Import API.

## Step 3: Test with sample events

Now messages published to our Pubsub topic will trigger an invocation of the function and route events to Mixpanel. Let's give it a try by manually sending a message via the PubSub UI.

On the topic page, navigate to `Messages -> Publish message`.

<Frame>
  <img alt="image" />
</Frame>

Then paste in the following events as the message body.

```json events theme={"system"}
{"event": "test_event", "properties": {"distinct_id": "Sunrostern", "$insert_id": "28096095", "title": "Creator Giveaway for Publishing Notes", "url": "https://www.viewert.com", "score": "1", "time": 1628315585}}
{"event": "test_event", "properties": {"distinct_id": "feross", "$insert_id": "28059483", "title": "`at` Method for Relative Indexing", "url": "https://v8.dev/features/at-method", "score": "1", "time": 1628074042}}
{"event": "test_event", "properties": {"distinct_id": "prostoalex", "$insert_id": "28069645", "title": "Home Classrooms Became a Necessity During Covid. Now They\u2019re a Selling Point", "url": "https://www.wsj.com/articles/home-classrooms-covid-real-estate-11628100036", "score": "1", "time": 1628135271}}
{"event": "test_event", "properties": {"distinct_id": "bingewave", "$insert_id": "28063639", "title": "Building a Live Streaming Movie App and Live TV Website \u2013 ReactJS", "url": "https://medium.com/bingewave/building-a-live-streaming-movie-app-live-tv-website-part-1-d0857aaac8ea", "score": "1", "time": 1628097439}}
{"event": "test_event", "properties": {"distinct_id": "jashkenas", "$insert_id": "28063632", "title": "Classic Research in Data Visualization", "url": "https://observablehq.com/@tophtucker/classic-research-in-data-visualization", "score": "1", "time": 1628097398}}
{"event": "test_event", "properties": {"distinct_id": "ivandiblasi68", "$insert_id": "28091778", "title": "Il sistema sanitario irlandese colpito da un ransomware", "url": "https://www.kaspersky.it/blog/irish-health-service-ransomware/24680/", "score": "1", "time": 1628278340}}
{"event": "test_event", "properties": {"distinct_id": "akdav", "$insert_id": "28091776", "title": "DeFi and KYC", "url": "https://link.medium.com/bsn7z9Jmvib", "score": "1", "time": 1628278312}}
{"event": "test_event", "properties": {"distinct_id": "webscraping99", "$insert_id": "28085411", "title": "LinkedIn Profile Detail Scrapers \u2013 Ahmad Software Technologies", "url": "https://ahmadsoftwaretechnologies3.mypixieset.com/linkedin-profile-detail-scrapers/", "score": "1", "time": 1628246831}}
{"event": "test_event", "properties": {"distinct_id": "Dorimoody", "$insert_id": "28064346", "title": "Our Children and Our Citations: Each One, Both Together", "url": "https://www.plough.com/en/topics/life/work/our-children-and-our-citations-each-one-both-together", "score": "1", "time": 1628101041}}
{"event": "test_event", "properties": {"distinct_id": "feross", "$insert_id": "28064342", "title": "The SEC Has Its Eye on Crypto", "url": "https://www.bloomberg.com/opinion/articles/2021-08-04/the-sec-has-its-eye-on-crypto", "score": "1", "time": 1628101019}}
```

Once you `Publish`, the function will trigger and pass the above payload to the Cloud Function. Within a minute, you should see an `Import succeeded` log line in the Cloud Function logs.

You can then navigate to the [Events](http://mixpanel.com/report/live) page to see the events in Mixpanel.

<Frame>
  <img alt="image" />
</Frame>

## Step 4: Connecting your production pipeline

At this point, you can route events from your production Pub/Sub topic through a Cloud Function in a similar manner as described above. Simplify modify the Cloud Function to transform events from your internal event format into the format expected by Mixpanel. This is also a good point to strip any PII.

Once connected, this will result in a steady stream of events being sent to Mixpanel. Happy streaming!

# Error Handling

In rare instances, Mixpanel's /import API may return a 429 or 5XX error. These can be safely retried. We recommend an exponential backoff with jitter strategy, as written in the sample code above. PubSub can be configured to perform exponential backoff if the function itself times out.

If the payload is malformed, our API might return a 400 error. In this case, the item cannot be ingested and this error should not be retried. Enqueue these messages onto a dead-letter-queue for inspection later on. This might happen while initially testing the connector, but should be rare in production, assuming the shape of data flowing through the pipeline remains consistent.

Google has a [great reference](https://cloud.google.com/pubsub/docs/handling-failures) on best practices for handling both retryable and non-retryable errors.


# Google Sheets
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/google-sheets



## Overview

Mixpanel has a native extension for Google Sheets that enables you to import CSV data to your Mixpanel project, and export your Mixpanel reports/cohorts to your Sheets.

The source code for this extension lives [here](https://github.com/mixpanel/sheets).

<Frame>
  <iframe />
</Frame>

## Install the plugin

Visit the [Sheets ⇔ Mixpanel Google Workspace Marketplace page](https://workspace.google.com/marketplace/app/sheets_%E2%87%94_mixpanel/1078767167468) to install the extension. Learn more about the permissions requested [here](/docs/tracking-methods/integrations/google-sheets#permissions).

After installing, you will see the Sheets ⇔ Mixpanel dropdown under "extensions" in any Google Sheet. This module provides two modes, which are exposed in the main menu:

<Frame>
  <img alt="gsheets-main-menu" />
</Frame>

* **Sheet → Mixpanel:** import event/user/group/table data from the current sheet.
* **Mixpanel → Sheet:** export reports or cohort data from your mixpanel project

Each UI has a simple user interface, and is essentially a form you fill out that contains the necessary details to carry out your desired result.

## Import from Google Sheet

**Sheet → Mixpanel** queries your currently active sheet to get your sheet's column headers.

Once you choose the type of data you are importing, you will use the visual mapper to connect the column headers from your sheet to the required fields for the type of mixpanel data you are importing:

<Frame>
  <img alt="gsheets-mapping" />
</Frame>

Here is a summary of Mixpanel's [data model](/docs/data-structure/concepts) and [required fields for event data](/docs/data-structure/concepts#anatomy-of-an-event):

* **event name:** what to call each event in mixpanel
* **distinct\_id:** the unique user identifier to whom the event is attributed (learn more [here](/docs/tracking-methods/id-management#distinct-id))
* **time:** a valid date or time; if the sheet recognizes your chosen column as a 'date' or time', it should work as intended
* **insert\_id:** a value used to deduplicate records (optional)

All other columns in your spreadsheet will get sent as properties (event, user, or group).

You will also need to provide the following details found in your [project settings](/docs/orgs-and-projects/managing-projects#project-details):

* **project\_id**
* **project\_token**
* **project\_region** (data residency)
* **project\_secret** (or [Service Account](/reference/service-accounts))

<Warning>
  Note: since v1.12 syncs are not supported for events.
</Warning>

Next, learn about [runs and syncs](/docs/tracking-methods/integrations/google-sheets#runs-and-syncs) below.

## Export to Google Sheet

**Mixpanel → Sheet** queries your Mixpanel project for a report or cohort and makes the results available in a new Sheet.

This will replicate the functionality when [exporting a CSV file from the Mixpanel UI](/docs/export-methods#exporting-reports).

There are a number of parameters needed to fetch a CSV from mixpanel. The simplest way to gather those parameters is to paste the URL of the report/cohort you wish to sync from your Mixpanel project, and the app should parse for them automatically:

<Frame>
  <img alt="gsheets-parse" />
</Frame>

In case the URL does not contain all the values you need, the UI requires:

* A [Service Account](/reference/service-accounts) (consumer or higher permission)
* A report URL with `mixpanel.com` or `eu.mixpanel.com` (to resolve data residency)
* your [project\_id](/docs/orgs-and-projects/managing-projects#viewing-project-information)
* your [workspace\_id](/reference/query-api-authentication#:~:text=Projects%20with%20Data,a%20request%20parameter.)
* [report\_id](/reference/insights-query#:~:text=The%20ID%20of%20your%20Insights%20report%20can%20be%20found%20from%20the%20url%3A%20https%3A//mixpanel.com/report/1/insights%23report/%3CYOUR_BOOKMARK_ID%3E/example%2Dreport) OR [cohort\_id](/reference/cohorts-list)

<Warning>
  Note: since v1.12 insights, funnels, & retention are the only supported reports.
</Warning>

Next, learn about [runs and syncs](/docs/tracking-methods/integrations/google-sheets#runs-and-syncs) below.

## Runs and Syncs

Each UI has a similar user interface for you to input your details with four key actions at the bottom:

<Frame>
  <img alt="gsheets-four-actions" />
</Frame>

* **Run:** run the current configuration once; results are display in the UI
* **Sync:** run the current configuration every hour; run receipts are stored in a log sheet
* **Save:** store the current configuration
* **Clear:** delete this sheet's sync and reload the UI

You may only have one sync active per sheet at a time. If you are planning to sync data from your sheet to Mixpanel, it is recommended that you do a "run" first.

Once created, syncs will run on an hourly schedule; they can also be manually triggered from the main menu by choosing **Sync Now!**:

<Frame>
  <img alt="gsheets-sync-now" />
</Frame>

<Warning>
  Note: since v1.12 syncs are not supported for events.
</Warning>

## Permissions

**Limited User Policy**

Sheets™ ⇔ Mixpanel use and transfer to any other app of information received from Google APIs will adhere to [Google API Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy#additional_requirements_for_specific_api_scopes), including the Limited Use requirements.

The app is free to use and does not contain ads, nor will any data collected by Sheets™ ⇔ Mixpanel be resold in any way. No human can read your spreadsheets; usage data is collected and anonymized only to improve the end-user's experience.

**Permissions**

Using the principle of least-privilege, Sheets™ ⇔ Mixpanel requests access to three sensitive scopes to support application functionality, which are explained below:

* `https://www.googleapis.com/auth/script.container.ui` is used to draw a dynamic UI which maps the columns headers of your currently active Google Sheet™ into dropdowns in the extension interface.
* `https://www.googleapis.com/auth/script.scriptapp` is used to support scheduled hourly "sync" functionality so the pipeline you've configured in the UI can run automatically.
* `https://www.googleapis.com/auth/script.external_request` is used to send your mapped data to mixpanel and to request your report/cohort data from mixpanel.

No other sensitive scopes are requested by the application.

## FAQ

**1. Why isn't my recurring sync exporting data, even though a manual run works?**

A recurring sync that is not exporting data despite a functional manual sync may be indicative of a stale trigger caused by the extension entering a bad state (could be caused by a number of reason originating in your local Google Workspace instance).

As a troubleshooting step please navigate to [Apps Script > My Triggers from your Google Workspace](https://script.google.com/home/triggers), delete the existing Mixpanel Sheets extension trigger, then try creating a new recurring sync to generate a new trigger.

**2. Why is my sync failing to authenticate even though I entered the correct Mixpanel credentials?**

Some users report seeing the error `Authorization is required to perform that action.` when setting up a sync, despite providing the correct Mixpanel authentication. This issue occurs when you are logged into multiple Google accounts simultaneously, where the sheet is owned by one account (e.g., personal) but the extension is installed on another account (e.g., business).

To resolve the issue, log out and reinstall the extension on the same account you use to access the sheet.


# Google Tag Manager
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/google-tag-manager



This page walks through Mixpanel's native integration with Google Tag Manager (GTM). The source code is hosted [here](https://github.com/mixpanel/mixpanel-gtm-template) for reference.

## Installation

Our [video walkthrough](https://user-images.githubusercontent.com/556882/154125933-b584de10-b7fa-4668-b815-7429192d867a.mp4) demonstrates how get started using our GTM template.

<Frame>
  <video>
    <source type="video/mp4" />
  </video>
</Frame>

The easiest way to install the custom template is to locate it in the [Google Tag Manager community template gallery](https://tagmanager.google.com/gallery/#/owners/mixpanel/templates/mixpanel-gtm-template). You can install the template via the Google Tag Manager user interface.

To **manually install** the template, e.g. for debugging prior to the changes being published in the community template gallery, follow the steps below:

1. Download the `./src/template.tpl` file locally.
2. Open a **Google Tag Manager** *Web* container via the [Google Tag Manager user interface](https://tagmanager.google.com/). Preferably one already deployed on a website where you can test the template in real-world use cases. (Learn more about creating a container [here](https://support.google.com/tagmanager/answer/14842164?hl=en\&ref_topic=15191151\&sjid=13808649871508707391-NC))
3. In the GTM UI, browse to **Templates**, and in the box titled **Tag Templates**, click the blue **New** button.
4. Once the **Template Editor** is open, click the menu (three vertical dots) in the top-right corner of the window and choose **Import**.
5. Select the `template.tpl` file you downloaded locally.
6. Follow the prompts. Once the import is complete, the Template Editor should show the Mixpanel template in edit mode.
7. Click **Save** to save the template, and then proceed to close the Template Editor.
8. In the GTM UI, browse to **Tags** and click **New** to create a new tag.
9. From the list of available tag templates, choose the **Mixpanel** template you just imported to the container.

## How It Works

The template brings the functionality of the [Mixpanel JS SDK](/docs/tracking-methods/sdks/javascript) to Google Tag Manager so that you can implement Mixpanel through the Tag Manager interface without needing to directly edit your website's code.

GTM will load our custom-created [Javascript wrapper](https://github.com/mixpanel/mixpanel-js/blob/master/src/loaders/mixpanel-js-wrapper.md) with predefined tags. These tags correspond to core [Javascript SDK methods](/docs/tracking-methods/integrations/google-tag-manager#tag-to-function-mapping). You can decide when to trigger each tag (on specific pages, button clicks, etc.).

The wrapper overcomes the restrictions GTM's templating system places on available Javascript APIs.

## Initialization

When *any* Mixpanel GTM tag fires, it automatically tries to initialize a new instance using the **Initialization Options** configured in the tag. If an instance with the given name has already been initialized on the page, the initialization process will be skipped.

This way, the user does not need to worry about initialization; just ensure that the Initialization Options are configured consistently across the tags.

### Custom Initialization Options

To add initialization options for capabilities like [Session Replay](/docs/tracking-methods/sdks/javascript#implementation--sampling) (`record_sessions_percent`), [Session Replay UI controls](/docs/tracking-methods/sdks/javascript/javascript-replay#remote-configuration) (`remote_settings_mode`), [Heatmaps](/docs/tracking-methods/sdks/javascript#heatmaps) (`record_heatmap_data`), [Feature Flags](/docs/featureflags), routing data to [EU Servers for EU Data Residency](/docs/tracking-methods/sdks/javascript#eu-data-residency), or routing data to [IN Servers for India Data Residency](/docs/tracking-methods/sdks/javascript#india-data-residency) to Google Tag Manager:

1. Add a new tag in GTM and choose the Mixpanel tag type
2. For the **Project Token** field, enter [your Mixpanel project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)
3. For **Tag Type**, select **init** from the dropdown
4. For **Initialization**, choose **Set Options Manually**
5. In the **Option** section, add the relevant key-value pair according to your needs. The config options are listed [here](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelset_config).

For example:

* `record_heatmap_data` as the key and set a boolean value of `true`
* `api_host: https://api-eu.mixpanel.com` if your project has EU Data Residency
* `api_host: https://api-in.mixpanel.com` if your project has India Data Residency

6. For the Triggering section, choose an early GTM lifecycle event, such as `Initialization - All Pages` or `Consent Initialization - All Pages`.

### Google Tag Manager with Custom Autocapture Configurations

To use [autocapture initialization options](/docs/tracking-methods/sdks/javascript#autocapture), such as `capture_extra_attrs` with GTM, you will need to create a [custom Javascript variable](https://support.google.com/tagmanager/answer/7683362?hl=en) in GTM, then use that variable for your Autocapture configuration.

<Steps>
  <Step title="Create a Custom Javascript Variable in GTM">
    First, create a Custom Javascript variable that returns the autocapture configuration object:

    1. In GTM, go to **Variables > User-Defined Variables > New**
    2. Choose **Custom Javascript** as the variable type
    3. Add code that returns the autocapture configuration object, including the `capture_extra_attrs` option

    For example, the Custom Javascript variable might look like this:

    ```javascript Javascript theme={"system"}
    function() {
     return {
       pageview: "full-url",
       click: true,
       input: true,
       scroll: true,
       submit: true,
       capture_extra_attrs: ['data-cta-name', 'data-cta-position']
     };
    }
    ```
  </Step>

  <Step title="Use the Variable in Your Mixpanel Tag">
    Once the custom variable is created:

    1. Edit the Mixpanel initialization tag in GTM
    2. For the Autocapture option, instead of selecting "Enabled" or "Disabled" from the dropdown, select the custom Javascript variable
  </Step>

  <Step title="Verify Your Implementation">
    After setting up the tag with the custom variable:

    1. Use GTM's [preview mode](https://support.google.com/tagmanager/answer/6107056?hl=en\&sjid=13808649871508707391-NC) to verify that the tag is firing correctly
    2. Check in the browser's developer console that the Mixpanel configuration includes the custom autocapture settings
    3. Verify in Mixpanel that the extra attributes are being captured with your events

    This approach allows for customized autocapture options beyond the simple enabled/disabled toggle that's available in the standard GTM template interface.
  </Step>
</Steps>

### Google Tag Manager with Feature Flag Configuration

Feature Flags allow you to control feature rollout, conduct A/B testing, and manage application behavior without deploying new code. Since the GTM integration wraps the [Mixpanel JavaScript SDK](/docs/tracking-methods/sdks/javascript), feature flags are implemented using the same JS SDK methods. For a full reference, see the [Feature Flags overview](/docs/featureflags) and [JavaScript SDK flags guide](/docs/tracking-methods/sdks/javascript/javascript-flags).

#### Flag Initialization

1. Open your Mixpanel `init` tag in GTM
2. Under Feature Flags,

   * a) Select Enabled to enable feature flag fetching.
   * b) If your flags use a data group key as a custom Variant Assignment Key (e.g., `company_id`) or Runtime Targeting, you'll need to pass a context object.

     * You can create a **Custom JavaScript Variable** that returns the flags config object:

       ```javascript Javascript theme={"system"}
       function() {
         return {
           context: {
             company_id: "your_company_id",
             custom_properties: {
               platform: "web",
             },
           },
         };
       }
       ```
     * You can create a **Data Layer Variable** in GTM whose value is set by your application to return the flags config object, and then reference that variable in your Mixpanel init tag.

#### Flag Evaluation

There are multiple ways to evaluate feature flags after initialization of the Mixpanel tag in GTM.

The most flexible way would be to direct use in your application by referencing `window.mixpanel` which is available once GTM loads the Mixpanel tag

```javascript Javscript theme={"system"}
// Check if a Feature Gate flag is enabled
await window.mixpanel.flags.is_enabled("flag_key", false)

// Get the variant value for an Experiment or Dynamic Configuration flag
await window.mixpanel.flags.get_variant_value("flag_key", "control")
```

Alternatively, you can implement this logic in GTM directly such as in Custom HTML tags or in Custom Javascript variables to evaluate flags and push the results to the data layer for use by your implementation.

If the current user is in your feature flag rollout, evaluation will trigger tracking an exposure event, `$experiment_started`, to Mixpanel.

## Sending Mixpanel Commands

After adding the **Project Token** to its respective field, you need to choose what **type** of tag to use. Each type corresponds with some command you can use with the Mixpanel Javascript API.

<Warning>
  Note that `init`, `push`, and any of the "getter" commands are not supported in the template.
</Warning>

The more complex tag types (`group`, `people`, and `track`) are elevated to the top of the drop-down menu with the `-` prefix to separate them from the other commands.

Once you select a tag type, **additional options may appear.** Please have a look at the SDK reference for details on how to configure these options.

### GTM Template Default Overrides vs. JS SDK

As of October 2025, the GTM template sets two initialization defaults that differ from the JS SDK. This applies to anyone who installed the template fresh or opted into new versions of the template update.

| Option                 | GTM Template Default | JS SDK Default |
| ---------------------- | -------------------- | -------------- |
| `persistence`          | `localStorage`       | `cookie`       |
| `stop_utm_persistence` | `true`               | `false`        |

Switching between template versions and/or the JS SDK without accounting for these can change how persistent user data is stored and whether UTM parameters persist across subsequent events. To override either, add them as [Custom Initialization Options](#custom-initialization-options).

### Tag to Function Mapping

**Essential Tags**

These are tags you will likely need in any Mixpanel-GTM implementation:

| GTM Tag Type     | Equivalent Mixpanel SDK Method (Link to Spec)                                                                                                 | Function Description                                                                                                                                                                            |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Track          | [`track`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneltrack)                   | Tracks an event. This is the most important and frequently used Mixpanel function.                                                                                                              |
| - Track Pageview | [`track_pageview`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneltrack_pageview) | Tracks a default Mixpanel page view event, which can include extra default event properties to improve page view data                                                                           |
| init             | [`init`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelinit)                     | Initializes a new instance of Mixpanel                                                                                                                                                          |
| identify         | [`identify`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelidentify)             | Identifies a user with a unique ID to track user activity across devices and ties a user to their events. If using feature flags, this will also trigger a reload of flags with the new user id |
| register         | [`register`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelregister)             | Registers a set of [super properties](/docs/tracking-methods/sdks/javascript#setting-super-properties), which are included with all events. Overwrites existing super properties if present     |
| reset            | [`reset`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelreset)                   | Clears super properties and generates a new random distinct\_id                                                                                                                                 |

**Group Tags for Group Analytics**

| GTM Tag Type    | Equivalent Mixpanel SDK Method (Link to Spec)                                                                                                | Function Description                                                              |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| add\_group      | [`add_group`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneladd_group)          | Adds a new group for the user                                                     |
| remove\_group   | [`remove_group`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelremove_group)    | Removes a group from the user                                                     |
| set\_group      | [`set_group`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelset_group)          | Registers the current user into one/many groups                                   |
| group.remove    | [`group.remove`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelgroupremove)     | Removes a group property from a group. The value will be ignored if doesn't exist |
| group.set       | [`group.set`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelgroupset)           | Sets properties on a group, overwriting existing values if present                |
| group.set\_once | [`group.set_once`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelgroupset_once) | Set properties on a group, only if they do not yet exist                          |
| group.union     | [`group.union`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelgroupunion)       | Merges a given list with a list-valued group property, excluding duplicate values |
| group.unset     | [`group.unset`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelgroupunset)       | Unsets properties on a group permanently                                          |

**People Tags for User Profiles**

| GTM Tag Type        | Equivalent Mixpanel SDK Method (Link to Spec)                                                                                                        | Function Description                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| people.append       | [`people.append`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeopleappend)           | Appends a value to a list-typed user property                                               |
| people.delete\_user | [`people.delete_user`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeopledelete_user) | Permanently deletes the current user profile from Mixpanel (using the current distinct\_id) |
| people.increment    | [`people.increment`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeopleincrement)     | Increments/decrements numeric user profile properties                                       |
| people.remove       | [`people.remove`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeopleremove)           | Removes a value from a list-typed user property                                             |
| people.set          | [`people.set`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeopleset)                 | Sets properties on a user profile, overwriting existing values if present                   |
| people.set\_once    | [`people.set_once`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeople.set_once)      | Sets properties on a user profile, only if they do not yet exist                            |
| people.union        | [`people.union`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeople.union)            | Merges a given list with a list-valued user property, excluding duplicate values            |
| people.unset        | [`people.unset`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeople.unset)            | Unsets properties on a user profile permanently                                             |

**Additional Mappings**

| GTM Tag Type                  | Equivalent Mixpanel SDK Method (Link to Spec)                                                                                                                       | Function Description                                                                                                                                                                                                                                                                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| alias                         | [`alias`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelalias)                                         | Creates an alias which Mixpanel will use to remap one id to another (Only relevant for projects using [Legacy ID Management](https://github.com/mixpanel/docs-legacy/blob/main/legacy/aliases.md#manage-identity-with-alias-and-identify-methods) or [Original ID Merge](/docs/tracking-methods/id-management/identifying-users-original)) |
| clear\_opt\_in\_out\_tracking | [`clear_opt_in_out_tracking`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelclear_opt_in_out_tracking) | Clears the user's opt in/out status and sets it to the default specified in `init` (`false` by default)                                                                                                                                                                                                                                    |
| disable                       | [`disable`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneldisable)                                     | Disables specific events from being tracked                                                                                                                                                                                                                                                                                                |
| opt\_in\_tracking             | [`opt_in_tracking`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelopt_in_tracking)                     | Opts the user in to data tracking and cookies/localstorage                                                                                                                                                                                                                                                                                 |
| opt\_out\_tracking            | [`opt_out_tracking`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelopt_out_tracking)                   | Opts the user out of data tracking and cookies/localstorage                                                                                                                                                                                                                                                                                |
| register\_once                | [`register_once`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelregister_once)                         | Registers a set of super properties only once. This will not overwrite existing super properties                                                                                                                                                                                                                                           |
| set\_config                   | [`set_config`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelset_config)                               | Updates the configuration for the Mixpanel instance                                                                                                                                                                                                                                                                                        |
| time\_event                   | [`time_event`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneltime_event)                               | Starts timing an event by including the time between this call and a later 'track' call for the same event as the `$duration` event property                                                                                                                                                                                               |
| track\_forms                  | [`track_forms`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneltrack_forms)                             | Tracks form submissions                                                                                                                                                                                                                                                                                                                    |
| track\_links                  | [`track_links`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneltrack_links)                             | Track clicks on a set of document elements                                                                                                                                                                                                                                                                                                 |
| start\_session\_recording     | [`start_session_recording`](/docs/session-replay/implement-session-replay/session-replay-web#start-capturing-replay-data)                                           | Forces recording to begin, regardless of the `record_sessions_percent` init option. This will have no effect if replay data collection is already in progress                                                                                                                                                                              |
| stop\_session\_recording      | [`stop_session_recording`](/docs/session-replay/implement-session-replay/session-replay-web#stop-capturing-replay-data)                                             | Stops any active replay data collection. This will have no effect if there is no replay data collection in progress                                                                                                                                                                                                                        |
| unregister                    | [`unregister`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelunregister)                               | Delete a super property stored with the current user                                                                                                                                                                                                                                                                                       |

## Firing The Tag

Once you are happy with your tag, add a [Trigger](https://support.google.com/tagmanager/topic/7679384?hl=en\&ref_topic=3441647,3441645,2789291,\&sjid=13808649871508707391-NC) to it. For example, to trigger your tag with every page load, add the **All Pages** trigger.

Be sure to save the tag once you are done.

## Testing

You can then enter [Preview mode](https://support.google.com/tagmanager/answer/6107056?hl=en\&sjid=13808649871508707391-NC) by clicking the blue **Preview** button in the Google Tag Manager UI. This opens a new tab with your website running the GTM container, and you can proceed to test the Mixpanel tag as if the container were published. In the Tag Assistant Preview tab, you can see additional information about the trigger events, tags, and variables that fire while you are browsing the page in Preview mode.

You can also enable the Javascript SDK's [Debug Mode](/docs/tracking-methods/sdks/javascript#debug-mode) by following [Steps 1-4](http://localhost:3000/docs/tracking-methods/integrations/google-tag-manager#custom-initialization-options). Then, add `debug` and `true` as an Option key and Option value, respectively.

## FAQ

### Why is my Mixpanel tag not firing?

* Ensure that the tag is properly configured with the correct Project Token in your Project Settings
* Verify that the trigger conditions are met. For example, if you set the tag to fire on "All Pages," make sure you are testing on a page that matches this condition.
* Check the browser console for any Javascript errors that might be preventing the tag from executing
* Use the GTM Preview mode to see if the tag is firing and if there are any errors in the console

### Why are my events not found in Mixpanel?

* Check if the Project Token in the GTM tag matches the one in your Mixpanel project settings
* Use GTM Preview mode to ensure tags are firing.
* Check the browser console for Mixpanel logs (enable debug mode).
* Disable ad blockers, as they can [block client-side tracking](/docs/tracking-best-practices/debugging#ad-blockers-and-do-not-track-settings).
* Make sure your variables are set up correctly.

### Does the Mixpanel template work with iOS/Android/AMP/Server Containers?

The Mixpanel GTM template *only* works with web containers.


# Langfuse
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/langfuse



[Langfuse](https://langfuse.com) is an open-source LLM engineering platform that provides observability and analytics for AI applications. This integration allows you to **automatically sync LLM metrics from Langfuse into your Mixpanel dashboards**, enabling you to understand how your AI features impact user behavior and business outcomes.

Use this integration to answer questions like:

* *"Are my most active users also the ones who are most engaged with my LLM content?"*
* *"Does interacting with the LLM feature relate to higher retention rates?"*
* *"How does the LLM feature impact my conversion rates?"*
* *"Does the user feedback captured in Langfuse correlate with user behavior in Mixpanel?"*

## Setup

### Prerequisites

* An active Langfuse account with a project configured
* Your Mixpanel Project Token (found in Project Settings)

### Configure the integration

1. Log into your Langfuse account and navigate to your project settings
2. Find the Mixpanel integration section
3. Select your Mixpanel region:

   * **US**: api.mixpanel.com
   * **EU**: api-eu.mixpanel.com
   * **India**: api-in.mixpanel.com
4. Enter your Mixpanel Project Token
5. Enable the integration

### Data synchronization

Once enabled, Langfuse will:

* Perform an initial sync of all historical data from your Langfuse project
* Automatically sync new data every hour (with a 30-minute delay)

Your Mixpanel dashboards will stay up to date with your latest LLM metrics.

## Data Schema

### User Matching

Langfuse automatically maps user identifiers to ensure seamless data integration:

| Langfuse Field                        | Mixpanel Field | Description                                                                                 |
| ------------------------------------- | -------------- | ------------------------------------------------------------------------------------------- |
| `user_id`                             | `distinct_id`  | Primary user identifier                                                                     |
| Trace/generation/score timestamp      | `time`         | Event timestamp (milliseconds since epoch)                                                  |
| `trace.metadata.$mixpanel_session_id` | `session_id`   | Optional session identifier (add this to your Langfuse trace metadata for session tracking) |

### Events

The integration sends three event types to Mixpanel:

#### `[Langfuse] Trace`

Represents a complete LLM interaction (e.g., a user conversation or workflow).

**Properties:**

* `time`: Milliseconds since epoch when the event occurred
* `distinct_id`: User ID or anonymous identifier
* `$user_id`: User ID sent to Mixpanel's native user ID field
* `$insert_id`: Unique identifier for deduplication
* `session_id`: Optional session identifier (from `$mixpanel_session_id` in metadata, or falls back to Langfuse session\_id)
* `langfuse_trace_name`: The name of the trace
* `langfuse_url`: The URL of the trace in Langfuse
* `langfuse_user_url`: Deep link to the user profile in Langfuse
* `langfuse_id`: The unique identifier of the trace
* `langfuse_cost_usd`: The total cost associated with the trace
* `langfuse_count_observations`: The number of observations (LLM calls) in the trace
* `langfuse_session_id`: The session ID related to the event
* `langfuse_project_id`: The project ID associated with the event
* `langfuse_user_id`: User ID related to the event (defaults to `langfuse_unknown_user` if null)
* `langfuse_latency`: The latency of the trace in milliseconds
* `langfuse_release`: Release information associated with the trace
* `langfuse_version`: The version of the trace
* `langfuse_tags`: Tags associated with the trace
* `langfuse_environment`: The environment associated with the trace (e.g., production, staging)
* `langfuse_event_version`: The integration version of Langfuse

#### `[Langfuse] Generation`

Represents an individual LLM generation (e.g., a single API call to OpenAI, Anthropic, etc.).

**Properties:**

* `time`: Milliseconds since epoch when the generation started
* `distinct_id`: User ID or anonymous identifier
* `$user_id`: User ID sent to Mixpanel's native user ID field
* `$insert_id`: Unique identifier for deduplication
* `session_id`: Optional session identifier (from `$mixpanel_session_id` in metadata, or falls back to Langfuse session\_id)
* `langfuse_generation_name`: The name of the generation
* `langfuse_trace_name`: Name of the trace related to the generation
* `langfuse_trace_id`: The unique identifier of the trace related to the generation
* `langfuse_url`: The URL of the generation in Langfuse
* `langfuse_user_url`: Deep link to the user profile in Langfuse
* `langfuse_id`: Unique identifier of the generation
* `langfuse_cost_usd`: Computed total cost of the generation
* `langfuse_input_units`: Number of tokens used in the input/prompt
* `langfuse_output_units`: Number of tokens produced by the generation
* `langfuse_total_units`: Total number of tokens consumed in the generation process
* `langfuse_session_id`: The session ID associated with the trace of the generation
* `langfuse_project_id`: The project ID where the generation occurred
* `langfuse_user_id`: The user ID that started the trace linked to the generation (defaults to `langfuse_unknown_user` if unavailable)
* `langfuse_latency`: The observed latency of the generation in milliseconds
* `langfuse_time_to_first_token`: The time taken to generate the first token when streaming (milliseconds)
* `langfuse_release`: Release information of the trace attached to the generation
* `langfuse_version`: The version information about the generation
* `langfuse_model`: The model used during this generation (e.g., gpt-4, claude-3-sonnet)
* `langfuse_level`: The level associated with the generation
* `langfuse_tags`: Tags attached to the trace of the generation
* `langfuse_environment`: The environment associated with the generation
* `langfuse_event_version`: The integration version with Langfuse

#### `[Langfuse] Score`

Represents user feedback, evaluations, or quality metrics.

**Properties:**

* `time`: Milliseconds since epoch when the score event occurred
* `distinct_id`: User ID or anonymous identifier
* `$user_id`: User ID sent to Mixpanel's native user ID field
* `$insert_id`: Unique identifier for deduplication
* `session_id`: Optional session identifier (from `$mixpanel_session_id` in metadata, or falls back to Langfuse session\_id)
* `langfuse_score_name`: The name associated with the score (e.g., "user\_feedback", "accuracy")
* `langfuse_score_value`: The numeric value of the score
* `langfuse_score_string_value`: The string value of the score (for BOOLEAN and CATEGORICAL scores)
* `langfuse_score_data_type`: The data type of the score (NUMERIC, BOOLEAN, or CATEGORICAL)
* `langfuse_score_comment`: Comments attached to the score
* `langfuse_score_metadata`: Additional metadata attached to the score
* `langfuse_trace_name`: The name of the trace associated with the score
* `langfuse_trace_id`: The unique identifier of the trace associated with the score
* `langfuse_user_url`: Deep link to the user profile in Langfuse
* `langfuse_id`: The unique identifier of the score
* `langfuse_session_id`: The session ID related to the score's trace
* `langfuse_project_id`: The project ID linked with the score's trace
* `langfuse_user_id`: The user ID that triggered the trace tied to the score (defaults to `langfuse_unknown_user` if not available)
* `langfuse_release`: The release information of the trace associated with the score
* `langfuse_tags`: Tags related to the trace of the score
* `langfuse_environment`: The environment associated with the score
* `langfuse_event_version`: The integration version with Langfuse

## Use Cases

### Get Started with the Analytics for AI Dashboard Template

The fastest way to see value from this integration is to use Mixpanel's **Analytics for AI dashboard template**. This pre-built dashboard provides instant insights into how your LLM features are performing and how they impact user behavior.

[**View the Analytics for AI Dashboard Template →**](https://mixpanel.com/p/NaKPyubj6EuA4oV75taqrq)

The template includes ready-to-use reports for:

* **LLM Feature Adoption**: Track how many users are engaging with your AI features
* **Cost Analysis**: Monitor your LLM spending by user and feature
* **Performance Metrics**: Visualize latency, token usage, and generation times
* **User Feedback**: Analyze scores and ratings from Langfuse
* **Retention Impact**: Understand retention rates of AI feature users

### Analyze LLM Feature Adoption

Create funnels to track:

* Users who trigger `[Langfuse] Trace` events
* Conversion to key actions in your product
* Retention rates for AI feature users vs. non-users

### Monitor LLM Costs by User Segment

Build insights to:

* Group users by `langfuse_cost_usd` total spend
* Segment by user properties (plan type, company size, etc.)
* Identify high-cost users or sessions

### Correlate User Feedback with Behavior

Analyze how `[Langfuse] Score` events relate to:

* Session length and engagement
* Feature usage patterns
* Churn or upgrade likelihood

### Track Model Performance Impact

Compare:

* `langfuse_latency` across different `langfuse_model` values
* Token usage efficiency (`langfuse_total_units`)
* Cost differences between model versions

## Troubleshooting

**Events not appearing in Mixpanel?**

* Verify you selected the correct Mixpanel region in Langfuse
* Confirm your Project Token is correct
* Allow up to 90 minutes for the first sync to complete
* Check that your Langfuse project has trace data

**User matching issues?**

* Ensure the `user_id` in Langfuse matches the `distinct_id` in Mixpanel
* For session tracking, add `$mixpanel_session_id` to your Langfuse trace metadata

**Need additional help?** Contact Langfuse support or submit a feature request on their [ideas board](https://langfuse.com/ideas).

## Learn More

* [Langfuse Mixpanel Integration Documentation](https://langfuse.com/integrations/analytics/mixpanel)
* [Langfuse Documentation](https://langfuse.com/docs)
* [Langfuse GitHub](https://github.com/langfuse/langfuse)
* [LLM Observability Best Practices](https://langfuse.com/docs/observability)


# LaunchDarkly
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/launchdarkly



## Overview

This guide helps send LaunchDarkly feature flag impressions as events to Mixpanel. This is useful if you want to answer questions like:

* What did my users do after being exposed to an experiment?
* Did users who were exposed convert better than users who didn't?
* Were the right set of users exposed to my experiment?

Doing this involves sending impression events from LaunchDarkly to Mixpanel and doing the analysis in Mixpanel.

## Exporting data from LaunchDarkly

In order to perform its analyses, Mixpanel needs impression events. These events tell Mixpanel which user was exposed to which variant at which time.

These events must be called `$experiment_started` and must have the `Experiment name` and `Variant name` properties -- Mixpanel recognizes these events and uses them to autopopulate the [Experiments report](/docs/experiments).

```json theme={"system"}
{
  "event": "$experiment_started",
  "properties": {
    "distinct_id": "alice@example.com",
    "time": 1709275888,
    "Experiment name": "my_experiment",
    "Variant name": "control"
  }
}
```

LaunchDarkly does not export this by default, so there are two options:

1. Pay to [export](https://docs.launchdarkly.com/home/getting-started) from LaunchDarkly to Pubsub. If you go this route, you will need to write some code that pulls from PubSub and pushes to Mixpanel. We have a sample guide [here](/docs/tracking-methods/integrations/google-pubsub). This is server-side, so will likely be more accurate, but requires more work to integrate.
2. Log assignments with wrapper code (see [below](#logging-assignments-with-wrapper-code)). This is more convenient, but can be less reliable due to the limitations of client-side tracking.

## Logging assignments with wrapper code

To manually log LaunchDarkly assignments, you'll need to find all places in your code where feature flags are being invoked and replace with a wrapper function. The example below is based on Javascript, see [LaunchDarkly SDK documentation](https://docs.launchdarkly.com/sdk) to find the syntax for your language of choice.

### Find all places where feature flags are being invoked

LaunchDarkly’s SDK exposes methods for retrieving whether or not a feature is enabled for the current user.

```js theme={"system"}
const variation = client.variation("YOUR_EXPERIMENT_KEY", "control");
if (variation == "variant_abc") {
  // show the variant you are testing
} else if (variation == "control") {
  // show control
}
```

### Track events to Mixpanel

In order to capture assignment data, every time the feature flag is invoked, you need to log the user, timestamp, and which experiment and variant they're seeing.

To do this for all experiments, we recommend wrapping the code that checks whether a feature flag is enabled in a helper function. You can then call `mixpanel.track` to send an event as part of that helper function:

```js theme={"system"}
function checkFeatureEnabled(experimentKey, defaultValue) {
  // determine whether or not this feature is enabled for the current user
  const variation = client.variation(experimentKey, defaultValue);

  // This assumes the Mixpanel SDK is initialized
  // Note: Use this precise event name
  mixpanel.track("$experiment_started", {
      "Experiment name": experimentKey,
      "Variant name": variation,
  });

  // return the variation
  return variation;
}
```

It is possible that an engineer on your team could call this new function before showing the new feature to the user. Be sure that the assignment event is only sent once the user experiences the feature you are experimenting on.

## Using the events in Mixpanel

If you track events according to the above spec, you can use the [Experiments report](/docs/experiments) to get a bird's eye view of all experiments you have running.

You can also build [cohorts](/docs/users/cohorts) of users in each variant, and then filter/breakdown by those cohorts in any report in Mixpanel.


# Mobile Attribution
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/mobile-attribution-tracking



Determining the source and channels for your mobile traffic can be complex to set up yourself, especially for installs, since the user goes mainly through the Google Play Store or the Apple App Store before continuing their journey, and mapping that can be a challenge. In our view, it’s best to partner with a service that can focus on reliably mapping that journey, and [we have a list of partners](https://mixpanel.com/partners/integrations?categories=attribution-deep-linking) that we encourage customers to review for this purpose.

> Specifically for Android installs, the Android SDK itself supports a function called [getInstallReferrer](https://developer.android.com/reference/com/android/installreferrer/api/ReferrerDetails#getInstallReferrer\(\)) which you can leverage to parse some of the source data if you’d prefer to not implement through a partner, although for a smaller subset of the attribution data.

Mobile attribution partner integrations work in 3 main ways:

* Webhooks/Callbacks: the partner sends the attribution data to your servers
* SDK → SDK integrations: your app leverages the partner SDK to send the data to Mixpanel
* Partner Server → Mixpanel integrations; the partner directly sends the data to Mixpanel

Each one has its benefits and drawbacks, although **usually Webhooks or the SDK → SDK route will be the best fit** in terms of configuration and correctness.

## Webhooks

Some of our partners support webhooks (or callbacks); the idea being that you can set up the partner so that when there’s new data for an install/re-engagement, said data is sent from the partner to your server or a service of your choosing (if you want to offload processing it). The data you receive will have an install/device ID and the attribution data. You can then either choose to send that data directly to Mixpanel ([through our ingestion APIs](/reference/import-events)) or, better yet, store it in a data warehouse so you have that on your end, and leverage [our data warehouse connectors](/docs/tracking-methods/warehouse-connectors) to import that data to Mixpanel.

> **Note**: Adjust is just selected alphabetically from the list of partners. We encourage customers to review the list and choose based on the ones that fit their requirements best.

Picking Adjust as a partner to provide an example, we can see their section [on callbacks here](https://help.adjust.com/en/article/server-callbacks#single-activity-callbacks). The callback returns, as one of the values, an `adid` (Adjust device ID). This is also a value you will have available in the SDK in the client. You can send this to your own server from the client so that, when you receive that `adid` value, you know which user this belongs to, so you can send the data to Mixpanel with the right distinct\_id.

To fully illustrate the workflow, you could create a table in your DB that holds the attribution data for the device with the `adid` value as the primary key (data that you will receive from the webhook). Then, when the app launches, you will have both the `adid` from the SDK as well as the distinct\_id from Mixpanel after you initialize the library, which you can update your table with, and if the user authenticates, you will also have a map of `adid` to authenticated user ID which you can also update. You can then build a view that has the event data you want to send in which you would use the distinct\_id from after initializing the library to send the event with and, if you also have the user ID (because the user authenticated), you can create another view for the profile using the user ID as the distinct\_id (profiles should be created with the authenticated ID only). Both of those views can be directly connected to the project via the data warehouse connector or you can also design a process that reads from the view and sends the data to our APIs.

**Advantages:**

* Highly configurable. Once you receive the data, you can choose how to send the data to Mixpanel, what part of that data, and even transform it before you send it
* Highest level of data accuracy. As you can edit/transform the data before you send it, it gives you the ability to further clean/transform the data you ultimately send. As a use case, sometimes, the attribution source for a device changes (even for the install). If the partner supports sending you callbacks for each of the values of the attribution, you can receive that data and choose what best fits your use case to then send it to Mixpanel

**Disadvantages**:

* Requires setup in your server (or another 3rd party service) to receive the partner’s webhook and process it.

## SDK to SDK

Another recommended way to approach this which is highly configurable would be to leverage the partner’s SDK (which you need to install in any of the solutions), and when the app launches for the first time, you would use their SDK to query the attribution data asynchronously. Once you receive it on the device, assuming you also have Mixpanel’s SDK installed, you can then track the attribution through both sending your own install event with that data and, potentially, also sending it to your server or storing it in local storage (that way, if the user authenticates, you can also choose to store it in the profile from the value you had already saved).

> **Note**: Adjust is just selected alphabetically from the list of partners. We encourage customers to review the list and choose based on the ones that fit their requirements best.

Picking Adjust as a partner to provide an example, in their docs, we can see [the section of the documentation](https://help.adjust.com/en/article/mixpanel-sdk-integration) which refers to querying the attribution data in the device. Once you download the data, an example workflow would be to check local storage (shared preferences) and if you have not yet stored the attribution data, you would proceed to do so and also send the app install event with properties with said attribution data. Below you will see an example of that idea for Android:

```java theme={"system"}
private trackAttribution(AdjustAttribution attribution){
		if(isAttributionAlreadyStored()){ //function to check if the data is already on the device
		    return;// data already stored, nothing to do
		}
		JSONObject props = new JSONObject();
		insertJsonProperty(props, "[Adjust]Network", attribution.network);
		insertJsonProperty(props, "[Adjust]Campaign", attribution.campaign);
		insertJsonProperty(props, "[Adjust]Adgroup", attribution.adgroup);
		insertJsonProperty(props, "[Adjust]Creative", attribution.creative);
		
		storeAttribution(props); //store the data for later user
		mixpanel.track("install", props);//send the install event since this is the first time it has been received
}
private void insertJsonProperty(JSONObject props, String name, String value) {
    try {
        if (value != null) {
            props.put(name, value);
        }
    } catch(JSONException e) { }
}
```

**Advantages:**

* Highly configurable. Once you receive the data, you can choose how to send the data to Mixpanel, what part of that data
* Does not require any additional infrastructure to maintain
* Less likely to cause ID management issues as all the tracking is done via the Mixpanel SDK so there is no other potential ID to join from other systems.

**Disadvantages:**

* Requires a bit more implementation work than Partner Server to Mixpanel and requires app updates to pause/resume

## Partner Server to Mixpanel

Most of our attribution partners support a form of server-to-server integration. The main idea is that you will install the partner’s SDK in your app and follow their configuration instructions. Part of those instructions usually involve querying Mixpanel’s distinct\_id (unique ID for the user) in the device and sending that over to their server. Once the partner has the attribution data, as well as knows which is the distinct\_id for that user in that device, they will send said data in the form of events and properties (as well as profile properties) directly from the partner server to Mixpanel.

**Advantages**:

* These kinds of integrations usually require the least amount of setup on the app. If you don’t track events in Mixpanel from the app directly (just from the server) could sometimes even be done without an app update.
* Once set up, you can enable/disable the functionality from the partner’s page without another app update, and change some settings

**Disadvantages**:

* ID management issues; by default, the partner will send the data with an ID of their choosing which will be different from the one you’re tracking events with, so you can get into a state in which the data sent from the integration is not connected to the user data you’ve tracked otherwise.
* Hidden profiles; even when setting up ID management correctly, if sending profile data is enabled, anonymous profiles can be created for users which can be problematic as (on ID merge enabled projects) you can merge events, but merging profiles is not supported, which can lead to 1 (or more) profiles to be hidden if you have multiple profiles for the user.
* Not as configurable; events and properties will be sent with the defaults sent by the partner which some partners have configuration options for, but can be limited.


# mParticle
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/mparticle



## Overview

[mParticle](https://www.mparticle.com/) is a customer data platform (CDP) that enables you to track event data and route it to various downstream destinations. As a native partner, Mixpanel seamlessly integrates with mParticle. If you use mParticle for tracking, you can send your data to Mixpanel with just a few clicks.

## How the Integration Works

In simple terms, mParticle collects data from any number of inputs (mParticle APIs, mobile apps, web, external feeds), transforms it, and then forwards it to your Mixpanel project.

mParticle forwards two main types of data:

* **Event Data:** Any action done by users in your app
* **Audience Data:** Data about users, including profile properties

Refer to the [mParticle Getting Started Guide](https://docs.mparticle.com/guides/getting-started/create-an-input) for detailed instructions on how to install mParticle.

## Setup

<Note>
  The mParticle to Mixpanel integration relies on your mParticle data implementation schema and must align with the requirements outlined below. While many mParticle SDK methods generally align with Mixpanel's, not all are supported. This may take some fine-tuning and testing to ensure the accuracy of the data.
</Note>

### 1. Install mParticle

Install mParticle as outlined in the [Getting Started Guide](https://docs.mparticle.com/guides/getting-started/create-an-input).

### 2. Add Mixpanel as a destination in the Connections Workflow

Add Mixpanel as a downstream destination in your [Connections Workflow](https://docs.mparticle.com/guides/platform-guide/connections/). This is configured in **Data Platform > Setup > Outputs** in the mParticle UI.

#### Configuration Settings

| Setting Name             | Data Type | Default Value   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------ | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Project Token (Required) | `string`  | none            | Found in your Mixpanel project settings.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Project API Secret       | `string`  | none            | Found in your Mixpanel project settings. This is required to forward Historical Data older than 5 days, which is sent to [Mixpanel's import API](/reference/import-events).                                                                                                                                                                                                                                                                                                                             |
| External Identity Type   | `string`  | Customer Id     | This is the identifier sent to Mixpanel to be used as a user's distinct ID. mParticle recommends using the `mparticle ID` for brand new implementations, which works in hand with the default [Profile Conversion Strategy](https://docs.mparticle.com/guides/idsync/profile-conversion-strategy/). This identifier acts as the distinct ID within mParticle to track pre- and post-identified activity. [More information on mParticle's IDSync](https://docs.mparticle.com/guides/idsync/use-cases/). |
| Target Server            | `string`  | Standard Server | Configure to match your [Mixpanel server residency](/docs/privacy/eu-residency).                                                                                                                                                                                                                                                                                                                                                                                                                        |

<Frame>
  <img alt="mparticle_output_mapping" />
</Frame>

#### Add Mixpanel Output to your connection

Under Setup > Connections, add your new Mixpanel output and select your settings:

| Setting Name                     | Data Type | Default Value        | Description                                                                                                                                                                                                                                                                  |
| -------------------------------- | --------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Use Mixpanel People              | `boolean` | true                 | Enable to send people to Mixpanel as users.                                                                                                                                                                                                                                  |
| Include User Attributes          | `boolean` | true                 | Enable to track user attributes as event properties.                                                                                                                                                                                                                         |
| Include Attribution Info         | `boolean` | false                | Enable to include publisher and campaign names when tracking events.                                                                                                                                                                                                         |
| Create Profile Only If Logged In | `boolean` | false                | If enabled, mParticle will only send data to Mixpanel for identified users.                                                                                                                                                                                                  |
| Include IP Address               | `boolean` | true                 | If enabled, Mixpanel will use the IP address for location data. IP addresses are not stored in events.                                                                                                                                                                       |
| Super Properties                 | `string`  | false                | Set super properties to be included with any event, regardless of the "Include User Attributes" setting. Must be in event data to populate in the dropdown. [Learn more about Mixpanel's super properties](/docs/tracking-methods/sdks/javascript#setting-super-properties). |
| Upper Case IDFA and IDFV         | `boolean` | false                | Enable to set IDFA and IDFV values as uppercase.                                                                                                                                                                                                                             |
| Forward Web Requests Server Side | `boolean` | false                | Enable to send web requests server side.                                                                                                                                                                                                                                     |
| Send Event Attributes as Objects | `boolean` | true                 | Enable to send attributes as objects (recommended).                                                                                                                                                                                                                          |
| Simplified ID Merge              | `boolean` | false                | Enable if using simplified ID merge.                                                                                                                                                                                                                                         |
| Min Platform Version             | `List`    | "Select App Version" | Filter by app version.                                                                                                                                                                                                                                                       |

[View all connection settings](https://docs.mparticle.com/integrations/mixpanel/event/#connection-settings)

<Note>
  If your project is using Simplified ID merge, you must set the "Simplified ID Merge" Connection Setting to `true` to merge `$device_id` and `$user_id` properly.
</Note>

### 3. Identify Users

Identify users calling `mParticle.Identity.Login()` when users sign up and log in.

mParticle has four [IDSync methods](https://docs.mparticle.com/developers/client-sdks/web/idsync/) on the web SDK:

* **Identify**: Called automatically at session start, which generates an anonymous ID.
* **Login**: Called on signup and login to identify a user.
* **Logout**: Called on logout to clear user data from local storage.
* **Modify**: Used to modify mParticle user identities, such as updating an email address. Typically, this will not be used with Mixpanel.

When identifying users, you need to provide the `customer ID` or other known value as determined by [mParticle's identity priorities](https://docs.mparticle.com/guides/idsync/components/#identity-priorities). While mParticle manages identity internally, the External ID value set in your mParticle configuration settings will be set as the `$distinct_id` for Mixpanel. While mParticle accepts several user identifiers, only one will be sent as the External ID to Mixpanel.

Here is an example `Login()` call using [mParticle's Web SDK](https://docs.mparticle.com/developers/client-sdks/web/idsync/). If you plan to set user attributes on signup, you need to include them in a callback function as mParticle runs these operations asynchronously. While email is included as an identifier, it is also included in the callback to be set as a profile property. If your project uses Customer ID as the External ID, then it would not be necessary to include email in the identity request for Mixpanel.

```javascript Javascript theme={"system"}
//create main request body of identifiers

let identityRequest = {
	userIdentities: {
		email: user.email,
		customerid: user.id
	}
};
//optional callback to set attributes after the identify call is complete

let identityCallback = function (result) {
	const mParticleUser = result.getUser();
	if (mParticleUser) {
		mParticleUser.setUserAttributes({
			favorite_genre: user.favorite_genre,
			plan_type: user.plan,
			app: "music-finder",
			email: user.email
		});
	} 
};

//send request body and callback to login endpoint

mParticle.Identity.login(identityRequest, identityCallback);
```

### 4. Create User Profiles

To create profiles and set profile properties, call `SetUserAttribute`. These will persist until overwritten. Note that if you identify a user in mParticle with email, it must also be set as an attribute to store it as a Mixpanel profile property.

Here is an example call to set user attributes:

```javascript Javascript theme={"system"}
// get current user

let currentUser = mParticle.Identity.getCurrentUser();

//set user attribute

currentUser.setUserAttribute("plan_type", "Premium");
```

### 5. Track User Actions

While each of mParticle's client SDKs [automatically captures some events](https://docs.mparticle.com/developers/client-sdks/web/event-tracking/#automatically-tracked-events), you can track custom events to send to Mixpanel.

Custom events contain the following attributes:

* A free-form name string
* A custom event type (required for custom events)
* A free-form map of custom attributes

Here is a simple custom event with event types defined beforehand:

```javascript Javascript theme={"system"}
//define event types - these are used to further classify your data.

EventType = {
  Navigation: 1,
  Location: 2,
  Search: 3,
  Transaction: 4,
  UserContent: 5,
  UserPreference: 6,
  Social: 7,
  Other: 8
}

//track the event

mParticle.logEvent(
  'Song Played', // event name
  mParticle.EventType.UserAction, // event type
{
  // custom attributes
  'Song Name':'Blinding Lights',
  'Artist': 'The Weeknd'
} 
);
```

### 6. Check for Success

[Open up Events View in Mixpanel](http://mixpanel.com/report/events) to view incoming events.

## Sending Audiences to Mixpanel using Cohorts

By default, mParticle does not have a way to map audiences to Mixpanel. Instead, you can forward an audience to Mixpanel by creating a profile property for users and then creating a cohort with that property. Here are the steps below:

1. Add an Audience Output under `Data Platform > Setup > Audience`. This is similar to creating your output, where you need to add your project token and match your data residency to your project.
2. Create an Audience (if none exist) under `Segmentation > Audiences` and specify your target output.
3. Activate your connection
4. Return to `Data Platform > Setup > Audience` and add the connected audience to the Audience Output.
5. Verify the size of the audience. You may need to wait until your audience has finished calculating, as shown by the percentage marker under audience. Smaller audience sizes (\< 100k) may not preview.

<Frame>
  <img alt="mparticle_audience_count" />
</Frame>

*mParticle will add a user property called "SegmentMembership" to audience members' user profiles in Mixpanel*

<Frame>
  <img alt="mixpanel_audience_property" />
</Frame>

6. Create a cohort in Mixpanel looking for the audience ID or name if you specified that in your setup.

<Frame>
  <img alt="mixpanel_mparticle_cohort" />
</Frame>

## Debugging

For debugging purposes, it can be useful to see exactly what mParticle is sending to Mixpanel.

You can validate this data through the [mParticle Live Stream](https://docs.mparticle.com/guides/platform-guide/live-stream/) and [Event Forwarding page](https://docs.mparticle.com/guides/platform-guide/event-forwarding/). You can also use the [mParticle Logger in your configuration](https://docs.mparticle.com/developers/client-sdks/web/custom-logger/) for real-time errors with your implementation.

### Live Stream

The Live Stream provides a real-time view of all data flowing in and out of mParticle.

Here, you can filter by source and examine the JSON data for specific events or which events/user attributes were included in a batch message.

Access the Live Stream page under **Data Platform > Live Stream** using the left navigation.

<Frame>
  <img alt="live_stream" />
</Frame>

### Event Forwarding

The Event Forwarding page provides an overview of the volume of data ingested by your inputs and the volume of data forwarded to your connected output integrations.

Access the Event Forwarding page under **Data Platform > Event Forwarding** using the left navigation.

Here, you can select your input(s) and any number of outputs to compare events ingested by mParticle and forwarded to Mixpanel to determine any unexpected discrepancies or errors. You can also [add filters to your connections](https://docs.mparticle.com/guides/platform-guide/data-filter/) to control which data goes into Mixpanel.

<Frame>
  <img alt="event_forwarding" />
</Frame>

### Logger

To log warnings and other information, please see the [mParticle's custom logger documentation](https://docs.mparticle.com/developers/client-sdks/web/custom-logger/). For example, the Web SDK allows you to set "logLevel" to `warning` or `verbose`.

```javascript Javascript theme={"system"}
window.mParticle = {
			config: {
				isDevelopmentMode: true,
				logLevel: 'verbose',
				appName: "music-finder"
			},
		};
```

## FAQ

**1. Why are my mParticle data not appearing in my project?**

This could be due to several reasons:

* **Storing data in the EU:** A common issue is that the data in mParticle is enabled to be sent to an EU endpoint, but the Mixpanel data is still being stored outside of the EU. Both endpoints for mParticle and Mixpanel need to point to the EU. Check your Mixpanel data residency in your project settings, and set your mParticle residency under `output configuration > Mixpanel Target Server`.

<Frame>
  <img alt="Mixpanel Residency" />
</Frame>

<Frame>
  <img alt="mParticle Residency" />
</Frame>

* **Project Token mismatch:** Please ensure the project token on your mParticle output matches the token in your Mixpanel project

**2. Why are there duplicate or disconnected profiles in Mixpanel?**

* This can happen if you are attempting to set profile attributes before calling `Login` or as a separate call at the same time as mParticle's login method. If you want to create a profile right after signing up, be sure to wrap your `setUserAttribute` call in a callback function. Example in [identify users](/docs/tracking-methods/integrations/mparticle#3-identify-users) section.
* If you are using [Simplified ID Merge](/docs/tracking-methods/id-management/identifying-users-simplified), please ensure that the "Simplified ID Merge" setting is selected in your connection output settings.

**3. How do I register super properties using mParticle?**

* Super properties can be set in your connection output settings.

**4. How can I filter for events that originate from mParticle in my project?**

* Events coming from mParticle will show a value of "Web" under `Mixpanel Library`. You may need to include an attribute with events that indicate the source is "mParticle".

**5. Why are my audiences not forwarding to Mixpanel?**

Please check the following settings:

* Ensure you have an audience output configured under `Data Platform > Setup > Audience` with your audience selected.
* Ensure your audience is targeting your audience output.
* Ensure your audience has fully processed in mParticle.
* Download your audience to ensure proper enrollment.
* You must create a cohort in Mixpanel defined by the profile property of the audience ID or name.


# Next.js
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/nextjs



1. Start by [installing the SDK](/docs/quickstart/install-mixpanel).
2. Set up environment variables for your Mixpanel token

   a. Create a `.env.local` file in the root of your Next.js project (note: for production use `.env.production`).

   b. Then, add your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).

   ```javascript theme={"system"}
   // Paste in your token
   NEXT_PUBLIC_MIXPANEL_TOKEN=YOUR_PROJECT_TOKEN
   ```
3. Create a utility file to initialize the Mixpanel SDK in your Next.js application

   a. Create a file (e.g., `mixpanelClient.js`) under the `lib/` folder of your Next.js project

   b. Add the following code to the file:

   ```javascript theme={"system"}
   import mixpanel from 'mixpanel-browser';

   const MIXPANEL_TOKEN = process.env.NEXT_PUBLIC_MIXPANEL_TOKEN;

   export const initMixpanel = () => {
     if (!MIXPANEL_TOKEN) {
       console.warn('Mixpanel token is missing! Check your .env file.');
       return;
     }
    
     mixpanel.init(MIXPANEL_TOKEN, { autocapture: true });
   }
   ```
4. Initialize Mixpanel in your Next.js application

   a. **If using page router**, open or create the file `_app.js` or `app.tsx` in your pages/ directory. Then import and initialize Mixpanel inside `useEffect`. You’ll also need to track pageviews manually using `useRouter`.

   ```javascript theme={"system"}
   import { useEffect } from 'react';
   import { useRouter } from 'next/router';
   import { initMixpanel, trackPageView } from '../lib/mixpanelClient';

   function MyApp({ Component, pageProps }) {
     const router = useRouter();

     useEffect(() => {
       initMixpanel(); // Initialize Mixpanel

       const handleRouteChange = (url) => {
         trackPageView(url); // Track pageviews
       };

       // Track page views on route change
       router.events.on('routeChangeComplete', handleRouteChange);

       return () => {
         router.events.off('routeChangeComplete', handleRouteChange);
       };
     }, [router.events]);

     return <Component {...pageProps} />;
   }

   export default MyApp;
   ```

   b. **If using app router**, first create a client component in a file (e.g. `components/MixpanelProvider.js`) to handle the client-side initialization.

   ```javascript theme={"system"}
   'use client';

   import { useEffect } from 'react';
   import { initMixpanel } from '../lib/mixpanelClient';

   export default function MixpanelProvider({ children }) {

     useEffect(() => {
       initMixpanel(); // Initialize Mixpanel
     }, []);

     return <>{children}</>;
   }
   ```

   Next, open or create the file `layout.js` or `layout.tsx` in your app/ directory and wrap the body component with the MixpanelProvider.

   ```javascript theme={"system"}
   import { MixpanelProvider } from '../components/MixpanelProvider';

   export default function RootLayout({ children }) {

     return (
       <html lang="en">
         <body>
         <MixpanelProvider>{children}</MixpanelProvider>
         </body>
       </html>
     );
   }
   ```
5. Run the development server, test your application (click some things, submit some things, etc.) and check the Mixpanel live event view to confirm that events are sending via Autocapture.


# Rudderstack
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/rudderstack



[RudderStack](https://rudderstack.com/) is a customer data pipeline platform for collecting, routing and processing data from your website, apps, data warehouse and cloud apps.

With RudderStack, you can build customer data pipelines that connect your whole customer data stack and then make them smarter by triggering enrichment and activation in customer tools based on analysis in your data warehouse.

For detailed instructions on how to use RudderStack with Mixpanel, please refer to the [RudderStack documentation](https://docs.rudderstack.com/destinations/analytics/mixpanel).


# Segment
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/segment



## Overview

Segment, a Customer Data Platform (CDP), enables you to track event data and route it to various downstream destinations. As a native partner, Mixpanel seamlessly integrates with Segment. If you use Segment for tracking, you can send your data to Mixpanel with just a few clicks.

## How the Integration Works

In the simplest form, the Segment libraries (“Sources”) generate messages about what is happening in your site or app, and send them to the Segment servers. Segment then translates the content of those messages into different formats for use by other tools (which we call ‘Destinations’), and sends the translated messages to those tools. The Segment servers also archive a copy of the data, and can send data to your storage systems (such as databases, warehouses, or bulk-storage buckets).

Mixpanel is one of the supported Segment destinations. With this integration, you can easily send your data collected from your Segment source into your Mixpanel project as a downstream destination.

For detailed instructions on how to install the Segment tracking library, please refer to the [Segment Getting Started Guide](https://segment.com/docs/getting-started/02-simple-install/).

## Quick Start

### 1. Integrate with Segment

Once you've installed and initialized a Segment library in your application, get your data into Mixpanel by following the instructions for setting up the [Mixpanel (Actions) Destination](https://segment.com/docs/connections/destinations/catalog/actions-mixpanel/)

### 2. Identify Users

The next thing you need to do is identify your users, so that you can understand your users. We recommend calling `identify` when your user sign up and log in.

When you call [Segment's identify API](https://segment.com/docs/connections/spec/identify/), Mixpanel will set the specified `userId` as the Mixpanel `distinct_id`. Any `traits` you provide in the call will be applied as profile properties for the targeted user in Mixpanel.

### 3. Track User Actions

Lastly, track your users' actions using [Segment's track API call](https://segment.com/docs/connections/spec/track/), which would trigger [Mixpanel's import API](/reference/import-events) and ingest an event in your project.

### 4. Check for Success

[Open up Events View in Mixpanel](http://mixpanel.com/report/events) to view incoming events.

## Configure the Destination

<Note>
  We recommend using the [Mixpanel Actions destination](https://segment.com/docs/connections/destinations/catalog/actions-mixpanel/).
</Note>

Once you have installed the Segment library and see tracked data in your Segment instance, get your data into your Mixpanel project by setting up a destination [following the Segment documentation here](https://segment.com/docs/connections/destinations/catalog/actions-mixpanel/).

Below is a high-level summary of the steps to setup the Mixpanel destination:

1. In Segment, click the **Catalog** tab, filter for **Destinations**, and select Mixpanel to add the destination.

<Frame>
  <img alt="segment_catalog" />
</Frame>

2. Select a Segment source to stream to the destination.

<Frame>
  <img alt="segment_source" />
</Frame>

3. Set a name for the destination then choose a framework. We recommend **Actions** destination. ([Learn more about the framework options](https://segment.com/blog/mixpanel-actions-vs-classic-destinations-in-segment/))

<Frame>
  <img alt="segment_action_select" />
</Frame>

4. Provide your Mixpanel project credentials in the Basic Settings, then click the toggle at the bottom to enable the destination. The project credentials are found in [your project settings](https://mixpanel.com/settings/project/).

<Frame>
  <img alt="segment_enable_setting" />
</Frame>

## Data Mapping

Segment's Actions framework allows you to configure how Segment sends the data it receives from your source to Mixpanel.

### Preset Actions

The Mixpanel Actions destination comes with a preset of default mappings that you can use out the box. You can find them in the "Mappings" tab of the destination settings.

| Preset Name           | Segment Trigger                                                                                         | Mixpanel Action                                                                                                                                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Order Completed Calls | [Event type = "track"](https://segment.com/docs/connections/spec/track/) and event = "Order Completed"  | [Import Event](/reference/import-events) "Order Completed"                                                                                                                                                   |
| Track Calls           | [Event type = "track"](https://segment.com/docs/connections/spec/track/) and event != "Order Completed" | [Import Event](/reference/import-events)                                                                                                                                                                     |
| Screen Calls          | [Event type = "screen"](https://segment.com/docs/connections/spec/screen/)                              | [Import Event](/reference/import-events) "Viewed \{name}"                                                                                                                                                    |
| Identify Calls        | [Event type = "identify"](https://segment.com/docs/connections/spec/identify/)                          | Identify User ([Simplified API](/docs/tracking-methods/id-management/identifying-users-simplified#user_id) /[Original API](/reference/create-identity)) and [Set Profile Properties](/reference/profile-set) |
| Page Calls            | [Event type = "page"](https://segment.com/docs/connections/spec/page/)                                  | [Import Event](/reference/import-events) "Viewed \{name}"                                                                                                                                                    |
| Group Calls           | [Event type = "group"](https://segment.com/docs/connections/spec/group/)                                | [Identify Group](/reference/group-set-property)                                                                                                                                                              |

<Note>
  Note that the `id` Segment event property is a reserved property that is mapped to `distinct_id` in Mixpanel. Avoid sending events with an `id` event property from Segment.
</Note>

### Customize Mappings

<Warning>
  Note that `context` ([learn more here](https://segment.com/docs/connections/spec/common/#context)) is a Segment concept which does not have an equivalent in Mixpanel's data model. If there are keys inside of the `context` dictionary that you need to add to your event and it is not a default property that is already in the mapping, you will need to edit the `properties` object to manually include it.
</Warning>

You can customize the preset actions mapping or create new mappings to further configure your event payload before they are sent to Mixpanel.

To edit an existing mapping, click the "..." button in the actions table. To create a new mapping, click the "New Mapping" button in the top right of the UI.

<Frame>
  <img alt="segment_mapping" />
</Frame>

Editing or creating new mappings is done in 4 steps.

**1. Set Condition**

Define the [conditions](https://segment.com/docs/connections/destinations/actions/#conditions) under which the action should run. You can specify the conditions using a combination of **Event Type**, **Event Name**, and **Event Property**.

Let's say you want to create a mapping that is triggered for any events tracked on Android. In this case, we can set the condition to **Event Type** equal `Track` and **Event Property** `platform` equal `android`:

<Frame>
  <img alt="segment_condition" />
</Frame>

**2. Sample Payload**

For testing your mapping, set an example payload. You can use an existing event from your source, load a Segment-generated sample event, or create a sample payload manually.

Ensure that this example payload matches the condition you set above so that the Action applies to your expected payload. As a best practice, insert an example payload that you know should not match the condition to verify that your condition is specific enough to target only your expected payload.

Since we're creating a mapping for any events tracked on Android, we insert a test event payload that includes the property `platform` set to `android`:

<Frame>
  <img alt="segment_sample_payload" />
</Frame>

**3. Edit Mapping**

Edit the mapping of the Action to configure your output payload in your desired format. In this stage, we are essentially creating a Segment payload using data that is generated from Segment's SDK, which will then be sent to Mixpanel's destination mapping code for additional processing.

On the left side of the UI, you can configure the output value using the available data from your Segment source payload. On the right side of the UI, you can define the property names for the Segment payload that will be sent to Mixpanel.

If we want to append "ANDROID" to the names of events coming from this Android actions mapping, specify this in the Event Name row on the left-hand side:

<Frame>
  <img alt="segment_mapping_name" />
</Frame>

To include the `messageId` from the sample Segment payload as a Mixpanel event property called "Segment Message ID", edit the Event Properties mapping:

<Frame>
  <img alt="segment_mapping_properties" />
</Frame>

<Note>
  By default, the track preset takes the entire `properties` object from the Segment payload and uses it to generate "Event Properties" for the Mixpanel event payload. To edit the event properties mapping, you will need to manually define each property key-value pairs manually.

  <Frame>
    <img alt="segment_mapping_properties_edit" />
  </Frame>
</Note>

**4. Preview Payload**

Once you are done with configuring the mapping, preview how your sample payload is mapped through the Action by expanding on the "Event context". You can also ingest the sample payload into Mixpanel to see how it will appear in your project by clicking "Send test event to destination".

<Note>
  Note that while the Event Content tab is helpful for showing how your properties are getting mapped through the Action, your payload will go through additional processing before getting ingested in Mixpanel. Send the test payload to destination in order to preview how your event will appear inside your project.
</Note>

<Frame>
  <img alt="segment_test_event" />
</Frame>

## Implementing Group Analytics using Segment

There are 4 parts to implementing Group Analytics via Segment. Learn more about [Group Analytics here](/docs/data-structure/group-analytics) and the Segment Group Spec here.

**1. Define the Group Key in Mixpanel**

Create the Group Key in Mixpanel Project Settings. In this example, we are setting `company_id` as the group key.

<Frame>
  <img alt="1groupkey_projectsettings" />
</Frame>

**2. Configure your Group Actions Mapping**

<Note>
  If a Group Key mapping is not specified, Segment will use `$group_id` as the group key by default. In this case, set your group key in Mixpanel to `$group_id`.
</Note>

Edit the Group action preset or create a new action mapping to target your group calls. You should manually type in the group key in the mapping to the same as it appears in the Mixpanel settings.

Additionally, make sure the "Group ID" is mapped to the value of the groupId.

Since we set the group key to `company_id` earlier, we manually enter it as the Group Key in the mapping. The `groupId` is the default key that Segment uses as the identifier for a group, so we map it to the Group ID.

<Frame>
  <img alt="segment_group_mapping" />
</Frame>

**3. Create Group Profiles**

Calling Segment SDK function [analytics.group()](https://segment.com/docs/connections/spec/group/) will create Group Profile/Group Profile Properties in Mixpanel.

```js theme={"system"}
//the groupId is "some_company"
//the second argument contain 3 group profile properties to be set
analytics.group("some_company", {
    "$name": "some_company_name",
    "employees": 100,
    "id": "some_company"
})
```

Example Group Profile/Group Profile Properties created from the group method above:

<Frame>
  <img alt="4groupprofile" />
</Frame>

**4. Add Group Key as a User Profile Property**

In order to use Group Profile Properties when analyzing User Profiles, the user profile must have the Group Key/Group ID Value as a profile property.

Declare the Group Key in the identify method as a profile property (trait):

<Frame>
  <img alt="5identify" />
</Frame>

**5. Add Group Key as an Event Property to Events**

In order to connect events to a Group, the event must have the Group Key/Group ID Value as an event property.

The Group Key must be explicitly declared as an event property on every event track call in order for the event to be compatible with Group Analytics.

<Frame>
  <img alt="6trackcall" />
</Frame>

If you are using [Segment Device Mode](https://segment.com/docs/connections/destinations/catalog/mixpanel/#group-using-device-mode) (Classic destination):

* Declare the Group Key as a [Super Property](https://segment.com/docs/connections/destinations/catalog/mixpanel/#register-super-properties) so that the Group Key is sent in as an Event Property to client-side events.
* By default, all traits specified in the identify call will be registered as super properties. This means if you have the [“Automatically set all Traits as Super Properties and People Properties”](https://segment.com/docs/connections/destinations/catalog/mixpanel/#settings) setting turned on, all traits specified in the identify call will be added as both a super property and profile property for the user.

## Debugging

For debugging purposes, it can be useful to see exactly what Segment is sending to Mixpanel. You can validate this data through the [Segment Source Debugger](https://segment.com/docs/connections/sources/debugger/). In the Segment Source Debugger, you can select the event you are looking to validate:

<Frame>
  <img alt="debugger screenshot" />
</Frame>

Click the “Validate” button in the top right corner and choose “Mixpanel” as the destination. After the event has been sent, you can click to view the request from Segment to grab the data payload:

<Frame>
  <img alt="pasted image 0 (1)" />
</Frame>

You can then copy the data payload and decode it in a [base64 decoder](https://www.base64decode.org/) to see the JSON event that was sent to Mixpanel.

## Setting up Autocapture with Segment

<Note>
  Note: In most cases, we do not recommend implementing Autocapture with Segment to minimize the risks of identity management issues. Please consult with a member of our team if you choose to use this approach.
</Note>

It is possible to use Mixpanel’s Autocapture in conjunction with Segment; the following tutorial will show you how to implement Autocapture on your website in a way that integrated with [cloud mode](https://segment.com/docs/connections/sources/catalog/libraries/mobile/apple/cloud-mode-destinations/).

The Segment SDK does not currently support an Autocapture mechanism, so the way to integrate is to load the Mixpanel Javascript SDK on your website, and then use a snippet which implements Segment’s middleware pattern to ensure that the user and device\_ids match in the Segment and autocaptured data.

In this setup, the autocaptured event data will go directly to Mixpanel and will not pass through the Segment pipeline - however the user’s identity will be kept in sync between both systems allowing you to have consistent user flows in Mixpanel that properly join autocaptured data and Segment tracked data.

In the following code snippet we:

* Embed the Segment SDK in our app
* Send an event (`app loaded`) to Segment; this event is forwarded to Mixpanel
* Embed the Mixpanel SDK in our app

  * Activate Autocapture to track all track clicks
  * Ensure that Mixpanel, when loaded looks for Segment’s user and device\_ids
* Register middleware with Segment to ensure that, when Segment loads, it propagates identity data to Mixpanel

<Note>
  Important: the following snippet includes options for both simplified and original identity merge; please comment out the method you are not using.
</Note>

```HTML theme={"system"}
<!DOCTYPE html>
<html>
<head>
	<title>segment + mixpanel autocapture</title>

	<!-- SEGMENT INSTALL (analytics.js) -->
	<script type="text/javascript">
		const SEGMENT_WRITE_KEY = `dHWN9FMfq2Ocmsjx4oAZQ48KQRrZrrl0`;
		!function () {
			var i = "analytics", analytics = window[i] = window[i] || []; if (!analytics.initialize) if (analytics.invoked) window.console && console.error && console.error("Segment snippet included twice."); else {
				analytics.invoked = !0; analytics.methods = ["trackSubmit", "trackClick", "trackLink", "trackForm", "pageview", "identify", "reset", "group", "track", "ready", "alias", "debug", "page", "screen", "once", "off", "on", "addSourceMiddleware", "addIntegrationMiddleware", "setAnonymousId", "addDestinationMiddleware", "register"]; analytics.factory = function (e) { return function () { if (window[i].initialized) return window[i][e].apply(window[i], arguments); var n = Array.prototype.slice.call(arguments); if (["track", "screen", "alias", "group", "page", "identify"].indexOf(e) > -1) { var c = document.querySelector("link[rel='canonical']"); n.push({ __t: "bpc", c: c && c.getAttribute("href") || void 0, p: location.pathname, u: location.href, s: location.search, t: document.title, r: document.referrer }); } n.unshift(e); analytics.push(n); return analytics; }; }; for (var n = 0; n < analytics.methods.length; n++) { var key = analytics.methods[n]; analytics[key] = analytics.factory(key); } analytics.load = function (key, n) { var t = document.createElement("script"); t.type = "text/javascript"; t.async = !0; t.setAttribute("data-global-segment-analytics-key", i); t.src = "https://cdn.segment.com/analytics.js/v1/" + key + "/analytics.min.js"; var r = document.getElementsByTagName("script")[0]; r.parentNode.insertBefore(t, r); analytics._loadOptions = n; }; analytics._writeKey = "RT8UgSD2nynW0HbEg6djCUWuEvD2kOQA";; analytics.SNIPPET_VERSION = "5.2.0";
				analytics.load(SEGMENT_WRITE_KEY);
				analytics.track('app loaded', { version: 1 }); // sample segment "track" event
				analytics.page('my page'); // sample segment "page" event
			}
		}();

		// ! IMPORTANT: tell Segment to propagate Ids to Mixpanel
		analytics.addSourceMiddleware(({ payload, next, integrations }) => {
			if (payload.obj.type === 'track' || payload.obj.type === 'page') {
				if (window.mixpanel) {
					const segmentDeviceId = payload.obj.anonymousId;
					// -------------------------------------------
					// Comment out one of the below mixpanel.register methods depending on your ID Management Version
					// Original ID Merge
					mixpanel.register({ $device_id: segmentDeviceId, distinct_id: segmentDeviceId });
					// Simplified ID Merge
					mixpanel.register({ $device_id: segmentDeviceId, distinct_id: "$device:" + segmentDeviceId });
					// -------------------------------------------	
				
				}
			}
			if (payload.obj.type === 'identify') {
				if (window.mixpanel) {
					const userId = payload.obj.userId;
					mixpanel.identify(userId);
				}
			}
			next(payload);
		});
	</script>
	<!-- MIXPANEL INSTALL -->
	<script type="text/javascript">
	const MIXPANEL_TOKEN = "0c1e0f968cd6b969ce6c84fe89c95830";
	(function (f, b) { if (!b.__SV) { var e, g, i, h; window.mixpanel = b; b._i = []; b.init = function (e, f, c) { function g(a, d) { var b = d.split("."); 2 == b.length && ((a = a[b[0]]), (d = b[1])); a[d] = function () { a.push([d].concat(Array.prototype.slice.call(arguments, 0))); }; } var a = b; "undefined" !== typeof c ? (a = b[c] = []) : (c = "mixpanel"); a.people = a.people || []; a.toString = function (a) { var d = "mixpanel"; "mixpanel" !== c && (d += "." + c); a || (d += " (stub)"); return d; }; a.people.toString = function () { return a.toString(1) + ".people (stub)"; }; i = "disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking start_batch_senders people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split(" "); for (h = 0; h < i.length; h++) g(a, i[h]); var j = "set set_once union unset remove delete".split(" "); a.get_group = function () { function b(c) { d[c] = function () { call2_args = arguments; call2 = [c].concat(Array.prototype.slice.call(call2_args, 0)); a.push([e, call2]); }; } for (var d = {}, e = ["get_group"].concat(Array.prototype.slice.call(arguments, 0)), c = 0; c < j.length; c++) b(j[c]); return d; }; b._i.push([e, f, c]); }; b.__SV = 1.2; e = f.createElement("script"); e.type = "text/javascript"; e.async = !0; e.src = "undefined" !== typeof MIXPANEL_CUSTOM_LIB_URL ? MIXPANEL_CUSTOM_LIB_URL : "file:" === f.location.protocol && "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\/\//) ? "https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js" : "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"; g = f.getElementsByTagName("script")[0]; g.parentNode.insertBefore(e, g); } })(document, window.mixpanel || []);

	mixpanel.init(MIXPANEL_TOKEN, {
		autocapture: true,
		// ! IMPORTANT: tell Mixpanel to look for Segment's device ID
		loaded: function (mixpanel) {
			if (analytics && analytics.user) {
				const segmentDeviceId = analytics.user().anonymousId()
				if (segmentDeviceId) {
					// Comment out one of the below mixpanel.register methods depending on your ID Management Version
					// Original ID Merge
					mixpanel.register({ $device_id: segmentDeviceId, distinct_id: segmentDeviceId });
					// Simplified ID Merge
					mixpanel.register({ $device_id: segmentDeviceId });
				}
				const segmentUserId = analytics.user().id()
				if (segmentUserId) {
					mixpanel.identify(segmentUserId);
				}
			}
		}
	});
	</script>
</head>

<body>
	<h1>👋 hello segment + autocapture!</h1>
	<div class="buttons">
		<button id="clickMeButton">click me</button>
		<button id="dontClickMeButton">don't click me</button>
	</div>
</body>
</html>
```

## FAQ

**1. Why are my Segment data not appearing in my project?**

This could be due to several reasons:

* **Storing data in the EU:** A common issue is that the data in Segment is enabled to be sent to an EU endpoint but the Mixpanel data is still being stored outside of the EU. Both endpoints for Segment and Mixpanel need to point to the EU as described [here](https://segment.com/docs/connections/destinations/catalog/mixpanel/#enable-european-union-endpoint). If you have an existing Mixpanel project, you might need to have your data migrated to the EU. Please find further information [here](/docs/privacy/eu-residency#existing-customers).
* **[Cloud implementation vs. device implementation (Only applies to Classic destination; Action is cloud-mode only)](https://segment.com/docs/connections/destinations/#connection-modes):** Segment can be implemented via a cloud-based implementation or as an SDK on the device directly. Device implementation will send the data to Mixpanel directly while the cloud implementation will send it to Segment first. You can confirm your implementation by querying for the Mixpanel library property of the events in your project:

  * Cloud Mode will show as Mixpanel Library: Segment: analytics.js
  * Device Mode will show as Mixpanel Library: Segment: web
* **No user profile data in Mixpanel (Classic destination only)**: [Segment does not track Mixpanel People by default](https://segment.com/docs/connections/destinations/catalog/mixpanel/#people). This is a setting you need to enable in your Segment settings. To enable Mixpanel People, change the “Use Mixpanel People” setting in your Segment Settings UI.

**2. Why are there duplicated Segment events in my project?**

Mixpanel SDKs assign an [\$insert\_id](/reference/import-events#propertiesinsert_id) to each tracked event.

This allows Mixpanel to ensure no event is tracked more than once and events will be deduplicated based on the insert\_id. Segment does not assign an insert\_id to events. If the ingestion of an event is not confirmed by Mixpanel’s servers fast enough, Segment will retry to send the event.

This can lead to duplicate events in Mixpanel, they will likely have different insert\_ids as Mixpanel assigns each event without an insert\_id a unique new one. This behavior can be caused by sending huge batches of data at the same time and can be avoided by reducing the batch size and frequency of event sending from Segment to Mixpanel.

**3. How do I register super properties using Segment?**

Super properties can only be set when you are running in device mode and using the Classic destination. The super properties are automatically set with every property you pass into the analytics.identify() method. To have more control over the super properties you set, you can explicitly set super properties in your [Segment settings](https://segment.com/docs/connections/destinations/catalog/mixpanel/#explicitly-set-people-properties-and-super-properties).

**4. How do I track page views using Segment?**

In analytics.js, a Page call is included in the initialization snippet by default right after analytics.load(). Otherwise, you will want you will want to call [analytics.page()](https://segment.com/docs/connections/spec/page/) manually to track page view.

For the Preset Action, the default Event Name mapping for page call is `Viewed {name}`. To consolidate event names (e.g. "Page Viewed" or "Loaded a Page"), modify the Event Name mapping.

<Frame>
  <img alt="segment_page_name_mapping" />
</Frame>

**5. How can I filter for events that originate from Segment in my project?**

Events coming from Segment are marked with the event property `mp_lib` (Mixpanel Library) set to the name of the Segment SDK used to generate the event. For example, events sent using Segment's Javascript SDK will have the `mp_lib` property set to `Segment: analytics.js`.


# Shopify
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/shopify



Mixpanel [Autocapture](/docs/tracking-methods/autocapture) gathers pageviews, clicks, scroll events (and [more](/docs/tracking-methods/sdks/javascript#autocapture)!) automatically. With minimal setup, you can easily unlock fine-grain insights into how customers are engaging with your Shopify storefront. Alternatively, for a powerful cross-platform, no-code solution that syncs your data across surfaces like ad and payment platforms, consider the [Vendo/Mixpanel integration](/docs/tracking-methods/integrations/vendo) available in the [Shopify app store](https://apps.shopify.com/vendo).

This guide explores two simple options to integrate Mixpanel’s [Javascript SDK](/docs/tracking-methods/sdks/javascript) into your shop:

1. [Mixpanel SDK + Autocapture](#install-mixpanel-sdk-with-autocapture): collect data automatically (minimal setup)
2. [Mixpanel SDK +  Shopify Web Pixel](#mixpanel-sdk--shopify-web-pixel): define your own customer events (robust, yet approachable setup)

For optimal visibility, we recommend both! Shopify’s checkout flow is strict about only running proprietary scripts, but you can still fully capture conversion events by implementing Option 2 with the [Shopify Web Pixel](https://shopify.dev/docs/api/web-pixels-api#custom-web-pixels) setup guide.

## Install Mixpanel SDK with Autocapture

*Automatically collect customer events with minimal steps*

1. Copy the Mixpanel SDK code snippet at the top of [this guide](/docs/tracking-methods/sdks/javascript#installing-the-library)
2. Go to your Store Dashboard > Sales Channels > Online Store > Theme and click “Edit code”

   <Frame>
     <img alt="" />
   </Frame>
3. Open the theme.liquid file and scroll down to the closing `</head>` tag

   <Frame>
     <img alt="" />
   </Frame>
4. Paste the code snippet you just copied to add Mixpanel’s SDK (we’re almost there—we just need to do one more thing to enable it)

   <Frame>
     <img alt="" />
   </Frame>
5. Go to your Mixpanel Dashboard > Project Settings and copy your Project Token under Access Keys

   <Frame>
     <img alt="" />
   </Frame>
6. Back in your Shopify `theme.liquid` file, enable Mixpanel’s SDK by adding your Project Token to the `mixpanel.init` code (wrapped in `script` tags). Altogether, it should look like this:

   <Frame>
     <img alt="" />
   </Frame>
7. Confirm the configuration in your Mixpanel Project and enjoy a data pipeline flowing with `[Auto]` tracked events!

   <Frame>
     <img alt="" />
   </Frame>

## Mixpanel SDK + [Shopify Web Pixel](https://shopify.dev/docs/api/web-pixels-api#custom-web-pixels)

*Define your own customer events with an approachable setup*

1. Copy the Mixpanel SDK code snippet at the top of [this guide](/docs/tracking-methods/sdks/javascript#installing-the-library) and remove the `<script></script>` wrapper tags
2. Go to your Shopify Store > Settings > [Customer Events](https://admin.shopify.com/settings/customer_events), click “Add custom Pixel”, and name your Pixel something snazzy

   <Frame>
     <img alt="" />
   </Frame>
3. Add some code to get your Pixel up and running. This code is a three-part recipe that will:

   * Subscribe to Shopify’s Pixel Event API
   * Load the Mixpanel SDK snippet that you copied in step 1
   * Define and track the customer events we’d like to collect (reference the complete property list in [Shopify’s Web Pixel Event API](https://shopify.dev/docs/api/web-pixels-api/standard-events) docs)

   An outline of this structure looks like this:

   ```javascript theme={"system"}
   // Subscribe to Shopify Pixel Event API (https://shopify.dev/docs/api/web-pixels-api/standard-events)
   analytics.subscribe('EVENT_NAME', (event) => {

       // Paste Mixpanel SDK code snippet sans <script> tags
       (function (f, b) { if (!b.__SV) { var e, g, i, h; window.mixpanel = b; b._i = []; b.init = function (e, f, c) { function g(a, d) { var b = d.split("."); 2 == b.length && ((a = a[b[0]]), (d = b[1])); a[d] = function () { a.push([d].concat(Array.prototype.slice.call(arguments, 0))); }; } var a = b; "undefined" !== typeof c ? (a = b[c] = []) : (c = "mixpanel"); a.people = a.people || []; a.toString = function (a) { var d = "mixpanel"; "mixpanel" !== c && (d += "." + c); a || (d += " (stub)"); return d; }; a.people.toString = function () { return a.toString(1) + ".people (stub)"; }; i = "disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking start_batch_senders people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split( " "); for (h = 0; h < i.length; h++) g(a, i[h]); var j = "set set_once union unset remove delete".split(" "); a.get_group = function () { function b(c) { d[c] = function () { call2_args = arguments; call2 = [c].concat(Array.prototype.slice.call(call2_args, 0)); a.push([e, call2]); }; } for ( var d = {}, e = ["get_group"].concat( Array.prototype.slice.call(arguments, 0)), c = 0; c < j.length; c++) b(j[c]); return d; }; b._i.push([e, f, c]); }; b.__SV = 1.2; e = f.createElement("script"); e.type = "text/javascript"; e.async = !0; e.src = "undefined" !== typeof MIXPANEL_CUSTOM_LIB_URL ? MIXPANEL_CUSTOM_LIB_URL : "file:" === f.location.protocol && "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\/\//) ? "https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js" : "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"; g = f.getElementsByTagName("script")[0]; g.parentNode.insertBefore(e, g); } })(document, window.mixpanel || []);
       
       // Initialize Mixpanel SDK	
       mixpanel.init('YOUR_PROJECT_TOKEN');
       
       // Define and track events example
       mixpanel.track('My plain text event name', {
           productTitle: web.pixel.event.property.chain.here
           productPrice: web.pixel.event.property.chain.here
       })
   });
   ```

   Putting this recipe to work, here’s an example of how to track `product_viewed` events:

   ```javascript theme={"system"}
   // Subscribe to Shopify Pixel Event API
   analytics.subscribe('product_viewed', (event) => {

       // Load Mixpanel SDK 
       (function (f, b) { if (!b.__SV) { var e, g, i, h; window.mixpanel = b; b._i = []; b.init = function (e, f, c) { function g(a, d) { var b = d.split("."); 2 == b.length && ((a = a[b[0]]), (d = b[1])); a[d] = function () { a.push([d].concat(Array.prototype.slice.call(arguments, 0))); }; } var a = b; "undefined" !== typeof c ? (a = b[c] = []) : (c = "mixpanel"); a.people = a.people || []; a.toString = function (a) { var d = "mixpanel"; "mixpanel" !== c && (d += "." + c); a || (d += " (stub)"); return d; }; a.people.toString = function () { return a.toString(1) + ".people (stub)"; }; i = "disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking start_batch_senders people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split( " "); for (h = 0; h < i.length; h++) g(a, i[h]); var j = "set set_once union unset remove delete".split(" "); a.get_group = function () { function b(c) { d[c] = function () { call2_args = arguments; call2 = [c].concat(Array.prototype.slice.call(call2_args, 0)); a.push([e, call2]); }; } for ( var d = {}, e = ["get_group"].concat( Array.prototype.slice.call(arguments, 0)), c = 0; c < j.length; c++) b(j[c]); return d; }; b._i.push([e, f, c]); }; b.__SV = 1.2; e = f.createElement("script"); e.type = "text/javascript"; e.async = !0; e.src = "undefined" !== typeof MIXPANEL_CUSTOM_LIB_URL ? MIXPANEL_CUSTOM_LIB_URL : "file:" === f.location.protocol && "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\/\//) ? "https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js" : "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"; g = f.getElementsByTagName("script")[0]; g.parentNode.insertBefore(e, g); } })(document, window.mixpanel || []);
       
       // Initialize Mixpanel SDK	
       mixpanel.init('YOUR_PROJECT_TOKEN');
       
       // Track product_viewed
       const productVariant = event.data.productVariant;
       mixpanel.track('Product viewed', {
           productTitle: productVariant.title,
           productPrice: productVariant.price.amount
       });
   });
   ```

   And, another example of gathering `checkout_completed` events:

   ```javascript theme={"system"}
   // Subscribe to Shopify Pixel Event API
   analytics.subscribe('checkout_completed', (event) => {

       // Load Mixpanel SDK 
       (function (f, b) { if (!b.__SV) { var e, g, i, h; window.mixpanel = b; b._i = []; b.init = function (e, f, c) { function g(a, d) { var b = d.split("."); 2 == b.length && ((a = a[b[0]]), (d = b[1])); a[d] = function () { a.push([d].concat(Array.prototype.slice.call(arguments, 0))); }; } var a = b; "undefined" !== typeof c ? (a = b[c] = []) : (c = "mixpanel"); a.people = a.people || []; a.toString = function (a) { var d = "mixpanel"; "mixpanel" !== c && (d += "." + c); a || (d += " (stub)"); return d; }; a.people.toString = function () { return a.toString(1) + ".people (stub)"; }; i = "disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking start_batch_senders people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split( " "); for (h = 0; h < i.length; h++) g(a, i[h]); var j = "set set_once union unset remove delete".split(" "); a.get_group = function () { function b(c) { d[c] = function () { call2_args = arguments; call2 = [c].concat(Array.prototype.slice.call(call2_args, 0)); a.push([e, call2]); }; } for ( var d = {}, e = ["get_group"].concat( Array.prototype.slice.call(arguments, 0)), c = 0; c < j.length; c++) b(j[c]); return d; }; b._i.push([e, f, c]); }; b.__SV = 1.2; e = f.createElement("script"); e.type = "text/javascript"; e.async = !0; e.src = "undefined" !== typeof MIXPANEL_CUSTOM_LIB_URL ? MIXPANEL_CUSTOM_LIB_URL : "file:" === f.location.protocol && "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\/\//) ? "https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js" : "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"; g = f.getElementsByTagName("script")[0]; g.parentNode.insertBefore(e, g); } })(document, window.mixpanel || []);
       
       // Initialize Mixpanel SDK	
       mixpanel.init('YOUR_PROJECT_TOKEN');
       
       // Track checkout_completed
       const checkout = event.data.checkout;
       mixpanel.track('Checkout completed', {
           value: checkout.totalPrice.amount,
           created_at: event.timestamp,
           order_number: checkout.order.id,
           userId: event.clientId,
           order_id: checkout.order.id,
           products: checkout.lineItems.map((item) => {
           return {
               product_id: item.id,
               title: item.variant.product.title,
               quantity: item.quantity,
               price: item.variant.price.amount,
               currency: item.variant.price.currencyCode,
               sku: item.variant.sku,
               size: item.variant.product.size
           }
       })
   });
   ```
4. Click “Test” to confirm the Shopify Web Pixel API is connected (next, we’ll confirm Mixpanel is receiving those events from Shopify)

   <Frame>
     <img alt="" />
   </Frame>
5. Connect the Pixel to release it into the wild

   <Frame>
     <img alt="" />
   </Frame>
6. Visit your Shopify storefront and trigger your custom events
7. Verify data is flowing into your Mixpanel dashboard and enjoy tracking custom conversions  in real time! 🎉

   <Frame>
     <img alt="" />
   </Frame>

   <Frame>
     <img alt="" />
   </Frame>


# Snowplow
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/snowplow



If you already use Snowplow to collect event data, it's easy to route that data to Mixpanel. The value of connecting Snowplow and Mixpanel is to enable fast, self-serve product analytics on the events you already collect. Snowplow offers a native integration that forwards events directly to Mixpanel.

## How Snowplow Works

[Snowplow](https://snowplow.io/) is a customer data infrastructure platform for collecting and storing event data from your application. Teams use Snowplow's SDKs and platform to exercise full control over event data collection in their own cloud. Snowplow's [event-centric approach](https://docs.snowplow.io/docs/fundamentals/events) is fully compatible with Mixpanel; [our infrastructure](https://developer.mixpanel.com/docs/under-the-hood) is also purpose-built to ingest, store, and query events.

Below we show the architecture of a Snowplow pipeline from their [documentation](https://docs.snowplowanalytics.com/docs/fundamentals).

<Frame>
  <img alt="image" />
</Frame>

## How the Integration Works

The Mixpanel integration uses Snowplow's [event forwarding](https://docs.snowplow.io/docs/destinations/forwarding-events/integrations/mixpanel). It works as a destination in your Snowplow pipeline. As events flow through Snowplow's collection and enrichment process, the event forwarder sends validated events directly to Mixpanel, in near real-time, via the [Mixpanel Import API](/reference/import-events).

## Setup

### Create the Connection

Add Mixpanel as an event forwarding destination in your Snowplow pipeline. This is configured in **Destinations** > **Connections** in the Snowplow Console UI:

1. Select **Set up connection**, and choose **Loader connection** from the menu
2. Select Mixpanel as the destination type
3. Choose your Mixpanel server location
4. Enter your Mixpanel account credentials

### Identity Management

The integration automatically handles user identification using Mixpanel's simplified ID merge functionality. It uses `distinct_id` for user identification, and combines `domain_userid` with `client_session.user_id` for device tracking, automatically connecting anonymous and identified user activity.

### Schema Mapping

The integration provides default mappings for:

* Required fields: event name, timestamp, user ID, event ID
* Optional fields: geographic data, device information, browser details, UTM parameters

You can also add custom event properties using the format `properties.your_custom_field`.

For detailed setup instructions, refer to the [Snowplow documentation](https://docs.snowplow.io/docs/destinations/forwarding-events).


# Stripe
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/stripe



This guide demonstrates how to stream events from Stripe Webhooks to Mixpanel, via a Google Cloud Function. It requires access to a cloud account and \~10 minutes of setup time.

Note: This guide assumes you are running in Google Cloud Platform, and have the necessary IAM Access to have Cloud Functions read from GCS. An equivalent process works using AWS Lambda.

<Note>
  If you prefer not to build and maintain your data pipelines, consider using [Vendo](/docs/tracking-methods/integrations/vendo). The Vendo integration with Mixpanel enables you to integrate Stripe purchase and subscription data into Mixpanel without needing any custom development. Learn more [here](https://www.vendodata.com/connections/stripe?utm_source=mixpanel-partner-portal\&utm_medium=partner).
</Note>

## Step 1: Create a Cloud Function

Create a [new Cloud Function](https://console.cloud.google.com/functions/add), set the trigger to `HTTPS`, and check the box to Allow Unauthenticated Invocations, since this will be called from Stripe. Copy the URL, which should look something like `https://<zone>-<your-gcp-project>.cloudfunctions.net/stripe-demo`.

<Frame>
  <img alt="" />
</Frame>

Paste in the following code, which accepts Stripe's webhook format, and forwards it to Mixpanel's `/import` API:

<CodeGroup>
  ```python main.py theme={"system"}
  import functions_framework
  import json
  import requests

  @functions_framework.http
  def hello_http(request):
      req = request.get_json(silent=True)
      e = {
        'event': req['type'],
        'properties': {
          '$insert_id': req['id'],
          '$device_id': req['data']['object'].get('customer', ''), # If your project is on Original ID Merge, you would specify distinct_id for the user identifier
          'time': req['created'],
          **req['data']['object']
        }
      }
      resp = requests.post(
          "https://api.mixpanel.com/import",
          params={"strict": "1"},
          headers={
              "Content-Type": "application/x-ndjson",
              "User-Agent": "mixpanel-stripe"
          },
          auth=(request.args.get('token'), ""),
          data=json.dumps(e),
      )
      return resp.json()
  ```

  ```txt requirements.txt theme={"system"}
  functions-framework==3.*
  requests
  ```
</CodeGroup>

Click `Deploy`, which enables your Cloud Function to listen for new events.

## Step 2: Create a Stripe Webhook

Create a [Stripe Webhook](https://dashboard.stripe.com/webhooks/create) and paste in the URL of your Cloud Function, with your [Project Token](https://mixpanel.com/report/settings) as the `token` query parameter. So it should look something like `<function_url>.cloudfunctions.net?token=<your_token>`.

We recommend selecting all events, since it affords the most flexibility and you can filter them down easily in Mixpanel.

<Frame>
  <img alt="" />
</Frame>

🎉 Congrats: you now have a fully functioning Stripe -> Mixpanel integration!

## Next Steps

You can start doing analysis on the Stripe events. If you want to model your data more prior to ingesting it into Mixpanel, you can update the Cloud Function to do additional transformations. If you have historical Stripe data in a data warehouse, you can also use our Warehouse Connectors to BigQuery and Snowflake to load it into Mixpanel.


# Tealium
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/tealium



This guide demonstrates how to set up Mixpanel event tracking and identity management with [Tealium's IQ Tag Management Platform](https://tealium.com/resource/datasheet/tealium-iq/). Setup should take about 10 minutes, and will go over the following 5 steps:

1. Configuring Tag Hooks (one-time)
2. Connecting Mixpanel to Tealium (one-time)
3. Sending Events
4. Adding Event Properties
5. Identifying Users (one-time)

### Prerequisite: Tag Hooks

Tealium’s iQ Tag Management creates event streams fueled by [UDOs](https://docs.tealium.com/platforms/javascript/universal-data-object/) (Universal Data Objects).

For web applications, UDOs are just javascript objects with a special shape; they are automatically detected by the [Tealium utag SDK](https://docs.tealium.com/platforms/javascript/universal-tag/), and they look like this:

```javascript theme={"system"}
var utag_data = {
  "tealium_event": "page_view",
  // ^ the key is always 'tealium_event'
  // values will depend on your tealium implementation; standards: https://docs.tealium.com/platforms/javascript/track/#tealium_event

  //UDOs can contain any number of custom params
  "foo: "bar",
  "baz": "qux" 
}
```

In order to trigger Mixpanel events based on the values of `tealium_event`s, you’ll need to create a variable in Tealium’s data layer for `tealium_event` (the key not the value).

**This is a very common implementation pattern in Tealium**; if you’ve been using tealium for a while, you most likely have already mapped a UDO for `tealium_event` ... if you haven’t, here are the steps:

Find "data layer" in the main menu:

<Frame>
  <img alt="01-dataLayerMenu" />
</Frame>

Click "add variable":

<Frame>
  <img alt="02-addVar" />
</Frame>

The type is "UDO Variable"; the source is "tealium\_event" ... then click apply:

<Frame>
  <img alt="03-UDOVar" />
</Frame>

Now save and publish!

<Frame>
  <img alt="04-SavePublish" />
</Frame>

You should now see a "tealium\_event" variable in your UDOs:

<Frame>
  <img alt="05-TealiumEvent" />
</Frame>

( ^ it should look exactly like this! ^)

You are now ready to setup mixpanel events with triggers based on the *values* passed to `tealium_event` ... these values are usually strings like `page_view` , `product_view`, `search` etc...

## Connecting Mixpanel to Tealium

* Find the **tags** section of iQ Tag Manager:

<Frame>
  <img alt="06-NewTags" />
</Frame>

* Click **add tags** and find 'mixpanel' using the search

<Frame>
  <img alt="07-AddTag" />
</Frame>

* Click **add** to bring the Mixpanel tag into your Tealium workspace.

<Frame>
  <img alt="08-Mixpanel" />
</Frame>

You can now connect your Mixpanel project to Tealium and configure the tag's behavior.

You will need a [mixpanel account](https://mixpanel.com/register/) and a [mixpanel project](/docs/admin/organizations-projects/manage-projects) to continue.

In the first section of the tag wizard, enter your [**mixpanel project token**](https://help.mixpanel.com/hc/en-us/articles/115004502806-Find-Project-Token-) and click Next:

<Frame>
  <img alt="09-ConnectingTags" />
</Frame>

Next, you’ll setup **load rules** which determine which pages mixpanel will be deployed on.

In order for the mixpanel tag to appear on your pages, you will need to add a condition to your [**load rules**](https://docs.tealium.com/iq-tag-management/load-rules/about/) using the wizard. Load rules make it possible to conditionally apply tags in certain cases, based on variables and conditions that Tealium is aware of.

For testing, it’s perfectly fine to say "load on all pages":

<Frame>
  <img alt="10-LoadRules" />
</Frame>

Mixpanel should now be deployed on all known Tealium pages of your site. Next, you will set up mappings which fire Mixpanel events based on mappings created in Tealium.

## Sending Events

The final section of the tag wizard is where [**data mappings**](https://docs.tealium.com/iq-tag-management/data-mappings/about/) are configured. Data mappings are *essentially* a GUI-driven configuration that *will compose and deploy javascript snippets* on your Tealium-tagged pages (if the load rules are met).

That the goal of this guide is to turn something of this form:

```javascript theme={"system"}
var utag_data = {	"tealium_event": "page_view" }
```

Into the equivalent javascript:

```javascript theme={"system"}
mixpanel.track('hello from tealium!')
```

When a user loads the page.

Here’s how you can setup this mapping:

* Use the `tealium_event` UDO variable to tell Tealium to pass `tealium_event` *values* to the mixpanel tag:
* Click "variables" dropdown and choose "tealium\_event"

<Frame>
  <img alt="11-Variables" />
</Frame>

* Bind the trigger `page_view` (from the UDO `tealium_event`) *to* the mixpanel method `track`:
* Click 'add’ when it looks like this... and then done

<Frame>
  <img alt="12-Categories" />
</Frame>

* You should now have this binding:

<Frame>
  <img alt="13-Binding" />
</Frame>

This will track the UDO `page_view` wherever it appears on our site.

Next, give the event a name in mixpanel...

For this tutorial, we’ll use a [**custom value**](https://docs.tealium.com/iq-tag-management/data-mappings/about/#custom-value-mapping) ... this is added as another variable in tealium’s data mapper:

* Click "variables" drop down and choose use custom value:

<Frame>
  <img alt="14-CustomValue" />
</Frame>

* Define your "custom value"

<Frame>
  <img alt="15-CustomText" />
</Frame>

* Now, in the **event parameters** menu bind our custom value `hello... from tealium` to the `eventName` for `track`:

<Frame>
  <img alt="16-AddAndDone" />
</Frame>

* Click "add" and "done" when you’ve mapped your custom value to Track : Event Name

Our final mapping now looks like this:

<Frame>
  <img alt="17-FinalMapping" />
</Frame>

If your screen looks similar, you’re ready to save and publish!

<Frame>
  <img alt="18-SaveAndDone" />
</Frame>

Wait a couple moments for tealium to apply the updates to your environment, and then load one of your pages (that has this tag deployed)

Pop open the developer console in your browser... you can see two requests to mixpanel:

<Frame>
  <img alt="19-debugging" />
</Frame>

If you’re using a [tealium browser extension debugger,](https://chrome.google.com/webstore/detail/tealium-tools/gidnphnamcemailggkemcgclnjeeokaa?hl=en-US) or have forced the utag into [debug mode by modifying the cookie](https://docs.tealium.com/platforms/javascript/debugging/#debug-mode):

```jsx theme={"system"}
document.cookie="utagdb=true";
```

You can see the tag’s rendering states:

<Frame>
  <img alt="20-debugStates" />
</Frame>

Or... you can skip all that debugging noise and just go to mixpanel, and click into the [events report](https://help.mixpanel.com/hc/en-us/articles/4402837164948-Events-formerly-Live-View-) to see your new fresh event!

<Frame>
  <img alt="21-MixpanelEvents" />
</Frame>

You just implemented Tealium → Mixpanel. You will repeat this process for additional events you wish to create.

## Adding Event Properties

Because Tealium wraps the Mixpanel JS SDK, Mixpanel's [default event properties](/docs/data-structure/property-reference#default-properties) will be including on every event.

Any "custom" event properties will need to be mapped within Tealium using he following structure: **MY UDO ⇒**  **`track.properties.KEY_NAME`** where `KEY_NAME` is the **label** you want to use for the **property key in mixpanel**... the **value** will be the value of the UDO at runtime:

<Frame>
  <img alt="22-NewProps" />
</Frame>

A single event may have many custom properties mapped; that might look like this:

<Frame>
  <img alt="23-MultipleMappings" />
</Frame>

Adding event properties is as simple as modifying the existing mapping to an event, and saving and publishing. Once you trigger your new tag you will the correct UDO value *and* the label you specified in the mapper show up in mixpanel

<Frame>
  <img alt="24-SuccessfulEvent" />
</Frame>

Note: you can always rename property keys' display labels [in lexicon](https://help.mixpanel.com/hc/en-us/articles/360001307806-Lexicon-Overview#adding-or-changing-descriptions)

## Identifying Users

**Important:** cross device tracking assumes you know the identity of the current user.. **`identify()`** should *only* be called on "authenticated" (logged in) pages/actions.

Ultimately, we are trying to get Tealium to render this tag:

```js theme={"system"}
mixpanel.identify(uniqueUserId)
```

Where `uniqueUserId` is a string value that refers to the canonical user id for the current ("logged in") user.

It’s critically important that this value uniquely identifies the end-user, across all devices they may have.

**Note:** some customer are tempted to use an email address as a unique identifier; this is (generally) not a good identifier, especially if users can change their email address... the value you pass to `identify` should never change for a single user.

* Assuming we have a UDO (or other javascript variable) that points to our UUID (unique user identifier)

<Frame>
  <img alt="25-IdentityStart" />
</Frame>

* Next, instruct Tealium when to use our `identify` tag... this is similar to how we used `page_view:track` directive to tell tealium to call `.track()` on the "tealium event" "page\_view" ... you will probably use some other UDO event here (like `log in` or `sign in`):

<Frame>
  <img alt="26-IdentityMap" />
</Frame>

* Select the `id_of_user` UDO (or whatever value represents our UUID for the end user) in the dropdown and proceed to **SELECT DESTINATION**

<Frame>
  <img alt="27-IdentityAdd" />
</Frame>

* Finally, map the `id_of_user` value to `event parameters` for the `identify` event and choose the specific parameter `unique ID` ... then click **ADD**

<Frame>
  <img alt="28-IdentityFinish" />
</Frame>

A final implementation of mixpanel within Tealium might look like this:

<Frame>
  <img alt="29-SampleComplete" />
</Frame>


# Vendo
Source: https://docs.mixpanel.com/docs/tracking-methods/integrations/vendo



## Overview

The Vendo integration with Mixpanel enables you to seamlessly sync events and properties across different data sources. This guide provides instructions on how to set up and configure Vendo to sync data to Mixpanel.

## How the Integration Works

Vendo collects event data from various sources like ad platforms, payment platforms and transforms the messages to match Mixpanel’s event schema, and forwards the enriched data into your Mixpanel project. Vendo also archives a copy of the data and can route it to additional storage systems if needed.

Mixpanel is one of the supported downstream destinations for Vendo. With this integration, you can seamlessly send data from your Vendo sources into your Mixpanel project.

For details about connections and configuration options, see [Vendo Developer Docs](https://docs.vendodata.com/en/?utm_source=mixpanel-partner-portal\&utm_medium=partner).

## Prerequisites

Before you begin, ensure you have the following:

* **Vendo Account:** Access to your Vendo dashboard.
* **Mixpanel Project:** An active Mixpanel project with API keys.
* **App Access:** Access to the apps that you want to connect with Vendo.

## Integration Setup

Follow these steps to configure Vendo for sending Google Ads to Mixpanel. The integration flow is similar for all sources.

1. Under Data Import, create a new connection.

<Frame>
  <img alt="vendo1" />
</Frame>

2. Select the data source you’d like to integrate to Mixpanel.

<Frame>
  <img alt="vendo1" />
</Frame>

3. Click "Connect App".

<Frame>
  <img alt="vendo1" />
</Frame>

4. Complete the authentication for the data source.

<Frame>
  <img alt="vendo1" />
</Frame>

5. Configure the source.

<Frame>
  <img alt="vendo1" />
</Frame>

6. Set Mixpanel as the downstream destination.

<Frame>
  <img alt="vendo1" />
</Frame>

7. Provide the details for your target Mixpanel project. These can be found in your project settings.

<Frame>
  <img alt="vendo1" />
</Frame>

8. Finalize the connection settings. Provide a name for the integration and optionally provide the start date if you are importing historical data.

<Frame>
  <img alt="vendo1" />
</Frame>


# SDKs
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks

Send data from your application into Mixpanel

Our SDKs allow you to implement Mixpanel in a wide range of environments. Visit our [Github repo](https://github.com/mixpanel) to see the library source code.

If you do not see an SDK in your preferred language, leverage our [HTTP APIs](/reference/ingestion-api) directly.

## Client-Side SDKs

<CardGroup>
  <Card title="Javascript" href="/docs/tracking-methods/sdks/javascript" />

  <Card title="React Native" href="/docs/tracking-methods/sdks/react-native" />

  <Card title="Android" href="/docs/tracking-methods/sdks/android" />

  <Card title="iOS (Objective-C)" href="/docs/tracking-methods/sdks/ios" />

  <Card title="iOS (Swift)" href="/docs/tracking-methods/sdks/swift" />

  <Card title="Flutter" href="/docs/tracking-methods/sdks/flutter" />

  <Card title="Unity" href="/docs/tracking-methods/sdks/unity" />
</CardGroup>

## Server-Side SDKs

<CardGroup>
  <Card title="Python" href="/docs/tracking-methods/sdks/python" />

  <Card title="Node.js" href="/docs/tracking-methods/sdks/nodejs" />

  <Card title="Ruby" href="/docs/tracking-methods/sdks/ruby" />

  <Card title="PHP" href="/docs/tracking-methods/sdks/php" />

  <Card title="Go" href="/docs/tracking-methods/sdks/go" />

  <Card title="Java" href="/docs/tracking-methods/sdks/java" />
</CardGroup>

## Session Replay SDKs

<CardGroup>
  <Card title="Session Replay (Android)" href="/docs/tracking-methods/sdks/android/android-replay" />

  <Card title="Session Replay (Swift)" href="/docs/tracking-methods/sdks/swift/swift-replay" />

  <Card title="Session Replay (React Native)" href="/docs/tracking-methods/sdks/react-native/react-native-replay" />
</CardGroup>

## Utility

<CardGroup>
  <Card title="Mixpanel-utils Module↗" href="https://github.com/mixpanel/mixpanel-utils" />
</CardGroup>


# Mixpanel SDKs: Android
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/android



## Getting Started

Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=android).

The [Full API Reference](http://mixpanel.github.io/mixpanel-android/index.html), [Library Source Code](https://github.com/mixpanel/mixpanel-android), and an [Example Application](https://github.com/mixpanel/sample-android-mixpanel-integration) is documented in our GitHub repo.

## Installing the Library

We publish builds of our library to the Maven central repository as an .aar file. This file contains all of the classes, resources, and configurations that you'll need to use the library.

To install the library inside Android Studio, declare it as dependency in your build.gradle file by adding the following line to the `dependencies` section in `app/build.gradle`:

```java Java theme={"system"}
implementation "com.mixpanel.android:mixpanel-android:7.+"
```

Once you've updated your `build.gradle` file, force Android Studio to sync with your new configuration by clicking the "Sync Project with Gradle Files" icon at the top of the window.

<Frame>
  <img alt="image" />
</Frame>

This should download the .aar dependency at which point you'll have access to the Mixpanel library API calls. If it cannot find the dependency, you should make sure you've specified `mavenCentral()` as a repository in your `build.gradle`.

In order for the library to work you'll need to ensure that you're requesting the following permissions in your `AndroidManifest.xml`:

```xml Java theme={"system"}
<!--
This permission is required to allow the application to send
events and properties to Mixpanel.
-->
<uses-permission
  android:name="android.permission.INTERNET" />

<!--
  This permission is optional but recommended so we can be smart
  about when to send data.
 -->
<uses-permission
  android:name="android.permission.ACCESS_NETWORK_STATE" />

<!--
  This permission is optional but recommended so events will
  contain information about bluetooth state
-->
<uses-permission
  android:name="android.permission.BLUETOOTH" />
```

After the installation, import the library and initialize Mixpanel in your code by calling [`MixpanelAPI.getInstance()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#getInstance\(android.content.Context,java.lang.String,boolean\)) with your application context, your [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens), and `false` value for automatic events.

```java Java theme={"system"}
import com.mixpanel.android.mpmetrics.MixpanelAPI;


public class MainActivity extends ActionBarActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        MixpanelAPI mixpanel = MixpanelAPI.getInstance(this, "YOUR_PROJECT_TOKEN", false);
    }
}
```

### Library Configuration

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/android#privacy-friendly-tracking).
</Warning>

The library can be initialized with different configurations. See a complete list of the configuration options and methods under [`MPConfig`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MPConfig.html).

You can set the library configuration by adding `meta-data` entries under the `<application>` of your app's `AndroidManifest.xml`.

**Example Usage**

```xml Java theme={"system"}
<!-- disable auto flushing on app backgrounding -->
<meta-data android:name="com.mixpanel.android.MPConfig.FlushOnBackground"
           android:value="false" />
<!-- enable debug logs -->           
<meta-data android:name="com.mixpanel.android.MPConfig.EnableDebugLogging"
           android:value="true" />
```

The [`MPConfig`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MPConfig.html) provide a few methods that you can call to set and retrieve your configuration after the library has already been initialized.

**Example Usage**

```java Java theme={"system"}
// initialize Mixpanel with automatic events disabled
trackAutomaticEvents = false;
MixpanelAPI mixpanel = 
    MixpanelAPI.getInstance(this, "YOUR_PROJECT_TOKEN", trackAutomaticEvents);
```

## Sending Events

Use [`.track()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#track\(java.lang.String\)) to send an event by providing the event name and any event properties. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```java Java theme={"system"}
// initialize Mixpanel
MixpanelAPI mixpanel = 
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false);

//Create event properties object
JSONObject props = new JSONObject();
props.put('Gender', 'Female');
props.put('Plan', 'Premium');

//track "some_event"
// with "Gender" and "Plan" event properties
mixpanel.track('some_event', props);
```

### Timing Events

You can track the time it took for an action to occur, such as an image upload or a comment post, using [`.timeEvent()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#timeEvent\(java.lang.String\)). This will mark the "start" of your action, which will be timed until you finish with a track call. The time duration is then recorded in the "Duration" property.

**Example Usage**

```java Java theme={"system"}
MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, MIXPANEL_TOKEN, false);

// start the timer for the event "Image Upload"
mixpanel.timeEvent("Image Upload");

// 20 seconds later...

// stop the timer if the imageUpload() method returns true
if(imageUpload()){
    // track "Image Upload" event with "Duration" event prop set to 20
    mixpanel.track("Image Upload");
}
```

### Flushing Events

To preserve battery life and customer bandwidth, the Mixpanel library doesn't send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background.

Call [`.flush()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#flush\(\)) manually if you want to force a flush at a particular moment.

**Example Usage**

```java Java theme={"system"}
// flush batched events for ingestion immediately
mixpanel.flush();
```

**Flush Batch Size**

By default, Mixpanel will flush events immediately if a batch reaches 50 events. Use the [`.setFlushBatchSize()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#setFlushBatchSize\(int\)) method to adjust the batch size limit for flushing.

**Example Usage**

```java Java theme={"system"}
// flush if event batch size reaches 100
mixpanel.setFlushBatchSize(100);
```

#### Importing Historical Events

The Android SDK is a tracking SDK designed for real-time tracking in a client-side environment. Calling `.track()` triggers a request to our [/track API endpoint](/reference/track-event), which will validate for events with a timestamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested**.

For bulk import of historical events older than 5 days, we will need to use the [/import API endpoint](/reference/import-events) which is optimized for scripting and supports ingesting historical data. We recommend the [Python SDK](/docs/tracking-methods/sdks/python) (see the [`.import_data()`](https://mixpanel.github.io/mixpanel-python/#primary-interface) function) and [mixpanel-utils module](https://github.com/mixpanel/mixpanel-utils) (see the [`import_events()`](https://github.com/mixpanel/mixpanel-utils?tab=readme-ov-file#import-events) function) which both leverages the /import API for event ingestion.

## Setting Super Properties

Super properties are global event properties that you define once and apply to all events.

To register super properties, call [`.registerSuperProperties()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#registerSuperProperties\(org.json.JSONObject\)).

Use [`.registerSuperPropertiesOnce()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#registerSuperPropertiesOnce\(org.json.JSONObject\)) to register super properties without overwriting existing values.

```java Java theme={"system"}
MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false);

// register "name" as a super property
JSONObject props = new JSONObject();
props.put('name', 'Sam');
mixpanel.registerSuperProperties(props);

//register "city" as an additional super property
// ignore "name" since it already exists
JSONObject moreProps = new JSONObject();
moreProps.put('name', 'Samantha');
moreProps.put('city', 'San Francisco');
mixpanel.registerSuperPropertiesOnce(moreProps);


//track "some_event"
// event will include "name" prop set to "Sam"
// and "city" prop set to "San Francisco"
mixpanel.track('some_event');
```

If you have properties you'd like all events to include, you can also set the super properties when initializing the Mixpanel object.

**Example Usage**

```java Java theme={"system"}

// create object of super properties
JSONObject yourSuperProps = new JSONObject();
yourSuperProps.put('name', 'Samantha');
yourSuperProps.put('city', 'San Francisco');

//create Mixpanel instance with super properties above
MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', yourSuperProps, false);
```

Our mobile libraries store your super properties in local storage. They will persist so long as the app is installed (between launches and updates). Uninstalling the app will remove that customers super properties.

See more methods related to super properties in the complete library reference [here](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html).

## Managing User Identity

You can handle the identity of a user using the [`.identify()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#identify\(java.lang.String,boolean\)) and [`.reset()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#reset\(\)) methods. Learn more about [identity management](/docs/tracking-methods/id-management/identity-management) and [identifying users](/docs/tracking-methods/id-management/identifying-users).

### Identify

<Warning>
  We recommend against calling `.identify()` for anonymous visitors to your site.
</Warning>

Call [`.identify()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#identify\(java.lang.String,boolean\)) when you know the identity of the current user, passing in their user ID as an argument. This is typically at account registration and at log in.

```java Java theme={"system"}
// create Mixpanel instance
MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false);

// user logs in and tracks a sign in event
mixpanel.track('sign in');

// upon sign in, identify the user with their ID
// ensure future events sent from the user have distinct_id 12345
mixpanel.identify('12345');
```

### Call Reset at Logout

Call [`.reset()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#reset\(\)) to clear data attributed to a user when they logout. This will clear the local storage and allows you to handle [multiple users on a single device](/docs/tracking-methods/id-management/identifying-users-simplified#multiple-users-one-device).

**Example Usage**

```java Java theme={"system"}
// your user logs out and tracks a log out event
mixpanel.track('log out');

// clear local storage and generate new distinct_id
mixpanel.reset();
```

### Custom Device ID Generation

The Android SDK provides a [`DeviceIdProvider`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/DeviceIdProvider.html) interface for implementing custom device ID generation logic. This allows you to control where device IDs are stored and whether they persist across `.reset()` calls.

<Warning>
  Using a custom device ID provider is an architectural decision that should be made at project inception. Changing this after deployment can cause user identity management issues.
</Warning>

Configure the device ID provider using [`MixpanelOptions.Builder()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelOptions.Builder.html) when initializing the SDK. If the provider returns `null`, an empty string, or throws an exception, the SDK will fall back to generating a UUID-based device ID.

**Example Usage**

```java Java theme={"system"}
// create a device ID provider
DeviceIdProvider provider = () -> {
    return getYourCustomDeviceId();
};

// configure Mixpanel with custom device ID provider
MixpanelOptions options = new MixpanelOptions.Builder()
    .deviceIdProvider(provider)
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(
    context,
    "YOUR_PROJECT_TOKEN",
    false,
    options
);
```

**Persistent vs Ephemeral IDs**

Returning the same value each time the provider is called creates a persistent device ID that survives `.reset()` calls. Returning different values generates a new device ID on each reset.

```java Java theme={"system"}
// persistent ID - survives reset() calls
DeviceIdProvider persistentProvider = () -> {
    return getStoredDeviceId(); // returns same value every time
};

// ephemeral ID - changes on reset() calls
DeviceIdProvider ephemeralProvider = () -> {
    return generateNewDeviceId(); // returns new value each time
};
```

## Storing User Profiles

Once your users are identified, create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Android SDK provides a few methods for setting profile properties under the [`MixpanelAPI.People`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html) interface accessible via [`.getPeople()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#getPeople\(\)). These methods will trigger requests to the [/engage API endpoint](/reference/profile-set).

### Setting Profile Properties

<Note>
  You must call `.identify()` before setting profile properties in order to associate the profile properties you set with the target user. If identify is not called, the profile update will be queued for ingestion until an identify call is made.
</Note>

Set profile properties on a user profile by calling the [`.getPeople().set()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#set\(org.json.JSONObject\)) method.

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```java Java theme={"system"}
MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false);

// You must call identify to associate the profile update with the user
// the first param is for the user ID
// the second param is a flag for allowing profile updates
mixpanel.identify('12345', true);

// Sets user's "Plan" attribute to "Premium"
mixpanel.getPeople().set('plan', 'Premium');

// Update "plan" from "Premium" to "Enterprise"
mixpanel.getPeople().set('plan', 'Enterprise');
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html)

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title=".setOnce()">
    The [`.getPeople().setOnce()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#setOnce\(org.json.JSONObject\)) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```java Java theme={"system"}
    // set profile properties for user "1234"
    JSONObject props = new JSONObject();
    props.put('name', 'Sam');

    mixpanel.identify('1234', true);
    mixpanel.getPeople().set(props);

    // will be ignored since "name" already exists
    mixpanel.getPeople().setOnce('name', 'Samantha');

    // set "location" group prop since it does not exist
    mixpanel.getPeople().setOnce('location', 'us');
    ```
  </Tab>

  <Tab title=".append()">
    The [`.getPeople().append()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#append\(java.lang.String,java.lang.Object\)) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```java Java theme={"system"}
    // set profile properties for user "1234"
    JSONObject props = new JSONObject();
    String roles[] = {'sales','engineer'};
    props.put('name', 'Sam');
    props.put('roles', roles);

    mixpanel.identify('1234', true);
    mixpanel.getPeople().set(props);

    // add "legal" to "roles"  
    // new role values are ['sales','engineer','legal']
    mixpanel.getPeople().append('roles', 'legal');

    // .append() allows duplicates
    // new "roles" values are ['sales','engineer','legal', 'legal']
    mixpanel.getPeople().append('roles', 'legal');
    ```
  </Tab>

  <Tab title=".union()">
    The [`.getPeople().union()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#union\(java.lang.String,org.json.JSONArray\)) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```java Java theme={"system"}
    // set profile properties for user "1234"
    JSONObject props = new JSONObject();
    String roles[] = {'sales','engineer'};
    props.put('name', 'Sam');
    props.put('roles', roles);

    mixpanel.identify('1234', true);
    mixpanel.getPeople().set(props);

    // append "engineer" to "roles"
    // will be ignored since "engineer" already exists in "roles"
    mixpanel.getPeople().union('roles', 'engineer');

    // append "legal" to "roles"
    // new role values are ['sales','engineer','legal']
    mixpanel.getPeople().union('roles', 'legal');
    ```
  </Tab>

  <Tab title=".increment()">
    The [`.getPeople().increment()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#increment\(java.lang.String,double\)) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```java Java theme={"system"}
    // set profile properties for user "1234"
    JSONObject props = new JSONObject();
    props.put('name', 'Sam');
    props.put('age', 25);

    mixpanel.identify('1234', true);
    mixpanel.getPeople().set(props);

    // increment "age" by 2
    mixpanel.getPeople().increment('age',2);

    // use negative number to decrement
    // decrement "age" by 5
    mixpanel.getPeople().increment('age',-5);
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

The Android SDK provides a few method for adding individual users to a group and setting group profile properties.

### Adding Users to a Group

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

Call the [`.setGroup()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#setGroup\(java.lang.String,java.util.List\)) method to register the current user to a group, which would add the `group_key` as an event property set to the `group_id` value to all events moving forward.

**Example Usage**

```java Java theme={"system"}
// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');
 
// track "some_event"
// event property "company" = ["mixpanel"] is added automatically
mixpanel.track('some_event');

//alternatively you can manually define the group key
JSONObject groupKey = new JSONObject();
groupKey.put('company','mixpanel');

mixpanel.track('some_event', groupKey)
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

Call [`.addGroup()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#addGroup\(java.lang.String,java.lang.Object\)) to add additional `group_id`s to an existing list.

**Example Usage**

```java Java theme={"system"}
// assign the current user to the "mixpanel" company group
// events will contain 'company' prop set to ["mixpanel"]
mixpanel.setGroup('company', 'mixpanel');

// add "mp-us" as an additional company group
// new "company" value is ["mixpanel","mp-us"]
mixpanel.addGroup('company', 'mp-us');

// track "some_event"
// event property "company" = ["mixpanel","mp-us"] is added automatically
mixpanel.track('some_event');
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `.getPeople().set()` call.

**Example Usage**

```java Java theme={"system"}
MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false);

mixpanel.identify('12345', true);

// Sets group key "company" as a user prop 
// with group id "mixpanel" as the value
mixpanel.getPeople().set('company', 'mixpanel');
```

### Setting Group Profile Properties

Create a group profile by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

To set group profile properties, specify the group that needs to be updated by calling [`.getGroup()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#getGroup\(java.lang.String,java.lang.Object\)), then set the group properties by chaining the [`.set()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#set\(org.json.JSONObject\)) method, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```java Java theme={"system"}
// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');

// specify the target group using the group_key and group_id
// set "industry" as a group profile prop to "analytics"
mixpanel.getGroup('company','mixpanel').set('industry','analytics');
```

### Other Group Profile Methods

See all of the methods under the Group class [here](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title=".setOnce()">
    The [`.getGroup().setOnce()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#setOnce\(org.json.JSONObject\)) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```java Java theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    JSONObject groupProps = new JSONObject();
    groupProps.put('name', 'Mixpanel');

    mixpanel.getGroup('company','mixpanel').set(groupProps);

    // ignored since "name" is already exists
    mixpanel.getGroup('company','mixpanel').setOnce('name','mp');

    // set "location" group prop since it does not exist
    mixpanel.getGroup('company','mixpanel').setOnce('location','us');
    ```
  </Tab>

  <Tab title=".unset()">
    The [`.getGroup().unset()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#unset\(java.lang.String\)) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```java Java theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    JSONObject groupProps = new JSONObject();
    groupProps.put('name', 'Mixpanel');
    groupProps.put('employee_count', '100');

    mixpanel.getGroup('company','mixpanel').set(groupProps);

    // delete "employee_count" from the group profile
    mixpanel.getGroup('company','mixpanel').unset('employee_count');

    // only "name" remains as a group prop
    ```
  </Tab>

  <Tab title=".union()">
    The [`.getGroup().union()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#union\(java.lang.String,org.json.JSONArray\)) method append new values to a list property, excluding duplicates.

    Use this method to create a list group profile property that only contains unique values without duplicates.

    **Example Usage**

    ```java Java theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    JSONObject groupProps = new JSONObject();
    String features[] = {'reports','alerts','cohorts'};
    groupProps.put('name', 'Mixpanel');
    groupProps.put('features', features);

    mixpanel.getGroup('company','mixpanel').set(groupProps);


    // add "data pipeline" to "features" prop
    // ignore "alert" since it is a duplicate value
    mixpanel.getGroup('company','mixpanel').union('features', [
        'data pipeline',
        'alerts'
        ]);
    ```
  </Tab>

  <Tab title=".remove()">
    The [`.getGroup().remove()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#remove\(java.lang.String,java.lang.Object\)) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```java Java theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    JSONObject groupProps = new JSONObject();
    String features[] = {'reports','alerts','cohorts'};
    groupProps.put('name', 'Mixpanel');
    groupProps.put('features', features);

    mixpanel.getGroup('company','mixpanel').set(groupProps);

    //remove "alerts" from "features"
    // "features" now contain ["reports","cohorts"]
    mixpanel.getGroup('company','mixpanel').remove('features', 'alerts');
    ```
  </Tab>
</Tabs>

## Autocapture

The Mixpanel Android SDK provides methods on the `autocapture` object to help you track common user interactions with minimal instrumentation. These methods fire standardized events that are recognized by the Mixpanel platform.

### Screen View & Screen Leave

Modern mobile apps use a variety of UI frameworks and architectural patterns — single-Activity apps with Jetpack Compose, multi-Activity apps with Fragments, or a mix of both. Each defines and transitions between "screens" differently, making it impractical for the SDK to automatically detect screen boundaries across all setups. Instead, you hook `trackScreenView` and `trackScreenLeave` into your app's navigation, giving you full control over what counts as a screen and when transitions happen.

Track screen navigations using `trackScreenView` and `trackScreenLeave`. These methods fire the following events:

| Method               | Mixpanel Event   |
| -------------------- | ---------------- |
| `trackScreenView()`  | `$mp_page_view`  |
| `trackScreenLeave()` | `$mp_page_leave` |

Both events automatically include `current_page_title` (the screen name) and `$mp_autocapture: true`.

<Tabs>
  <Tab title="Jetpack Compose">
    Observe the navigation controller's current route inside a `LaunchedEffect`:

    ```kotlin theme={"system"}
    val currentRoute = navController.currentBackStackEntryAsState().value?.destination?.route
    var previousRoute by remember { mutableStateOf<String?>(null) }

    LaunchedEffect(currentRoute) {
        currentRoute?.let { route ->
            val mixpanel = MixpanelAPI.getInstance(context, "YOUR_TOKEN", true)

            previousRoute?.let { mixpanel.autocapture.trackScreenLeave(it) }
            mixpanel.autocapture.trackScreenView(route)

            previousRoute = route
        }
    }
    ```
  </Tab>
</Tabs>

#### Passing Custom Properties

Both methods accept an optional `JSONObject` parameter for custom properties. For example, forwarding UTM params from a deep link:

```kotlin theme={"system"}
val utmProps = JSONObject().apply {
    put("utm_source", uri.getQueryParameter("utm_source"))
    put("utm_medium", uri.getQueryParameter("utm_medium"))
    put("utm_campaign", uri.getQueryParameter("utm_campaign"))
}
mixpanel.autocapture.trackScreenView("PromoScreen", utmProps)
```

## Session Replay

Install the [Session Replay SDK for Android](/docs/tracking-methods/sdks/android/android-replay) to record replay data. Learn more about [Session Replay](/docs/session-replay) and [implementing Session Replay on Android](/docs/tracking-methods/sdks/android/android-replay).

## Debugging and Logging

### Enable SDK logs

To enable debug mode, add the following permission within your `AndroidManifest.xml` inside the `<application>` tag:

```xml Java theme={"system"}
...
<application>
    <!-- enable debug logging-->
    <meta-data
      android:name="com.mixpanel.android.MPConfig.EnableDebugLogging"
      android:value="true" />
    ...
</application>
...
```

Learn more about [debugging](/docs/tracking-best-practices/debugging).

### Network Failover

Configure a backup host for automatic failover when the primary API endpoint is unreachable. The default primary endpoint is `api.mixpanel.com` (or your configured custom endpoint for EU/India data residency or proxy server). This can be used as a troubleshooting fallback when network calls to the Mixpanel endpoint are blocked or unreachable.

**Setup**

```java Java theme={"system"}
MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN");
mixpanel.setBackupHost("api-backup.mixpanel.com");
```

**AndroidManifest.xml Configuration**

```xml theme={"system"}
<application>
    <meta-data
      android:name="com.mixpanel.android.MPConfig.BackupHost"
      android:value="api-backup.mixpanel.com" />
</application>
```

The SDK automatically retries failed requests to the backup host, preserving the same URL path, authentication, and headers as the primary.

**How It Works**

Failover triggers:

* Network failures (connection timeout, DNS errors)
* Non 4xx HTTP status codes

No failover for:

* Client errors (HTTP 4xx) - indicates invalid request
* Successful responses (HTTP 200 OK)
* Parse errors

This works with proxy server setups as well - if the proxy fails, the backup will be tried.

**Requirements**

Your backup host must:

* Support the same API endpoints (`/track/`, `/engage/`, `/groups/`)
* Accept the same authentication mechanism as the primary host
* Use the same URL scheme and port as configured for the primary host

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Android SDK provide methods to help you protect user data.

Learn more about [Privacy](/docs/privacy/overview).

### Opt Out of Tracking

The Android SDK is initialized with tracking enabled by default. Use the [`.optOutTracking()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#optOutTracking\(\)) method to opt the user out of data tracking and local storage for the current Mixpanel instance.

**Example Usage**

```java Java theme={"system"}
//send "some_event"
mixpanel.track('some_event');

// opt user out of tracking
// SDK is prevented from sending any data
mixpanel.optOutTracking();

// this track call will not work
mixpanel.track('some_other_event');
```

**Opt Out by Default**

You can initialize the library with users opted out of tracking by default using the `optOutTrackingDefault` configuration. Once the user is ready to be tracked, call [`.optInTracking()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#optInTracking\(\)) to start tracking.

**Example Usage**

```java Java theme={"system"}
// users opted out of tracking by default
optOutTrackingDefault = true;
trackAutomaticEvents = false;
MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', optOutTrackingDefault, trackAutomaticEvents);


// this track call will not work
mixpanel.track('some_event');

// opt user back into tracking
mixpanel.optInTracking();
 
// this track call will work
mixpanel.track('some_other_event');
```

### EU Data Residency

Route data to Mixpanel's EU servers by setting the `serverURL` to `https://api-eu.mixpanel.com` during initialization using `MixpanelOptions`.

<Note>
  Setting `serverURL` during initialization ensures all requests (events, profiles, and feature flags) use the correct endpoint from the start.
</Note>

```java Java theme={"system"}
MixpanelOptions options = new MixpanelOptions.Builder()
    .serverURL("https://api-eu.mixpanel.com")
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", trackAutomaticEvents, options);
```

You can also configure endpoints via `<meta-data>` tags in your `AndroidManifest.xml` under the `<application>` tag:

```xml Java theme={"system"}
...
<application>
    <!--set request URLs to Mixpanel EU domain-->
    <meta-data android:name="com.mixpanel.android.MPConfig.EventsEndpoint"
           android:value="https://api-eu.mixpanel.com/track?ip=1" />
    <meta-data android:name="com.mixpanel.android.MPConfig.PeopleEndpoint"
           android:value="https://api-eu.mixpanel.com/engage?ip=1" />
    <meta-data android:name="com.mixpanel.android.MPConfig.GroupsEndpoint"
           android:value="https://api-eu.mixpanel.com/groups" />
    <meta-data android:name="com.mixpanel.android.MPConfig.FlagsEndpoint"
           android:value="https://api-eu.mixpanel.com/flags" />
    ...
</application>
...
```

### India Data Residency

Route data to Mixpanel's India servers by setting the `serverURL` to `https://api-in.mixpanel.com` during initialization using `MixpanelOptions`.

<Note>
  Setting `serverURL` during initialization ensures all requests (events, profiles, and feature flags) use the correct endpoint from the start.
</Note>

```java Java theme={"system"}
MixpanelOptions options = new MixpanelOptions.Builder()
    .serverURL("https://api-in.mixpanel.com")
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", trackAutomaticEvents, options);
```

You can also configure endpoints via `<meta-data>` tags in your `AndroidManifest.xml` under the `<application>` tag:

```xml Java theme={"system"}
...
<application>
    <!--set request URLs to Mixpanel India domain-->
    <meta-data android:name="com.mixpanel.android.MPConfig.EventsEndpoint"
           android:value="https://api-in.mixpanel.com/track?ip=1" />
    <meta-data android:name="com.mixpanel.android.MPConfig.PeopleEndpoint"
           android:value="https://api-in.mixpanel.com/engage?ip=1" />
    <meta-data android:name="com.mixpanel.android.MPConfig.GroupsEndpoint"
           android:value="https://api-in.mixpanel.com/groups" />
    <meta-data android:name="com.mixpanel.android.MPConfig.FlagsEndpoint"
           android:value="https://api-in.mixpanel.com/flags" />
    ...
</application>
...
```

### Disable Geolocation

The Android SDK parse the request IP address to generate geolocation properties for events and profiles. To disable geolocation, add the following meta-data entry under the `<application>` tag of your app's `AndroidManifest.xml`.

```xml Java theme={"system"}
<application>
...
  <!-- disable geolocation parsing -->
  <meta-data android:name="com.mixpanel.android.MPConfig.UseIpAddressForGeolocation" 
            android:value="false" />
...
</application>
```

Learn more about [geolocation](/docs/tracking-best-practices/geolocation).

## App Links Tracking

The Mixpanel library has built in support for tracking in-bound and out-bound [App Links](https://developers.facebook.com/docs/applinks). App Links is a specification to help standardize deep-linking between apps as well as give you additional information about how users are getting to and from your own mobile app.

In order for Mixpanel to track App Links, your app must satisfy the following dependencies:

* [Bolts Framework](https://github.com/BoltsFramework/Bolts-Android) >= v1.1.2
* [Android Support Library v4](https://developer.android.com/topic/libraries/support-library/features#v4)+.

<Note>
  If your application does not meet these requirements, the Mixpanel library will log debug messages about App Links tracking not being enabled. This is NOT an error and can be safely ignored.
</Note>

**Tracking In-bound App Links**

If a user comes to your app via an App Link, Mixpanel will automatically track a `$al_nav_in` event with meta information about where they came from.

**Tracking Out-bound App Links**

If you're linking to other applications using the Bolts framework, Mixpanel will track a `$al_nav_out` event with additional meta information about where the user is being linked to.

```java Java theme={"system"}
...
bolts.AppLinkNavigation.navigateInBackground(this, "http://anotherapp.com/app/link");
...
```

## Tracking Via Proxy

This guide demonstrates how to route events from Mixpanel's Android SDKs via a proxy in your own domain. This is useful to reduce the likelihood of ad-blockers impacting your tracking.

There are two steps: setting up a proxy server and pointing the SDK at your server.

**Step 1: Set up a proxy server** The simplest way is to use our [sample nginx config](https://github.com/mixpanel/tracking-proxy). This config redirects any calls made to your proxy server to Mixpanel.

**Step 2: Point Android SDK at your server**

Add the following line, replacing `YOUR_PROXY_DOMAIN` with your proxy server's domain.

**Example Usage**

```java theme={"system"}
// route data to your proxy server
mixpanel.setServerURL("https://<YOUR_PROXY_DOMAIN>");
```

## Backup Host

When you set a backup host, the SDK will first attempt to send data to the primary Mixpanel endpoint. If this request fails, the SDK will then automatically retry the request using the specified backup host. The SDK will use the same URL path, protocol (HTTP/HTTPS), and query parameters as the original request, only replacing the primary host portion of the URL with the backup host.

**Example Usage via SDK**

```java theme={"system"}
// route data to your backup host
mixpanel.setBackupHost("my.backuphost.com");
```

**Example Usage via AndroidManifest.xml**

You can also set your backup host in your `AndroidManifest.xml`:

```xml Java theme={"system"}
<meta-data android:name="com.mixpanel.android.MPConfig.BackupHost" 
           android:value="my.backuphost.com" />
```

## Release History

[See All Releases](https://github.com/mixpanel/mixpanel-android/releases).


# Implement Feature Flags (Android)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/android/android-flags



## Overview

This developer guide will assist you in configuring your Android platform for Feature Flags using the [Mixpanel Android SDK](/docs/tracking-methods/sdks/android). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

For complete Android SDK documentation, see the [Android SDK guide](/docs/tracking-methods/sdks/android).

## Prerequisites

Before implementing Feature Flags, ensure:

* You are on an Enterprise subscription plan  and have the latest version of the SDK installed (minimum supported version is [`v8.2.4`](https://github.com/mixpanel/mixpanel-android/releases/tag/v8.2.4)). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK.
* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Flag Initialization

Initializing the SDK with feature flags enabled requires passing a `FeatureFlagOptions` configuration to `MixpanelOptions`. This enables making an outbound request to Mixpanel servers with the current user context. The server will assign the user context to a variant for each feature flag according to how they are configured in the Mixpanel UX.

The response will include an assigned variant for each flag that the user context is in a rollout group for. If a flag is not returned, it most likely signifies that the user was either not in the rollout percentage for a flag or in the configured targeting cohort.

**Example Usage**

```java Java theme={"system"}
FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .build();

MixpanelOptions options = new MixpanelOptions.Builder()
    .featureFlagOptions(featureFlagOptions)
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", false, options);
```

If your flag is configured with a Variant Assignment Key other than `distinct_id` or `device_id` for any of the feature flags in your project, then the call to initialize feature flags must include those keys.

For example, for a Variant Assignment Key, `company_id`, you would setup the SDK as follows:

```java Java theme={"system"}
JSONObject context = new JSONObject();
context.put("company_id", "X");

FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .context(context)
    .build();

MixpanelOptions options = new MixpanelOptions.Builder()
    .featureFlagOptions(featureFlagOptions)
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(getApplicationContext(), "YOUR_PROJECT_TOKEN", false, options);
```

If you are using Runtime Targeting in any of the feature flags in your project, then any properties that you use in targeting should be included in a `custom_properties` node within the context:

```java theme={"system"}
JSONObject customProperties = new JSONObject();
customProperties.put("platform", "android");

JSONObject context = new JSONObject();
context.put("company_id", "X");
context.put("custom_properties", customProperties);

FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .context(context)
    .build();

MixpanelOptions options = new MixpanelOptions.Builder()
    .featureFlagOptions(featureFlagOptions)
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(getApplicationContext(), "YOUR_PROJECT_TOKEN", false, options);
```

## Flag Persistence

Minimum supported SDK version: [`v8.7.0`](https://github.com/mixpanel/mixpanel-android/releases/tag/v8.7.0)

By default (`networkOnly`), the SDK fetches fresh flag assignments and waits for the network response before variant calls complete. You can enable persistence to persist assignments to SharedPreferences so they are available immediately on subsequent launches.

Configure a `variantLookupPolicy` on the `FeatureFlagOptions` builder:

**`networkFirst`** — The SDK waits for the network on every launch. If the network call fails, the persisted value is returned as a fallback. Async getter calls block until the fetch completes (or the fallback is resolved).

```java Java theme={"system"}
FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .variantLookupPolicy(VariantLookupPolicy.networkFirst())
    .build();

// getVariantValue waits for the network. Falls back to persisted value if network fails.
mixpanel.flags.getVariantValue("my-feature-flag", "control", new FlagCompletionCallback<Object>() {
    @Override
    public void onComplete(Object value) {
        // value is from the network response, or from persistence if the network was unavailable
    }
});
```

**`persistenceUntilNetworkSuccess`** — Persisted variants are returned immediately on launch. Each getter call while serving persisted data triggers a background network fetch (deduplicated — only one fetch runs at a time). If the fetch fails, persisted data continues to be served and the next getter call retries the fetch. Once a fetch succeeds, the in-memory state updates and subsequent calls no longer trigger background fetches.

```java Java theme={"system"}
FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .variantLookupPolicy(VariantLookupPolicy.persistenceUntilNetworkSuccess())
    .build();

// getVariantValue returns immediately from persistence. Each call triggers a background fetch
// until a network response succeeds and replaces the persisted state.
mixpanel.flags.getVariantValue("my-feature-flag", "control", new FlagCompletionCallback<Object>() {
    @Override
    public void onComplete(Object value) {
        // value is from persistence; background fetch retries on each call until network succeeds
    }
});
```

To customize the TTL (default: 24 hours), pass the value in milliseconds:

```java Java theme={"system"}
long ttlMs = 12 * 60 * 60 * 1000L; // 12 hours
FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .variantLookupPolicy(VariantLookupPolicy.networkFirst(ttlMs))
    .build();
```

### Variant source

Every `MixpanelFlagVariant` carries a `source` field indicating where the value came from: `Source.Network`, `Source.Persistence`, or `Source.Fallback`. Use `getVariant()` to receive the full variant object.

```java Java theme={"system"}
MixpanelFlagVariant fallback = new MixpanelFlagVariant("control", "control");
mixpanel.flags.getVariant("my-feature-flag", fallback, new FlagCompletionCallback<MixpanelFlagVariant>() {
    @Override
    public void onComplete(MixpanelFlagVariant variant) {
        Object value = variant.value;
        MixpanelFlagVariant.Source source = variant.source; // Network, Persistence, or Fallback
    }
});
```

### `$experiment_started` properties

When a variant is served, the `$experiment_started` exposure event includes:

* `$variant_source` — `"network"` or `"persistence"`
* `$persisted_at_in_ms` — epoch ms when the variant set was persisted *(persistence only)*
* `$ttl_in_ms` — the configured TTL in ms *(persistence only)*

<Note>
  Persisted variants are tied to the current `distinct_id`. Calling `identify()` with a new ID or calling `reset()` clears persisted data and triggers a fresh fetch.
</Note>

## Flag Reload

Following initialization, you can reload feature flag assignments in a couple of ways:

1. After a user logs in or out of your application and you call `identify`, a feature flag reload will be triggered.

```java theme={"system"}
String updatedDistinctId = "";
// Reload after login
mixpanel.identify(updatedDistinctId);
```

2. To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags:

```java theme={"system"}
// Manually reload flags if desired
mixpanel.flags.loadFlags();
```

3. To update the feature flags context after initialization and trigger a reload with the new values, use `setContext`. This completely replaces the previously set custom context.

```java theme={"system"}
Map<String, Object> newContext = new HashMap<>();
newContext.put("company_id", "Y");

Map<String, Object> customProperties = new HashMap<>();
customProperties.put("platform", "android");
newContext.put("custom_properties", customProperties);

mixpanel.flags.setContext(newContext, new FlagCompletionCallback<Boolean>() {
    @Override
    public void onComplete(Boolean success) {
        // Flags have been re-fetched with the new context
    }
});
```

4. Calling `reset()` clears all feature flag assignments from memory and triggers a new fetch for the updated `distinct_id`. Requires SDK version [`v8.7.0`](https://github.com/mixpanel/mixpanel-android/releases/tag/v8.7.0) or later.

```java theme={"system"}
mixpanel.reset();
// Flags are cleared immediately. A new fetch begins for the anonymous distinct_id.
```

## Deferred Flag Loading

By default, feature flags are automatically fetched when the app first enters the foreground (`prefetchFlags` defaults to `true`). If your workflow requires calling `identify()` before the first flag fetch — for example, to ensure flags are evaluated against the correct user — you can defer automatic loading by setting `prefetchFlags(false)`:

```java theme={"system"}
FeatureFlagOptions featureFlagOptions = new FeatureFlagOptions.Builder()
    .enabled(true)
    .prefetchFlags(false)
    .build();

MixpanelOptions options = new MixpanelOptions.Builder()
    .featureFlagOptions(featureFlagOptions)
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", false, options);

// Flags will not be fetched until identify() or loadFlags() is called
mixpanel.identify("user-123");
```

When `prefetchFlags` is set to `false`, flags will not be loaded until you explicitly call `identify()` or `mixpanel.flags.loadFlags()`.

## Flag Evaluation

Lookup the assigned value for a feature flag. This action triggers tracking an exposure event, `$experiment_started` to your Mixpanel project *if* the user context is in a rollout group for the feature flag.

### Asynchronous Flag Variant Retrieval

**Experiment Flags: Get Variant Value**

```java theme={"system"}
// Get just the flag value asynchronously
String fallback = "control"; // the value to use if the user doesn't match any of the flag's rollout rules
mixpanel.flags.getVariantValue("my-feature-flag", fallback, new FlagCompletionCallback<Object>() {
    @Override
    public void onComplete(Object value) {
        // This runs on the main thread
        if (value.equals("variant_a")) {
            showExperienceForVariantA();
        } else if (value.equals("variant_b")) {
            showExperienceForVariantB();
        } else {
            showDefaultExperience();
        }
    }
});
```

**FeatureGates: Check if Flag is Enabled/Disabled**

```java theme={"system"}
// Check if a boolean flag is enabled asynchronously
boolean fallback = false; // the value to use if the user doesn't match any of the flag's rollout rules
mixpanel.flags.isEnabled("my-boolean-flag", fallback, new FlagCompletionCallback<Boolean>() {
    @Override
    public void onComplete(Boolean isEnabled) {
        // This runs on the main thread
        if (isEnabled) {
            showNewFeature();
        } else {
            showOldFeature();
        }
    }
});
```

### Synchronous Flag Variant Retrieval

**Experiment Flags: Get Variant Value**

```java theme={"system"}
// Get just the flag value synchronously
String fallback = "control"; // the value to use if the user doesn't match any of the flag's rollout rules
Object flagValue = mixpanel.flags.getVariantValueSync("my-feature-flag", fallback);

// Use flag value in your application logic
if (flagValue.equals("variant_a")) {
    showExperienceForVariantA();
} else if (flagValue.equals("variant_b")) {
    showExperienceForVariantB();
} else {
    showDefaultExperience();
}
```

**Feature Gates: Check if Flag is Enabled/Disabled**

```java theme={"system"}
// Check if a boolean flag is enabled
boolean fallback = false; // the value to use if the user doesn't match any of the flag's rollout rules
boolean isEnabled = mixpanel.flags.isEnabledSync("my-boolean-flag", fallback);

if (isEnabled) {
    showNewFeature();
} else {
    showOldFeature();
}
```

### Get All Flag Assignments

You can retrieve all feature flag assignments at once. These methods do **not** trigger `$experiment_started` tracking events.

**Synchronous**

`getAllVariantsSync()` returns a `Map<String, MixpanelFlagVariant>` containing all current flag assignments. If flags have not been loaded yet, it returns an empty map.

```java theme={"system"}
Map<String, MixpanelFlagVariant> allFlags = mixpanel.flags.getAllVariantsSync();

for (Map.Entry<String, MixpanelFlagVariant> entry : allFlags.entrySet()) {
    Log.d("Flags", entry.getKey() + ": " + entry.getValue().value);
}
```

**Asynchronous**

`getAllVariants()` returns a `Map<String, MixpanelFlagVariant>` via a callback. If flags have not been loaded yet, it will attempt to fetch them before returning.

```java theme={"system"}
mixpanel.flags.getAllVariants(new FlagCompletionCallback<Map<String, MixpanelFlagVariant>>() {
    @Override
    public void onComplete(Map<String, MixpanelFlagVariant> allFlags) {
        for (Map.Entry<String, MixpanelFlagVariant> entry : allFlags.entrySet()) {
            Log.d("Flags", entry.getKey() + ": " + entry.getValue().value);
        }
    }
});
```

## Frequently Asked Questions

### What if I'm not receiving any flags on SDK initialization?

1. **Check your project token**:

* Ensure you're using the correct project token from your [Mixpanel project settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

2. **Review flag configuration**:

* Make sure your feature flag is enabled
* Check the flag's rollout percentage

  * User contexts that are not assigned to the rollout percentage will not receive flags
* If you are using a targeting cohort, verify on the mixpanel 'Users' page that the user's `distinct_id` is a member of that cohort.

3. **Review SDK parameters**:

* Ensure `FeatureFlagOptions` is configured with `.enabled(true)` and passed to `MixpanelOptions`
* If using a custom Variant Assignment Key, ensure it is included in the `FeatureFlagOptions` `.context()` JSONObject
* If using Runtime Targeting, ensure all properties used in targeting are included in the `custom_properties` object within the `FeatureFlagOptions` context

4. **Check flags readiness**: Use `areFlagsReady()` to check if flags have been loaded before making synchronous calls
5. **Enable debug logging**: Check Android logs for detailed information about flag requests and responses


# OpenFeature Provider (Android)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/android/android-openfeature



## Overview

This guide covers using Mixpanel's [Feature Flags](/docs/featureflags) through the [OpenFeature](https://openfeature.dev/) standard with the Mixpanel Android OpenFeature provider. OpenFeature provides a vendor-agnostic API for feature flag evaluation, allowing you to switch between providers without changing your application code.

For the native Mixpanel SDK approach, see the [Feature Flags (Android)](/docs/tracking-methods/sdks/android/android-flags) guide.

## Prerequisites

* Enterprise subscription plan with Feature Flags enabled
* Android SDK 21+
* Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Installation

Add to your `build.gradle.kts`:

```kotlin theme={"system"}
dependencies {
    implementation("com.mixpanel.android:mixpanel-android-openfeature:<version>")
    implementation("dev.openfeature:kotlin-sdk-android:0.7.2")
}
```

## Quick Start

```kotlin theme={"system"}
import com.mixpanel.android.openfeature.MixpanelProvider
import com.mixpanel.android.mpmetrics.MixpanelOptions
import dev.openfeature.kotlin.sdk.OpenFeatureAPI

// 1. Create the provider
val options = MixpanelOptions.Builder()
    .featureFlags()
    .build()
val provider = MixpanelProvider(context, "YOUR_PROJECT_TOKEN", options)

// 2. Register the provider with OpenFeature
OpenFeatureAPI.setProviderAndWait(provider)

// 3. Get a client and evaluate flags
val client = OpenFeatureAPI.getClient()
val showNewFeature = client.getBooleanValue("new-feature-flag", false)

if (showNewFeature) {
    // New feature is enabled!
}
```

### Using an Existing MixpanelAPI Instance

```kotlin theme={"system"}
import com.mixpanel.android.mpmetrics.MixpanelAPI

val mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", false, options)
val provider = MixpanelProvider(mixpanel.getFlags())

OpenFeatureAPI.setProviderAndWait(provider)
```

<Warning>
  This provider does **not** call `mixpanel.identify()` or `mixpanel.track()`. If you need to update the logged-in user or use [Runtime Events](/docs/featureflags/runtime-events) for targeting, call these methods on the **same `MixpanelAPI` instance** whose `Flags` object was passed to the provider.
</Warning>

```kotlin theme={"system"}
val provider = MixpanelProvider(context, "YOUR_PROJECT_TOKEN", options)

// Use the same instance for identity and tracking
provider.mixpanel?.identify("user-123")
provider.mixpanel?.track("Purchase Completed")
```

## Usage

### Flag Types and Evaluation Methods

| Mixpanel Flag Type | Variant Values                          | OpenFeature Method                                                                                      |
| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Feature Gate       | `true` / `false`                        | `getBooleanValue()`                                                                                     |
| Experiment         | boolean, string, number, or JSON object | `getBooleanValue()`, `getStringValue()`, `getIntegerValue()`, `getDoubleValue()`, or `getObjectValue()` |
| Dynamic Config     | JSON object                             | `getObjectValue()`                                                                                      |

```kotlin theme={"system"}
val client = OpenFeatureAPI.getClient()

// Feature Gate
val isFeatureOn = client.getBooleanValue("new-checkout", false)

// Experiment with string variants
val buttonColor = client.getStringValue("button-color-test", "blue")

// Experiment with numeric variants
val maxItems = client.getIntegerValue("max-items", 10)
val threshold = client.getDoubleValue("score-threshold", 0.5)

// Dynamic Config
val featureConfig = client.getObjectValue("homepage-layout", Value.Structure(mapOf(
    "layout" to Value.String("grid"),
    "itemsPerRow" to Value.Integer(3)
)))
```

### Evaluation Context

Context must be set globally via `OpenFeatureAPI.setContext()`:

```kotlin theme={"system"}
import dev.openfeature.kotlin.sdk.ImmutableContext
import dev.openfeature.kotlin.sdk.Value

OpenFeatureAPI.setContext(ImmutableContext(
    attributes = mutableMapOf(
        "email" to Value.String("user@example.com"),
        "plan" to Value.String("premium")
    )
))
```

<Warning>
  Per-evaluation context (the optional `context` parameter on evaluation methods) is **not supported** by this provider. Context must be set globally via `OpenFeatureAPI.setContext()`, which triggers a re-fetch of flag values from Mixpanel.
</Warning>

### Runtime Properties

Pass `custom_properties` in the evaluation context for runtime targeting:

```kotlin theme={"system"}
OpenFeatureAPI.setContext(ImmutableContext(
    attributes = mutableMapOf(
        "custom_properties" to Value.Structure(mapOf(
            "tier" to Value.String("enterprise"),
            "seats" to Value.Integer(50),
        ))
    )
))
```

<Note>
  Unlike some providers, `targetingKey` is not used as a special bucketing key. It is passed as another context property. Mixpanel's server-side configuration determines which properties are used for targeting and bucketing.
</Note>

### Full Resolution Details

```kotlin theme={"system"}
val details = client.getBooleanDetails("my-feature", false)

println(details.value)
println(details.variant)
println(details.reason)
println(details.errorCode)
```

### User Identity

This provider does **not** call `mixpanel.identify()`. Manage identity through the same Mixpanel instance:

```kotlin theme={"system"}
provider.mixpanel?.identify("user-123")
```

## Error Handling

| Error Code           | When                                                          |
| -------------------- | ------------------------------------------------------------- |
| `PROVIDER_NOT_READY` | Flags evaluated before the provider has finished initializing |
| `FLAG_NOT_FOUND`     | The requested flag does not exist in Mixpanel                 |
| `TYPE_MISMATCH`      | The flag value type does not match the requested type         |

## Troubleshooting

### Flags Always Return Default Values

1. **Feature flags not enabled:** Ensure MixpanelOptions includes `.featureFlags()`.
2. **Provider not ready:** Use `setProviderAndWait` to ensure initialization.
3. **Network issues:** Check Logcat for failed requests.
4. **Flag not configured:** Verify the flag exists and is enabled.

### Flags Not Updating After Context Change

Update context and the provider will re-fetch flags:

```kotlin theme={"system"}
OpenFeatureAPI.setContext(ImmutableContext(
    attributes = mutableMapOf("plan" to Value.String("premium"))
))
```


# Implement Session Replay (Android)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/android/android-replay



## Overview

This developer guide will assist you in configuring your Android app for [Session Replay](/docs/session-replay) using the [Session Replay SDK (Android)](/docs/tracking-methods/sdks/android/android-replay). Learn more about [viewing captured Replays in your project here](/docs/session-replay).

<Note>
  Mobile Session Replay is generally available (GA) to customers on all plans and in all regions.
</Note>

## Best Practices

Session Replay provides powerful insights into user behavior, but it also introduces risks, especially on mobile. These risks are not unique to Mixpanel; they are common across the entire session replay product category. Because SDKs run on end-user devices and screen content may include sensitive data, we recommend implementing / testing Session Replay carefully. Be especially cautious with masking, edge-case testing, and rollout strategies. For more information on risk categories and best practices, read more [here](/docs/session-replay#best-practices)

## Prerequisite

You are already a Mixpanel customer and have the latest version of the [Mixpanel Android SDK](/docs/tracking-methods/sdks/android) installed (minimum supported version is [`v8.0.2`](https://github.com/mixpanel/mixpanel-android/releases/tag/v8.0.2)). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK.

The Session Replay SDK requires a minimum Android API version of 21 or higher.

## Installation

You can integrate the [Mixpanel Android Session Replay SDK](/docs/tracking-methods/sdks/android/android-replay) into your Android project using Maven Central.

### Add to your project

1. Open your existing Android Studio project where you want to integrate the Mixpanel Android Session Replay SDK.
2. Add the following dependency to your module's `build.gradle` or `build.gradle.kts`:

```gradle theme={"system"}
dependencies {
    implementation("com.mixpanel.android:mixpanel-android-session-replay:VERSION_NAME")
}
```

Replace `VERSION_NAME` with the latest version available on [Maven Central](https://central.sonatype.com/artifact/com.mixpanel.android/mixpanel-android-session-replay).

3. Sync your project with Gradle files.

### Initialize

You should have the main Mixpanel Android SDK installed (minimum version `v8.0.2`), if not, please refer to [Prerequisite](/docs/tracking-methods/sdks/android).

Initialize the `MPSessionReplay` SDK in your `Application` class:

**Example Usage**

```kotlin theme={"system"}
private fun initializeMixpanel() {
    val token = "MY_PROJECT_TOKEN"
    val trackAutomaticEvents = true
 
    val mixpanel = MixpanelAPI.getInstance(this, token, trackAutomaticEvents)
    mixpanel.identify("DISTINCT_ID")
 
 
    val config = MPSessionReplayConfig(
        wifiOnly = false,
        enableLogging = true
    )
 
    MPSessionReplay.initialize(this, token, mixpanel.distinctId, config)
}
```

## Data Residency

<Info>
  Available in Session Replay SDK version `1.4.0` and later.
</Info>

If your Mixpanel project lives in the EU or India data center, or you route all Mixpanel traffic through a self-hosted proxy, set `serverUrl` on `MPSessionReplayConfig`. The SDK exposes a `DataResidency` object with the managed region URLs so you don't have to hardcode them.

| Region       | `DataResidency` constant | URL                           |
| ------------ | ------------------------ | ----------------------------- |
| US (default) | `DataResidency.US`       | `https://api.mixpanel.com`    |
| EU           | `DataResidency.EU`       | `https://api-eu.mixpanel.com` |
| India        | `DataResidency.IN`       | `https://api-in.mixpanel.com` |

**Example Usage**

```kotlin Kotlin theme={"system"}
import com.mixpanel.android.sessionreplay.utils.DataResidency

val config = MPSessionReplayConfig(
    wifiOnly = false,
    serverUrl = DataResidency.EU
)
MPSessionReplay.initialize(this, token, mixpanel.distinctId, config)
```

You can also pass any fully-qualified HTTPS URL — useful when routing replay traffic through a self-hosted proxy:

```kotlin Kotlin theme={"system"}
val config = MPSessionReplayConfig(
    serverUrl = "https://mixpanel-proxy.yourcompany.com"
)
```

Learn more about [EU Data Residency](/docs/privacy/eu-residency) and [India Data Residency](/docs/privacy/in-residency).

## Capturing Replays

<Warning>
  Test in a sandbox project and start with a 100% sample rate. This allows you to monitor performance, usage, and ensure your privacy rules align with your company policies.
</Warning>

You can capturing replay data using a sampling method (recommended), or customize when and where replays are captured manually using methods provided by the Session Replay Android SDK.

By default recording begins automatically upon initialization. This behavior is configurable via the `autoStartRecording` property of `MPSessionReplayConfig`.

### Sampling

We recommend using the sampling method unless you need to customize when you capture replay data.

To enable Session Replay and set your sampling rate, create a `MPSessionReplayConfig` object and set the `recordingSessionsPercent` with a value between `0.0` and `100.0` (default). At `0.0` no sessions will be recorded, at `100.0` all sessions will be recorded.

To start, we recommend using an 100% sampling rate to ensure replay capture is behaving as expected, then adjust according to your specific analytics needs.

**Example Usage**

```kotlin theme={"system"}
// records 100% of all sessions
MPSessionReplayConfig(recordingSessionsPercent = 100.0)
```

### Manual Capture

To programatically start and stop replay capture, use the `.startRecording()` and `.stopRecording()` methods.

#### Start Capturing Replay

When calling `.startRecording()` recording always begins regardless of the `recordingSessionsPercent` configuration. You may optionally specify a sampling percentage when calling `.startRecording()`

```kotlin theme={"system"}
// start recording with a specified sampling rate (10%)
MPSessionReplay.getInstance()?.startRecording(sessionsPercent = 10.0)
```

Recording automatically stops when the app goes into the background. If the `autoStartRecording` configuration is `true` (default) recording will automatically start when the app returns to the foreground.

`.startRecording()` will have no effect if recording is already in progress.

**Example Usage**

```kotlin Kotlin theme={"system"}
// manually trigger a replay capture
MPSessionReplay.getInstance()?.startRecording()
```

#### Stop Capturing Replay Data

Call `.stopRecording()` to stop any active replay data collection. The SDK automatically stops recording when the app goes to the background.

`.stopRecording()` will have no effect if there is no recording in progress.

**Example Usage**

```kotlin Kotlin theme={"system"}
// manually end a replay capture
MPSessionReplay.getInstance()?.stopRecording()
```

#### Example Use Cases for Manual Capture

| Scenario                                                                  | Guidance                                                                                                                                                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| We have a sensitive screen we don't want to capture                       | When user is about to access the sensitive screen, call `.stopRecording()`. To resume recording once they leave this screen, you can resume recording with `.startRecording()` |
| We only want to record certain types of users (e.g. Free plan users only) | Using your application code, determine if current user meets the criteria of users you wish to capture. If they do, then call `.startRecording()` to begin recording           |
| We only want to users utilizing certain features                          | When user is about to access the feature you wish to capture replays for, call `.startRecording()` to begin recording                                                          |

### Additional Configuration Options

Upon initialization you can provide a `MPSessionReplayConfig` object to customize your replay capture.

The current configuration options are:

| Option                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                   | Default                    |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `wifiOnly`                 | When `true`, replay events will only be flushed to the server when the device has a WiFi connection. If there is no wifi, flushes are skipped and the events remain in the in-memory queue until wifi is restored (or until the queue reaches its limit and the oldest events are evicted to make room for newer events). <br /> When `false`, replay events will be flushed with any network connection, including cellular. | `true`                     |
| `autoMaskedViews`          | This is a `Set` of enum options for the types of views that should be masked by the SDK automatically.                                                                                                                                                                                                                                                                                                                        | `Image`, `Text`, and `Web` |
| `autoStartRecording`       | This is a boolean value that determines whether or not recording begins automatically upon initialization and when returning to the foreground. <br /> **Deprecated in v1.1.0:** Use `recordingSessionsPercent` set to `0.0` to disable automatic recording.                                                                                                                                                                  | `true`                     |
| `recordingSessionsPercent` | This is a value between `0.0` and `100.0` that controls the sampling rate for recording session replays. <br /> At `0.0` no sessions will be recorded. At `100.0` all sessions will be recorded.                                                                                                                                                                                                                              | `100.0`                    |
| `flushInterval`            | Specifies the flush interval (in seconds) at which session replay events are sent to the Mixpanel server.                                                                                                                                                                                                                                                                                                                     | `10`                       |
| `enableLogging`            | This is a boolean value that determines whether or not debugging logs are printed to the console.                                                                                                                                                                                                                                                                                                                             | `false`                    |
| `remoteSettingsMode`       | Setting for handling remote configuration during SDK initialization. Can be `DISABLED`, `FALLBACK`, `STRICT`.                                                                                                                                                                                                                                                                                                                 | `DISABLED`                 |

**autoMaskedViews Example Usage**

```kotlin Kotlin theme={"system"}
// mask images only
MPSessionReplayConfig(autoMaskedViews = mutableSetOf(AutoMaskedView.Image))

// disable auto masking
MPSessionReplayConfig(autoMaskedViews = emptySet())
```

#### Identity Management

The Mixpanel distinct ID for the current user can be passed into the initializer and changed at runtime by calling the `.identify(distinctId =)` method:

**Example Usage**

```kotlin theme={"system"}
// initialize the main Mixpanel tracking SDK
 MixpanelAPI.getInstance(this, token, trackAutomaticEvents)

// initialize the session replay SDK with the project token and distinct ID from above
 MPSessionReplay.initialize(this, token, mixpanel.distinctId)
```

To change the distinct ID later:

```kotlin theme={"system"}
// for example when the user logs out
fun logout() {
    // reset the main Mixpanel tracking SDK to generate a new distinct ID
    mixpanel.reset()
    val newDistinctId = mixpanel.distinctId
    // change session replay distinct ID
    MPSessionReplay.getInstance()?.identify(distinctId = newDistinctId)
}
```

#### Manual Flushing

You can flush any currently queued session replay events at any time by calling `.flush()`:

```kotlin theme={"system"}
MPSessionReplay.getInstance()?.flush()
```

## Remote Configuration

<Note>
  Available only for customers with a paid session replay add-on.
</Note>

By setting `remote_settings_mode` you can quickly set SDK options for your project in Mixpanel under `Settings > Organization Settings > Session Replay`.

Three modes are available:

* `DISABLED`: Do not use remote configuration and proceed to use the SDK initialization config provided in `MPSessionReplay.initialize`
* `FALLBACK`: Attempt to retrieve remote configuration and proceed with those settings. If there is failure or timeout (500 ms), will use previously cached remote settings (from last successful fetch) or the SDK initialization config.
* `STRICT`: Requires successful remote configuration fetch for SDK initialization.

Can use this setting to quickly update and adjust configurations to your liking.

List of currently supported remote settings:

* `recordingSessionsPercent`

Settings that are not yet supported, will not appear in the remote configuration. These non-included options will use the value from the SDK initialization config.

## Replay ID

When a replay capture begins, a Replay ID is generated by the SDK and is attached as an event property (`$mp_replay_id`) to events tracked by the SDK during the capture session. Events containing the same `$mp_replay_id` will appear in the same Replay.

If you are sending any events not coming from the SDK, add the `$mp_replay_id` event property to attribute the event to a specific Replay.

You can use the `getReplayId()` method to return the Replay ID for the current replay capture. The method will return an empty object if there is no active replay capture in progress.

**Example Usage**

```kotlin Kotlin theme={"system"}
// return the $mp_replay_id for the currently active capture
MPSessionReplay.getInstance()?.getReplayId()
// {$mp_replay_id: '19221397401184-063a51e0c3d58d-17525637-1d73c0-1919139740f185'}
```

### Logging

Developers can enable or disable logging with the `enableLogging` option of the `MPSessionReplayConfig` object.

**Example Usage**

```kotlin theme={"system"}
val config = MPSessionReplayConfig(wifiOnly = false, enableLogging = true)
MPSessionReplay.initialize(appContext = this, token = token, distinctId = distinctId, config = config)
```

### Server-side Stitching

Server-Side Stitching allows you to easily watch Replays for events that were not fired from the SDK.

It works by inferring the Replay that an event belong using the Distinct ID and time property attached to the event. This is especially useful if you have events coming in from multiple sources.

For example, let's say a user with Distinct ID "ABC" has a Replay recorded from 1-2pm. Two hours later, an event was sent from your warehouse with a timestamp of 1:35pm with Distinct ID "ABC". Server-Side Stitching will infer that the event should belong in the same Replay.

To ensure Server-Side Stitching works, call [`identify()`](/docs/tracking-methods/sdks/android#identify) from the client-side using our SDK with the user's `$user_id`. This guarantees that events generated from both the client-side and server-side share the same Distinct ID. Learn more about [identifying users](/docs/tracking-methods/id-management).

## Debugging

<Note>
  `$mp_session_record` is exempt from your plan data allowance.
</Note>

To check your implementation, select **Session Replay** from the side navigation in your Mixpanel project to see whether replays are being captured and appearing as expected. When a capture begins, a "Session Recording Checkpoint" event (`$mp_session_record`) also appears in your project; you can use this to verify that Session Replay is implemented correctly.

If you are using the [recommended sampling method](/docs/tracking-methods/sdks/android/android-replay#sampling) to capture your Replays but having trouble finding the Replays in your project, try calling `.startRecording()` manually and see if the `$mp_session_record` event appears. If it does appear but you are still struggling to locate your Replays, you may want to increase your sampling rate.

***

### Troubleshooting

If you are still struggling with either of the following common issues:

* Replays are not showing up in my project
* Replays are not displaying my UI correctly

Please [submit a request to our Support team](https://mixpanel.com/get-support) and include the following information:

* Whether your issue is with iOS, Android, or both
* Your Session Replay (SR) code snippet
* Where you initialize the Mobile Session Replay SDK
* Any relevant logs
* (If applicable) A link to a replay showing the issue
* (If applicable) A screenshot of the UI or a description of the expected behavior

## Privacy

Mixpanel offers a privacy-first approach to Session Replay, including features such as data masking. Mixpanel's Session Replay privacy controls were designed to assist customers in protecting end user privacy. Read more [here](/docs/session-replay/session-replay-privacy-controls).

### User Data

The Mixpanel SDK will always mask all inputs. To protect end-user privacy, input text fields cannot be unmasked.

By default, all text, images, and WebViews are also masked.

You can unmask these elements at your own discretion using the [`autoMaskedViews` config option described above](/docs/tracking-methods/sdks/android/android-replay#additional-configuration-options).

Along with other data, the SDK respects all Do Not Track (DNT) settings as well as manual opt-out for any replay data.

#### Mark Views as Sensitive

All `EditText` and `TextView` components are masked by default. `EditText` cannot be unmasked, while `TextView` can be unmasked.

You can also mark any views as sensitive using `mpReplaySensitive` or `addSensitiveView`. Views marked as "sensitive" will be masked.

**Example Usage**

```kotlin Kotlin theme={"system"}
// Compose
Image(
    painter = painterResource(id = R.drawable.family_photo),
    contentDescription = "Family Photo",
    modifier = Modifier.mpReplaySensitive(true)
)
 
// XML
val creditCardView: ImageView = findViewById(R.id.creditCardView)
MPSessionReplay.getInstance()?.addSensitiveView(creditCardView)
```

Set `mpReplaySensitive` to `false` to mark any view as safe. Views marked as "safe" will not be masked.

**Example Usage**

```kotlin Kotlin theme={"system"}
// Compose
Image(
    painter = painterResource(id = R.drawable.family_photo),
    contentDescription = "Family Photo",
    modifier = Modifier.mpReplaySensitive(false)
)
```

### Retention

By default, Mixpanel retains Session Replays for 30 days from the date the replay is ingested and becomes available for viewing within Mixpanel. Customers on our [Enterprise plan](https://mixpanel.com/pricing/) can customize this retention period between 7 days and 360 days. Once a replay is expired, there is no way to view that replay.

### Legal (Beta Terms)

Our Session Replay Beta Service Addendum can be found [here](https://mixpanel.com/legal/session-replay-beta-service-addendum/).

The alpha and beta of Mixpanel's mobile session replay SDK will track certain events and send them to Mixpanel so that Mixpanel can understand and improve the alpha and beta mobile session replay feature experience. These events include starting and stopping a session, adding and removing sensitive classes, adding sensitive views and adding safe views. Nothing about your application will be included in this tracking; only your usage of the Mixpanel Session Replay SDK.

## Known Product Limitations

* Jetpack Compose apps (Android only) have limited support for automatic masking of sensitive views, so if your app uses Jetpack Compose, you should manually mark sensitive views and test thoroughly.
* At this time, webview masking is all-or-none, meaning embedded webviews in your mobile app can only be masked entirely or not at all, which may reduce the value of Session Replay for apps with many webviews—be sure to test thoroughly in your use case.
* Android Session Replay requires a minimum Android API level of 21. Older versions are not supported.

## FAQ

#### How does Session Replay work in Android?

Session Replay observes user interactions within your app, capturing UI hierarchy changes and storing them as images, which are then sent to Mixpanel. Mixpanel reconstructs these images, applying recorded events as an end-user completes them.

Within Mixpanel's platform, you can view a reconstruction of your end-user's screen as they navigate your app.

However, Session Replay is not a literal video recording of your end-user's screen; end-user actions are not video-recorded.

#### Can I prevent Session Replay from recording sensitive content?

The Mixpanel SDK will always mask all inputs. By default, all text, images, and WebViews on a page.

Additionally, you can customize how you leverage our SDK to fully control (1) where to record and (2) whom to record. Consider the [manual capture example scenarios](/docs/tracking-methods/sdks/android/android-replay#manual-capture), [SDK configuration options](/docs/tracking-methods/sdks/android/android-replay#additional-configuration-options), and [manual view masking example](/docs/tracking-methods/sdks/android/android-replay#mark-views-as-sensitive) provided above to customize the replay capture of your implementation.

#### How can I estimate how many Replays I will generate?

If you already use Mixpanel, the [Session Start events](/docs/features/sessions) are a way to estimate the rough amount of replays you might expect. This is especially true if you use timeout-based query sessions. However, because our sessions are defined at query time, we cannot guarantee these metrics will be directly correlated.

When you enable Session Replay, use the above proxy metric to determine a starting sampling percentage, which will determine how many replays will be sent. You can always adjust this as you go to calibrate to the right level.

#### How does Session Replay affect my app's bandwidth consumption?

The bandwidth impact of Session Replay depends on the setting of the [`wifiOnly` parameter](/docs/tracking-methods/sdks/android/android-replay#additional-configuration-options).

By default, `wifiOnly` is set to `true`, which means replay events are only flushed to the server when the device has a wifi connection. If there is no wifi, flushes are skipped, and the events remain in the in-memory queue until WiFi is restored. This ensures no additional cellular data is used, preventing users from incurring additional data charges.

When `wifiOnly` is set to `false`, replay events are flushed with any available network connection, including cellular. In this case, the amount of cellular data consumed depends on the intensity of user interactions and the typical session length of your app. Users may incur additional data charges if large amounts of data are transmitted over cellular connections.

#### How does Session Replay for mobile work if my app is offline?

Session Replay for mobile does not work in offline mode.

#### Does it work in XML/Jetpack Compose apps?

Yes, standard XML-based apps are fully supported while Jetpack Compose apps have limited support for automatic masking of sensitive views. If your app is using Jetpack Compose, it is recommended that you manually mark your views as sensitive.

#### Does it support Java based app?

Yes, Java and Kotlin are fully interoperable.

#### Does Mobile Session Replay work with my CDP?

Yes — but only if the Mixpanel Session Replay SDK is installed client-side.

Mobile Session Replay is compatible with CDPs like Segment and mParticle, but you must integrate the Mixpanel Session Replay SDK directly in your mobile app. Without it, replays won’t be captured.

Key Considerations:

* If you are using Segment server-side, session replays will not be recorded, since the SDK isn’t running in the app.
* For Segment's client-side Analytics-Kotlin SDK, you can use Segment’s Plugin Architecture to enrich events with the \$mp\_replay\_id property, ensuring they’re linked to their replays.
* The Mixpanel Session Replay SDK is separate from the standard Mixpanel tracking SDK. You do not need the regular SDK, but the Replay SDK must be configured with a distinct\_id and project token.
* Events can be linked to replays either by:

  * Manually attaching the current replay ID to each event
  * Using server-side stitching after the fact


# Mixpanel SDKs: Flutter
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/flutter



## Getting Started

Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=flutter).

The [Full API Reference](https://mixpanel.github.io/mixpanel-flutter), [Library Source Code](https://github.com/mixpanel/mixpanel-flutter), and an [Example Application](https://github.com/mixpanel/mixpanel-flutter/tree/main/example) is documented in our GitHub repo.

## Installing the Library

To install the library in your [Flutter development environment](https://docs.flutter.dev/get-started/install), declare it as a dependency in the `pubspec.yaml` file of your package:

```yaml theme={"system"}
# add Mixpanel library to your dependencies
dependencies:
    mixpanel_flutter: ^1.x.x # set this to your desired version
```

Once you added the library to your dependencies, use the command line to install the library:

```bash theme={"system"}
# install packages in your dependencies
$ flutter pub get
```

After the installation, import the package in your Dart code, then initialize the SDK with the [`Mixpanel.init()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/init.html) using your [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).

```dart theme={"system"}
// import the library
import 'package:mixpanel_flutter/mixpanel_flutter.dart';
...
class _YourClassState extends State<YourClass> {
  Mixpanel mixpanel;

  @override
  void initState() {
    super.initState();
    initMixpanel();
  }

  Future<void> initMixpanel() async {
    // initialize Mixpanel
    mixpanel = await Mixpanel.init("YOUR_PROJECT_TOKEN", trackAutomaticEvents: false);
  }
}
...
```

Now you can access `mixpanel` throughout the rest of your application.

**Flutter Web Support**

Add the following snippet to your `web/index.html` inside the `<head></head>` tag in your project:

```html theme={"system"}
<script src="./assets/packages/mixpanel_flutter/assets/mixpanel.js"></script>
```

### Library Configuration

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/flutter#privacy-friendly-tracking).
</Warning>

The Mixpanel instance can be customized with different configurations. The [`Mixpanel.init()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/init.html) method accepts arguments that sets some configurations on your instance upon initialization.

After initialization, you can further customize the instance using the configuration options [here](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel-class.html).

**Example Usage**

```dart theme={"system"}
...
// initialize Mixpanel without autotrack disabled
mixpanel = await Mixpanel.init("YOUR_PROJECT_TOKEN", trackAutomaticEvents: false);

// enable debug logs post-init
mixpanel.setLoggingEnabled(true);
...
```

## Sending Events

Use [`.track()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/track.html) to send an event by providing the event name and any event properties. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```dart theme={"system"}
//Track 'some_event' with "plan" event prop
mixpanel.track('some_event', {'plan': 'premium'});
```

### Timing Events

You can track the time it took for an action to occur, such as an image upload or a comment post, using [`.timeEvent()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/timeEvent.html). This will mark the "start" of your action, which will be timed until you finish with a track call. The time duration is then recorded in the "Duration" property.

```dart theme={"system"}
// start the timer for the event "Image Upload"
mixpanel.timeEvent("Image Upload");

// 20 seconds later...

// track "Image Upload" event with Duration event prop set to 20
mixpanel.track("Image Upload");
```

### Flushing Events

To preserve battery life and customer bandwidth, the Mixpanel library doesn’t send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background.

Call [`.flush()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/flush.html) manually if you want to force a flush at a particular moment.

**Example Usage**

```dart theme={"system"}
// flush batched events for ingestion immediately
mixpanel.flush();
```

#### Importing Historical Events

The Flutter SDK is a tracking SDK designed for real-time tracking in a client-side environment. Calling `.track()` triggers a request to our [/track API endpoint](/reference/track-event), which will validate for events with a timestamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested**.

For bulk import of historical events older than 5 days, we will need to use the [/import API endpoint](/reference/import-events) which is optimized for scripting and supports ingesting historical data. We recommend the [Python SDK](/docs/tracking-methods/sdks/python) (see the [`.import_data()`](https://mixpanel.github.io/mixpanel-python/#primary-interface) function) and [mixpanel-utils module](https://github.com/mixpanel/mixpanel-utils) (see the [`import_events()`](https://github.com/mixpanel/mixpanel-utils?tab=readme-ov-file#import-events) function) which both leverages the /import API for event ingestion.

## Setting Super Properties

Super properties are global event properties that you define once and apply to all events.

To register super properties, call [`.registerSuperProperties()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/registerSuperProperties.html).

Use [`.registerSuperPropertiesOnce()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/registerSuperPropertiesOnce.html) to register super properties without overwriting existing values.

**Example Usage**

```dart theme={"system"}
// register a "name" super property
mixpanel.registerSuperProperties({'name': 'sam'});

// track "some_event"
// "name" is automatically added as an event prop
mixpanel.track('some_event');

// this is ignored because "name" already exists
mixpanel.registerSuperPropertiesOnce({'name': 'samantha'});

// register a "location" super property
mixpanel.registerSuperPropertiesOnce({'location': 'us'});
```

Our mobile libraries store your super properties in local storage. They will persist so long as the app is installed (between launches and updates). Uninstalling the app will remove that customers super properties.

See more methods related to super properties in the complete library reference [here](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel-class.html).

## Managing User Identity

You can handle the identity of a user using the [`.identify()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/identify.html) and [`.reset()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/reset.html) methods. Learn more about [identity management](/docs/tracking-methods/id-management/identity-management) and [identifying users](/docs/tracking-methods/id-management/identifying-users).

### Identify

<Warning>
  We recommend against calling `.identify()` for anonymous visitors to your site.
</Warning>

Call [`.identify()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/identify.html) when you know the identity of the current user, passing in their user ID as an argument. This is typically at account registration and at log in.

**Example Usage**

```dart theme={"system"}
// user logs in and tracks a sign in event
mixpanel.track('sign in');

// upon sign in, identify the user with their ID
// ensure future events sent from the user have distinct_id 12345
mixpanel.identify('12345');
```

### Call Reset at Logout

Call [`.reset()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/reset.html) to clear data attributed to a user when they logout. This will clear the local storage and allows you to handle [multiple users on a single device](/docs/tracking-methods/id-management/identifying-users-simplified#multiple-users-one-device).

**Example Usage**

```dart theme={"system"}
// your user logs out and tracks a log out event
mixpanel.track('log out');

// clear local storage and generate new distinct_id
mixpanel.reset();
```

## Storing User Profiles

Once your users are identified, create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Flutter SDK provides a few methods for setting profile properties under the [`People`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/People-class.html) class accessible via [`.getPeople()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/getPeople.html). These methods will trigger requests to the [/engage API endpoint](/reference/profile-set).

### Setting Profile Properties

<Note>
  You must call `.identify()` before setting profile properties in order to associate the profile properties you set with the target user. If identify is not called, the profile update will be queued for ingestion until an identify call is made.
</Note>

Set profile properties on a user profile by calling the [`.getPeople().set()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/People/set.html) method.

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```dart theme={"system"}
// You must call identify to associate the profile update with the user
// Sets user's "Plan" attribute to "Premium"
mixpanel.identify("12345");
mixpanel.getPeople().set("Plan", "Premium");

// Update "plan" from "Premium" to "Enterprise"
mixpanel.getPeople().set("Plan", "Enterprise");
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/People-class.html)

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title=".setOnce()">
    The [`.getPeople().setOnce()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/People/setOnce.html) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```dart theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    mixpanel.getPeople().set('name':'sam');

    // will be ignored since "name" already exists
    mixpanel.getPeople().setOnce('name', 'samantha');

    // set "location" user prop since it does not exist
    mixpanel.getPeople().setOnce('location', 'us');
    ```
  </Tab>

  <Tab title=".append()">
    The [`.getPeople().append()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/People/append.html) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```dart theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    mixpanel.getPeople().set({
        'name':'sam',
        'roles': ['sales','engineer']
    });

    // add "legal" to "roles"  
    // new role values are ['sales','engineer','legal']
    mixpanel.getPeople().append('roles', 'legal');

    // .append() allows duplicates
    // new "roles" values are ['sales','engineer','legal', 'legal']
    mixpanel.getPeople().append('roles', 'legal');
    ```
  </Tab>

  <Tab title=".union()">
    The [`.getPeople().union()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/People/union.html) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```dart theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    mixpanel.getPeople().set({
        'name':'sam',
        'roles': ['sales','engineer']
    });

    // append "engineer" to "roles"
    // will be ignored since "engineer" already exists in "roles"
    mixpanel.getPeople().union('roles', 'engineer');

    // append "legal" to "roles"
    // new role values are ['sales','engineer','legal']
    mixpanel.getPeople().union('roles', 'legal');
    ```
  </Tab>

  <Tab title=".increment()">
    The [`.getPeople().increment()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/People/increment.html) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```dart theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    mixpanel.getPeople().set({
        'name':'sam',
        'age': 25
    });

    // increment "age" by 2
    mixpanel.getPeople().increment('age',2);

    // use negative number to decrement
    // decrement "age" by 5
    mixpanel.getPeople().increment('age',-5);
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

The Android SDK provides a few method for adding individual users to a group and setting group profile properties.

### Adding Users to a Group

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

Call the [`.setGroup()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/setGroup.html) method to register the current user to a group, which would add the `group_key` as an event property set to the `group_id` value to all events moving forward.

**Example Usage**

```dart theme={"system"}
// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');
 
// track "some_event"
// event property "company" = ["mixpanel"] is added automatically
mixpanel.track('some_event');

//alternatively you can manually define the group key
mixpanel.track('some_event', {'company':'mixpanel'});
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

Call [`.addGroup()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/addGroup.html) to add additional `group_id`s to an existing list.

**Example Usage**

```dart theme={"system"}
// assign the current user to the "mixpanel" company group
// events will contain 'company' prop set to ["mixpanel"]
mixpanel.setGroup('company', 'mixpanel');

// add "mp-us" as an additional company group
// new "company" value is ["mixpanel","mp-us"]
mixpanel.addGroup('company', 'mp-us');

// track "some_event"
// event property "company" = ["mixpanel","mp-us"] is added automatically
mixpanel.track('some_event');
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `.getPeople().set()` call.

**Example Usage**

```dart theme={"system"}
// set group key "company" as user prop
// with group id "mixpanel" as the value
mixpanel.identify("12345");
mixpanel.getPeople().set("company", "mixpanel");
```

### Setting Group Profile Properties

Create a group profiles by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

To set group profile properties, specify the group that needs to be updated by calling [`.getGroup()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/getGroup.html), then set the group properties by chaining the [`.set()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/MixpanelGroup/set.html) method, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```dart theme={"system"}
// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');

// specify the target group using the group_key and group_id
// set "industry" as a group profile prop to "analytics"
mixpanel.getGroup('company','mixpanel').set('industry','analytics');
```

### Other Group Profile Methods

See all of the methods under the Group class [here](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/MixpanelGroup-class.html).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title=".setOnce()">
    The [`.getGroup().setOnce()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/MixpanelGroup/setOnce.html) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```dart theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    mixpanel.getGroup('company','mixpanel').set('name', 'Mixpanel');

    // ignored since "name" is already exists
    mixpanel.getGroup('company','mixpanel').setOnce('name','mp');

    // set "location" group prop since it does not exist
    mixpanel.getGroup('company','mixpanel').setOnce('location','us');
    ```
  </Tab>

  <Tab title=".unset()">
    The [`.getGroup().unset()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/MixpanelGroup/unset.html) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```dart theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    mixpanel.getGroup('company','mixpanel').set('name', 'Mixpanel');
    mixpanel.getGroup('company','mixpanel').set('employee_count', 100);

    // delete "employee_count" from the group profile
    mixpanel.getGroup('company','mixpanel').unset('employee_count');

    // only "name" remains as a group prop
    ```
  </Tab>

  <Tab title=".union()">
    The [`.getGroup().union()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/MixpanelGroup/union.html) method append new values to a list property, excluding duplicates.

    Use this method to create a list group profile property that only contains unique values without duplicates.

    **Example Usage**

    ```dart theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    mixpanel.getGroup('company','mixpanel').set('features', ['reports','alerts','cohorts']);

    // add "data pipeline" to "features" prop
    // ignore "alert" since it is a duplicate value
    mixpanel.getGroup('company','mixpanel').union('features', [
        'data pipeline',
        'alerts'
        ]);
    ```
  </Tab>

  <Tab title=".remove()">
    The [`.getGroup().remove()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/MixpanelGroup/remove.html) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```dart theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    mixpanel.getGroup('company','mixpanel').set('features', ['reports','alerts','cohorts']);

    //remove "alerts" from "features"
    // "features" now contain ["reports","cohorts"]
    mixpanel.getGroup('company','mixpanel').remove('features', 'alerts');
    ```
  </Tab>
</Tabs>

## Autocapture

The Mixpanel Flutter SDK provides methods on the `autocapture` object to help you track common user interactions with minimal instrumentation. These methods fire standardized events that are recognized by the Mixpanel platform.

### Screen View & Screen Leave

Flutter apps use widget-based routing with `Navigator`, `GoRouter`, or other packages, each handling screen transitions differently. This makes it impractical for the SDK to automatically detect screen boundaries. Instead, you hook `trackScreenView` and `trackScreenLeave` into your app's navigation, giving you full control over what counts as a screen and when transitions happen.

Track screen navigations using `trackScreenView` and `trackScreenLeave`. These methods fire the following events:

| Method               | Mixpanel Event   |
| -------------------- | ---------------- |
| `trackScreenView()`  | `$mp_page_view`  |
| `trackScreenLeave()` | `$mp_page_leave` |

Both events automatically include `current_page_title` (the screen name) and `$mp_autocapture: true`.

<Tabs>
  <Tab title="Navigator">
    Create a `NavigatorObserver` and attach it to your `MaterialApp`:

    ```dart theme={"system"}
    class MixpanelNavigatorObserver extends NavigatorObserver {
      final Future<Mixpanel> _mixpanelFuture;
      MixpanelNavigatorObserver(this._mixpanelFuture);

      @override
      void didPush(Route route, Route? previousRoute) {
        super.didPush(route, previousRoute);
        _mixpanelFuture.then((mp) async {
          if (previousRoute?.settings.name != null) {
            await mp.autocapture.trackScreenLeave(previousRoute!.settings.name!);
          }
          if (route.settings.name != null) {
            await mp.autocapture.trackScreenView(route.settings.name!);
          }
        });
      }

      @override
      void didPop(Route route, Route? previousRoute) {
        super.didPop(route, previousRoute);
        _mixpanelFuture.then((mp) async {
          if (route.settings.name != null) {
            await mp.autocapture.trackScreenLeave(route.settings.name!);
          }
          if (previousRoute?.settings.name != null) {
            await mp.autocapture.trackScreenView(previousRoute!.settings.name!);
          }
        });
      }

      @override
      void didReplace({Route? newRoute, Route? oldRoute}) {
        super.didReplace(newRoute: newRoute, oldRoute: oldRoute);
        _mixpanelFuture.then((mp) async {
          if (oldRoute?.settings.name != null) {
            await mp.autocapture.trackScreenLeave(oldRoute!.settings.name!);
          }
          if (newRoute?.settings.name != null) {
            await mp.autocapture.trackScreenView(newRoute!.settings.name!);
          }
        });
      }

      @override
      void didRemove(Route route, Route? previousRoute) {
        super.didRemove(route, previousRoute);
        _mixpanelFuture.then((mp) async {
          if (route.settings.name != null) {
            await mp.autocapture.trackScreenLeave(route.settings.name!);
          }
        });
      }
    }
    ```

    ```dart theme={"system"}
    MaterialApp(
      navigatorObservers: [MixpanelNavigatorObserver(mixpanelFuture)],
      // ...
    );
    ```
  </Tab>
</Tabs>

#### Passing Custom Properties

Both methods accept an optional `properties` parameter. For example, forwarding UTM params from a deep link:

```dart theme={"system"}
final utmProps = {
  "utm_source": uri.queryParameters["utm_source"],
  "utm_medium": uri.queryParameters["utm_medium"],
  "utm_campaign": uri.queryParameters["utm_campaign"],
};
await mixpanel.autocapture.trackScreenView("PromoScreen", properties: utmProps);
```

## Debug Mode

To enable debug mode, call [`.setLoggingEnabled()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/setLoggingEnabled.html) with `true`.

**Example Usage**

```dart theme={"system"}
// enable debug logs
mixpanel.setLoggingEnabled(true);
```

Learn more about [debugging](/docs/tracking-best-practices/debugging).

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Flutter SDK provide methods to help you protect user data.

Learn more about [Privacy](/docs/privacy/overview).

### Opt Out of Tracking

The Android SDK is initialized with tracking enabled by default. Use the [`.optOutTracking()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/optOutTracking.html) method to opt the user out of data tracking and local storage for the current Mixpanel instance.

**Example Usage**

```dart theme={"system"}
//send "some_event"
mixpanel.track('some_event');

// opt user out of tracking
// SDK is prevented from sending any data
mixpanel.optOutTracking();

// this track call will not work
mixpanel.track('some_other_event');
```

**Opt Out by Default**

You can initialize the library with users opted out of tracking by default using the `optOutTrackingDefault` configuration. Once the user is ready to be tracked, call [`.optInTracking()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/optInTracking.html) to start tracking.

**Example Usage**

```dart theme={"system"}
...
// initialize Mixpanel with users opt out of tracking by default
mixpanel = await Mixpanel.init("YOUR_PROJECT_TOKEN", trackAutomaticEvents: false, optOutTrackingDefault: true);

// opt user back in to tracking afterwards
mixpanel.optInTracking();
...
```

### EU Data Residency

Route data to Mixpanel's EU servers by passing the `serverURL` parameter when initializing the client. This ensures every request is routed to the correct region from the very first event.

**Example Usage**

```dart theme={"system"}
// route data to Mixpanel's EU domain at initialization
mixpanel = await Mixpanel.init(
  "YOUR_PROJECT_TOKEN",
  trackAutomaticEvents: false,
  serverURL: "https://api-eu.mixpanel.com",
);
```

Alternatively, you can set the `serverURL` property after initializing the client.

**Example Usage**

```dart theme={"system"}
// set request URL to Mixpanel's EU domain
mixpanel.setServerURL("https://api-eu.mixpanel.com");
```

### India Data Residency

Route data to Mixpanel's India servers by passing the `serverURL` parameter when initializing the client. This ensures every request is routed to the correct region from the very first event.

**Example Usage**

```dart theme={"system"}
// route data to Mixpanel's India domain at initialization
mixpanel = await Mixpanel.init(
  "YOUR_PROJECT_TOKEN",
  trackAutomaticEvents: false,
  serverURL: "https://api-in.mixpanel.com",
);
```

Alternatively, you can set the `serverURL` property after initializing the client.

**Example Usage**

```dart theme={"system"}
// set request URL to Mixpanel's India domain
mixpanel.setServerURL("https://api-in.mixpanel.com");
```

### Disable Geolocation

The Flutter SDK parse the request IP address to generate geolocation properties for events and profiles. To disable geolocation, call [`.setUseIpAddressForGeolocation()`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/setUseIpAddressForGeolocation.html) with `false`.

**Example Usage**

```dart theme={"system"}
// disable geolocation from IP parsing
mixpanel.setUseIpAddressForGeolocation(false);
```

Learn more about [geolocation](/docs/tracking-best-practices/geolocation).

## Legacy Automatically Tracked Events

Mixpanel's SDKs have a legacy feature to automatically collect common mobile events. We don't recommend enabling this, as these events rely on client-side state and can be unreliable compared to tracking server-side. You can still enable this feature by turning the flag `trackAutomaticEvents: true` when initializing Mixpanel. More details [here](https://github.com/mixpanel/mixpanel-flutter?tab=readme-ov-file#2-initialize-mixpanel).

You can see a list of events tracked automatically for [iOS here](/docs/tracking-methods/sdks/swift#legacy-automatically-tracked-events) and [Android here](/docs/tracking-methods/sdks/android#legacy-automatically-tracked-events).

## Tracking Via Proxy

This guide demonstrates how to route events from Mixpanel's Flutter SDKs via a proxy in your own domain. This is useful to reduce the likelihood of ad-blockers impacting your tracking.

There are two steps: setting up a proxy server and pointing the SDK at your server.

**Step 1: Set up a proxy server** The simplest way is to use our [sample nginx config](https://github.com/mixpanel/tracking-proxy). This config redirects any calls made to your proxy server to Mixpanel.

**Step 2: Point Flutter SDK at your server** Pass the `serverURL` parameter when initializing the client, replacing `YOUR_PROXY_DOMAIN` with your proxy server's domain. This ensures every request is routed to your proxy from the very first event.

**Example Usage**

```dart theme={"system"}
// route data to your proxy server at initialization
mixpanel = await Mixpanel.init(
  "YOUR_PROJECT_TOKEN",
  trackAutomaticEvents: false,
  serverURL: "https://<YOUR_PROXY_DOMAIN>",
);
```

Alternatively, you can set the `serverURL` property after initializing the client.

**Example Usage**

```dart theme={"system"}
// route data to your proxy server
mixpanel.setServerURL("https://<YOUR_PROXY_DOMAIN>");
```

Specifically for Flutter Web, add your proxy server to the `mixpanel.init` call:

**Example Usage**

```js theme={"system"}
mixpanel.init("<YOUR_PROJECT_TOKEN>", {api_host: "https://<YOUR_PROXY_DOMAIN>"});
```

## Release History

[See all releases.](https://github.com/mixpanel/mixpanel-flutter/releases)


# Implement Feature Flags (Flutter)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/flutter/flutter-flags



## Overview

This developer guide will assist you in configuring your Flutter application for Feature Flags using the [Mixpanel Flutter SDK](/docs/tracking-methods/sdks/flutter). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

Feature Flags in the Flutter SDK work across iOS, Android, and Web platforms.

For complete Flutter SDK documentation, see the [Flutter SDK guide](/docs/tracking-methods/sdks/flutter).

## Prerequisites

Before implementing Feature Flags, ensure:

* You are on an Enterprise subscription plan and have the latest version of the SDK installed (minimum supported version is `v2.5.0`). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK.
* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Flag Initialization

Initializing the SDK with feature flags enabled requires passing a `FeatureFlagsConfig` with `enabled: true` to the `Mixpanel.init()` method. This enables making an outbound request to Mixpanel servers with the current user context. The server will assign the user context to a variant for each feature flag according to how they are configured in the Mixpanel UX.

The response will include an assigned variant for each flag that the user context is in a rollout group for. If a flag is not returned, it most likely signifies that the user was excluded by filtering rules or the rollout percentage for the flag.

**Example Usage**

```dart theme={"system"}
import 'package:mixpanel_flutter/mixpanel_flutter.dart';

// Initialize Mixpanel with feature flags enabled
Mixpanel mixpanel = await Mixpanel.init(
  "YOUR_PROJECT_TOKEN",
  trackAutomaticEvents: false,
  featureFlags: FeatureFlagsConfig(enabled: true),
);
```

If your flag is configured with a Variant Assignment Key other than `distinct_id` or `device_id` for any of the feature flags in your project, then the call to initialize feature flags must include those keys.

For example, for a Variant Assignment Key, `company_id`, you would setup the SDK as follows:

```dart theme={"system"}
Mixpanel mixpanel = await Mixpanel.init(
  "YOUR_PROJECT_TOKEN",
  trackAutomaticEvents: false,
  featureFlags: FeatureFlagsConfig(
    enabled: true,
    context: {
      "company_id": "X",
    },
  ),
);
```

If you are using Runtime Targeting in any of the feature flags in your project, then any properties that you use in targeting should be included in a `custom_properties` node within the context:

```dart theme={"system"}
Mixpanel mixpanel = await Mixpanel.init(
  "YOUR_PROJECT_TOKEN",
  trackAutomaticEvents: false,
  featureFlags: FeatureFlagsConfig(
    enabled: true,
    context: {
      "company_id": "X",
      "custom_properties": {
        "platform": "flutter",
      },
    },
  ),
);
```

## Flag Persistence

Minimum supported SDK version: [`v2.8.0`](https://github.com/mixpanel/mixpanel-flutter/releases/tag/v2.8.0)

<Note>
  Flag persistence is supported on iOS and Android. Web support is coming soon. On Web, the `variantLookupPolicy` is treated as `networkOnly` regardless of what is configured.
</Note>

By default (`networkOnly`), the SDK fetches fresh flag assignments and waits for the network response before variant calls complete. You can enable persistence so that assignments are persisted on-device and available immediately on subsequent launches (iOS and Android only).

Configure a `variantLookupPolicy` on `FeatureFlagsConfig`:

**`networkFirst`** — The SDK waits for the network on every launch. If the network call fails, the persisted value is returned as a fallback. Async getter calls block until the fetch completes (or the fallback is resolved).

```dart theme={"system"}
Mixpanel mixpanel = await Mixpanel.init(
  "YOUR_PROJECT_TOKEN",
  trackAutomaticEvents: false,
  featureFlags: FeatureFlagsConfig(
    enabled: true,
    variantLookupPolicy: VariantLookupPolicy.networkFirst(),
  ),
);

// getVariantValue waits for the network. Falls back to persisted value if network fails.
FeatureFlags flags = mixpanel.getFeatureFlags();
dynamic value = await flags.getVariantValue("my-feature-flag", "control");
// value is from the network response, or from persistence if the network was unavailable
```

**`persistenceUntilNetworkSuccess`** — Persisted variants are returned immediately on launch. On iOS and Android, each getter call while serving persisted data triggers a background network fetch. If the fetch fails, persisted data continues to be served and the next getter call retries the fetch. Once a fetch succeeds, the in-memory state updates and subsequent calls no longer trigger background fetches.

```dart theme={"system"}
Mixpanel mixpanel = await Mixpanel.init(
  "YOUR_PROJECT_TOKEN",
  trackAutomaticEvents: false,
  featureFlags: FeatureFlagsConfig(
    enabled: true,
    variantLookupPolicy: VariantLookupPolicy.persistenceUntilNetworkSuccess(),
  ),
);

// getVariantValue returns immediately from persistence. Each call (iOS/Android) triggers a
// background fetch until a network response succeeds and replaces the persisted state.
FeatureFlags flags = mixpanel.getFeatureFlags();
dynamic value = await flags.getVariantValue("my-feature-flag", "control");
// value is from persistence; background fetch retries on each call until network succeeds
```

To customize the TTL (default: 24 hours), pass a `Duration`:

```dart theme={"system"}
Mixpanel mixpanel = await Mixpanel.init(
  "YOUR_PROJECT_TOKEN",
  trackAutomaticEvents: false,
  featureFlags: FeatureFlagsConfig(
    enabled: true,
    variantLookupPolicy: VariantLookupPolicy.networkFirst(
      persistenceTtl: Duration(hours: 12),
    ),
  ),
);
```

### Variant source

Every `MixpanelFlagVariant` carries a `source` field indicating where the value came from: `NetworkSource`, `PersistenceSource` (with a `persistedAt` timestamp), or `FallbackSource`. Use `getVariant()` to receive the full variant object.

```dart theme={"system"}
FeatureFlags flags = mixpanel.getFeatureFlags();
final fallback = MixpanelFlagVariant(key: "control", value: "control");
MixpanelFlagVariant variant = await flags.getVariant("my-feature-flag", fallback);
final value = variant.value;
final source = variant.source; // NetworkSource, PersistenceSource, or FallbackSource
```

### `$experiment_started` properties

When a variant is served, the `$experiment_started` exposure event includes:

* `$variant_source` — `"network"` or `"persistence"`
* `$persisted_at_in_ms` — epoch ms when the variant set was persisted *(persistence only)*
* `$ttl_in_ms` — the configured TTL in ms *(persistence only)*

<Note>
  Persisted variants are tied to the current `distinct_id`. Calling `identify()` with a new ID or calling `reset()` clears persisted data and triggers a fresh fetch.
</Note>

## Flag Reload

Following initialization, you can reload feature flag assignments. The available methods vary by platform.

### Reload via identify (All Platforms)

After a user logs in or out of your application and you call `identify`, a feature flag reload will be triggered. This works consistently across iOS, Android, and Web.

```dart theme={"system"}
String updatedDistinctId = "";
// Reload after login
mixpanel.identify(updatedDistinctId);
```

### Manual Reload

To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags:

```dart theme={"system"}
FeatureFlags flags = mixpanel.getFeatureFlags();

// Manually reload flag assignments
await flags.loadFlags();
```

<Note>
  On Web, `loadFlags()` is not supported. Use `updateContext()` to trigger a flag reload instead.
</Note>

### Update Context

You can update the feature flags context after initialization, which will replace the current context and trigger a reload with the new values. This is supported on all platforms (iOS, Android, and Web).

```dart theme={"system"}
FeatureFlags flags = mixpanel.getFeatureFlags();

// Update context and reload flags
await flags.updateContext({
  "company_id": "Y",
  "custom_properties": {
    "platform": "flutter",
  },
});
```

<Note>
  `updateContext` completely replaces the previously set custom context — it does not merge with existing values. The returned `Future` completes when the flag re-fetch is complete.
</Note>

### Reset

Calling `reset()` clears all feature flag assignments from memory and triggers a new fetch for the updated `distinct_id`. Requires SDK version [`v2.8.0`](https://github.com/mixpanel/mixpanel-flutter/releases/tag/v2.8.0) or later.

```dart theme={"system"}
mixpanel.reset();
// Flags are cleared immediately. A new fetch begins for the anonymous distinct_id.
```

### Check Flags Ready

Before evaluating flags, you can check if they have been loaded:

```dart theme={"system"}
FeatureFlags flags = mixpanel.getFeatureFlags();

bool ready = await flags.areFlagsReady();
if (ready) {
  // Flags are loaded and ready to use
}
```

### Feature Gates: Check if Flag is Enabled/Disabled

```dart theme={"system"}
FeatureFlags flags = mixpanel.getFeatureFlags();

// Check if a boolean flag is enabled
// The fallback value is used if the user doesn't match any of the flag's rollout rules
bool isEnabled = await flags.isEnabled("my-boolean-flag", false);

if (isEnabled) {
  showNewFeature();
} else {
  showOldFeature();
}
```

### Experiment and Dynamic Config Flags: Get Variant Value

```dart theme={"system"}
FeatureFlags flags = mixpanel.getFeatureFlags();

// Get the flag value
// The fallback value is used if the user doesn't match any of the flag's rollout rules
dynamic value = await flags.getVariantValue("my-feature-flag", "control");

// Use flag value in your application logic
if (value == "variant_a") {
  showExperienceForVariantA();
} else if (value == "variant_b") {
  showExperienceForVariantB();
} else {
  showDefaultExperience();
}
```

### Get All Variants

Starting from Flutter SDK version `2.7.0`, you can retrieve all currently loaded flag assignments at once using `getAllVariants()`. This returns a `Map<String, MixpanelFlagVariant>` containing every flag the user is assigned to from the most recent fetch. This method does **not** trigger an exposure event for any flag.

```dart theme={"system"}
FeatureFlags flags = mixpanel.getFeatureFlags();

// Get the variant value for a single flag
dynamic value = await flags.getVariantValue("my-feature-flag", "control");

// Get all flag variants, mapped from the flag key to its assigned variant
Map<String, MixpanelFlagVariant> allFlags = await flags.getAllVariants();
```

## Exposure Events

Calling `isEnabled` or `getVariantValue` triggers tracking an exposure event, `$experiment_started` to your Mixpanel project *if* the user context is in a rollout group for the feature flag. Note that `getAllVariants()` does not trigger exposure events.

## Frequently Asked Questions

### What if I'm not receiving any flags on SDK initialization?

1. **Check your project token**:

* Ensure you're using the correct project token from your [Mixpanel project settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

2. **Review flag configuration**:

* Make sure your feature flag is enabled
* Check the flag's rollout percentage

  * User contexts that are not assigned to the rollout percentage will not receive flags
* If you are using a targeting cohort, verify on the mixpanel 'Users' page that the user's `distinct_id` is a member of that cohort.

3. **Review SDK parameters**:

* Ensure `FeatureFlagsConfig(enabled: true)` is passed to `Mixpanel.init()`
* If using a custom Variant Assignment Key, ensure it is included in the `context` map
* If using Runtime Targeting, ensure all properties used in targeting are included in the `custom_properties` object within `context`

4. **Check flags readiness**: Use `areFlagsReady()` to check if flags have been loaded before making flag evaluation calls
5. **Enable debug logging**: Call `mixpanel.setLoggingEnabled(true)` to see detailed information about flag requests and responses


# Implement Session Replay (Flutter)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/flutter/flutter-replay



## Overview

This developer guide will assist you in configuring your Flutter app for [Session Replay](/docs/session-replay) using the [Session Replay SDK (Flutter)](https://github.com/mixpanel/mixpanel-flutter-session-replay). Learn more about [viewing captured Replays in your project here](/docs/session-replay).

## Best Practices

Session Replay provides powerful insights into user behavior, but it also introduces risks, especially on mobile. These risks are not unique to Mixpanel; they are common across the entire session replay product category. Because SDKs run on end-user devices and screen content may include sensitive data, we recommend implementing / testing Session Replay carefully. Be especially cautious with masking, edge-case testing, and rollout strategies. For more information on risk categories and best practices, read more [here](/docs/session-replay#best-practices).

## Prerequisites

* You are already a Mixpanel customer.
* \[Optional] We recommend having the latest [Mixpanel Flutter SDK](/docs/tracking-methods/sdks/flutter) installed. The Mixpanel Flutter SDK provides a `distinctId` (via `mixpanel.distinctId`) that you can pass to Session Replay during initialization to associate replays with your Mixpanel analytics identity.

| Platform | Minimum Version |
| -------- | --------------- |
| Flutter  | 3.38+           |
| Dart     | 3.8+            |
| iOS      | 13.0+           |
| Android  | API 24 (7.0+)   |
| macOS    | 10.15+          |

## Installation

Add to your `pubspec.yaml`:

```yaml theme={"system"}
dependencies:
  mixpanel_flutter_session_replay: VERSION
```

Replace `VERSION` with the latest version available on [pub.dev](https://pub.dev/packages/mixpanel_flutter_session_replay/versions).

Then run `flutter pub get` to install the package.

### Initialize

Session Replay requires initializing an instance and wrapping your app with `MixpanelSessionReplayWidget`. The SDK does not use a singleton — store the instance using State, Provider, or whichever state management fits your app.

Pass the instance to `MixpanelSessionReplayWidget` to begin capturing. Initialize asynchronously to avoid delaying your app's first frame — the widget handles transitioning from a `null` instance to an initialized one.

```dart theme={"system"}
import 'package:mixpanel_flutter_session_replay/mixpanel_flutter_session_replay.dart';

class _MyAppState extends State<MyApp> {
  MixpanelSessionReplay? _sessionReplay;

  @override
  void initState() {
    super.initState();
    _initSessionReplay();
  }

  Future<void> _initSessionReplay() async {
    final result = await MixpanelSessionReplay.initialize(
      token: 'YOUR_MIXPANEL_TOKEN',
      distinctId: 'user_123', // or mixpanel.distinctId
      options: SessionReplayOptions(
        autoRecordSessionsPercent: 100.0,
      ),
    );
    if (result.success) {
      setState(() => _sessionReplay = result.instance);
    } else {
      debugPrint('Session Replay init failed: ${result.errorMessage}');
    }
  }

  @override
  Widget build(BuildContext context) {
    return MixpanelSessionReplayWidget(
      instance: _sessionReplay, // null until initialization completes
      child: MaterialApp(home: HomeScreen()),
    );
  }
}
```

## Data Residency

If your Mixpanel project lives in the EU or India data center, or you route all Mixpanel traffic through a self-hosted proxy, set `serverUrl` on `SessionReplayOptions`. The SDK exposes a `DataResidency` class with the managed region URLs so you don't have to hardcode them.

| Region       | `DataResidency` constant | URL                           |
| ------------ | ------------------------ | ----------------------------- |
| US (default) | `DataResidency.us`       | `https://api.mixpanel.com`    |
| EU           | `DataResidency.eu`       | `https://api-eu.mixpanel.com` |
| India        | `DataResidency.india`    | `https://api-in.mixpanel.com` |

**Example Usage**

```dart theme={"system"}
import 'package:mixpanel_flutter_session_replay/mixpanel_flutter_session_replay.dart';

final result = await MixpanelSessionReplay.initialize(
  token: 'YOUR_MIXPANEL_TOKEN',
  distinctId: 'user_123',
  options: SessionReplayOptions(
    autoRecordSessionsPercent: 100.0,
    serverUrl: DataResidency.eu,
  ),
);
```

You can also pass any fully-qualified HTTPS URL — useful when routing replay traffic through a self-hosted proxy:

```dart theme={"system"}
options: SessionReplayOptions(
  serverUrl: 'https://mixpanel-proxy.yourcompany.com',
)
```

Learn more about [EU Data Residency](/docs/privacy/eu-residency) and [India Data Residency](/docs/privacy/in-residency).

## Quick Start

Here's a quick overview of some available controls. For a more in-depth guide, continue reading.

```dart theme={"system"}
// start recording manually (with optional sampling rate)
sessionReplay.startRecording(sessionsPercent: 100.0);

// stop recording
sessionReplay.stopRecording();

// update user identity
sessionReplay.identify('new_distinct_id');

// mask a sensitive widget
MixpanelMask(child: Text('Sensitive text'))

// unmask a safe widget
MixpanelUnmask(child: Text('Public text'))

// flush queued events
await sessionReplay.flush();
```

See [Masking Behavior](/docs/tracking-methods/sdks/flutter/flutter-replay#masking-behavior) for detailed examples of how `MixpanelMask`, `MixpanelUnmask`, and auto-masking interact.

## Capturing Replays

<Warning>
  Test in a sandbox project and start with a 100% sample rate. This allows you to monitor performance, usage, and ensure your privacy rules align with your company policies.
</Warning>

By default, recording begins automatically upon initialization, configurable via the `autoRecordSessionsPercent` option.

### Sampling

We recommend using automatic sampling for most use cases. Use [manual capture](/docs/tracking-methods/sdks/flutter/flutter-replay#manual-capture) if you need control over exactly when recording starts and stops.

To enable Session Replay, set `autoRecordSessionsPercent` between 0.0 and 100.0. At 0.0, no sessions are recorded. At 100.0, all sessions are recorded.

To start, we recommend using a 100% sampling rate to ensure replay capture is behaving as expected, then adjust according to your specific analytics needs.

```dart theme={"system"}
// records 100% of all sessions
options: SessionReplayOptions(
  autoRecordSessionsPercent: 100.0,
)
```

### Manual Capture

To programmatically start and stop replay capture, use the `.startRecording()` and `.stopRecording()` methods.

**Start capturing replay**

When calling `.startRecording()`, recording will begin with the sample rate that was passed to `sessionsPercent` (100% default).

```dart theme={"system"}
// start recording (100%)
sessionReplay.startRecording();

// start recording with a specified sampling rate (10%)
sessionReplay.startRecording(sessionsPercent: 10.0);
```

`.startRecording()` has no effect if recording is already in progress.

**Stop capturing replay data**

Call `.stopRecording()` to stop any active replay data collection. The SDK automatically stops recording when the app loses focus.

```dart theme={"system"}
// manually end a replay capture
sessionReplay.stopRecording();
```

**Example use cases for manual capture**

| Scenario                                                                  | Guidance                                                                                                                                                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| We have a sensitive screen we don't want to capture                       | When user is about to access the sensitive screen, call `.stopRecording()`. To resume recording once they leave this screen, you can resume recording with `.startRecording()` |
| We only want to record certain types of users (e.g. Free plan users only) | Using your application code, determine if current user meets the criteria of users you wish to capture. If they do, then call `.startRecording()` to begin recording           |
| We only want to record users utilizing certain features                   | When user is about to access the feature you wish to capture replays for, call `.startRecording()` to begin recording                                                          |

### Additional Configuration Options

Upon initialization you can provide a `SessionReplayOptions` object to customize your replay capture.

| Option                      | Description                                                                                                                                                                                                                                                                   | Default                       |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `autoMaskedViews`           | Set of enum options for view types that will be automatically masked by the SDK. See [Masking Behavior](/docs/tracking-methods/sdks/flutter/flutter-replay#masking-behavior)                                                                                                  | `{text, image}`               |
| `autoRecordSessionsPercent` | Value between 0.0 and 100.0 that controls the sampling rate for session replay recording                                                                                                                                                                                      | `100.0`                       |
| `flushInterval`             | Specifies the flush interval at which session replay events are sent to the Mixpanel server                                                                                                                                                                                   | `10 seconds`                  |
| `logLevel`                  | Controls the level of debugging logs printed to the console                                                                                                                                                                                                                   | `LogLevel.none`               |
| `storageQuotaMB`            | Maximum MB for the local event queue                                                                                                                                                                                                                                          | `50`                          |
| `remoteSettingsMode`        | Setting for handling remote configuration during SDK initialization. Can be `RemoteSettingsMode.disabled`, `RemoteSettingsMode.fallback`, or `RemoteSettingsMode.strict`. See [Remote Configuration](/docs/tracking-methods/sdks/flutter/flutter-replay#remote-configuration) | `RemoteSettingsMode.disabled` |
| `debugOptions`              | Debug configuration for mask overlay visualization. See [Debug Options](/docs/tracking-methods/sdks/flutter/flutter-replay#debug-options)                                                                                                                                     | `null` (disabled)             |
| `platformOptions`           | Platform-specific options. See [Platform Options](/docs/tracking-methods/sdks/flutter/flutter-replay#platform-options-mobile-only)                                                                                                                                            | `PlatformOptions()`           |

**Example usage:**

```dart theme={"system"}
final result = await MixpanelSessionReplay.initialize(
  token: 'YOUR_MIXPANEL_TOKEN',
  distinctId: 'user_123',
  options: SessionReplayOptions(
    autoRecordSessionsPercent: 100.0,
    autoMaskedViews: {AutoMaskedView.image, AutoMaskedView.text},
    logLevel: LogLevel.debug,
    flushInterval: Duration(seconds: 10),
    platformOptions: PlatformOptions(
      mobile: MobileOptions(wifiOnly: true),
    ),
  ),
);
```

#### Platform Options (mobile only)

| Option            | Description                                                                                                                                                          | Default           |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `mobile`          | Mobile-specific options (iOS/Android). See properties below                                                                                                          | `MobileOptions()` |
| `mobile.wifiOnly` | When `true`, replay events will only be flushed when the device has WiFi. When `false`, replay events will be flushed with any network connection including cellular | `true`            |

#### Debug Options

When non-null, enables debug features such as colored overlays showing masked, auto-masked, and unmasked regions.

<Frame>
  <img alt="Debug overlay demo showing orange auto-mask, red MixpanelMask, and green MixpanelUnmask regions" />
</Frame>

The overlay is a development tool only and is not visible in the captured replay. A few specifics worth knowing:

* **Debug builds only.** The overlay is gated on Flutter's `kDebugMode`, so it only renders in debug builds and is a no-op in profile and release builds.
* **Visible on the device, never in the replay.** The colored rectangles are painted on top of the boundary the SDK captures, so they sit outside the recorded screenshot. The replay sees the SDK's own opaque masks applied to the captured image, not the debug colors. The overlay is also non-interactive — it sits behind an `IgnorePointer`, so taps still reach your app.
* **Refreshes per capture, not per frame.** Mask region detection runs as part of the screenshot pipeline, so the overlay updates each time a new capture completes — at most once every \~500ms while the UI is active, not on every Flutter frame. During fast interactions or animations you may briefly see overlay rectangles in stale positions until the next capture catches up.

| Option                        | Description                                                                                              | Default                |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------- |
| `overlayColors`               | Color configuration for mask overlay visualization. When null, overlay is disabled. See properties below | `DebugOverlayColors()` |
| `overlayColors.maskColor`     | Color for manually masked regions (`MixpanelMask` and security-enforced)                                 | `Colors.red`           |
| `overlayColors.autoMaskColor` | Color for auto-masked regions (text and images)                                                          | `Colors.orange`        |
| `overlayColors.unmaskColor`   | Color for `MixpanelUnmask` regions                                                                       | `Colors.green`         |
| `overlayColors.opacity`       | Opacity of the overlay layer (0.0 = transparent, 1.0 = opaque)                                           | `0.5`                  |

```dart theme={"system"}
options: SessionReplayOptions(
  debugOptions: DebugOptions(
    overlayColors: DebugOverlayColors(
      maskColor: Colors.red,       // MixpanelMask and security-enforced regions
      autoMaskColor: Colors.orange, // Auto-masked text and image regions
      unmaskColor: Colors.green,    // MixpanelUnmask regions
      opacity: 0.5,
    ),
  ),
)
```

## Identity Management

The Mixpanel distinct ID for the current user can be passed into the initializer and changed at runtime by calling the `.identify()` method:

```dart theme={"system"}
// initialize the main Mixpanel tracking SDK
final mixpanel = await Mixpanel.init('YOUR_MIXPANEL_TOKEN', trackAutomaticEvents: true);

// initialize the session replay SDK with the project token and distinct ID from above
final result = await MixpanelSessionReplay.initialize(
  token: 'YOUR_MIXPANEL_TOKEN',
  distinctId: mixpanel.distinctId,
);
```

To change the distinct ID later:

```dart theme={"system"}
// for example when the user logs out
void logout() {
  // reset the main Mixpanel tracking SDK to generate a new distinct ID
  mixpanel.reset();
  final newDistinctId = mixpanel.distinctId;
  // change session replay distinct ID
  sessionReplay.identify(newDistinctId);
}
```

## Manual Flushing

You can flush any currently queued session replay events at any time by calling `.flush()`:

```dart theme={"system"}
await sessionReplay.flush();
```

## Remote Configuration

<Note>
  Available only for customers with a paid session replay add-on.
</Note>

By setting `remoteSettingsMode` you can quickly set SDK options for your project in Mixpanel under `Settings > Organization Settings > Session Replay`.

Three modes are available:

* `RemoteSettingsMode.disabled` (default): Do not use remote configuration and proceed to use the SDK initialization config provided in `MixpanelSessionReplay.initialize`.
* `RemoteSettingsMode.fallback`: Attempt to retrieve remote configuration and proceed with those settings. If there is a failure or timeout, will use previously cached remote settings (from last successful fetch) or the SDK initialization config.
* `RemoteSettingsMode.strict`: Requires a successful remote configuration fetch. If the fetch fails, recording is disabled and no replays will be sent.

Use this setting to quickly update and adjust configurations to your liking.

```dart theme={"system"}
final result = await MixpanelSessionReplay.initialize(
  token: 'YOUR_MIXPANEL_TOKEN',
  distinctId: 'user_123',
  options: SessionReplayOptions(
    remoteSettingsMode: RemoteSettingsMode.fallback,
  ),
);
```

List of currently supported remote settings:

* `autoRecordSessionsPercent`

Settings that are not yet supported will not appear in the remote configuration. These non-included options will use the value from the SDK initialization config.

## Replay ID

When a replay capture begins, a Replay ID is generated by the SDK and is attached as an event property (`$mp_replay_id`) to events tracked by the Mixpanel SDK during the capture session. Events containing the same `$mp_replay_id` will appear in the same Replay.

If you are sending any events not coming from the Mixpanel SDK, add the `$mp_replay_id` event property to attribute the event to a specific Replay.

You can read the active Replay ID from the `replayId` property on your `MixpanelSessionReplay` instance. The property will be `null` if there is no active replay capture in progress.

```dart theme={"system"}
final activeReplayId = sessionReplay.replayId;
```

## Server-Side Stitching

Server-Side Stitching allows you to easily watch Replays for events that were not fired from the SDK.

It works by inferring the Replay that an event belongs to using the Distinct ID and time property attached to the event. This is especially useful if you have events coming in from multiple sources.

For example, let's say a user with Distinct ID "ABC" has a Replay recorded from 1-2pm. Two hours later, an event was sent from your warehouse with a timestamp of 1:35pm with Distinct ID "ABC". Server-Side Stitching will infer that the event should belong in the same Replay.

To ensure Server-Side Stitching works, call [`identify()`](/docs/tracking-methods/sdks/flutter#identify) from the client-side using our SDK with the user's `$user_id`. This guarantees that events generated from both the client-side and server-side share the same Distinct ID. Learn more about [identifying users](/docs/tracking-methods/id-management).

## Logging

Developers can enable or disable logging with the `logLevel` option of the `SessionReplayOptions` object.

```dart theme={"system"}
final result = await MixpanelSessionReplay.initialize(
  token: 'YOUR_MIXPANEL_TOKEN',
  distinctId: distinctId,
  options: SessionReplayOptions(
    logLevel: LogLevel.debug,
  ),
);
```

## Debugging

<Note>
  `$mp_session_record` is exempt from your plan data allowance.
</Note>

To check your implementation, select **Session Replay** from the side navigation in your Mixpanel project to see whether replays are being captured and appearing as expected. When a capture begins, a "Session Recording Checkpoint" event (`$mp_session_record`) also appears in your project; you can use this to verify that Session Replay is implemented correctly.

If you are using the [recommended sampling method](/docs/tracking-methods/sdks/flutter/flutter-replay#sampling) to capture your Replays but having trouble finding the Replays in your project, try calling `.startRecording()` manually and see if the `$mp_session_record` event appears. If it does appear but you are still struggling to locate your Replays, you may want to increase your sampling rate.

## Troubleshooting

If you are still struggling with either of the following common issues:

* Replays are not showing up in my project
* Replays are not displaying my UI correctly

Please [submit a request to our Support team](https://mixpanel.com/get-support) and include the following information:

* Whether your issue is with iOS, Android, macOS, or all platforms
* Your Session Replay code snippet
* Where you initialize the Session Replay SDK
* Any relevant logs (enable with `logLevel: LogLevel.debug`)
* (If applicable) A link to a replay showing the issue
* (If applicable) A screenshot of the UI or a description of the expected behavior

## Privacy

Mixpanel offers a privacy-first approach to Session Replay, including features such as data masking. Mixpanel's Session Replay privacy controls were designed to assist customers in protecting end user privacy. Read more [here](/docs/session-replay/session-replay-privacy-controls).

### User Data

The Mixpanel SDK will always mask all detected text inputs. To protect end-user privacy, input text fields cannot be unmasked.

By default, we attempt to identify all text and image views.

You can unmask these elements at your own discretion using the [`autoMaskedViews` config option](/docs/tracking-methods/sdks/flutter/flutter-replay#additional-configuration-options). See [Masking Behavior](/docs/tracking-methods/sdks/flutter/flutter-replay#masking-behavior) for detailed examples of how masking directives interact.

### Mark Widget Sensitivity

All text input widgets (`TextField`, `TextFormField`, `CupertinoTextField`) are masked by default. Text inputs cannot be unmasked.

Wrap any widget with `MixpanelMask` to force masking, or `MixpanelUnmask` to prevent auto-masking. These directives apply to the entire subtree.

```dart theme={"system"}
Column(
  children: [
    // This entire card and its contents will be masked
    MixpanelMask(
      child: Card(
        child: Column(
          children: [
            Text('Account Number: 1234-5678'),
            Text('Balance: \$10,000'),
          ],
        ),
      ),
    ),

    // This section will not be auto-masked (except text inputs)
    MixpanelUnmask(
      child: Row(
        children: [
          Image.asset('logo.png'), // visible, even if images are auto-masked
          Text('Public info'),     // visible, even if text is auto-masked
          TextField(),             // still masked — text inputs are always masked
        ],
      ),
    ),
  ],
)
```

For detailed scenarios showing how masking directives interact (nesting, overflow, security), see [Masking Behavior](/docs/tracking-methods/sdks/flutter/flutter-replay#masking-behavior).

## Masking Behavior

This section documents how `MixpanelMask`, `MixpanelUnmask`, auto-masking, and security masking (text entry) interact during view tree traversal. All examples below use `autoMaskedViews: {image}` — text is **not** auto-masked, image **is** auto-masked.

### Sensitive Container

```text theme={"system"}
MixpanelMask                  ← container rect + context=mask
  └─ Column
    ├─ Text("Name")            ← MASKED (context=mask)
    ├─ Image(avatar)           ← MASKED (context=mask)
    └─ TextField(email)        ← MASKED (security)
```

<Frame>
  <img alt="Sensitive container" />
</Frame>

`MixpanelMask` masks all descendants — auto-masking config is irrelevant.

### Insensitive Container

```text theme={"system"}
MixpanelUnmask                 context=unmask
  └─ Column
    └─ Container
      ├─ Text("Public label")   ← visible (unmask overrides auto-masking)
      ├─ Row
      │   ├─ Image(logo.png)    ← visible (auto-masked normally, but unmask overrides)
      │   └─ Text("caption")    ← visible
      └─ TextField(password)    ← MASKED (security override)
```

<Frame>
  <img alt="Insensitive container" />
</Frame>

`MixpanelUnmask` overrides auto-masking. Text entry is always masked regardless.

### Sensitive Container with Overflow

```text theme={"system"}
MixpanelMask (150x80)          ← container rect + context=mask
  └─ Column
    └─ Stack(clip: none)
      ├─ Text("Inside")        ← MASKED (context=mask)
      └─ Positioned(right: -120)
        └─ Text("Outside")     ← MASKED (leaf rect covers overflow)
```

<Frame>
  <img alt="Overflow masked" />
</Frame>

Leaf rects ensure overflow children are masked even outside container bounds.

### MixpanelMask > MixpanelUnmask

```text theme={"system"}
MixpanelMask                   ← container rect + context=mask
  └─ Column
    ├─ Text("Header")          ← MASKED (context=mask)
    ├─ MixpanelUnmask            context=unmask (inner override)
    │   └─ Row
    │     └─ Text("Public")    ← no leaf rect, but container rect still covers it
    └─ Text("Footer")         ← MASKED (context=mask)
```

<Frame>
  <img alt="MixpanelMask then MixpanelUnmask" />
</Frame>

The inner unmask is tracked but visually covered by the outer container rect unless the child overflows.

### MixpanelMask > MixpanelUnmask with Overflow

```text theme={"system"}
MixpanelMask (150x80)            ← container rect + context=mask
  └─ Column
    └─ Stack(clip: none)
      ├─ Text("Inside")          ← MASKED (context=mask)
      └─ MixpanelUnmask            context=unmask (inner override)
        └─ Positioned(right: -120, top: 15)
          └─ Text("Unmasked")    ← visible (unmask context, outside container rect)
```

<Frame>
  <img alt="MixpanelMask with MixpanelUnmask overflow" />
</Frame>

Unmasked children that overflow the container rect bounds are visible.

### MixpanelUnmask > MixpanelMask

```text theme={"system"}
MixpanelUnmask                 context=unmask
  └─ Column
    ├─ Text("Public")          ← visible (unmask context)
    └─ MixpanelMask            ← container rect + context=mask
      └─ Row
        └─ Text("Private")    ← MASKED (context=mask)
```

<Frame>
  <img alt="MixpanelUnmask then MixpanelMask" />
</Frame>

Innermost directive wins — the inner `MixpanelMask` overrides the outer unmask for its subtree.

### Text Entry Security

```text theme={"system"}
MixpanelUnmask                        context=unmask
  └─ Column
    ├─ Text("Username")               ← visible (unmask context)
    ├─ TextField("tyler@example.com") ← MASKED (security, always)
    ├─ Text("Password")               ← visible (unmask context)
    └─ TextField("••••••••")          ← MASKED (security, always)
```

<Frame>
  <img alt="Text entry security" />
</Frame>

Text entry fields (`TextField`, `CupertinoTextField`, `EditableText`) are **always** masked regardless of directives or auto-masking config.

### Auto-masking (no explicit directive)

```text theme={"system"}
Column                    context=none (default)
  ├─ Text("Hello World")  ← visible (text not in autoMaskedViews)
  ├─ Image(photo.jpg)     ← MASKED (image in autoMaskedViews)
  └─ TextField(search)    ← MASKED (security, always)
```

<Frame>
  <img alt="Auto-masking" />
</Frame>

Without any masking directive, auto-masking applies based on `autoMaskedViews` config. Text entry is always masked regardless.

## Retention

By default, Mixpanel retains Session Replays for 30 days from the date the replay is ingested and becomes available for viewing within Mixpanel. Customers on our [Enterprise plan](https://mixpanel.com/pricing/) can customize this retention period between 7 days and 360 days. Once a replay is expired, there is no way to view that replay.

## FAQ

#### How does Session Replay work in Flutter?

Session Replay observes user interactions within your app, capturing UI hierarchy changes and storing them as images, which are then sent to Mixpanel. Mixpanel reconstructs these images, applying recorded events as an end-user completes them.

Within Mixpanel's platform, you can view a reconstruction of your end-user's screen as they navigate your app.

However, Session Replay is not a literal video recording of your end-user's screen; end-user actions are not video-recorded.

#### Can I prevent Session Replay from recording sensitive content?

The Mixpanel SDK will always mask identifiable text inputs. By default, all text and images on a page are also masked.

Additionally, you can customize how you leverage our SDK to fully control (1) where to record and (2) whom to record. Consider the [manual capture example scenarios](/docs/tracking-methods/sdks/flutter/flutter-replay#manual-capture), [SDK configuration options](/docs/tracking-methods/sdks/flutter/flutter-replay#additional-configuration-options), and [manual widget masking](/docs/tracking-methods/sdks/flutter/flutter-replay#mark-widget-sensitivity) provided above to customize the replay capture of your implementation. See [Masking Behavior](/docs/tracking-methods/sdks/flutter/flutter-replay#masking-behavior) for detailed examples.

#### How can I estimate how many Replays I will generate?

If you already use Mixpanel, the [Session Start events](/docs/features/sessions) are a way to estimate the rough amount of replays you might expect. This is especially true if you use timeout-based query sessions. However, because our sessions are defined at query time, we cannot guarantee these metrics will be directly correlated.

When you enable Session Replay, use the above proxy metric to determine a starting sampling percentage, which will determine how many replays will be sent. You can always adjust this as you go to calibrate to the right level.

#### How does Session Replay affect my app's bandwidth consumption?

The bandwidth impact of Session Replay depends on the setting of the [`wifiOnly` parameter](/docs/tracking-methods/sdks/flutter/flutter-replay#platform-options-mobile-only).

By default, `wifiOnly` is set to `true`, which means replay events are only flushed to the server when the device has a wifi connection. If there is no wifi, flushes are skipped, and the events remain in the local disk queue until WiFi is restored. This ensures no additional cellular data is used, preventing users from incurring additional data charges.

When `wifiOnly` is set to `false`, replay events are flushed with any available network connection, including cellular. In this case, the amount of cellular data consumed depends on the intensity of user interactions and the typical session length of your app. Users may incur additional data charges if large amounts of data are transmitted over cellular connections.

#### How does Session Replay for mobile work if my app is offline?

Session Replay events are saved to a local disk queue when no network connection is available (or when `wifiOnly` is `true` and there is no WiFi). The SDK will automatically flush queued events once a suitable connection is restored. However, the queue is **not** persisted across app restarts — any events that have not been flushed before the app is terminated will be lost.

#### Does Mobile Session Replay work with my CDP?

Yes — but only if the Mixpanel Session Replay SDK is installed client-side.

Mobile Session Replay is compatible with CDPs like Segment and mParticle, but you must integrate the Mixpanel Flutter Session Replay SDK directly in your app. Without it, replays won't be captured.

Key Considerations:

* If you're using Segment server-side, session replays will not be recorded, since the SDK isn't running in the app.
* The Mixpanel Session Replay SDK is separate from the standard Mixpanel tracking SDK. You do not need the regular SDK, but the Replay SDK must be configured with a `distinctId` and project token.
* Events can be linked to replays either by:

  * Manually attaching the current replay ID (`$mp_replay_id`) to each event
  * Using server-side stitching after the fact


# Mixpanel SDKs: Go
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/go



## Getting Started

The Mixpanel Go library is designed to be used for scripting, or in circumstances when a client can't or won't run client side scripts

The [Full API Reference](https://pkg.go.dev/github.com/mixpanel/mixpanel-go), [Library Source Code](https://github.com/mixpanel/mixpanel-go), and [Examples](https://github.com/mixpanel/mixpanel-go/tree/main/examples) are documented in our GitHub repo.

## Installing the Library

Install the library with [Go get](https://pkg.go.dev/cmd/go/internal/get). Run the following command in your CLI to install:

```shell theme={"system"}
# install mixpanel library using Go get
go get github.com/mixpanel/mixpanel-go
```

Once the library is installed, create an instance of Mixpanel in your code by calling the [`NewApiClient()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#NewApiClient) using [your project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).

```go theme={"system"}
// create an instance of Mixpanel
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")
```

### Library Configuration

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/go#privacy-friendly-tracking).
</Warning>

The library can be initialized with different configurations. See a complete list of the configuration options[here](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#Options).

You can override the default configuration using the `options` argument when initializing the library.

**Example Usage**

```go theme={"system"}
// create an instance of Mixpanel and include Service Account credentials
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN",
	mixpanel.ServiceAccount(7282615, "service_account_name", "service_account_secret")
)
```

## Sending Events

Use [`Track()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.Track) to send an event by providing the distinct\_id, event name, and any event properties. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```go theme={"system"}
ctx := context.Background()

// initialize Mixpanel
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

// track "some_event" with "plan" event prop
err := mp.Track(ctx, []*mixpanel.Event{
	mp.NewEvent("some_event", "", map[string]any{
		"plan": "premium",
	}),
})
```

Mixpanel can determine default geolocation data (`$city`, `$region`, `mp_country_code`) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your data center. [Read about best practices for geolocation with server-side implementations](https://mixpanel.com/blog/2014/09/08/everything-about-server-side-updates/).

### Importing Historical Events

The [`Track()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.Track) function is designed for real-time tracking in a server-side environment and will trigger request to the [/track API endpoint](/reference/track-event), which will validate for events with a time stamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested.**

Use the [`Import()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.Import) function to import events that occurred more than 5 days in the past. The `Import()` function is based on the [/import API endpoint](/reference/import-events).

**Example Usage**

```go theme={"system"}
ctx := context.Background()

// initialize Mixpanel
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

//create an event
event := mp.NewEvent("import test event", mixpanel.EmptyDistinctID, nil)
event.AddTime(time.Now())
event.AddInsertID("insert_id")
importEvents := []*mixpanel.Event{event}

// import event older than 5 days
if err := mp.Import(ctx, importEvents, mixpanel.ImportOptionsRecommend); 
err != nil {
	panic(err)
}
```

You can also use the [mp-utils python module](https://github.com/mixpanel/mixpanel-utils) designed for scripting.

## Managing User Identity

Since the Go SDK is a server-side library, IDs are not generated by the SDK. Instead, you will need to generate and manage the distinct\_id yourself and include it in your events and profile data.

Learn more about [server-side identity management](/docs/tracking-methods/id-management/identifying-users-simplified#server-side-identity-management).

## Storing User Profiles

Create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Go SDK provides a few methods for setting profile properties, which will trigger requests to the [/engage API endpoint](/reference/profile-set).

Mixpanel determines default geolocation data (`$city`, `$region`, `mp_country_code`) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your data center. [Learn more about best practices for geolocation.](/docs/tracking-best-practices/geolocation).

### Setting Profile Properties

Set profile properties on a user profile by calling [`PeopleSet()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.PeopleSet).

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```go theme={"system"}
ctx := context.Background()
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

// create a payload to create profile for distinct_id 12345
// with "name" and "plan" user props
exampleUser := mixpanel.NewPeopleProperties("12345", map[string]any{
	"name": "John",
	"plan": "premium",
	"$ip": 0, // prevent geolocation update
})

// pass the profile payload in the PeopleSet function
err := mp.PeopleSet(ctx,
	[]*mixpanel.PeopleProperties{
		exampleUser,
	},
)
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient).

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title="PeopleSetOnce()">
    The [`PeopleSetOnce()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.PeopleSetOnce) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```go theme={"system"}
    ctx := context.Background()
    mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

    // create a user profile with name and plan user props
    exampleUser := mixpanel.NewPeopleProperties("12345", map[string]any{
    	"name": "John",
    	"plan": "premium",
    	"$ip": 0, // prevent geolocation update
    })
    err := mp.PeopleSet(ctx,
    	[]*mixpanel.PeopleProperties{
    		exampleUser,
    	},
    )

    userUpdateA := mixpanel.NewPeopleProperties("12345", map[string]any{
    	"name": "samantha",
    	"$ip": 0,
    })
    // will be ignored since "name" already exists
    err := mp.PeopleSetOnce(ctx,
    	[]*mixpanel.PeopleProperties{
    		userUpdateA,
    	},
    )

    userUpdateB := mixpanel.NewPeopleProperties("12345", map[string]any{
    	"location": "us",
    	"$ip": 0,
    })
    // set "location" user prop since it does not exist
    err := mp.PeopleSetOnce(ctx,
    	[]*mixpanel.PeopleProperties{
    		userUpdateB,
    	},
    )
    ```
  </Tab>

  <Tab title="PeopleAppendListProperty()">
    The [`PeopleAppendListProperty()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.PeopleAppendListProperty) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```go theme={"system"}
    ctx := context.Background()
    mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

    // create a user profile with name and roles user props
    exampleUser := mixpanel.NewPeopleProperties("12345", map[string]any{
    	"name": "John",
    	"roles": []string{"sales", "engineer"},
    	"$ip": 0, // prevent geolocation update
    })
    err := mp.PeopleSet(ctx,
    	[]*mixpanel.PeopleProperties{
    		exampleUser,
    	},
    )


    // add "legal" to "roles"  
    // new role values are ['sales','engineer','legal']
    if err := mp.PeopleAppendListProperty(ctx, "12345", map[string]any{
    	"roles": []string{"legal"},
    }); err != nil {
    	return err
    }

    // .append() allows duplicates
    // new "roles" values are ['sales','engineer','legal', 'legal']
    if err := mp.PeopleAppendListProperty(ctx, "12345", map[string]any{
    	"roles": []string{"legal"},
    }); err != nil {
    	return err
    }
    ```
  </Tab>

  <Tab title="PeopleUnionProperty()">
    The [`PeopleUnionProperty()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.PeopleUnionProperty) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```go theme={"system"}
    ctx := context.Background()
    mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

    // create a user profile with name and roles user props
    exampleUser := mixpanel.NewPeopleProperties("12345", map[string]any{
    	"name": "John",
    	"roles": []string{"sales", "engineer"},
    	"$ip": 0, // prevent geolocation update
    })
    err := mp.PeopleSet(ctx,
    	[]*mixpanel.PeopleProperties{
    		exampleUser,
    	})

    // "engineer" ignored since it already exists
    // append "legal" to "roles"
    err := mp.PeopleUnionProperty(ctx, "12345", map[string]any{
    	"vehicles": []string{"engineer", "legal"},
    })
    ```
  </Tab>

  <Tab title="PeopleIncrement()">
    The [`PeopleIncrement()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.PeopleIncrement) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```go theme={"system"}
    // initialize Mixpanel
    ctx := context.Background()
    mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

    // create a user profile with name and roles user props
    exampleUser := mixpanel.NewPeopleProperties("12345", map[string]any{
    	"name": "John",
    	"age": 25,
    	"$ip": 0, // prevent geolocation update
    })
    err := mp.PeopleSet(ctx,
    	[]*mixpanel.PeopleProperties{
    		exampleUser,
    	})

    // increment "age" by 2
    err := mp.PeopleIncrement(ctx, "12345", map[string]int{
    	"age": 2,
    })

    // use negative number to decrement
    // decrement "age" by 5
    err := mp.PeopleIncrement(ctx, "12345", map[string]int{
    	"age": -5,
    })

    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

### Sending Group Identifiers With Events

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

To send group identifiers with your events, set the `group_key` as an event property with the `group_id` as the value.

**Example Usage**

```go theme={"system"}
ctx := context.Background()
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

// send "some_event"
// event will be attributed to the "mixpanel" company group
mp.Track(ctx, []*mixpanel.Event{
	mp.NewEvent("some_event", "sample_distinct_id", map[string]any{
		"Plan Type": "Premium",
		"company":   "mixpanel",
	}),
})
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

**Example Usage**

```go theme={"system"}
ctx := context.Background()
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

// send "some_event"
// event is attributed to 2 company groups: "mp-us" and "mp-eu"
mp.Track(ctx, []*mixpanel.Event{
	mp.NewEvent("some_event", "sample_distinct_id", map[string]any{
		"Plan Type": "Premium",
		"company":   []string{"mp-us", "mp-eu"},
	}),
})
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `.PeopleSet` call.

**Example Usage**

```go theme={"system"}
ctx := context.Background()
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

// create a payload to create profile for distinct_id 12345
// with group key "company" as user prop and group ID "mixpanel" as value
exampleUser := mixpanel.NewPeopleProperties("12345", map[string]any{
	"name": "sam",
	"company": "mixpanel",
	"$ip": 0
})

// pass the profile payload in the PeopleSet function
err := mp.PeopleSet(ctx,
	[]*mixpanel.PeopleProperties{
		exampleUser,
	},
)
```

### Setting Group Profile Properties

Create a group profiles by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

The Go SDK provides a few methods for setting group profile properties, which will trigger requests to the [/engage API endpoint](/reference/group-set-property).

To set group profile properties, use the [`GroupSet()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.GroupSet) method.

**Example Usage**

```go theme={"system"}
ctx := context.Background()
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

// Create or update a the "mixpanel" company group
// setting "Industry" and "Name" as group props
mp.GroupSet(ctx, "company", "mixpanel", map[string]any{
	"Industry": "Analytics",
	"Name":        "Mixpanel",
})
```

### Other Group Profile Methods

See all of the group methods under the [here](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title="GroupSetOnce()">
    The [`GroupSetOnce()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.GroupSetOnce) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```go theme={"system"}
    ctx := context.Background()
    mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

    // set group profile for "mixpanel" company group
    mp.GroupSet(ctx, "Company", "mixpanel", map[string]any{
    	"Name": "Mixpanel",
    	"employee_count": 100
    })

    // ignored since "Name" is already exists
    mp.GroupSetOnce(ctx, "Company", "mixpanel", map[string]any{
    	"Name": "mp-us",
    })

    // set "location" group prop since it does not exist
    mp.GroupSetOnce(ctx, "Company", "mixpanel", map[string]any{
    	"location": "us",
    })
    ```
  </Tab>

  <Tab title="GroupDeleteProperty()">
    The [`GroupDeleteProperty()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.GroupDeleteProperty) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```go theme={"system"}
    ctx := context.Background()
    mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

    // set group profile for "mixpanel" company group
    mp.GroupSet(ctx, "Company", "mixpanel", map[string]any{
    	"Name": "Mixpanel",
    	"employee_count": 100
    })

    // delete "employee_count" from the group profile
    mp.GroupDeleteProperty(ctx, "Company", "mixpanel", "employee_count")

    // only "Name" remains as a group prop
    ```
  </Tab>

  <Tab title="GroupUnionListProperty()">
    The [`GroupUnionListProperty()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.GroupUnionListProperty) method append new values to a list property, excluding duplicates.

    Use this method to create a list group profile property that only contains unique values without duplicates.

    **Example Usage**

    ```go theme={"system"}
    ctx := context.Background()
    mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

    // set group profile for "mixpanel" company group
    mp.GroupSet(ctx, "Company", "mixpanel", map[string]any{
    	"Name": "Mixpanel",
    	"features": []string{"alert","report","cohort"},
    })

    // add "data pipeline" to "features" prop
    // ignore "alert" since it is a duplicate value
    mp.GroupUnionListProperty(ctx, "Company", "mixpanel", map[string]any{
    	"features": []string{"data pipeline","alert"},
    })
    ```
  </Tab>

  <Tab title="GroupRemoveListProperty()">
    The [`GroupRemoveListProperty()`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#ApiClient.GroupRemoveListProperty) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```go theme={"system"}
    ctx := context.Background()
    mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

    // set group profile for "mixpanel" company group
    mp.GroupSet(ctx, "Company", "mixpanel", map[string]any{
    	"Name": "Mixpanel",
    	"features": []string{"alert","report","cohort"},
    })

    // remove "alerts" from "features"
    // "features" now contain ["reports","cohorts"]
    mp.GroupRemoveListProperty(ctx, "Company", "mixpanel", map[string]any{
    	"features": []string{"alert"},
    })
    ```
  </Tab>
</Tabs>

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Go SDK has a few configurations to help you protect user data.

Since this is a server-side tracking library where you have control of the servers, your server is responsible for determining whether to send data about a particular user or not.

### EU Data Residency

Route data to Mixpanel's EU servers by using the [`EuResidency`](https://pkg.go.dev/github.com/mixpanel/mixpanel-go#EuResidency) option during the library initialization.

```go theme={"system"}
ctx := context.Background()

//Initialize Mixpanel with request URL set to Mixpanel's EU domain
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN", mixpanel.EuResidency())
```

### IN Data Residency

Route data to Mixpanel's IN servers by using the [`InResidency`](https://github.com/mixpanel/mixpanel-go/blob/2d7b4a098b47064e7ae5874472368e8699232a96/mixpanel.go#L138) option during the library initialization.

```go theme={"system"}
ctx := context.Background()

//Initialize Mixpanel with request URL set to Mixpanel's IN domain
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN", mixpanel.InResidency())
```

### Disable Geolocation

The Go SDK parse the request IP address to generate geolocation properties for events and profiles. You may want to disable them to prevent the unintentional setting of your data's geolocation to the location of your server that is sending the request, or to prevent geolocation data from being tracked entirely.

You can also disable geolocation for individual requests by setting the `$ip`/`ip` in your events and profile payloads to `0`.

**Example Usage**

```go theme={"system"}
ctx := context.Background()
mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")

// set profile without geolocation parsing
exampleUser := mixpanel.NewPeopleProperties("12345", map[string]any{
	"name": "John",
	"plan": "premium",
	"$ip": 0, // prevent geolocation update
})
err := mp.PeopleSet(ctx,
	[]*mixpanel.PeopleProperties{
		exampleUser,
	},
)

// track "some_event" without setting geolocation
err := mp.Track(ctx, []*mixpanel.Event{
	mp.NewEvent("some_event", "", map[string]any{
		"plan": "premium",
		"ip": "0",
	}),
})
```

## Release History

[See all releases.](https://github.com/mixpanel/mixpanel-go/releases)


# Implement Feature Flags (Go)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/go/go-flags



## Overview

This developer guide will assist you in configuring your server-side Go platform for [Feature Flags](/docs/featureflags) using the [Mixpanel Go SDK](/docs/tracking-methods/sdks/go). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

## Prerequisites

Before implementing [Feature Flags](/docs/featureflags), ensure:

* You are on an Enterprise subscription plan and have the [Mixpanel Go SDK](https://github.com/mixpanel/mixpanel-go) installed. If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK. The minimum supported version is [`v2.0.0`](https://github.com/mixpanel/mixpanel-go/releases/tag/v2.0.0)

```bash theme={"system"}
go get github.com/mixpanel/mixpanel-go@v2.0.0
```

* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Flag Evaluation Scenarios

There are two scenarios available for using the Go SDK for feature flagging: Local Evaluation and Remote Evaluation.

For local evaluation, the SDK will poll Mixpanel servers for feature flag configurations. Assignment of user contexts to variants will be done locally within the SDK. This mode is recommended for low latency since there is no network call made at assignment time.

For remote evaluation, the SDK will make a network call to Mixpanel servers at assignment time. This mode is recommended for use cases where you want to leverage Mixpanel cohorts for user targeting or sticky variants for persistent variant assignments.

In either case there is also the capability to evaluate all flags for a given user context at once, to avoid needing to make multiple calls to get individual flag variants for the same user. This is particularly useful for remote evaluation to avoid incurring additional network calls.

## Local Evaluation

<Warning>
  Targeting by Mixpanel cohorts and sticky variants are not supported in Local Evaluation mode.
</Warning>

* The SDK is configured with a `flags.LocalFlagsConfig` struct that specifies parameters:

  1. `APIHost` - If your project is in the EU/IN region, this should be set to route to `api-eu.mixpanel.com`/`api-in.mixpanel.com` respectively.
  2. `EnablePolling` - This should be set to `true` to enable polling for new flag configurations.
  3. `PollingInterval` - This is the interval (`time.Duration`) at which the SDK will poll Mixpanel servers for feature flag configurations.
* The SDK will continue to poll for the lifetime of the SDK instance or until stopped.

```go theme={"system"}
package main

import (
	"context"
	"time"

	mixpanel "github.com/mixpanel/mixpanel-go"
	"github.com/mixpanel/mixpanel-go/flags"
)

func main() {
	localConfig := flags.LocalFlagsConfig{
		FlagsConfig: flags.FlagsConfig{
			APIHost: "api.mixpanel.com",
		},
		EnablePolling:   true,
		PollingInterval: 60 * time.Second,
	}

	mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN", mixpanel.WithLocalFlags(localConfig))

	ctx := context.Background()

	// If EnablePolling is set to false, this will fetch definitions only once for the lifetime of the SDK.
	mp.LocalFlags.StartPollingForDefinitions(ctx)

	// This should be the 'key' of the feature flag from Mixpanel's UX.
	flagKey := "sample-flag"

	// This is the fallback variant to return if the user context is not in a rollout group for the flag.
	fallbackValue := "control"

	// Current user context for evaluation.
	// At minimum, this needs to include the user's distinct_id.
	// If any of your feature flags use a Variant Assignment Key other than 'distinct_id', this should also include those keys for evaluation. For example, 'company_id' below
	// If any of your feature flags use Runtime targeting, this should also include 'custom_properties' for evaluation
	userContext := flags.FlagContext{
		"distinct_id": "1234",
		"company_id":  "X",
		"custom_properties": map[string]any{
			"platform": "go",
		},
	}

	// Gets the assigned variant for the flag for the given user context.
	// This will return the fallbackValue if the user context is not in an assignment group for the flag.
	variantValue, err := mp.LocalFlags.GetVariantValue(ctx, flagKey, fallbackValue, userContext)

	// Check if a feature is enabled (returns boolean)
	isEnabled, err := mp.LocalFlags.IsEnabled(ctx, "new_feature", userContext)
}
```

## Remote Evaluation

* The SDK is configured with a `flags.RemoteFlagsConfig` struct to use remote evaluation.

### Get a specific variant

```go theme={"system"}
package main

import (
	"context"

	mixpanel "github.com/mixpanel/mixpanel-go"
	"github.com/mixpanel/mixpanel-go/flags"
)

func main() {
	remoteConfig := flags.RemoteFlagsConfig{
		FlagsConfig: flags.FlagsConfig{
			APIHost: "api.mixpanel.com",
		},
	}

	mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN", mixpanel.WithRemoteFlags(remoteConfig, mixpanel.DefaultFlagsExposureTracker))

	ctx := context.Background()

	// GetVariantValue usage is the same as for local evaluation, but will make a network call to Mixpanel servers at assignment time.
	variantValue, err := mp.RemoteFlags.GetVariantValue(ctx, flagKey, fallbackValue, userContext)

	// IsEnabled also works with remote flags
	isEnabled, err := mp.RemoteFlags.IsEnabled(ctx, "beta_feature", userContext)
}
```

### Evaluate all flags at once

Below is a remote evaluation sample of evaluating all flags for a given user context at once.

```go theme={"system"}
package main

import (
	"context"

	mixpanel "github.com/mixpanel/mixpanel-go"
	"github.com/mixpanel/mixpanel-go/flags"
)

func main() {
	userContext := flags.FlagContext{
		"distinct_id": "1234",
	}

	remoteConfig := flags.RemoteFlagsConfig{
		FlagsConfig: flags.FlagsConfig{
			APIHost: "api.mixpanel.com",
		},
	}

	mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN", mixpanel.WithRemoteFlags(remoteConfig, mixpanel.DefaultFlagsExposureTracker))

	ctx := context.Background()

	// Returns a map, mapping flag keys to assigned variants ONLY for flags that the user context is in an assignment group for.
	// By default, this will not track an exposure event.
	variants, err := mp.RemoteFlags.GetAllVariants(ctx, userContext)

	// Given a flag key and the selected variant for that key, manually track an exposure event for a given flag and assigned variant, after exposing the user to the variant
	mp.RemoteFlags.TrackExposureEvent(ctx, flagKey, selectedVariant, userContext)
}
```

## Custom Exposure Tracking

By default, the SDK sends exposure events synchronously via `DefaultFlagsExposureTracker`. You can provide a custom `TrackerBuilder` — a function that receives the `*ApiClient` and returns a `flags.Tracker` — to control how exposure events are sent.

### Asynchronous tracker

For example, to avoid blocking on exposure event delivery, you could wrap the tracking call in a goroutine like shown below. If desired, you could implement controls around how many active go routines can be in flight at once.

```go theme={"system"}
package main

import (
	"context"

	mixpanel "github.com/mixpanel/mixpanel-go"
	"github.com/mixpanel/mixpanel-go/flags"
)

func asyncTracker(client *mixpanel.ApiClient) flags.Tracker {
	return func(distinctID string, eventName string, props map[string]any) {
		go func() {
			event := client.NewEvent(eventName, distinctID, props)
			_ = client.Track(context.Background(), []*mixpanel.Event{event})
		}()
	}
}

func main() {
	localConfig := flags.LocalFlagsConfig{
		FlagsConfig: flags.FlagsConfig{
			APIHost: "api.mixpanel.com",
		},
		EnablePolling:   true,
		PollingInterval: 60 * time.Second,
	}
	mp = mixpanel.NewApiClient("YOUR_PROJECT_TOKEN", mixpanel.WithLocalFlagsAndTracker(localConfig, asyncTracker))
}
```


# OpenFeature Provider (Go)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/go/go-openfeature



## Overview

This guide covers using Mixpanel's [Feature Flags](/docs/featureflags) through the [OpenFeature](https://openfeature.dev/) standard with the Mixpanel Go OpenFeature provider. OpenFeature provides a vendor-agnostic API for feature flag evaluation, allowing you to switch between providers without changing your application code.

For the native Mixpanel SDK approach, see the [Feature Flags (Go)](/docs/tracking-methods/sdks/go/go-flags) guide.

## Prerequisites

* Enterprise subscription plan with Feature Flags enabled
* Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Installation

```bash theme={"system"}
go get github.com/mixpanel/mixpanel-go/openfeature
go get github.com/open-feature/go-sdk
```

## Quick Start

```go theme={"system"}
package main

import (
    "context"
    "fmt"

    mixpanelopenfeature "github.com/mixpanel/mixpanel-go/openfeature"
    "github.com/mixpanel/mixpanel-go/v2/flags"
    of "github.com/open-feature/go-sdk/openfeature"
)

func main() {
    // 1. Create the Mixpanel OpenFeature provider with local evaluation
    provider, err := mixpanelopenfeature.NewProviderWithLocalConfig("YOUR_PROJECT_TOKEN", flags.LocalFlagsConfig{})
    if err != nil {
        panic(err)
    }

    // 2. Register the provider with OpenFeature
    of.SetProvider(provider)
    client := of.NewClient("my-app")

    // 3. Evaluate flags
    showNewFeature, _ := client.BooleanValue(context.Background(), "new-feature-flag", false, of.EvaluationContext{})

    if showNewFeature {
        fmt.Println("New feature is enabled!")
    }
}
```

## Initialization

### Local Evaluation (Recommended)

Flag definitions are fetched from Mixpanel and evaluated locally. This is faster and works offline after the initial fetch.

<Warning>
  Targeting by Mixpanel cohorts and sticky variants are not supported in Local Evaluation mode.
</Warning>

```go theme={"system"}
provider, err := mixpanelopenfeature.NewProviderWithLocalConfig("YOUR_PROJECT_TOKEN", flags.LocalFlagsConfig{})
```

### Remote Evaluation

Each flag evaluation makes a request to Mixpanel's servers.

```go theme={"system"}
provider, err := mixpanelopenfeature.NewProviderWithRemoteConfig("YOUR_PROJECT_TOKEN", flags.RemoteFlagsConfig{})
```

### Using an Existing Mixpanel Instance

```go theme={"system"}
mp := mixpanel.NewApiClient("YOUR_TOKEN", mixpanel.WithLocalFlags(flags.LocalFlagsConfig{}))
mp.LocalFlags.StartPollingForDefinitions(context.Background())

provider, err := mixpanelopenfeature.NewProvider(mp.LocalFlags)
```

## Usage

### Flag Types and Evaluation Methods

| Mixpanel Flag Type | Variant Values                          | OpenFeature Method                                                                  |
| ------------------ | --------------------------------------- | ----------------------------------------------------------------------------------- |
| Feature Gate       | `true` / `false`                        | `BooleanValue()`                                                                    |
| Experiment         | boolean, string, number, or JSON object | `BooleanValue()`, `StringValue()`, `FloatValue()`, `IntValue()`, or `ObjectValue()` |
| Dynamic Config     | JSON object                             | `ObjectValue()`                                                                     |

```go theme={"system"}
ctx := context.Background()
evalCtx := of.EvaluationContext{}

// Feature Gate
enabled, _ := client.BooleanValue(ctx, "new-checkout", false, evalCtx)

// Experiment with string variants
buttonColor, _ := client.StringValue(ctx, "button-color-test", "blue", evalCtx)

// Numeric flags
threshold, _ := client.FloatValue(ctx, "score-threshold", 0.5, evalCtx)
maxItems, _ := client.IntValue(ctx, "max-items", 10, evalCtx)

// Dynamic Config
config, _ := client.ObjectValue(ctx, "homepage-layout", map[string]any{
    "layout": "grid",
}, evalCtx)
```

### Evaluation Context

```go theme={"system"}
evalCtx := of.NewEvaluationContext("user-123", map[string]any{
    "email": "user@example.com",
    "plan":  "premium",
})

enabled, _ := client.BooleanValue(ctx, "premium-feature", false, evalCtx)
```

<Note>
  Unlike some providers, `targetingKey` is not used as a special bucketing key. It is passed as another context property. Mixpanel's server-side configuration determines which properties are used for targeting and bucketing.
</Note>

### Full Resolution Details

```go theme={"system"}
details, _ := client.BooleanValueDetails(ctx, "my-feature", false, of.EvaluationContext{})

fmt.Println(details.Value)
fmt.Println(details.Variant)
fmt.Println(details.Reason)
fmt.Println(details.ErrorCode)
```

### Accessing the Underlying Mixpanel Client

```go theme={"system"}
provider, _ := mixpanelopenfeature.NewProviderWithLocalConfig("YOUR_TOKEN", flags.LocalFlagsConfig{})

provider.Mixpanel.Track(ctx, []*mixpanel.Event{
    {Name: "button_clicked", Properties: map[string]any{"color": "blue"}},
})
```

### Shutdown

```go theme={"system"}
provider.Shutdown()
```

## Error Handling

| Error Code           | When                                                                        |
| -------------------- | --------------------------------------------------------------------------- |
| `PROVIDER_NOT_READY` | Flags evaluated before the local provider has finished fetching definitions |
| `FLAG_NOT_FOUND`     | The requested flag does not exist in Mixpanel                               |
| `TYPE_MISMATCH`      | The flag value type does not match the requested type                       |

## Troubleshooting

### Flags Always Return Default Values

1. **Provider not ready:** Ensure polling has started and definitions have been received.
2. **Flag not configured:** Verify the flag exists and is enabled in your Mixpanel project.
3. **Network issues:** For remote evaluation, check that your application can reach Mixpanel's API.

### Type Mismatch Errors

The flag's value type must match the evaluation method. `IntValue()` accepts whole-number `float64` values. `FloatValue()` accepts any numeric type.


# Mixpanel SDKs: iOS (Objective-C) - Deprecated
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/ios



<Warning>
  **Deprecated:** This SDK is deprecated and will not receive new features. We recommend using the [Swift SDK](/docs/tracking-methods/sdks/swift) for all new projects and migrations.
</Warning>

## Getting Started

Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=ios).

The [Full API Reference](https://mixpanel.github.io/mixpanel-iphone/index.html), [Library Source Code](https://github.com/mixpanel/mixpanel-iphone/), and an [Example Application](https://github.com/mixpanel/mixpanel-iphone/tree/master/HelloMixpanel) is documented in our GitHub repo.

## Installing the Library

You can install the Objective-C library by using CocoaPods, Carthage, or Swift Package Manager.

<Tabs>
  <Tab title="CocoaPods">
    1. Install CocoaPods by typing the following in your command line:

    ```bash theme={"system"}
    # install CocoaPods
    gem install cocoapods
    ```

    2. After install CocoaPods, create a local CocoaPods spec mirror by running the following:

    ```bash theme={"system"}
    # Create CocoaPods spec mirror
    pod setup
    ```

    3. Then navigate to your Xcode project directory and create a Podfile by running the following:

    ```bash theme={"system"}
    # create Podfile in project directory
    pod init
    ```

    4. Open the Podfile that was generated and add the Mixpanel library to your dependencies:

    ```ruby Ruby theme={"system"}
    # add Mixpanel library to dependencies
    target 'MyApp' do
      pod 'Mixpanel'
    end
    ```

    5. Install the Mixpanel library and create a new Xcode workspace by running the following in the Xcode project directory:

    ```bash theme={"system"}
    # install library in your dependencies
    pod install
    ```
  </Tab>

  <Tab title="Carthage">
    Mixpanel supports [Carthage](https://github.com/Carthage/Carthage#quick-start) to package your dependencies as a framework. Include the following dependency in your Cartfile:

    ```bash theme={"system"}
    # add Mixpanel library to your dependencies
    github "mixpanel/mixpanel-iphone"
    ```
  </Tab>

  <Tab title="Swift Package Manager">
    1. In Xcode, select File > Add Packages...
    2. Enter the package URL for [this repository](https://github.com/mixpanel/mixpanel-iphone) and select version v4.0.0 or above.
  </Tab>
</Tabs>

After installing the library, import the library into `AppDelegate.m` and create an instance of Mixpanel using [`sharedInstanceWithToken:`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/sharedInstanceWithToken:) with your project token inside [`application:didFinishLaunchingWithOptions:`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate#//apple_ref/occ/intfm/UIApplicationDelegate/application:willFinishLaunchingWithOptions:).

```objc Objective-C theme={"system"}
//import library to AppDelegate
#import "Mixpanel/Mixpanel.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
...
  //create Mixpanel instance
  [Mixpanel sharedInstanceWithToken:@"YOUR_PROJECT_TOKEN" trackAutomaticEvents:NO];
...
}
```

After you create the Mixpanel instance with your project token, you can return to the instance by calling [`sharedInstance`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/sharedInstance).

```objc Objective-C theme={"system"}
// Returns to a previously initialized Mixpanel instance
Mixpanel *mixpanel = [Mixpanel sharedInstance];
```

### Library Configuration

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/ios#privacy-friendly-tracking).
</Warning>

The library can be initialized with different configurations. See a complete list of the configuration options [here](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/sharedInstanceWithToken:).

**Example Usage**

```objc Objective-C theme={"system"}
//import library to AppDelegate
#import "Mixpanel/Mixpanel.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
...
  //create Mixpanel instance with trackCrashes enabled
  [Mixpanel sharedInstanceWithToken:@"YOUR_PROJECT_TOKEN" trackAutomaticEvents:NO trackCrashes:YES];
...
}
```

## Sending Events

Use [`track:properties:`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/track:properties:) to send an event by providing the event name and any event properties. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```objc Objective-C theme={"system"}
// send "some_event"
// with "Plan" event prop set to "Premium"
Mixpanel *mixpanel = [Mixpanel sharedInstance];
[mixpanel track:@"some_event"
     properties:@{ @"Plan": @"Premium" }];
```

### Timing Events

You can track the time it took for an action to occur, such as an image upload or a comment post, using [`timeEvent:`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/timeEvent:). This will mark the "start" of your action, which you can then finish with a track call. The time duration is then recorded in the "Duration" property.

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

// start the timer for the event "Image Upload"
[mixpanel timeEvent:@"Image Upload"];

// 20 seconds later...

[self uploadImageWithSuccessHandler:^{
    // track "Image Upload" event with "Duration" event prop set to 20
    [mixpanel track:@"Image Upload"];
}];
```

### Flushing Events

To preserve battery life and customer bandwidth, the Mixpanel library doesn't send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background.

Call [`flush`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/flush) manually if you want to force a flush at a particular moment.

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

// flush batched events for ingestion immediately
[mixpanel flush];
```

**Flush Interval**

You can update the default flush interval from 60 seconds to another interval using [`flushInterval`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/flushInterval).

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

//set the flush interval to every 120 seconds
[Mixpanel sharedInstance].flushInterval = 120;
```

#### Importing Historical Events

The Objective-C SDK is a tracking SDK designed for real-time tracking in a client-side environment. Calling `track:properties:` triggers a request to our [/track API endpoint](/reference/track-event), which will validate for events with a timestamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested**.

For bulk import of historical events older than 5 days, we will need to use the [/import API endpoint](/reference/import-events) which is optimized for scripting and supports ingesting historical data. We recommend the [Python SDK](/docs/tracking-methods/sdks/python) (see the [`.import_data()`](https://mixpanel.github.io/mixpanel-python/#primary-interface) function) and [mixpanel-utils module](https://github.com/mixpanel/mixpanel-utils) (see the [`import_events()`](https://github.com/mixpanel/mixpanel-utils?tab=readme-ov-file#import-events) function) which both leverages the /import API for event ingestion.

## Setting Super Properties

Super properties are global event properties that you define once and apply to all events.

To register super properties, call [`registerSuperProperties:`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/registerSuperProperties:)

Use [`registerSuperPropertiesOnce:`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/registerSuperPropertiesOnce:) to register super properties without overwriting existing values.

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

// register "name" as a super property
[mixpanel registerSuperProperties:@{@"Name": @"Sam"}];

// track "some_event"
// "Name" event prop is included in the event
[mixpanel track:@"some_event"];

// ignored since "name" already exists
[mixpanel registerSuperPropertiesOnce:@{@"Name": @"Samantha"}];
```

Our mobile libraries store your super properties in local storage. They will persist so long as the app is installed (between launches and updates). Uninstalling the app will remove that customers super properties.

See more methods related to super properties in the complete library reference [here](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#).

## Managing User Identity

You can handle the identity of a user using the [`identify:`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/identify:) and [`reset`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/reset) methods. Learn more about [identity management](/docs/tracking-methods/id-management/identity-management) and [identifying users](/docs/tracking-methods/id-management/identifying-users).

### Identify

<Warning>
  We recommend against calling `.identify()` for anonymous visitors to your site.
</Warning>

Call [`identify:`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/identify:) when you know the identity of the current user, passing in their user ID as an argument. This is typically at account registration and at log in.

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

// your user signs in and tracks a sign in event
[mixpanel track:@"sign in"];

// upon sign in, identify the user with their ID
// ensure future events sent from the user have distinct_id 12345
[mixpanel identify:@"12345"];
```

### Call Reset at Logout

Call [`reset`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/reset) to clear data attributed to a user when they logout. This will clear the local storage and allows you to handle [multiple users on a single device](/docs/tracking-methods/id-management/identifying-users-simplified#multiple-users-one-device).

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

// your user signs out and tracks a log out event
[mixpanel track:@"log out"];

// upon logout, call reset to clear local storage
// new distinct_id is generated for events moving forward
[mixpanel reset];
```

<Note>
  Since v3.6.2, Mixpanel stopped using the IFA(ID for Advertisers) as a distinct\_id, meaning calls to reset will generate a new random UUID.

  If you want to use IFV(identifierForVendor) as the distinct\_id, you can set `MIXPANEL_UNIQUE_DISTINCT_ID=1` in build settings `Preprocessor Macros` on the Mixpanel framework target. The IFV will not change when you call `reset`, but will change upon app uninstalls/reinstalls.
</Note>

## Storing User Profiles

Once your users are identified, create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Objective-C SDK provides a few methods for setting profile properties under [`MixpanelPeople`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelPeople.html) accessible via [`.people`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/people). These methods will trigger requests to the [/engage API endpoint](/reference/profile-set).

### Setting Profile Properties

<Note>
  You must call `identify:` before setting profile properties in order to associate the profile properties you set with the target user. If identify is not called, the profile update will be queued for ingestion until an identify call is made.
</Note>

You can set properties on a user profile with [`.people set:`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelPeople.html#//api/name/set:).

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

// You must call identify to associate the profile update with the user
[mixpanel identify:@"12345"];

// Set user's "Plan" profile prop to "Premium"
[mixpanel.people set:@{@"Plan": @"Premium"}];

// Overwrite user's "Plan" profile prop to "Enterprise"
[mixpanel.people set:@{@"Plan": @"Enterprise"}];
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelPeople.html)

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title="setOnce:">
    The [`.people setOnce:`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelPeople.html#//api/name/setOnce:) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```objc Objective-C theme={"system"}
    Mixpanel *mixpanel = [Mixpanel sharedInstance];

    // set profile properties for user "12345"
    [mixpanel identify:@"12345"];
    [mixpanel.people set:@{@"name": @"Sam"}];

    // will be ignored since "name" already exists
    [mixpanel.people setOnce:@{@"name": @"Samantha"}];

    // set "location" property since it does not exist
    [mixpanel.people setOnce:@{@"location": @"global"}];
    ```
  </Tab>

  <Tab title="append:">
    The [`.people append:`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelPeople.html#//api/name/append:) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```objc Objective-C theme={"system"}
    Mixpanel *mixpanel = [Mixpanel sharedInstance];

    // set profile properties for user "12345"
    [mixpanel identify:@"12345"];
    [mixpanel.people set:@{
      @"roles": @[@"sales",@"engineer"]
      }];

    // add "legal" to "roles"
    [mixpanel.people append:@{
      @"roles": @"legal"
    }];

    // new "roles" values are ['sales','engineer','legal']
    ```
  </Tab>

  <Tab title="union:">
    The [`.people union:`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelPeople.html#//api/name/union:) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```objc Objective-C theme={"system"}
    Mixpanel *mixpanel = [Mixpanel sharedInstance];

    // set profile properties for user "12345"
    [mixpanel identify:@"12345"];
    [mixpanel.people set:@{
      @"roles": @[@"sales",@"engineer"]
      }];

    // will be ignored since "engineer" already exists in "roles"
    [mixpanel.people union:@{
      @"roles": @"engineer"
    }];
    // "roles" = ['sales','engineer']

    // add "engineer" to "roles"
    // append: allows duplicates
    [mixpanel.people append:@{
      @"roles": @"engineer"
    }];
    // "roles" = ['sales','engineer','engineer']

    ```
  </Tab>

  <Tab title="increment:by">
    The [`.people increment:by`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelPeople.html#//api/name/increment:by:) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```objc Objective-C theme={"system"}
    Mixpanel *mixpanel = [Mixpanel sharedInstance];

    // set profile properties for user "12345"
    [mixpanel identify:@"12345"];
    [mixpanel.people set:@{
      @"age": @25
      }];

    // increment "age" by 2
    [mixpanel.people increment:@"age" by:@2];

    // use negative number to decrement
    //decrement "age" by 5
    [mixpanel.people increment:@"age" by:@-5];
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

The Objective-C SDK provides a few method for adding individual users to a group and setting group profile properties.

### Adding Users to a Group

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

Call the [`setGroup:groupID:`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/setGroup:groupID:) to register the current user to a group, which would add the `group_key` as an event property set to the `group_id` value to all events moving forward.

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

// assign the current user to the "mixpanel" company group
[mixpanel setGroup:@"company" groupID:@"mixpanel"];

// track "some_event"
// event property "company" = "mixpanel" is added automatically
[mixpanel track:@"some_event"];

// alternatively you can define the group key manually
[mixpanel track:@"some_event"
      properties:@{@"company": @"mixpanel"}];
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

Call [`setGroup:groupIDs:`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/setGroup:groupIDs:) to add additional `group_id`s to an existing list.

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

// assign the current user to the "mixpanel" company group
// events will contain 'company' prop set to ["mixpanel"]
[mixpanel setGroup:@"company" groupIDs:@"mixpanel"];

// add "mp-us" as an additional company group
// new "company" value is ["mixpanel","mp-us"]
[mixpanel setGroup:@"company" groupIDs:@["mp-us"]];

// track "some_event"
// event property "company" = ["mixpanel","mp-us"] is added automatically
[mixpanel track:@"some_event"];
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `set` call.

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

// You must call identify to associate the profile update with the user
[mixpanel identify:@"12345"];

// Set group key "company" as user prop
// with group id "mixpanel" as value
[mixpanel.people set:@{@"company": @"mixpanel"}];
```

### Setting Group Profile Properties

Create a group profiles by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

To set group profile properties, specify the group that needs to be updated by calling [`getGroup:groupID`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/getGroup:groupID:), then set the group properties by chaining the [`set:`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelGroup.html#//api/name/set:) method, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

// assign the current user to the "mixpanel" company group
[mixpanel setGroup:@"company" groupIDs:@"mixpanel"];

// specify the target group using the group_key and group_id using getGroup:
// set "industry" as a group profile prop to "analytics" using set:
[[mixpanel getGroup:@"company", groupID:@"mixpanel"] set:@{
        @"industry": @"analytics"}];
```

### Other Group Profile Methods

See all of the methods under the MixpanelGroup class [here](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelGroup.html).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title="setOnce:">
    The [`getGroup:groupID setOnce:`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelGroup.html#//api/name/setOnce:) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```objc Objective-C theme={"system"}
    Mixpanel *mixpanel = [Mixpanel sharedInstance];

    // assign the current user to the "mixpanel" company group
    [mixpanel setGroup:@"company" groupIDs:@"mixpanel"];

    // set group profile properties
    [[mixpanel getGroup:@"company" groupID:@"mixpanel"] set:@{
      @"name": @"Mixpanel"
      }];

    // ignored since "name" is already exists
    [[mixpanel getGroup:@"company" groupID:@"mixpanel"] setOnce:@{
          @"name": @"mp"}];

    // set "country" group prop since it does not exist
    [[mixpanel getGroup:@"company" groupID:@"mixpanel"] setOnce:@{
          @"country": @"us"}];

    ```
  </Tab>

  <Tab title="unset:">
    The [`getGroup:groupID unset:`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelGroup.html#//api/name/unset:) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```objc Objective-C theme={"system"}
    Mixpanel *mixpanel = [Mixpanel sharedInstance];

    // assign the current user to the "mixpanel" company group
    [mixpanel setGroup:@"company" groupIDs:@"mixpanel"];

    // set group profile properties
    [[mixpanel getGroup:@"company" groupID:@"mixpanel"] set:@{
      @"name": @"Mixpanel",
      @"employee_count": @100
      }];

    // delete "employee_count" from the group profile
    [[mixpanel getGroup:@"company" groupID:@"mixpanel"] unset:@"employee_count"];

    // The group only has the "name" property remaining
    ```
  </Tab>

  <Tab title="union:values:">
    The [`getGroup:groupID union:values:`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelGroup.html#//api/name/union:values:) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```objc Objective-C theme={"system"}
    Mixpanel *mixpanel = [Mixpanel sharedInstance];

    // assign the current user to the "mixpanel" company group
    [mixpanel setGroup:@"company" groupIDs:@"mixpanel"];

    // set group profile properties
    [[mixpanel getGroup:@"company" groupID:@"mixpanel"] set:@{
      @"name": @"Mixpanel",
      @"features": @[@"reports",@"alerts",@"cohorts"],
      }];

    // add "data pipeline" to "features" prop
    // ignore "alert" since it is a duplicate value
    [[mixpanel getGroup:@"company" groupID:@"mixpanel"] union: @"features"
          values: @[@"data pipeline",@"alert"]];
    ```
  </Tab>

  <Tab title="remove:value:">
    The [`getGroup:groupID remove:value:`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelGroup.html#//api/name/remove:value:) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```objc Objective-C theme={"system"}
    Mixpanel *mixpanel = [Mixpanel sharedInstance];

    // assign the current user to the "mixpanel" company group
    [mixpanel setGroup:@"company" groupIDs:@"mixpanel"];

    // set group profile properties
    [[mixpanel getGroup:@"company" groupID:@"mixpanel"] set:@{
      @"name": @"Mixpanel",
      @"features": @[@"reports",@"alerts",@"cohorts"],
      }];

    //remove "alert" from "features"
    [[mixpanel getGroup:@"company" groupID:@"mixpanel"] remove: @"features" 
          value: @"alert"];

    // "features" = ["reports","cohorts"]
    ```
  </Tab>
</Tabs>

## Debug Mode

Enable debug mode by setting the [`enableLogging`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/enableLogging) flag to `YES`.

**Example Usage**

```objc Objective-C theme={"system"}
// enable debug logging
[Mixpanel sharedInstance].enableLogging = YES;
```

Alternatively, you can add the following Preprocessor Macros in Build Settings:

* `MIXPANEL_DEBUG=1` - logs queueing and flushing of events to Mixpanel
* `MIXPANEL_ERROR=1` - logs any errors related to connections or malformed events

If you're using CocoaPods, you'll need to add this to the Pod target instead of your main app project's target:

<Frame>
  <img alt="image" />
</Frame>

You can also add this to your Podfile to ensure everyone on your team will always have logging enabled:

```ruby Ruby theme={"system"}
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      settings = config.build_settings['GCC_PREPROCESSOR_DEFINITIONS']
      settings = ['$(inherited)'] if settings.nil?

      if target.name == 'Pods-MyProject-Mixpanel'
        settings << 'MIXPANEL_DEBUG=1'
        settings << 'MIXPANEL_ERROR=1'
      end

      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] = settings
    end
  end
end
```

Learn more about [debugging](/docs/tracking-best-practices/debugging).

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Objective-C SDK provide methods to help you protect user data.

Learn more about [Privacy](/docs/privacy/overview).

### Opt Out of Tracking

The Objective-C SDK is initialized with tracking enabled by default. Use the [`optOutTracking`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/optOutTracking) method to opt the user out of data tracking and local storage for the current Mixpanel instance.

**Example Usage**

```objc Objective-C theme={"system"}
Mixpanel *mixpanel = [Mixpanel sharedInstance];

//send "some_event"
[mixpanel track:@"some_event"];

// opt user out of tracking
// SDK is prevented from sending any data
[mixpanel optOutTracking];

// this track call will not work
[mixpanel track:@"some_event"];
```

**Opt Out by Default**

You can initialize the library with users opted out of tracking by default using the [`optOutTrackingDefault`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/sharedInstanceWithToken:trackAutomaticEvents:optOutTrackingByDefault:) configuration. Once the user is ready to be tracked, call [`optInTracking`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/optInTracking) to start tracking.

**Example Usage**

```objc Objective-C theme={"system"}
// create Mixpanel instance with users opt out of tracking by default
// SDK is prevented from sending data
Mixpanel *mixpanel = [Mixpanel sharedInstanceWithToken:@"YOUR_PROJECT_TOKEN" 
        trackAutomaticEvents:NO optOutTrackingByDefault:YES];

// this track call will not work
[mixpanel track:@"some_event"];

//opt user into tracking
[mixpanel optInTracking];

// send "some_event"
[mixpanel track:@"some_event"];
```

### EU Data Residency

Route data to Mixpanel's EU servers by setting the `serverURL` flag after initializing the Mixpanel instance.

```objc Objective-C theme={"system"}
// set request URL to Mixpanel's EU domain
Mixpanel *mixpanel = [Mixpanel sharedInstance];
self.mixpanel.serverURL = @"https://api-eu.mixpanel.com";
```

### India Data Residency

Route data to Mixpanel's India servers by setting the `serverURL` flag after initializing the Mixpanel instance.

```objc Objective-C theme={"system"}
// set request URL to Mixpanel's India domain
Mixpanel *mixpanel = [Mixpanel sharedInstance];
self.mixpanel.serverURL = @"https://api-in.mixpanel.com";
```

### Disable Geolocation

The Objective-C SDK parse the request IP address to generate geolocation properties for events and profiles. To disable geolocation, set the [`useIPAddressForGeoLocation`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/useIPAddressForGeoLocation) flag to `NO`.

**Example Usage**

```objc Objective-C theme={"system"}
// disable geolocation
[Mixpanel sharedInstance].useIPAddressForGeoLocation = NO;
```

## Legacy Automatically Tracked Events

Mixpanel's mobile SDKs have a legacy feature to automatically collect common mobile events. We don't recommend enabling this, as these events rely on client-side state and can be unreliable.

Ensure autotracked mobile events are disabled by setting `trackAutomaticEvents` to `NO` during initialization.

**Example Usage**

```objc Objective-C theme={"system"}
//initialize Mixpanel with autotrack disabled
[Mixpanel sharedInstanceWithToken:@"YOUR_PROJECT_TOKEN" trackAutomaticEvents:NO];
```

| Raw Name          | Display Name          | Description                                                                                                                                                                                                                                                                                                                                           |
| ----------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \$ae\_first\_open | First App Open        | Tracks the first time the user has opened the app. This event is retriggered if the user reinstalls the app or clears local storage. A user property First App Open Date (`$ae_first_app_open_date`) is tracked to indicate the date when app was first opened.                                                                                       |
| \$ae\_updated     | App Updated           | Executes when a user updates the app from the previous version. A Version Updated (`$ae_updated_version`) property is tracked to store the new app version.                                                                                                                                                                                           |
| \$ae\_crashed     | App Crashed           | Executes when Mixpanel receives either an exception or a signal that indicated the app has crashed. A Crash Reason (`$ae_crashed_reason`) property is tracked to help identify the type of crash.                                                                                                                                                     |
| \$ae\_session     | App Session           | Executes when a user spends more than 10 seconds in the app. A Session Length (`$ae_session_length`) property is tracked to reflect the number of seconds user spent in the session. In addition, there are two user properties tracked: Total App Sessions (`$ae_total_app_sessions`) and Total App Session Length (`$ae_total_app_session_length`). |
| \$ae\_iap         | In App Purchase (IAP) | Executes when a user conducts an in-app purchase through your app. Mixpanel provides three properties for this event: Product Name (`$ae_iap_name`), Product Quantity (`$ae_iap_quantity`), and Product Price (`$ae_iap_price`).                                                                                                                      |

## Release History

[See All Releases](https://github.com/mixpanel/mixpanel-iphone/releases).


# Mixpanel SDKs: Java
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/java/index



## Getting Started

The Mixpanel Java library is useful for tracking events from Java servers.

The [Full API Reference](http://mixpanel.github.io/mixpanel-java/), [Library Source Code](https://github.com/mixpanel/mixpanel-java) and an [Example Application](https://github.com/mixpanel/mixpanel-java/blob/master/src/demo/java/com/mixpanel/mixpanelapi/demo/MixpanelAPIDemo.java) is documented in our GitHub repo.

## Installing the Library

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/java#privacy-friendly-tracking).
</Warning>

To install the library, declare it as a dependency in your project's `pom.xml` file:

```xml theme={"system"}
<dependency>
    <groupId>com.mixpanel</groupId>
    <artifactId>mixpanel-java</artifactId>
    <version>1.5.2</version>
</dependency>
```

<Note>
  If you're not using Maven to build your project, you can browse and download the library jar directly from [Maven central](http://search.maven.org/#search%7Cga%7C1%7Cmixpanel-java).
</Note>

To use the library, import the [`MessageBuilder`](http://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html), [`MixpanelAPI`](http://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MixpanelAPI.html), and [`ClientDelivery`](http://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/ClientDelivery.html) classes in to your code.

The library sends data by using `MessageBuilder` to create payload messages, using `ClientDelivery` to bundle the messages, then using `MixpanelAPI` to push the bundles into Mixpanel.

The `MessageBuilder` instance must be initialized with [your project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).

```java theme={"system"}
// import the classes from the library
import com.mixpanel.mixpanelapi.MessageBuilder; // create messages
import com.mixpanel.mixpanelapi.ClientDelivery; // bundle messages
import com.mixpanel.mixpanelapi.MixpanelAPI; // send bundles to Mixpanel

// initialize MessageBuilder class
MessageBuilder messageBuilder =
    new MessageBuilder("YOUR_PROJECT_TOKEN");
```

## Sending Events

To send events, use the [`event()`](http://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#event-java.lang.String-java.lang.String-org.json.JSONObject-) method under the [`MessageBuilder`](http://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html) class to create the event message payload by providing a distinct\_id, event name, and any event properties. The JSONObjects produced by `MessageBuilder` are completely self-contained, and can be sent over a network or enqueued for later processing.

Then bundle the events using `ClientDelivery`, and send them to your project with `MixpanelAPI`. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the events into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```java theme={"system"}
// import library classes
import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.ClientDelivery;
import com.mixpanel.mixpanelapi.MixpanelAPI;

// initialize MessageBuilder with your project token
MessageBuilder messageBuilder =
    new MessageBuilder("YOUR_PROJECT_TOKEN");

// Create an event
JSONObject someEvent =
    messageBuilder.event(distinctId, "some_event", null);

// Create event properties
JSONObject props = new JSONObject();
props.put("Location", "San Francisco");
props.put("Plan", "Premium");

// create an event with event properties
JSONObject otherEvent =
    messageBuilder.event(distinctId, "other_event", props);

// initialize ClientDelivery, and bundle the 2 events above
ClientDelivery delivery = new ClientDelivery();
delivery.addMessage(someEvent);
delivery.addMessage(otherEvent);

// Initialize MixpanelAPI, then use it to send the bundle to your project
MixpanelAPI mixpanel = new MixpanelAPI();
mixpanel.deliver(delivery);
```

Mixpanel determines default geolocation data (`$city`, `$region`, `mp_country_code`) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your data center. [Learn more about best practices for geolocation.](/docs/tracking-best-practices/geolocation).

### Importing Historical Events

The Java SDK is a tracking SDK designed for real-time tracking in a server-side environment. When `MixpanelAPI` detects an event message, it triggers a request to our [/track API endpoint](/reference/track-event) to send the payload to your project, which will validate for events with a timestamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested**.

For bulk import of historical events older than 5 days, we will need to use the [/import API endpoint](/reference/import-events) which is optimized for scripting and supports ingesting historical data. We recommend the [Python SDK](/docs/tracking-methods/sdks/python) (see the [`.import_data()`](https://mixpanel.github.io/mixpanel-python/#primary-interface) function) and [mixpanel-utils module](https://github.com/mixpanel/mixpanel-utils) (see the [`import_events()`](https://github.com/mixpanel/mixpanel-utils?tab=readme-ov-file#import-events) function) which both leverages the /import API for event ingestion.

## Managing User Identity

Since the Java SDK is a server-side library, IDs are not generated by the SDK. Instead, you will need to generate and manage the distinct\_id yourself and include it in your events and profile data.

Learn more about [server-side identity management](/docs/tracking-methods/id-management/identifying-users-simplified#server-side-identity-management).

## Storing User Profiles

Create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Java SDK provides a few methods for setting profile properties, which will trigger requests to the [/engage API endpoint](/reference/profile-set).

Mixpanel determines default geolocation data (`$city`, `$region`, `mp_country_code`) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your data center. [Learn more about best practices for geolocation.](/docs/tracking-best-practices/geolocation).

### Setting Profile Properties

To set profile properties, create a profile update message payload with [`MessageBuilder.set`](http://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#set\(java.lang.String,%20org.json.JSONObject\)). Then send it to your project with [`MixpanelAPI`](http://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MixpanelAPI.html).

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```java theme={"system"}
// import classes from the library
import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;

// initialize MessageBuilder and MixpanelAPI
MessageBuilder messageBuilder =
    new MessageBuilder("YOUR_PROJECT_TOKEN");

MixpanelAPI mixpanel = new MixpanelAPI();

// create profile update message for "sample_distinct_id"
// with "Plan" property and geolocation disabled
JSONObject props = new JSONObject();
props.put("Plan", "Premium");
props.put("$ip", "0"); // do not update profile location
JSONObject newUser = messageBuilder.set("sample_distinct_id", props);

// Send the message to mixpanel
mixpanel.sendMessage(newUser);

// overwrite "Plan" with "deluxe"
JSONObject updateProps = new JSONObject();
updateProps.put("Plan", "deluxe");
updateProps.put("$ip", "0");
JSONObject updateUser = messageBuilder.set("sample_distinct_id", updateProps);
mixpanel.sendMessage(updateUser);
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties by creating different messages using `MessageBuilder`. See a complete reference of the available methods [here](http://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html)

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title="setOnce()">
    The [`MessageBuilder.setOnce()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#setOnce\(org.json.JSONObject\)) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```java Java theme={"system"}
    // import classes from the library
    import com.mixpanel.mixpanelapi.MessageBuilder;
    import com.mixpanel.mixpanelapi.MixpanelAPI;

    // initialize MessageBuilder and MixpanelAPI
    MessageBuilder messageBuilder =
        new MessageBuilder("YOUR_PROJECT_TOKEN");

    MixpanelAPI mixpanel = new MixpanelAPI();

    // create profile update message for "sample_distinct_id"
    JSONObject props = new JSONObject();
    props.put("name", "Sam");
    props.put("$ip", "0"); // do not update profile location
    JSONObject newUser = messageBuilder.set("sample_distinct_id", props);

    // Send the message to mixpanel
    mixpanel.sendMessage(newUser);

    // will be ignored since "name" already exists
    JSONObject updateProps = new JSONObject();
    updateProps.put("name", "Samantha");
    updateProps.put("$ip", "0");
    JSONObject updateUser = messageBuilder.setOnce("sample_distinct_id", updateProps);
    mixpanel.sendMessage(updateUser);
    ```
  </Tab>

  <Tab title="append()">
    The [`MessageBuilder.append()`](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#append-java.lang.String-org.json.JSONObject-) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```java Java theme={"system"}
    // import classes from the library
    import com.mixpanel.mixpanelapi.MessageBuilder;
    import com.mixpanel.mixpanelapi.MixpanelAPI;

    // initialize MessageBuilder and MixpanelAPI
    MessageBuilder messageBuilder =
        new MessageBuilder("YOUR_PROJECT_TOKEN");

    MixpanelAPI mixpanel = new MixpanelAPI();

    // create profile update message for "sample_distinct_id"
    JSONObject props = new JSONObject();
    String[] roles = {"sales", "engineer"};
    props.put("name", "Sam");
    props.put("roles", roles);
    props.put("$ip", "0");
    JSONObject newUser = messageBuilder.set("sample_distinct_id", props);
    mixpanel.sendMessage(newUser);

    // add "legal" to "roles"  
    // new role values are ['sales','engineer','legal']
    JSONObject newProps = new JSONObject();
    newProps.put("roles","legal")
    JSONObject updateUser = messageBuilder.append("sample_distinct_id", newProps);
    mixpanel.sendMessage(updateUser);

    // append allows duplicates
    // new "roles" values are ['sales','engineer','legal', 'legal']
    JSONObject newerProps = new JSONObject();
    newerProps.put("roles","legal")
    JSONObject updateUserAgain = messageBuilder.append("sample_distinct_id", newerProps);
    mixpanel.sendMessage(updateUserAgain);
    ```
  </Tab>

  <Tab title="union()">
    The [`MessageBuilder.union()`](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#union-java.lang.String-java.util.Map-) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```java Java theme={"system"}
    // import classes from the library
    import com.mixpanel.mixpanelapi.MessageBuilder;
    import com.mixpanel.mixpanelapi.MixpanelAPI;

    // initialize MessageBuilder and MixpanelAPI
    MessageBuilder messageBuilder =
        new MessageBuilder("YOUR_PROJECT_TOKEN");

    MixpanelAPI mixpanel = new MixpanelAPI();

    // create profile update message for "sample_distinct_id"
    JSONObject props = new JSONObject();
    String[] roles = {"sales", "engineer"};
    props.put('name', 'Sam');
    props.put('roles', roles);
    JSONObject newUser = messageBuilder.set("sample_distinct_id", props);
    mixpanel.sendMessage(newUser);

    // append "engineer" to "roles"
    // will be ignored since "engineer" already exists in "roles"
    JSONObject newProps = new JSONObject();
    newProps.put("roles","engineer");
    JSONObject updateRoles = messageBuilder.union("sample_distinct_id", newProps);
    mixpanel.sendMessage(updateRoles);

    // append "legal" to "roles"
    // new role values are ['sales','engineer','legal']
    JSONObject newerProps = new JSONObject();
    newerProps.put("roles","legal");
    JSONObject updateRolesAgain = messageBuilder.union("sample_distinct_id", newProps);
    mixpanel.sendMessage(updateRolesAgain);
    ```
  </Tab>

  <Tab title="increment()">
    The [`MessageBuilder.increment()`](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#increment-java.lang.String-java.util.Map-) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```java Java theme={"system"}
    // import classes from the library
    import com.mixpanel.mixpanelapi.MessageBuilder;
    import com.mixpanel.mixpanelapi.MixpanelAPI;

    // initialize MessageBuilder and MixpanelAPI
    MessageBuilder messageBuilder =
        new MessageBuilder("YOUR_PROJECT_TOKEN");

    MixpanelAPI mixpanel = new MixpanelAPI();

    // set profile properties for user "sample_distinct_id"
    JSONObject props = new JSONObject();
    props.put('name', 'Sam');
    props.put('age', 25);
    JSONObject newUser = messageBuilder.set("sample_distinct_id", props);
    mixpanel.sendMessage(newUser);

    // increment "age" by 2
    JSONObject newAge = new JSONObject();
    newAge.put("age", 2);
    JSONObject addAge = messageBuilder.increment("sample_distinct_id", newAge);
    mixpanel.sendMessage(addAge);

    // use negative number to decrement
    // decrement "age" by 5
    JSONObject newerAge = new JSONObject();
    newerAge.put("age", -5);
    JSONObject subtractAge = messageBuilder.increment("sample_distinct_id", newerAge);
    mixpanel.sendMessage(subtractAge);
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

### Sending Group Identifiers With Events

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

To send group identifiers with your events, set the `group_key` as an event property with the `group_id` as the value.

**Example Usage**

```java theme={"system"}
import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanelApi = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("YOUR_PROJECT_TOKEN");
 
// send event with "name" and "company" event props
// event is associated with the "mixpanel" company group
JSONObject props = new JSONObject();
props.put("name", "sam");
props.put("company", "mixpanel")
JSONObject eventPayload =
    messageBuilder.event("sample_distinct_id", "some_event", props);
mixpanel.sendMessage(eventPayload);
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

**Example Usage**

```java theme={"system"}
import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanelApi = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("YOUR_PROJECT_TOKEN");
 
// send event with "name" and "company" event props
// event is associated with the 2 company groups ("mp-eu" and "mp-us")
JSONObject props = new JSONObject();
String[] companies = {"mp-eu", "mp-us"};
props.put("name", "sam");
props.put("company", companies)
JSONObject eventPayload =
    messageBuilder.event("sample_distinct_id", "some_event", props);
mixpanel.sendMessage(eventPayload);
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `.set()` call.

```java theme={"system"}
// import classes from the library
import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;

// initialize MessageBuilder and MixpanelAPI
MessageBuilder messageBuilder =
    new MessageBuilder("YOUR_PROJECT_TOKEN");

MixpanelAPI mixpanel = new MixpanelAPI();

// create profile update message for "sample_distinct_id"
// with group key "company" as user prop and group id "mixpanel" as value
JSONObject props = new JSONObject();
props.put("company", "mixpanel");
props.put("$ip", "0"); // do not update profile location
JSONObject newUser = messageBuilder.set("sample_distinct_id", props);

// Send the message to mixpanel
mixpanel.sendMessage(newUser);
```

### Setting Group Profile Properties

Create a group profile by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

To set group profile properties, use the [`MessageBuilder.groupSet()`](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#groupSet-java.lang.String-java.lang.String-org.json.JSONObject-) function, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```java theme={"system"}
import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("YOUR_PROJECT_TOKEN");
 
// Create a group profile with group_key = "company", group_id = "mixpanel"
// and assign the properties "name" and "industry"
JSONObject groupProperties = new JSONObject();
groupProperties.put("name", "Mixpanel");
groupProperties.put("industry", "analytics");
JSONObject message = messageBuilder.groupSet(
    "company",
    "mixpanel",
    groupProperties
);
mixpanel.sendMessage(message);
```

### Other Group Profile Methods

See all of the group methods under the `MessageBuilder` class [here](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title=".groupSetOnce()">
    The [`MessageBuilder.groupSetOnce()`](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#groupSetOnce-java.lang.String-java.lang.String-org.json.JSONObject-) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```java theme={"system"}
    import com.mixpanel.mixpanelapi.MessageBuilder;
    import com.mixpanel.mixpanelapi.MixpanelAPI;

    MixpanelAPI mixpanel = new MixpanelAPI();
    MessageBuilder messageBuilder = new MessageBuilder("YOUR_PROJECT_TOKEN");

    // Create a group profile with group_key = "company", group_id = "mixpanel"
    JSONObject groupProperties = new JSONObject();
    groupProperties.put("name", "Mixpanel");
    groupProperties.put("industry", "analytics");
    JSONObject message = messageBuilder.groupSet(
        "company",
        "mixpanel",
        groupProperties
    );
    mixpanel.sendMessage(message);

    // will be ignored since "name" already exists
    JSONObject groupProps = new JSONObject();
    groupProps.put("name", "mp-us");
    JSONObject updateMsg = messageBuilder.groupSetOnce(
        "company",
        "mixpanel",
        groupProps
        );
    mixpanel.sendMessage(updateMsg);

    // set location group prop
    JSONObject newGroupProps = new JSONObject();
    newGroupProps.put("location", "us");
    JSONObject newUpdateMsg = messageBuilder.groupSetOnce(
        "company",
        "mixpanel",
        newGroupProps
    );
    mixpanel.sendMessage(newUpdateMsg);

    //
    ```
  </Tab>

  <Tab title=".groupUnset()">
    The [`MessageBuilder.groupUnset()`](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#groupUnset-java.lang.String-java.lang.String-java.util.Collection-) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```java Java theme={"system"}
    import com.mixpanel.mixpanelapi.MessageBuilder;
    import com.mixpanel.mixpanelapi.MixpanelAPI;

    MixpanelAPI mixpanel = new MixpanelAPI();
    MessageBuilder messageBuilder = new MessageBuilder("YOUR_PROJECT_TOKEN");

    // Create a group profile with group_key = "company", group_id = "mixpanel"
    JSONObject groupProperties = new JSONObject();
    groupProperties.put("name", "Mixpanel");
    groupProperties.put("industry", "analytics");
    JSONObject message = messageBuilder.groupSet(
        "company",
        "mixpanel",
        groupProperties
    );
    mixpanel.sendMessage(message);


    // delete "industry" from the group profile
    ArrayList<String> unsetPropNames = new ArrayList<>(
        Arrays.asList("industry")
    );
    JSONObject unsetMsg = messageBuilder.groupUnset(
        "company",
        "mixpanel",
        unsetPropNames
    );
    mixpanel.sendMessage(unsetMsg)

    // only "name" remains as a group prop
    ```
  </Tab>

  <Tab title=".groupUnion()">
    The [`MessageBuilder.groupUnion()`](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#groupUnion-java.lang.String-java.lang.String-java.util.Map-) method append new values to a list property, excluding duplicates.

    Use this method to create a list group profile property that only contains unique values without duplicates.

    **Example Usage**

    ```java Java theme={"system"}
    import com.mixpanel.mixpanelapi.MessageBuilder;
    import com.mixpanel.mixpanelapi.MixpanelAPI;

    MixpanelAPI mixpanel = new MixpanelAPI();
    MessageBuilder messageBuilder = new MessageBuilder("YOUR_PROJECT_TOKEN");

    // Create a group profile with group_key = "company", group_id = "mixpanel"
    ArrayList<String> featuresList = new ArrayList<String>(
        Arrays.asList("alert","report","cohort")
    );
    JSONObject groupProps = new JSONObject();
    groupProps.put("name", "Mixpanel");
    groupProps.put("features", featuresList);
    JSONObject message = messageBuilder.groupSet(
        "company",
        "mixpanel",
        groupProps
    );
    mixpanel.sendMessage(message);

    // add "data pipeline" to "features" prop
    // ignore "alert" since it is a duplicate value
    ArrayList<String> addFeaturesList = new ArrayList<String>(
        Arrays.asList("pipeline","alert")
    );
    JSONObject newGroupProps = new JSONObject();
    newGroupProps.put("features", addFeaturesList);
    JSONObject newMsg = messageBuilder.groupUnion(
        "company",
        "mixpanel",
        newGroupProps
    );
    mixpanel.sendMessage(newMsg);
    ```
  </Tab>

  <Tab title=".groupRemove()">
    The [`groupRemove()`](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#groupRemove-java.lang.String-java.lang.String-org.json.JSONObject-) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```java Java theme={"system"}
    import com.mixpanel.mixpanelapi.MessageBuilder;
    import com.mixpanel.mixpanelapi.MixpanelAPI;

    MixpanelAPI mixpanel = new MixpanelAPI();
    MessageBuilder messageBuilder = new MessageBuilder("YOUR_PROJECT_TOKEN");

    // Create a group profile with group_key = "company", group_id = "mixpanel"
    ArrayList<String> featuresList = new ArrayList<String>(
        Arrays.asList("alert","report","cohort")
    );
    JSONObject groupProps = new JSONObject();
    groupProps.put("name", "Mixpanel");
    groupProps.put("features", featuresList);
    JSONObject message = messageBuilder.groupSet(
        "company",
        "mixpanel",
        groupProps
    );
    mixpanel.sendMessage(message);

    //remove "alert" from "features"
    // "features" now contain ["reports","cohorts"]
    JSONObject removeFeature = new JSONObject();
    removeFeature.put("features","alert");
    JSONObject newMsg = messageBuilder.groupRemove(
        "company",
        "mixpanel",
        removeFeature
    )
    mixpanel.sendMessage(newMsg)
    ```
  </Tab>
</Tabs>

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Ruby SDK have a few configurations to help you protect user data.

Since this is a server-side tracking library where you have control of the servers, your server is responsible for determining whether to send data about a particular user or not.

### EU Data Residency

Route data to Mixpanel's EU servers by passing in positional arguments into the [`MixpanelAPI`](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MixpanelAPI.html) constructor:

**Example Usage**

```java theme={"system"}
// set event, people, and group endpoints to Mixpanel's EU domains
MixpanelAPI mixpanel = new MixpanelAPI( "https://api-eu.mixpanel.com/track",
                                        "https://api-eu.mixpanel.com/engage",
                                        "https://api-eu.mixpanel.com/groups");
```

### India Data Residency

Route data to Mixpanel's India servers by passing in positional arguments into the [`MixpanelAPI`](https://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MixpanelAPI.html) constructor:

**Example Usage**

```java theme={"system"}
// set event, people, and group endpoints to Mixpanel's India domains
MixpanelAPI mixpanel = new MixpanelAPI( "https://api-in.mixpanel.com/track",
                                        "https://api-in.mixpanel.com/engage",
                                        "https://api-in.mixpanel.com/groups");
```

### Disable Geolocation

The Java SDK parse the request IP address to generate geolocation properties for events and profiles. You may want to disable them to prevent the unintentional setting of your data's geolocation to the location of your server that is sending the request, or to prevent geolocation data from being tracked entirely.

To disable geolocation, set the `ip` of your events and profile updates to `0`.

**Example Usage**

```java theme={"system"}
import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.ClientDelivery;
import com.mixpanel.mixpanelapi.MixpanelAPI;

MessageBuilder messageBuilder =
    new MessageBuilder("YOUR_PROJECT_TOKEN");

MixpanelAPI mixpanel = new MixpanelAPI();

// create profile without updating geolocation
JSONObject userProps = new JSONObject();
userProps.put("Plan", "Premium");
userProps.put("$ip", "0"); // do not update profile location
JSONObject newUser = messageBuilder.set("sample_distinct_id", userProps);

//send event without geolocation parsing
JSONObject eventProps = new JSONObject();
eventProps.put("name", "sam");
eventProps.put("ip", "0");
JSONObject someEvent = messageBuilder.event(distinctId, "some_event", eventProps);


ClientDelivery delivery = new ClientDelivery();
delivery.addMessage(newUser);
delivery.addMessage(someEvent);

mixpanel.sendMessage(delivery);
```

## Release History

[See all releases.](https://github.com/mixpanel/mixpanel-java/releases)


# Implement Feature Flags (Java)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/java/java-flags



## Overview

This developer guide will assist you in configuring your server-side Java platform for [Feature Flags](/docs/featureflags) using the [Mixpanel Java SDK](/docs/tracking-methods/sdks/java). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

## Prerequisites

Before implementing [Feature Flags](/docs/featureflags), ensure:

* You are on an Enterprise subscription plan and have the appropriate version of the SDK installed (minimum supported version is `1.6.0-SNAPSHOT`). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK.
* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Flag Evaluation Modes

There are two modes available for using the Java SDK for feature flagging: Local Evaluation and Remote Evaluation.

For local evaluation, the SDK will poll Mixpanel servers for feature flag configurations. Assignment of user contexts to variants will be done locally within the SDK. This mode is recommended for low latency since there is no network call made at assignment time.

For remote evaluation, the SDK will make a network call to Mixpanel servers at assignment time. This mode is recommended for use cases where you want to leverage Mixpanel cohorts for user targeting or sticky variants for persistent variant assignments.

## Local Evaluation

<Warning>
  Targeting by Mixpanel cohorts and sticky variants are not supported in Local Evaluation mode.
</Warning>

* The SDK is configured with a `LocalFlagsConfig` object that specifies parameters:

  1. `apiHost` - If your project is in the EU/IN region, this should be set to route to `api-eu.mixpanel.com`/`api-in.mixpanel.com` respectively.
  2. `enablePolling` - This should be set to `true` to enable local evaluation.
  3. `pollingIntervalSeconds` - This is the interval in seconds at which the SDK will poll Mixpanel servers for feature flag configurations.
* The SDK will continue to poll for the lifetime of the SDK instance or until stopped.

```java theme={"system"}
import com.mixpanel.mixpanelapi.MixpanelAPI;
import com.mixpanel.mixpanelapi.featureflags.config.LocalFlagsConfig;
import java.util.HashMap;
import java.util.Map;

// Configure local flags
LocalFlagsConfig localConfig = LocalFlagsConfig.builder()
    .projectToken("YOUR_PROJECT_TOKEN")
    .apiHost("api.mixpanel.com")
    .enablePolling(true)
    .pollingIntervalSeconds(60)
    .requestTimeoutSeconds(10)
    .build();

// Initialize MixpanelAPI
MixpanelAPI mixpanel = new MixpanelAPI(localConfig);

// Start polling for flag definitions
mixpanel.getLocalFlags().startPollingForDefinitions();

// This should be the 'key' of the feature flag from Mixpanel's UX.
String flagKey = "sample-flag";

// This is the fallback variant to return if the user context is not in a rollout group for the flag.
String fallbackVariant = "control";

// Current user context for evaluation.
// At minimum, this needs to include the user's distinct_id.
// If any of your feature flags use a Variant Assignment Key other than 'distinct_id', this should also include those keys for evaluation. For example, 'company_id' below
// If any of your feature flags use Runtime targeting, this should also include 'custom_properties' for evaluation
Map<String, Object> userContext = new HashMap<>();
userContext.put("distinct_id", "1234");
userContext.put("company_id", "X");

Map<String, Object> customProperties = new HashMap<>();
customProperties.put("platform", "java");
userContext.put("custom_properties", customProperties);

// Get variant value for the flag
String variantValue = mixpanel.getLocalFlags().getVariantValue(flagKey, fallbackVariant, userContext);

// Check if flag is enabled (boolean check)
boolean isEnabled = mixpanel.getLocalFlags().isEnabled(flagKey, userContext);

// Clean up resources when done
mixpanel.close();
```

## Remote Evaluation

* The SDK is configured with a `RemoteFlagsConfig` object to use remote evaluation.

```java theme={"system"}
import com.mixpanel.mixpanelapi.MixpanelAPI;
import com.mixpanel.mixpanelapi.featureflags.config.RemoteFlagsConfig;
import java.util.HashMap;
import java.util.Map;

// Configure remote flags
RemoteFlagsConfig remoteConfig = RemoteFlagsConfig.builder()
    .projectToken("YOUR_PROJECT_TOKEN")
    .apiHost("api.mixpanel.com")
    .requestTimeoutSeconds(5)
    .build();

// Initialize MixpanelAPI
MixpanelAPI mixpanel = new MixpanelAPI(remoteConfig);

// Context for evaluation
Map<String, Object> userContext = new HashMap<>();
userContext.put("distinct_id", "user-123");

Map<String, Object> customProperties = new HashMap<>();
customProperties.put("platform", "java");
userContext.put("custom_properties", customProperties);

String flagKey = "sample-flag";
String fallbackVariant = "control";

// getVariantValue usage is the same as for local evaluation, but will make a network call to Mixpanel servers at assignment time.
String variantValue = mixpanel.getRemoteFlags().getVariantValue(flagKey, fallbackVariant, userContext);
System.out.println("Variant value: " + variantValue);

// Check if flag is enabled (boolean check)
boolean isEnabled = mixpanel.getRemoteFlags().isEnabled(flagKey, userContext);

// Clean up resources when done
mixpanel.close();
```

## Configuration Options

### LocalFlagsConfig Builder Options

* `projectToken(String)` - Your Mixpanel project token (required)
* `apiHost(String)` - API host without protocol (default: `"api.mixpanel.com"`)

  * For EU region: `"api-eu.mixpanel.com"`
  * For India region: `"api-in.mixpanel.com"`
* `enablePolling(boolean)` - Whether to enable automatic polling (default: `true`)
* `pollingIntervalSeconds(int)` - Polling interval in seconds (default: `60`)
* `requestTimeoutSeconds(int)` - Request timeout in seconds (default: `10`)

### RemoteFlagsConfig Builder Options

* `projectToken(String)` - Your Mixpanel project token (required)
* `apiHost(String)` - API host without protocol (default: `"api.mixpanel.com"`)

  * For EU region: `"api-eu.mixpanel.com"`
  * For India region: `"api-in.mixpanel.com"`
* `requestTimeoutSeconds(int)` - Request timeout in seconds (default: `5`)

## Additional Methods

### Evaluating All Flags

You can evaluate all flags at once using the `getAllVariantsByFlag()` method, which returns a map keyed by flag key:

```java theme={"system"}
import com.mixpanel.mixpanelapi.MixpanelAPI;
import com.mixpanel.mixpanelapi.featureflags.config.LocalFlagsConfig;
import com.mixpanel.mixpanelapi.featureflags.model.SelectedVariant;
import java.util.HashMap;
import java.util.Map;

LocalFlagsConfig config = LocalFlagsConfig.builder()
    .projectToken("YOUR_PROJECT_TOKEN")
    .build();

MixpanelAPI mixpanel = new MixpanelAPI(config);
mixpanel.getLocalFlags().startPollingForDefinitions();

Map<String, Object> userContext = new HashMap<>();
userContext.put("distinct_id", "user-123");

// Evaluate all flags at once, keyed by flag key
Map<String, SelectedVariant<Object>> allVariants = mixpanel.getLocalFlags().getAllVariantsByFlag(userContext, true);

for (Map.Entry<String, SelectedVariant<Object>> entry : allVariants.entrySet()) {
    String flagKey = entry.getKey();
    SelectedVariant<Object> variant = entry.getValue();
    System.out.println("Flag: " + flagKey + " = " + variant.getVariantValue());
}

// Clean up resources when done
mixpanel.close();
```

## Best Practices

### Context Management

* Always include `distinct_id` in your user context
* Include any custom properties used in your flag targeting rules
* Use consistent data types for context values across your application

### Resource Management

* Initialize the `MixpanelAPI` once and reuse it throughout your application
* Always call `close()` when shutting down to stop polling and release resources:

```java theme={"system"}
MixpanelAPI mixpanel = new MixpanelAPI(config);
try {
    // Use mixpanel here
} finally {
    mixpanel.close(); // Stops polling and releases resources
}
```

* For local evaluation, remember to start polling with `startPollingForDefinitions()`
* For local evaluation, you can also explicitly stop polling with `stopPollingForDefinitions()`:

```java theme={"system"}
mixpanel.getLocalFlags().stopPollingForDefinitions();
```


# OpenFeature Provider (Java)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/java/java-openfeature



## Overview

This guide covers using Mixpanel's [Feature Flags](/docs/featureflags) through the [OpenFeature](https://openfeature.dev/) standard with the Mixpanel Java OpenFeature provider. OpenFeature provides a vendor-agnostic API for feature flag evaluation, allowing you to switch between providers without changing your application code.

For the native Mixpanel SDK approach, see the [Feature Flags (Java)](/docs/tracking-methods/sdks/java/java-flags) guide.

## Prerequisites

* Enterprise subscription plan with Feature Flags enabled
* Java 8 or higher
* Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Installation

### Maven

```xml theme={"system"}
<dependency>
    <groupId>com.mixpanel</groupId>
    <artifactId>mixpanel-java-openfeature</artifactId>
    <version>0.1.0</version>
</dependency>
<dependency>
    <groupId>dev.openfeature</groupId>
    <artifactId>sdk</artifactId>
    <version>1.20.1</version>
</dependency>
```

### Gradle

```groovy theme={"system"}
implementation 'com.mixpanel:mixpanel-java-openfeature:0.1.0'
implementation 'dev.openfeature:sdk:1.20.1'
```

## Quick Start

```java theme={"system"}
import com.mixpanel.openfeature.MixpanelProvider;
import com.mixpanel.mixpanelapi.featureflags.config.LocalFlagsConfig;
import dev.openfeature.sdk.OpenFeatureAPI;
import dev.openfeature.sdk.Client;

// 1. Create and register the provider with local evaluation
MixpanelProvider provider = new MixpanelProvider(
    "YOUR_PROJECT_TOKEN",
    new LocalFlagsConfig("YOUR_PROJECT_TOKEN")
);
OpenFeatureAPI api = OpenFeatureAPI.getInstance();
api.setProvider(provider);

// 2. Get a client and evaluate flags
Client client = api.getClient();
boolean showNewFeature = client.getBooleanValue("new-feature-flag", false);

if (showNewFeature) {
    System.out.println("New feature is enabled!");
}
```

## Initialization

### Local Evaluation (Recommended)

<Warning>
  Targeting by Mixpanel cohorts and sticky variants are not supported in Local Evaluation mode.
</Warning>

```java theme={"system"}
MixpanelProvider provider = new MixpanelProvider(
    "YOUR_PROJECT_TOKEN",
    new LocalFlagsConfig("YOUR_PROJECT_TOKEN")
);
```

### Remote Evaluation

```java theme={"system"}
MixpanelProvider provider = new MixpanelProvider(
    "YOUR_PROJECT_TOKEN",
    new RemoteFlagsConfig("YOUR_PROJECT_TOKEN")
);
```

### Using an Existing MixpanelAPI Instance

```java theme={"system"}
MixpanelAPI mixpanel = new MixpanelAPI(new LocalFlagsConfig("YOUR_PROJECT_TOKEN"));
LocalFlagsProvider localFlags = mixpanel.getLocalFlags();
localFlags.startPollingForDefinitions();

MixpanelProvider provider = new MixpanelProvider(localFlags);
```

## Usage

### Flag Types and Evaluation Methods

| Mixpanel Flag Type | Variant Values                          | OpenFeature Method                                                                                      |
| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Feature Gate       | `true` / `false`                        | `getBooleanValue()`                                                                                     |
| Experiment         | boolean, string, number, or JSON object | `getBooleanValue()`, `getStringValue()`, `getIntegerValue()`, `getDoubleValue()`, or `getObjectValue()` |
| Dynamic Config     | JSON object                             | `getObjectValue()`                                                                                      |

```java theme={"system"}
Client client = api.getClient();

// Feature Gate
boolean isFeatureOn = client.getBooleanValue("new-checkout", false);

// Experiment with string variants
String buttonColor = client.getStringValue("button-color-test", "blue");

// Experiment with numeric variants
int maxItems = client.getIntegerValue("max-items", 10);
double threshold = client.getDoubleValue("score-threshold", 0.5);

// Dynamic Config
Value featureConfig = client.getObjectValue("homepage-layout", new Value("default"));
```

### Evaluation Context

```java theme={"system"}
MutableContext context = new MutableContext();
context.setTargetingKey("user-123");
context.add("email", "user@example.com");
context.add("plan", "premium");
context.add("beta_tester", true);

boolean value = client.getBooleanValue("premium-feature", false, context);
```

<Note>
  Unlike some providers, `targetingKey` is not used as a special bucketing key. It is passed as another context property. Mixpanel's server-side configuration determines which properties are used for targeting and bucketing.
</Note>

### Full Resolution Details

```java theme={"system"}
FlagEvaluationDetails<Boolean> details = client.getBooleanDetails("my-feature", false);

System.out.println(details.getValue());
System.out.println(details.getVariant());
System.out.println(details.getReason());
System.out.println(details.getErrorCode());
```

### Accessing the Underlying MixpanelAPI

```java theme={"system"}
MixpanelAPI mixpanel = provider.getMixpanel();
```

### Shutdown

```java theme={"system"}
provider.shutdown();
```

## Error Handling

| Error Code           | When                                                                       |
| -------------------- | -------------------------------------------------------------------------- |
| `PROVIDER_NOT_READY` | Flags evaluated before the local provider has finished loading definitions |
| `FLAG_NOT_FOUND`     | The requested flag does not exist in Mixpanel                              |
| `TYPE_MISMATCH`      | The flag value type does not match the requested type                      |

## Troubleshooting

### Flags Always Return Default Values

1. **Provider not ready:** Flag definitions are polled asynchronously. Allow time for the initial fetch.
2. **Invalid project token:** Verify the token matches your Mixpanel project.
3. **Flag not configured:** Verify the flag exists and is enabled.

### Type Mismatch Errors

1. Verify the flag's value type matches your evaluation method.
2. Use `getObjectValue()` for JSON objects.
3. Integer evaluation accepts `Long` and whole-number `Double` values within `Integer` bounds. Double evaluation accepts any numeric type.


# Mixpanel SDKs: Javascript
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript



## Getting Started

Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=javascript).

The [Full API Reference](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanel), [Library Source Code](https://github.com/mixpanel/mixpanel-js), and an [Example Application](https://github.com/mixpanel/mixpanel-js/tree/master/examples) is documented in our GitHub repo.

## Installing the Library

<Tabs>
  <Tab title="Snippet">
    The easiest way to install the library is to load it from our CDN to your website. Paste the following code snippet right before the closing `</head>` tag in your page HTML.

    ```html theme={"system"}
    <!-- Paste this right before your closing head tag -->
    <script type="text/javascript">
        (function (f, b) { if (!b.__SV) { var e, g, i, h; window.mixpanel = b; b._i = []; b.init = function (e, f, c) { function g(a, d) { var b = d.split("."); 2 == b.length && ((a = a[b[0]]), (d = b[1])); a[d] = function () { a.push([d].concat(Array.prototype.slice.call(arguments, 0))); }; } var a = b; "undefined" !== typeof c ? (a = b[c] = []) : (c = "mixpanel"); a.people = a.people || []; a.toString = function (a) { var d = "mixpanel"; "mixpanel" !== c && (d += "." + c); a || (d += " (stub)"); return d; }; a.people.toString = function () { return a.toString(1) + ".people (stub)"; }; i = "disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking start_batch_senders people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split( " "); for (h = 0; h < i.length; h++) g(a, i[h]); var j = "set set_once union unset remove delete".split(" "); a.get_group = function () { function b(c) { d[c] = function () { call2_args = arguments; call2 = [c].concat(Array.prototype.slice.call(call2_args, 0)); a.push([e, call2]); }; } for ( var d = {}, e = ["get_group"].concat( Array.prototype.slice.call(arguments, 0)), c = 0; c < j.length; c++) b(j[c]); return d; }; b._i.push([e, f, c]); }; b.__SV = 1.2; e = f.createElement("script"); e.type = "text/javascript"; e.async = !0; e.src = "undefined" !== typeof MIXPANEL_CUSTOM_LIB_URL ? MIXPANEL_CUSTOM_LIB_URL : "file:" === f.location.protocol && "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\/\//) ? "https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js" : "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"; g = f.getElementsByTagName("script")[0]; g.parentNode.insertBefore(e, g); } })(document, window.mixpanel || []);
    </script>
    ```

    Within the `script` tags, create an instance of the Mixpanel object by calling [`.init()`](https://github.com/mixpanel/mixpanel-js/blob/475b2c6853dd49ffc625daac3925bf37940ec390/doc/readme.io/javascript-full-api-reference.md#mixpanelinit) using your [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens) in your JS file. Any methods called from this object will target your project.

    ```javascript theme={"system"}
    // Create an instance of the Mixpanel object
    mixpanel.init("YOUR_PROJECT_TOKEN", {
        autocapture: true,
        track_pageview: true,
        record_sessions_percent: 100, //records 100% of all sessions
        record_heatmap_data: true,
    });
    ```

    Altogether, with your particular library configuration, the code snippet should follow this basic structure:

    ```html theme={"system"}
    <!-- Paste this right before your closing head tag -->
    <script type="text/javascript">
        (function (f, b) { if (!b.__SV) { var e, g, i, h; window.mixpanel = b; b._i = []; b.init = function (e, f, c) { function g(a, d) { var b = d.split("."); 2 == b.length && ((a = a[b[0]]), (d = b[1])); a[d] = function () { a.push([d].concat(Array.prototype.slice.call(arguments, 0))); }; } var a = b; "undefined" !== typeof c ? (a = b[c] = []) : (c = "mixpanel"); a.people = a.people || []; a.toString = function (a) { var d = "mixpanel"; "mixpanel" !== c && (d += "." + c); a || (d += " (stub)"); return d; }; a.people.toString = function () { return a.toString(1) + ".people (stub)"; }; i = "disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking start_batch_senders people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split( " "); for (h = 0; h < i.length; h++) g(a, i[h]); var j = "set set_once union unset remove delete".split(" "); a.get_group = function () { function b(c) { d[c] = function () { call2_args = arguments; call2 = [c].concat(Array.prototype.slice.call(call2_args, 0)); a.push([e, call2]); }; } for ( var d = {}, e = ["get_group"].concat( Array.prototype.slice.call(arguments, 0)), c = 0; c < j.length; c++) b(j[c]); return d; }; b._i.push([e, f, c]); }; b.__SV = 1.2; e = f.createElement("script"); e.type = "text/javascript"; e.async = !0; e.src = "undefined" !== typeof MIXPANEL_CUSTOM_LIB_URL ? MIXPANEL_CUSTOM_LIB_URL : "file:" === f.location.protocol && "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\/\//) ? "https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js" : "//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"; g = f.getElementsByTagName("script")[0]; g.parentNode.insertBefore(e, g); } })(document, window.mixpanel || []);

        // Create an instance of the Mixpanel object
        mixpanel.init("YOUR_PROJECT_TOKEN", {
            autocapture: true,
            track_pageview: true,
            record_sessions_percent: 100, //records 100% of all sessions
            record_heatmap_data: true,
        });
    </script>
    ```
  </Tab>

  <Tab title="NPM/Yarn">
    <Note>
      The JS library is named `mixpanel-browser` in NPM and Yarn. This is to distinguish it from our server-side Node.js library, which is available as `mixpanel`.
    </Note>

    The library is available as a package [on NPM](https://www.npmjs.com/package/mixpanel-browser) and [on Yarn](https://classic.yarnpkg.com/en/package/mixpanel-browser). Open your CLI, and run the following command in your root directory to install the library.

    ```bash theme={"system"}
    # via npm
    npm install --save mixpanel-browser

    # via yarn
    yarn add mixpanel-browser
    ```

    After installation, import the Mixpanel class in your JS file and create the Mixpanel object using your project token.

    ```javascript theme={"system"}
    // import mixpanel class from the library
    import mixpanel from 'mixpanel-browser'

    // create an instance Mixpanel object using your project token
    mixpanel.init("YOUR_PROJECT_TOKEN", {
        autocapture: true,
        track_pageview: true,
        record_sessions_percent: 100, //records 100% of all sessions
        record_heatmap_data: true,
    });
    ```
  </Tab>
</Tabs>

### Library Configuration

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/javascript#privacy-friendly-tracking).
</Warning>

The Mixpanel object can be initialized with different configurations. See a complete list of the configuration options and default values [here](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelset_config).

You can override the default configuration using the `config` argument when initializing the library.

**Example Usage**

```javascript theme={"system"}
// create an instance of the Mixpanel object
mixpanel.init('YOUR_PROJECT_TOKEN', {
    persistence: 'localStorage',    // set persistence to local storage
    debug: true,                    // enable debug log in console
});
```

You can update the configuration after initialization using the [`.set_config`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelset_config) method.

**Example Usage**

```javascript theme={"system"}
// create an instance of the Mixpanel object
mixpanel.init('YOUR_PROJECT_TOKEN', {
    debug: true,    // enable debug log in console
});

// disable debug log after initialization
mixpanel.set_config({
    debug: false
});

// debug is disabled
```

## Autocapture

Starting with SDK version 2.60.0, the Javascript SDK can autocapture events when you enable it. To do so, enable the autocapture configuration:

```javascript theme={"system"}
// create an instance of the Mixpanel object
mixpanel.init('YOUR_PROJECT_TOKEN', {
    autocapture: true,    // enable autocapture
});
```

If you'd like to change the default Autocapture settings, you can use custom configs. This is the default configuration:

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
  autocapture: {
    pageview: "full-url",
    click: true,
    dead_click: true,
    input: true,
    rage_click: true,
    scroll: true,
    submit: true,
    capture_text_content: false,
  },
});
```

**Omitting elements from Autocapture tracking**

Add the built-in `.mp-no-track` class to any element you wish to exclude from tracking. You can also opt an individual element out of being included in any tracking (including the `$elements` prop of another target's event) using the `.mp-sensitive` class.

Alternatively, you can update your Autocapture configuration using different blocking options:

1. `block_selectors`: used to block specific classes

Example:

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
  autocapture: {
    block_selectors: ['.class1', 'button.class2']
  },
});
```

2. `block_url_regexes`: used to block Autocapture from tracking on certain pages

Example:

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
  autocapture: {
    block_url_regexes: [/\/login\/?$/, /\/payment\/?$/]
  },
});
```

**Disabling Autocapture**

To disable Autocapture, see the following code sample:

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
    autocapture: false
});
```

Note that disabling Autocapture does not disable Session Replay, which is [configured separately](/docs/tracking-methods/sdks/javascript#session-replay).

**Autocapture Init Options**

| Option                             | Description                                                                                                                                                                                                                                                                                                             | Default             |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `click`                            | When set to `true`, Mixpanel will track element clicks. It will not track textContent unless `capture_text_content` is also set to `true`.                                                                                                                                                                              | `true`              |
| `dead_click`                       | When set to `true`, Mixpanel will track dead clicks on elements. You can also fine tune thresholds for classifying dead clicks using the [Dead Click Options](#dead-click-options) below.                                                                                                                               | `true`              |
| `rage_click`                       | When set to `true`, Mixpanel will track rage clicks on elements. You can also fine tune thresholds for classifying rage clicks using the [Rage Click Options](#rage-click-options) below.                                                                                                                               | `true`              |
| `input`                            | When set to `true`, Mixpanel will track when an input is provided. It will not capture input content.                                                                                                                                                                                                                   | `true`              |
| `pageview`                         | When set, Mixpanel will collect pageviews when some components of the URL change — including UTM parameters.                                                                                                                                                                                                            | `"full-url"`        |
| `scroll`                           | When set, Mixpanel will collect page scrolls at specified scroll intervals.                                                                                                                                                                                                                                             | `true`              |
| `submit`                           | When set to `true`, Mixpanel will track form submissions (but not submission content).                                                                                                                                                                                                                                  | `true`              |
| `capture_text_content`             | When set to `true`, Mixpanel will capture the textContent of any element.                                                                                                                                                                                                                                               | `false`             |
| `capture_extra_attrs`              | Enables specification of additional attributes to track.                                                                                                                                                                                                                                                                | `[]`                |
| `scroll_depth_percent_checkpoints` | Establishes the scroll depth intervals which trigger `Page Scroll` event.                                                                                                                                                                                                                                               | `[25, 50, 75, 100]` |
| `scroll_capture_all`               | When set to true, overrides `scroll_depth_percentage_checkpoints` and captures all scroll events.                                                                                                                                                                                                                       | `false`             |
| `block_url_regexes`                | Opts out specific pages from Autocapture.                                                                                                                                                                                                                                                                               | `[]`                |
| `allow_url_regexes`                | Opts in specific pages to Autocapture.                                                                                                                                                                                                                                                                                  | `[]`                |
| `block_selectors`                  | Opts out specific classes from Autocapture.                                                                                                                                                                                                                                                                             | `[]`                |
| `allow_selectors`                  | Opts in specific classes to Autocapture.                                                                                                                                                                                                                                                                                | `[]`                |
| `block_attrs`                      | Opts out specific attributes from Autocapture.                                                                                                                                                                                                                                                                          | `[]`                |
| `allow_element_callback`           | A user-provided function that determines whether a specific element should be tracked via Autocapture or not. The function receives the element as its first argument, and the DOM event as its second argument, and should return `true` if the element should be tracked (otherwise the element will NOT be tracked). | `not set`           |
| `block_element_callback`           | A user-provided function that determines whether a specific element should be blocked from tracking via Autocapture or not. The function receives the element as its first argument, and the DOM event as its second argument, and should return `true` if the element should be blocked.                               | `not set`           |

<span>Dead Click Options</span>

| Option       | Description                                                              | Default |
| ------------ | ------------------------------------------------------------------------ | ------- |
| `timeout_ms` | Time in milliseconds to wait after a click before qualifying it as dead. | `500`   |

<span>Rage Click Options</span>

| Option                      | Description                                                                                  | Default |
| --------------------------- | -------------------------------------------------------------------------------------------- | ------- |
| `threshold_px`              | Maximum pixel distance between clicks to be considered in the same location.                 | `30`    |
| `timeout_ms`                | Time window in milliseconds to group rapid consecutive clicks.                               | `1000`  |
| `click_count`               | Minimum number of clicks required within the time window to trigger rage click detection.    | `4`     |
| `interactive_elements_only` | When enabled, only tracks rage clicks on interactive elements (buttons, links, inputs, etc.) | `false` |

**HTML attributes captured by default**

By default, Autocapture collects the following HTML attributes on events:

| HTML Element Attribute | Description                                                                                                                 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `aria-label`           | Provides an accessible name for an element, used by assistive technologies like screen readers.                             |
| `aria-labelledby`      | Identifies one or more elements that serve as labels for the current element, improving accessibility.                      |
| `aria-described-by`    | References an element that provides additional description or context for the current element.                              |
| `href`                 | Specifies the URL of a linked resource, commonly used in `<a>` (anchor) and `<link>` elements.                              |
| `name`                 | Defines the name of an input field, form, or metadata element, often used for form controls and `<meta>` tags.              |
| `role`                 | Defines the semantic role of an element to assist accessibility tools in interpreting the page structure.                   |
| `title`                | Provides additional information about an element, typically displayed as a tooltip when hovered.                            |
| `type`                 | Specifies the type of an element, commonly used in `<input>` fields to define input behavior (e.g., text, password, email). |

**Default event properties on Autocapture events**

On Autocapture events, Mixpanel default-tracks the following properties:

| Event Property       | Description                                                                                                      |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `$event_type`        | The type of DOM event that was captured (e.g., "click", "submit").                                               |
| `$host`              | The hostname of the webpage where the event was triggered (e.g., `example.com`).                                 |
| `$pathname`          | The path portion of the URL where the event occurred (e.g., `/checkout`).                                        |
| `$elements`          | A list of elements that were involved in the event, useful for understanding element context.                    |
| `$target`            | The specific HTML element that triggered the event (e.g., a button or link).                                     |
| `$el_attr__href`     | The href attribute of the target element if it is a link (`<a>` tag).                                            |
| `$el_classes`        | The CSS classes associated with the target element.                                                              |
| `$el_tag_name`       | The tag name of the element that triggered the event (e.g., `button`, `a`, `div`).                               |
| `$viewportHeight`    | The height of the browser’s viewport at the time of the event.                                                   |
| `$viewportWidth`     | The width of the browser’s viewport at the time of the event.                                                    |
| `$clientX`           | The X-coordinate of the mouse pointer relative to the browser’s viewport when the event occurred.                |
| `$clientY`           | The Y-coordinate of the mouse pointer relative to the browser’s viewport when the event occurred.                |
| `$offsetX`           | The X-coordinate of the mouse pointer relative to the event target element.                                      |
| `$offsetY`           | The Y-coordinate of the mouse pointer relative to the event target element.                                      |
| `$pageHeight`        | The height of the full page.                                                                                     |
| `$pageWidth`         | The width of the full page.                                                                                      |
| `$pageX`             | The X-coordinate of the mouse pointer relative to the full page.                                                 |
| `$pageY`             | The Y-coordinate of the mouse pointer relative to the full page.                                                 |
| `$scroll_checkpoint` | The percentage of scrollbar that has been reached when crossing specific thresholds (e.g., 25%, 50%, 75%, 100%). |
| `$scroll_height`     | The height of the scrollable area of the page.                                                                   |
| `$scroll_percentage` | The percentage of the page that has been scrolled.                                                               |
| `$scroll_top`        | The number of pixels the page has been scrolled vertically.                                                      |
| `$screenX`           | The X-coordinate of the mouse pointer relative to the screen.                                                    |
| `$screenY`           | The Y-coordinate of the mouse pointer relative to the screen.                                                    |
| `$x`                 | The X-coordinate of the event, often synonymous with `$pageX`.                                                   |
| `$y`                 | The X-coordinate of the event, often synonymous with `$pageY`.                                                   |

## Sending Events

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for [historical imports](/docs/tracking-methods/sdks/javascript#importing-historical-events).
</Note>

The Javascript SDK provides a few different methods to send event data to your project. Calling any of the event tracking methods below will generate an event payload, then trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

All events sent from the JavaScript library will be sent over HTTPS.

### Track Events

Once you initialized the Mixpanel object, call `.track()` to send an event by providing the event name and any event properties.

**Example Usage**

```javascript JavaScript theme={"system"}
// Send a "Played song" event to Mixpanel
mixpanel.track("Played song",{
    "genre": "hip-hop"  // with an event property "genre" set to "hip-hop"
    }
);
```

<Note>
  Avoid using names containing `$` or `mp` (e.g. `$name`, `mp_country_code`, etc.) as they are used by our [reserved event properties](/docs/data-structure/property-reference/reserved-properties#reserved-event-properties) which receive special treatment in our UI or are used for special processing.
</Note>

#### Timing Events

You can track the time it took for an action to occur, such as an image upload or a comment post, using [`.time_event()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneltime_event). This will mark the “start” of your action, which will be timed until you finish with a `.track()` call. The time duration is then recorded in the “Duration” property.

```javascript Javascript theme={"system"}
// start the timer for the event "Image Upload"
mixpanel.time_event('Image Upload');

// 20 seconds later...

// track "Image Upload" event with "Duration" event prop set to 20
mixpanel.track('Image Upload');
```

### Track Page Views

Page view tracking is turned off by default. Page view events can be added automatically on every page load by enabling the `track_pageview` [config option](https://github.com/mixpanel/mixpanel-js/blob/v2.46.0/src/mixpanel-core.js#L88-L127) when creating the Mixpanel object.

If you have enabled Autocapture, you do not need to set up precision tracking for page view unless you are implementing in a single-page application.

**Example Usage**

```javascript JavaScript theme={"system"}
//create an instance of the Mixpanel object
mixpanel.init('YOUR_PROJECT_TOKEN', {
    track_pageview: true    // enable automatic pageview tracking
    });
```

The default `track_pageview` setting does not auto-track page views in single-page applications. For tracking dynamic page views in single-page applications, the `track_pageview` option can also accept the following values for tracking.

**Example Usage**

```javascript JavaScript theme={"system"}
// Track when the path changes, ignoring any query string or hash changes
mixpanel.init('YOUR_PROJECT_TOKEN', {
    track_pageview: "url-with-path"
    });

// Track when the path or query string change, ignoring hash changes
mixpanel.init('YOUR_PROJECT_TOKEN', {
    track_pageview: "url-with-path-and-query-string"
    });

// Track any URL changes in the path, query string, or hash
mixpanel.init('YOUR_PROJECT_TOKEN', {
    track_pageview: "full-url"
    });
```

The default page view event has the event name (`$mp_web_page_view`), and includes the event properties page title (`current_page_title`), URL components (`current_domain`, `current_url_path`, `current_url_protocol`, `current_url_search`), and [marketing parameters](/docs/tracking-methods/sdks/javascript#tracking-utm-parameters). Additional page view event properties can be added.

**Example Usage**

```javascript JavaScript theme={"system"}
// Send a default page view event "$mp_web_page_view"
mixpanel.track_pageview();

// Send a default page view event with additional "page" property
mixpanel.track_pageview({
    "page": "Pricing"
    });
```

### Track UTM Tags

The JavaScript library will automatically add the following UTM parameters present on the page to events fired from that page load:

* utm\_source
* utm\_campaign
* utm\_medium
* utm\_term
* utm\_content
* utm\_id
* utm\_source\_platform
* utm\_campaign\_id
* utm\_creative\_format
* utm\_marketing\_tactic

<Warning>
  UTM tracking is case sensitive and should be formatted in lowercase as shown in the examples above.
</Warning>

UTM parameters are by default persisted across events as [Super Properties](/docs/tracking-methods/sdks/javascript#setting-super-properties). To opt in to the recommended modern behavior most compatible with our [attribution models](/docs/features/computed-properties#attribution), use the SDK initialization option `{stop_utm_persistence: true}` to disable UTM param persistence (refer to our [Release Notes](https://github.com/mixpanel/mixpanel-js/releases/tag/v2.52.0) in GitHub).

**Example Usage**

```javascript Javascript theme={"system"}
//create an instance of the Mixpanel object
mixpanel.init('YOUR_PROJECT_TOKEN', {
    stop_utm_persistence: true    // disable utm persistence
    });
```

When UTM parameters for an identified user are seen for the first time, these will also be stored on the user profile as the following user properties:

* initial\_utm\_source
* initial\_utm\_campaign
* initial\_utm\_medium
* initial\_utm\_term
* initial\_utm\_content
* initial\_utm\_id
* initial\_utm\_source\_platform
* initial\_utm\_campaign\_id
* initial\_utm\_creative\_format
* initial\_utm\_marketing\_tactic

In addition to UTM parameters, Mixpanel will also add any advertising click IDs to events fired. These include:

* dclid
* fbclid
* gclid
* ko\_click\_id
* li\_fat\_id
* msclkid
* sccid
* ttclid
* twclid
* wbraid

Learn more about [UTM tracking](/docs/tracking-best-practices/traffic-attribution#web-attribution).

#### Other Tracking Methods

There are other less common methods for sending data to Mixpanel. Refer to the [full API documentation](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanel).

#### Importing Historical Events

The Javascript SDK is a tracking SDK designed for real-time tracking in a client-side environment. Calling the `.track()` method triggers a request to our [/track API endpoint](/reference/track-event), which will validate for events with a timestamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested**.

For bulk import of historical events older than 5 days, we will need to use the [/import API endpoint](/reference/import-events) which is optimized for scripting and supports ingesting historical data. We recommend the [Python SDK](/docs/tracking-methods/sdks/python) (see the [`.import_data()`](https://mixpanel.github.io/mixpanel-python/#primary-interface) function) and [mixpanel-utils module](https://github.com/mixpanel/mixpanel-utils) (see the [`import_events()`](https://github.com/mixpanel/mixpanel-utils?tab=readme-ov-file#import-events) function) which both leverages the /import API for event ingestion.

## Setting Super Properties

Super properties are global event properties that you define once and apply to all events.

To register super properties, call [`.register()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelregister).

Use [`.register_once()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelregister_once) to register super properties without overwriting existing values.

**Example Usage**

```javascript theme={"system"}
// register "name" as a super property
mixpanel.register({
    name: 'Sam',
});

// register "city" as an additional super property
// ignore "name" since it already exists
mixpanel.register_once({
    name: 'Samantha',
    city: 'San Francisco'
});

// track a "registration" event
// the event will include the "name" property set to "Sam"
// and "city" set to "San Francisco"
mixpanel.track('registration');
```

Your super properties are stored in the cookie generated by the domain that is loading the library. They will persist for the life of that cookie, which by default is 365 days. If you wish to change the life of the cookie, adjust the `cookie_expiration` configuration.

**Example Usage**

```javascript theme={"system"}
// set cookie_expiration to 90 days upon initialization
mixpanel.init('YOUR_PROJECT_TOKEN', {
    'cookie_expiration': 90
});
```

## Managing User Identity

You can handle the identity of a user using the `.identify()` and `.reset()` methods. Learn more about [identity management](/docs/tracking-methods/id-management/identity-management) and [identifying users](/docs/tracking-methods/id-management/identifying-users).

### Identify

<Warning>
  We recommend against calling `.identify()` for anonymous visitors to your site.
</Warning>

Call [`.identify()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelidentify) when you know the identity of the current user, passing in their user ID as an argument. This is typically at account registration and at log in.

**Example Usage**

```javascript theme={"system"}
// your user signs in and tracks a sign in event
mixpanel.track('sign in');

// upon sign in, identify the user with their ID
// ensure future events sent from the user have distinct_id 12345
mixpanel.identify('12345');
```

### Call Reset at Logout

Call [`.reset()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelreset) to clear data attributed to a user when they logout. This will clear the cookie/local storage and allows you to handle [multiple users on a single device](/docs/tracking-methods/id-management/identifying-users-simplified#multiple-users-one-device).

**Example Usage**

```javascript JavaScript theme={"system"}
// your user logs out and tracks a log out event
mixpanel.track('log out');

// generate new cookie with new distinct_id
mixpanel.reset();
```

## Storing User Profiles

Once your users are identified, create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Javascript SDK provides a few methods for setting profile properties under [`.people`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeople), which will trigger requests to the [/engage API endpoint](/reference/profile-set).

### Setting Profile Properties

<Note>
  You must call `.identify()` before setting profile properties in order to associate the profile properties you set with the target user. If identify is not called, the profile update will be queued for ingestion until an identify call is made.
</Note>

Set profile properties on a user profile by calling the [`.people.set()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeopleset) method.

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```javascript JavaScript theme={"system"}
// You must call identify to associate the profile update with the user
// Create "plan" profile prop for user "12345"
mixpanel.identify('12345');
mixpanel.people.set({
    plan: 'Premium'
    });

// We only need to call identify once per page load
mixpanel.people.set({
    plan: 'Enterprise',   // Update "plan" from "Premium" to "Enterprise"
    company: 'mixpanel'  // Create new "company" profile prop
});
```

### Other Types Of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeople).

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title=".set_once()">
    The [`.people.set_once()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeopleset_once) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```javascript theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    mixpanel.people.set({
        name: 'Sam',
    });

    // "name" will not be update since it already exists
    // "email" will be added to profile
    mixpanel.people.set_once({
        name: 'Samantha',
        email: 'sam@mail.com'
    });
    ```
  </Tab>

  <Tab title=".append()">
    The [`.people.append()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeopleappend) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```javascript theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    mixpanel.people.set({
        name: 'Sam',
        roles: ['sales','engineer']
    });

    // add "legal" to "roles"
    // new "roles" value is ['sales','engineer','legal']
    mixpanel.people.append('roles', 'legal');

    // append() allows duplicates
    // new "roles" values are ['sales','engineer','legal','legal']
    mixpanel.people.append('roles', 'legal');
    ```
  </Tab>

  <Tab title=".union()">
    The [`.people.union()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeopleunion) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```javascript theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    mixpanel.people.set({
        name: 'Sam',
        roles: ['sales','engineer']
    });

    // will be ignored since "engineer" already exists in "roles"
    mixpanel.people.union('roles', 'engineer');

    // add "legal" to "roles" since it doesn't exist yet
    mixpanel.people.union('roles', 'legal');
    ```
  </Tab>

  <Tab title=".increment()">
    The [`.people.increment()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelpeopleincrement) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```javascript theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    mixpanel.people.set({
        name: 'Sam',
        age: 25,
    });

      // increment "age" by 2
      mixpanel.people.increment('age',2);

      // use negative number to decrement
      // decrement "age" by 5
      mixpanel.people.increment('age',-5);
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel [Group Analytics](/docs/data-structure/group-analytics) is a paid add-on that allows behavioral data analysis by groups (e.g. company, team), as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

The Javascript SDK provides a few method for adding individual users to a group and setting group profile properties.

### Adding Users to a Group

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

Call the [`.set_group()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelset_group) method to register the current user to a group, which would add the `group_key` as an event property set to the `group_id` value to all events moving forward.

Alternatively, you can manually add the group key property to be more selective about which events to attribute to a group.

**Example Usage**

```javascript theme={"system"}
// assign the current user to the "mixpanel" company group
mixpanel.set_group('company', 'mixpanel');

// track "some_event"
// event property "company" = ["mixpanel"] is added automatically
mixpanel.track('some_event');

// alternatively you can manually set the group key on each event
mixpanel.track('some_event',{
    company: ['mixpanel']
});
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

Call [`.add_group()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneladd_group) to add additional `group_id` to an existing list.

**Example Usage**

```javascript theme={"system"}
// assign the current user to the "mixpanel" company group
// events will contain 'company' prop set to ["mixpanel"]
mixpanel.set_group('company', 'mixpanel');

// add "mp-us" as an additional company group
// new "company" value is ["mixpanel","mp-us"]
mixpanel.add_group('company', 'mp-us');

// track "some_event"
// event property "company" = ["mixpanel","mp-us"] is added automatically
mixpanel.track('some_event');
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `people.set()` call.

```javascript theme={"system"}
// set group key "company" as a user prop
// with group id "mixpanel" as value
mixpanel.people.set({"company":"mixpanel"})
```

### Setting Group Profile Properties

Create a group profiles by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

To set group profile properties, specify the group that needs to be updated by calling [`.get_group()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelget_group), then set the group properties by chaining the `.set()` method, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```javascript theme={"system"}
// assign the current user to the "mixpanel" company group
mixpanel.set_group('company', 'mixpanel');

// specify the target group using the group_key and group_id
// set "name", "features", and "employee_count" as group profile props
mixpanel.get_group('company','mixpanel').set({
    name: 'Mixpanel',
    features: ['reports','alerts','cohorts'],
    employee_count: 100
});
```

### Other Group Profile Methods

There are a few other methods for setting group profile properties under [`.group`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelgroup).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title=".set_once()">
    The [`.group.set_once()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelgroupset_once) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```javascript theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.set_group('company', 'mixpanel');

    // set group profile properties
    mixpanel.get_group('company','mixpanel').set({
        name: 'Mixpanel',
    });

    // ignore "name" since it already exists
    // add "color" as a group profile prop
    mixpanel.get_group('company','mixpanel').set_once({
        name: 'mp',
        color: 'purple'
    });
    ```
  </Tab>

  <Tab title=".unset()">
    The [`.group.unset()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelgroupunset) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```javascript theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.set_group('company', 'mixpanel');

    // set group profile properties
    mixpanel.get_group('company','mixpanel').set({
        name: 'Mixpanel',
        color: 'purple'
    });

    // delete "color" from the group profile
    mixpanel.get_group('company','mixpanel').unset('color');

    // only "name" remains as group profile prop
    ```
  </Tab>

  <Tab title=".union()">
    The [`.group.union()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelgroupunion) method append new values to a list property, excluding duplicates.

    Use this method to create a list group profile property that only contains unique values without duplicates.

    **Example Usage**

    ```javascript theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.set_group('company', 'mixpanel');

    // set group profile properties
    mixpanel.get_group('company','mixpanel').set({
        name: 'Mixpanel',
        features: ['reports','alerts','cohorts'],
    });

    // add "data pipeline" to "features" prop
    // ignore "alert" since it is a duplicate value
    mixpanel.get_group('company','mixpanel').union('features', [
        'data pipeline',
        'alerts'
        ]);
    ```
  </Tab>

  <Tab title=".remove()">
    The [`.group.remove()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelgroupremove) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```javascript theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.set_group('company', 'mixpanel');

    // set group profile properties
    mixpanel.get_group('company','mixpanel').set({
        name: 'Mixpanel',
        features: ['reports','alerts','cohorts'],
    });

    //remove "alert" from "features"
    // "feature" now contain values ["reports","cohorts"]
    mixpanel.get_group('company','mixpanel').remove('features', 'alert');
    ```
  </Tab>
</Tabs>

## Debug Mode

To enable debug mode, set the `debug` configuration option to `true` when initializing the Mixpanel object.

**Example Usage**

<Note>
  Remove this parameter before going into production.
</Note>

```javascript theme={"system"}
// enable debug log in the console
mixpanel.init('YOUR_PROJECT_TOKEN', {
    debug: true
});
```

If you implemented using the HTML snippet, the `mixpanel` object is globally accessible and you can enable debug mode directly from the console by calling `mixpanel.set_config({debug:true});`.

Learn more about [debugging](/docs/tracking-best-practices/debugging#debugging-with-the-browser-console-web).

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Javascript SDK provide methods to help you protect user data.

Learn more about [Privacy](/docs/privacy/overview).

### Opt Out of Tracking

The Javascript SDK is initialized with tracking enabled by default. Use the [`.opt_out_tracking()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelopt_out_tracking) method to opt the user out of data tracking and cookies/local storage for the current Mixpanel instance.

**Example Usage**

```javascript theme={"system"}
//send "some_event"
mixpanel.track('some_event');

// opt user out of tracking
// SDK is prevented from sending any data
mixpanel.opt_out_tracking();

// this track call will not work
mixpanel.track('some_other_event');
```

**Opt Out by Default**

You can initialize the library with users opted out of tracking by default using the `opt_out_tracking_by_default` configuration. Once the user is ready to be tracked, call [`.opt_in_tracking()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelopt_in_tracking) to start tracking.

**Example Usage**

```javascript theme={"system"}
// create an instance of the Mixpanel object
// users are opted out of tracking by default
mixpanel.init('YOUR_PROJECT_TOKEN', {
    opt_out_tracking_by_default: true
    });

// this track call will not work
mixpanel.track('some_event');

//opt user in to tracking
mixpanel.opt_in_tracking();

// send "some_other_event"
mixpanel.track('some_other_event');
```

### EU Data Residency

Route data to Mixpanel's EU servers by setting a `api_host` configuration when creating the Mixpanel object.

Learn more about [EU Data Residency](/docs/privacy/eu-residency).

**Example Usage**

```javascript theme={"system"}
// create an instance of the Mixpanel object
// route requests to Mixpanel's EU servers
mixpanel.init('YOUR_PROJECT_TOKEN', {
    api_host: 'https://api-eu.mixpanel.com',
});
```

### India Data Residency

Route data to Mixpanel's India servers by setting a `api_host` configuration when creating the Mixpanel object.

Learn more about [India Data Residency](/docs/privacy/in-residency).

**Example Usage**

```javascript theme={"system"}
// create an instance of the Mixpanel object
// route requests to Mixpanel's India servers
mixpanel.init('YOUR_PROJECT_TOKEN', {
    api_host: 'https://api-in.mixpanel.com',
});
```

### Disable Geolocation

The Javascript SDK parse the request IP address to generate geolocation properties for events and profiles. To disable geolocation, set the `ip` to `false` when initializing the library.

Learn more about [geolocation](/docs/tracking-best-practices/geolocation).

**Example Usage**

```javascript theme={"system"}
//create an instance of the Mixpanel object
// disable IP address for geolocation parsing
mixpanel.init('YOUR_PROJECT_TOKEN', {
    ip: false
});
```

### Disable Default Properties

To disable [default properties](/docs/data-structure/property-reference/default-properties) from being tracked, add them to the `property_blacklist` config flag when initializing the library.

**Example Usage**

```javascript theme={"system"}
//create an instance of the Mixpanel object
// stop setting the $os and $browser event properties
mixpanel.init('YOUR_PROJECT_TOKEN', {
    property_blacklist: ['$browser','$os']
});
```

## Mixpanel Cookie

By default, Mixpanel cookies send over HTTPS requests as part of the headers. However, Mixpanel’s JavaScript library provides a configuration to completely prevent the browser from transmitting your cookies with non-HTTPS requests.

To enable this, set the `secure_cookie` configuration from the default value of `false` to `true`.

**Example Usage**

```javascript theme={"system"}
// create an instance of the Mixpanel object
mixpanel.init('YOUR_PROJECT_TOKEN', {
    'secure_cookie': true   // prevent transmitting cookie with non-HTTPs requests
});
```

If you configure your instance to send data over HTTP (instead of HTTPS) but set `secure_cookie: true`, then your cookie data will not sent to the server.

#### Hosted Subdomains

By default, Mixpanel cookie works across subdomain, keeping Mixpanel's Distinct ID and [Super Properties](/docs/tracking-methods/sdks/javascript#setting-super-properties) consistent across your sub-domains. If you set persistence: 'localStorage', cross-subdomain tracking will not work because localStorage is not shared across subdomains. For hosted subdomains (see [complete list of affected domains](https://publicsuffix.org/list/effective_tld_names.dat)) that don't allow cross-subdomain cookies, disable cross-subdomain cookie by setting the  `cross_subdomain_cookie` configuration option to `false`. Alternatively, you can also use a `CNAME` to change from `yourdomain.hostapp.com` to `yourdomain.com`.

**Example Usage**

```javascript theme={"system"}
// create an instance of the Mixpanel object
mixpanel.init('YOUR_PROJECT_TOKEN', {
    'cross_subdomain_cookie': false   // prevent cookie persistence across subdomains
});
```

## Tracking Via Proxy

You can route events from Mixpanel's SDKs via a proxy in your own domain, which can reduce the likelihood of ad-blockers impacting your tracking.

<Frame>
  <img alt="image" />
</Frame>

There are two steps: setting up a proxy server and pointing our JavaScript SDK at your server.

### Step 1: Set up a proxy server

Below is a complete nginx reference configuration that proxies all Mixpanel traffic — tracking, Session Replay, and CDN assets — through your own domain. Adapt the path prefix and domain to your environment.

```nginx theme={"system"}
# -------------------------------------------------------------------
# Mixpanel Proxy – nginx reference config
# -------------------------------------------------------------------
# Proxies tracking, Session Replay, and CDN assets through your domain.
#
# Adapt the /_mp/ prefix and upstream hosts as needed.
# Using a variable for the upstream host forces nginx to use its
# configured resolver instead of the system resolver.
# -------------------------------------------------------------------

# Tracking endpoints → api.mixpanel.com
# If you have EU or IN residency enabled, use api-eu.mixpanel.com or api-in.mixpanel.com respectively
location /_mp/api/ {
    proxy_ssl_server_name on;
    proxy_set_header Host api.mixpanel.com;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $server_name;
    client_max_body_size 10m;
    proxy_pass https://api.mixpanel.com/;
}

# Proxy all async module files (recorder, targeting, etc.) to cdn.mxpnl.com/libs/
location /_mp/libs/ {
    proxy_ssl_server_name on;
    proxy_set_header Host cdn.mxpnl.com;
    proxy_pass https://cdn.mxpnl.com/libs/;
}
```

### Step 2: Point the JavaScript SDK at your proxy

Set `MIXPANEL_CUSTOM_LIB_URL` **before** the Mixpanel JS snippet to load the SDK itself through your proxy (not required if you load the SDK via npm/yarn):

```javascript theme={"system"}
const MIXPANEL_PROXY_HOST = "https://your-domain.com/_mp";
const MIXPANEL_CUSTOM_LIB_URL = MIXPANEL_PROXY_HOST + "/libs/mixpanel-2-latest.min.js";
```

Then pass the proxy paths in `mixpanel.init`:

```javascript theme={"system"}
mixpanel.init("YOUR_PROJECT_TOKEN", {
    api_host: MIXPANEL_PROXY_HOST + "/api",
    lib_base_path: MIXPANEL_PROXY_HOST + "/libs/",
});
```

| Init option     | Purpose                                                                                                                 |
| --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `api_host`      | Routes all tracking & Session Replay API calls through your proxy                                                       |
| `lib_base_path` | Base path for all async SDK modules (recorder, targeting, etc.) — loads them from your proxy instead of `cdn.mxpnl.com` |

<Warning>
  If you use Session Replay but only set `api_host` without setting `lib_base_path`, ad-blockers may still block the async module scripts loaded from `cdn.mxpnl.com`.
</Warning>

### Troubleshooting

| Symptom                                         | Likely cause                                                                                                                                                                                                      |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Session Replay recordings missing or corrupted  | Proxy is not forwarding `Authorization` / `Content-Encoding` headers correctly                                                                                                                                    |
| 4xx/5xx on tracking calls                       | Proxy path prefix not stripped properly — verify `proxy_pass` rewrites match your location blocks                                                                                                                 |
| Ad-blocker still blocks requests                | CDN assets are still loaded directly from `cdn.mxpnl.com` — set `MIXPANEL_CUSTOM_LIB_URL` and `lib_base_path`                                                                                                     |
| Feature flag requests `/flags` failing with 401 | The `/flags` endpoint requires an `Authorization` header, unlike `/track` which only needs the project token. Ensure your proxy explicitly forwards the `Authorization` header to Mixpanel and does not strip it. |

## Session Replay

See the developer's guide to implementing Session Replay with the Javascript SDK [here](/docs/tracking-methods/sdks/javascript/javascript-replay).

## Release History

[See All Releases](https://github.com/mixpanel/mixpanel-js/releases).


# Implement Feature Flags (Web)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript/javascript-flags



## Overview

This developer guide will assist you in configuring your web platform for Feature Flags using the [Mixpanel JavaScript SDK](/docs/tracking-methods/sdks/javascript). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

For complete JavaScript SDK documentation, see the [JavaScript SDK guide](/docs/tracking-methods/sdks/javascript).

## Prerequisites

Before implementing Feature Flags, ensure:

* You are on an Enterprise subscription plan and have the latest version of the SDK installed (minimum supported version is [`v2.71.0`](https://github.com/mixpanel/mixpanel-js/releases/tag/v2.71.0)). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK.
* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Flag Initialization

Initializing the SDK with the `flags` option enables making an outbound request to Mixpanel servers with the current user context.

The server will assign the user context to a variant for each feature flag according to the how they are configured in the Mixpanel UX.

The response will include an assigned variant for each flag that the user context is in a rollout group for. If a flag is not returned, it most likely signifies that the user was either not in the rollout percentage for a flag or in the configured targeting cohort.

**Example Usage**

```javascript Javascript theme={"system"}
mixpanel.init("YOUR_PROJECT_TOKEN", {
  debug: true,
  flags: true,
});
```

If your flag is configured with a Variant Assignment Key other than `distinct_id` or `device_id` for any of the feature flags in your project, then the call to initialize feature flags must include those keys.

For example, for a Variant Assignment Key, `company_id`, you would setup the SDK as follows.

```javascript Javascript theme={"system"}
mixpanel.init("YOUR_PROJECT_TOKEN", {
  debug: true,
  flags: {
    context: {
      company_id: "X",
    },
  },
});
```

If you are using Runtime Targeting in any of the feature flags in your project, then any properties that you use in targeting should be included in a `custom_properties` node within `context`:

```javascript theme={"system"}
mixpanel.init("YOUR_PROJECT_TOKEN", {
  debug: true,
  flags: {
    context: {
      company_id: "X",
      custom_properties: {
        platform: "web",
      },
    },
  },
});
```

## Flag Persistence

Minimum supported SDK version: [`v2.79.0`](https://github.com/mixpanel/mixpanel-js/releases/tag/v2.79.0)

By default, the SDK is in `networkOnly` persistence mode, where the network call for flag assignments are made and then we wait for the network response before async variant calls complete. You can enable persistence to store assignments in IndexedDB so they are available immediately on subsequent page loads.

Configure a `variantLookupPolicy` in the `flags` init options:

**`networkFirst`** — The SDK waits for the network on every launch. If the network call fails, the persisted value is returned as a fallback. Async getter calls block until the fetch completes (or the fallback is resolved).

```javascript theme={"system"}
mixpanel.init("YOUR_PROJECT_TOKEN", {
  flags: {
    persistence: {
      variantLookupPolicy: "networkFirst",
    },
  },
});

// The async get_variant_value waits for the call to succeed and falls back to persisted value if it exists. 
const variant_value = await mixpanel.flags.get_variant_value("my-feature-flag", "control");
```

**`persistenceUntilNetworkSuccess`** — Persisted variants are returned immediately on page load if they exist and are valid. Once a network call for flags succeeds, it will overwrite previously loaded persisted values.

```javascript theme={"system"}
mixpanel.init("YOUR_PROJECT_TOKEN", {
  flags: {
    persistence: {
      variantLookupPolicy: "persistenceUntilNetworkSuccess",
    },
  },
});

// get_variant_value returns immediately from persistence even if the network call is still in progress.
const variant_value = await mixpanel.flags.get_variant_value("my-feature-flag", "control");
```

To customize the TTL, add `persistenceTtlMs` alongside `variantLookupPolicy`. By default, the TTL is 24 hours.

```javascript theme={"system"}
mixpanel.init("YOUR_PROJECT_TOKEN", {
  flags: {
    persistence: {
      variantLookupPolicy: "networkFirst",
      persistenceTtlMs: 12 * 60 * 60 * 1000, // 12 hours
    },
  },
});
```

### Variant source

Every variant carries a `variant_source` field indicating where the value came from: `"network"`, `"persistence"`, or `"fallback"`. Use `get_variant` to receive the full variant object including this metadata.

```javascript theme={"system"}
const fallback = { key: "control", value: "control" };
const variant = await mixpanel.flags.get_variant("my-feature-flag", fallback);

const value = variant.value;
const source = variant.variant_source; // "network", "persistence", or "fallback"
```

### `$experiment_started` properties

When a variant is served, the `$experiment_started` exposure event includes:

* `$variant_source` — `"network"` or `"persistence"`
* `$persisted_at_in_ms` — epoch ms from when the persisted variant set was first stored.
* `$ttl_in_ms` — the configured TTL in ms, if the variant was from persistence

<Note>
  Persisted variants are tied to the current `distinct_id`. Calling `identify()` with a new ID or calling `reset()` clears persisted data and triggers a fresh fetch.
</Note>

## Flag Reload

Following initialization, you can reload feature flag assignments in a couple of ways:

1. After a user logs in or out of your application and you call `identify`, a feature flag reload will be triggered.

```javascript theme={"system"}
updated_distinct_id = ""
mixpanel.identify(updated_distinct_id)
```

2. To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags with a new context:

```javascript theme={"system"}
mixpanel.flags.update_context({
  company_id: "Y",
  custom_properties: {
    platform: "mobile",
  },
});
```

3. Calling `reset()` clears all feature flag assignments from memory and triggers a new fetch for the updated `distinct_id`. Requires SDK version [`v2.79.0`](https://github.com/mixpanel/mixpanel-js/releases/tag/v2.79.0) or later.

```javascript theme={"system"}
mixpanel.reset();
// Flags are cleared immediately. A new fetch begins for the anonymous distinct_id.
```

## Flag Evaluation

Lookup the assigned value for a feature flag. This action triggers tracking an exposure event, `$experiment_started` to your Mixpanel project.

### Asynchronous Flag Variant Retrieval

**Experiment Flags: Get Variant Value**

```javascript theme={"system"}
// Fetch the variant value once flags are ready and track an exposure event *if* the user context is in a rollout group for the feature flag.
const fallback = "control"; // the value to use if the user doesn't match any of the flag's rollout rules
const variant_value = await mixpanel.flags.get_variant_value("my-feature-flag", fallback);

// Use flag value in your application logic
if (variant_value == "variant_a") {
  showExperienceForVariantA();
} else if (variant_value == "variant_b") {
  showExperienceForVariantB();
} else if (variant_value == "control") {
  showDefaultExperience();
}
```

**Feature Gates: Check if Flag is Enabled/Disabled**

```javascript theme={"system"}
// Fetch the variant value once flags are ready and track an exposure event *if* the user context is in a rollout group for the feature flag.
const fallback = false;
const isEnabled = await mixpanel.flags.is_enabled("my-feature-flag", fallback);

// Use the result in your application logic. 
if (isEnabled) {
  showNewFeature();
} else {
  showOldFeature();
}
```

### Synchronous Flag Variant Retrieval

**Experiment Flags: Get Variant Value**

```javascript theme={"system"}
// Fetch the variant value once flags are ready and track an exposure event *if* the user context is in a rollout group for the feature flag.
const fallback = "control"; // the value to use if the user doesn't match any of the flag's rollout rules
const variant_value = mixpanel.flags.get_variant_value_sync("my-feature-flag", fallback);

// Use flag value in your application logic
if (variant_value == "variant_a") {
  showExperienceForVariantA();
} else if (variant_value == "variant_b") {
  showExperienceForVariantB();
} else if (variant_value == "control") {
  showDefaultExperience();
}
```

**Feature Gates: Check if Flag is Enabled/Disabled**

```javascript theme={"system"}
// Fetch the variant value once flags are ready and track an exposure event *if* the user context is in a rollout group for the feature flag.
const fallback = false;
const isEnabled = mixpanel.flags.is_enabled_sync("my-feature-flag", fallback);

// Use the result in your application logic. 
if (isEnabled) {
  showNewFeature();
} else {
  showOldFeature();
}
```

## Frequently Asked Questions

### What if I'm not receiving any flags on SDK initialization?

1. **Check your project token**:

   * Ensure you're using the correct project token from your [Mixpanel project settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)
2. **Review flag configuration**:

   * Make sure your feature flag is enabled
   * Check the flag's rollout percentage

     * User contexts that are not assigned to the rollout percentage will not be assigned variant values
   * If you are using a targeting cohort, verify on the mixpanel 'Users' page that the user's `distinct_id` is a member of that cohort.
3. **Review SDK parameters**:

   * Ensure `flags: true` or `flags: { context: {...} }` is included in the init options
   * If using a custom Variant Assignment Key, ensure it is included in the `context` object
   * If using Runtime Targeting, ensure all properties used in targeting are included in the `custom_properties` object within `context`
4. **Enable debug mode**: Use `debug: true` in initialization to see detailed logs in the browser console


# OpenFeature Provider (Web)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript/javascript-openfeature



## Overview

This guide covers using Mixpanel's [Feature Flags](/docs/featureflags) through the [OpenFeature](https://openfeature.dev/) standard with the Mixpanel Web OpenFeature provider. OpenFeature provides a vendor-agnostic API for feature flag evaluation, allowing you to switch between providers without changing your application code.

For the native Mixpanel SDK approach, see the [Feature Flags (Web)](/docs/tracking-methods/sdks/javascript/javascript-flags) guide.

## Prerequisites

* Enterprise subscription plan with Feature Flags enabled
* Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Installation

```bash theme={"system"}
npm install @mixpanel/openfeature-web-provider @openfeature/web-sdk mixpanel-browser
```

## Quick Start

```typescript theme={"system"}
import mixpanel from 'mixpanel-browser';
import { OpenFeature } from '@openfeature/web-sdk';
import { MixpanelProvider } from '@mixpanel/openfeature-web-provider';

// 1. Initialize Mixpanel with feature flags
mixpanel.init('YOUR_PROJECT_TOKEN', {
  flags: {
    context: { plan: 'premium' }
  }
});

// 2. Create and register the Mixpanel provider
const provider = new MixpanelProvider(mixpanel.flags);
await OpenFeature.setProviderAndWait(provider);

// 3. Get a client and evaluate flags
const client = OpenFeature.getClient();
const showNewFeature = client.getBooleanValue('new-feature-flag', false);

if (showNewFeature) {
  console.log('New feature is enabled!');
}
```

## Usage

### Flag Types and Evaluation Methods

| Mixpanel Flag Type | Variant Values                          | OpenFeature Method                                                                 |
| ------------------ | --------------------------------------- | ---------------------------------------------------------------------------------- |
| Feature Gate       | `true` / `false`                        | `getBooleanValue()`                                                                |
| Experiment         | boolean, string, number, or JSON object | `getBooleanValue()`, `getStringValue()`, `getNumberValue()`, or `getObjectValue()` |
| Dynamic Config     | JSON object                             | `getObjectValue()`                                                                 |

```typescript theme={"system"}
const client = OpenFeature.getClient();

// Feature Gate
const isFeatureOn = client.getBooleanValue('new-checkout', false);

// Experiment with string variants
const buttonColor = client.getStringValue('button-color-test', 'blue');

// Experiment with number variants
const maxItems = client.getNumberValue('max-items', 10);

// Dynamic Config
const featureConfig = client.getObjectValue('homepage-layout', {
  layout: 'grid',
  itemsPerRow: 3
});
```

### Evaluation Context

Context must be set globally via `OpenFeature.setContext()`:

```typescript theme={"system"}
await OpenFeature.setContext({
  email: 'user@example.com',
  plan: 'premium'
});
```

<Warning>
  Per-evaluation context (the optional third argument to evaluation methods) is **not supported** by this provider. Context must be set globally via `OpenFeature.setContext()`, which triggers a re-fetch of flag values from Mixpanel.
</Warning>

### Runtime Properties

Pass `custom_properties` in the evaluation context for runtime targeting:

```typescript theme={"system"}
await OpenFeature.setContext({
  custom_properties: {
    tier: 'enterprise',
    seats: 50,
    industry: 'technology'
  }
});
```

<Note>
  Unlike some providers, `targetingKey` is not used as a special bucketing key. It is passed as another context property. Mixpanel's server-side configuration determines which properties are used for targeting and bucketing.
</Note>

### Full Resolution Details

```typescript theme={"system"}
const details = client.getBooleanDetails('my-feature', false);

console.log(details.value);
console.log(details.variant);
console.log(details.reason);
console.log(details.errorCode);
```

### React Integration

```tsx theme={"system"}
import { OpenFeatureProvider, useBooleanFlagValue } from '@openfeature/react-sdk';
import { OpenFeature } from '@openfeature/web-sdk';
import mixpanel from 'mixpanel-browser';
import { MixpanelProvider } from '@mixpanel/openfeature-web-provider';

// Initialize outside of component
mixpanel.init('YOUR_PROJECT_TOKEN', {
  flags: {
    context: { plan: 'premium' }
  }
});
const provider = new MixpanelProvider(mixpanel.flags);
OpenFeature.setProvider(provider);

function App() {
  return (
    <OpenFeatureProvider>
      <MyComponent />
    </OpenFeatureProvider>
  );
}

function MyComponent() {
  const showBanner = useBooleanFlagValue('show-banner', false);

  return (
    <div>
      {showBanner && <Banner message="Welcome to our new feature!" />}
    </div>
  );
}
```

### User Identity

This provider does **not** call `mixpanel.identify()`. Manage identity through Mixpanel directly:

```typescript theme={"system"}
mixpanel.identify('user-123');
```

## Error Handling

| Error Code           | When                                                          |
| -------------------- | ------------------------------------------------------------- |
| `PROVIDER_NOT_READY` | Flags evaluated before the provider has finished initializing |
| `FLAG_NOT_FOUND`     | The requested flag does not exist in Mixpanel                 |
| `TYPE_MISMATCH`      | The flag value type does not match the requested type         |

To avoid `PROVIDER_NOT_READY`, use `setProviderAndWait`:

```typescript theme={"system"}
await OpenFeature.setProviderAndWait(provider);
```

## Troubleshooting

### Flags Always Return Default Values

1. **Feature flags not enabled:** Ensure Mixpanel was initialized with `flags` enabled:

   ```typescript theme={"system"}
   mixpanel.init('YOUR_TOKEN', { flags: { context: { plan: 'premium' } } });
   ```
2. **Provider not ready:** Use `setProviderAndWait` to ensure initialization.
3. **Network issues:** Check the browser console for failed requests.
4. **Flag not configured:** Verify the flag exists and is enabled.

### Flags Not Updating After Context Change

Update context and the provider will re-fetch flags:

```typescript theme={"system"}
await OpenFeature.setContext({ plan: 'premium' });
```


# Implement Session Replay (Web)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript/javascript-replay



## Overview

This developer guide will assist you in configuring your web platform for [Session Replay](/docs/session-replay) using the [Mixpanel JavaScript SDK](/docs/tracking-methods/sdks/javascript). Learn more about [viewing captured Replays in your project here](/docs/session-replay).

By default, Session Replay is disabled and will not be loaded into your application until explicitly enabled. In most cases, implementation is extremely simple, requiring only a single line of code to be changed.

## Prerequisite

You are a Mixpanel customer and have the latest version of the Mixpanel Javascript SDK installed (minimum supported version is [`v2.50.0`](https://github.com/mixpanel/mixpanel-js/releases/tag/v2.50.0)). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK.

## Data Residency

If your Mixpanel project lives in the EU or India data center, or you route all Mixpanel traffic through a self-hosted proxy, set `api_host` when you initialize the JavaScript SDK. Session Replay reuses the same `api_host` — there is no separate replay endpoint to configure.

| Region       | `api_host` value              |
| ------------ | ----------------------------- |
| US (default) | `https://api.mixpanel.com`    |
| EU           | `https://api-eu.mixpanel.com` |
| India        | `https://api-in.mixpanel.com` |

**Example Usage**

```javascript Javascript theme={"system"}
// Route Session Replay (and all other Mixpanel traffic) to the EU data center
mixpanel.init('YOUR_PROJECT_TOKEN', {
    api_host: 'https://api-eu.mixpanel.com',
    record_sessions_percent: 100
});
```

For self-hosted proxies, pass your proxy URL as `api_host`. If you also need the SDK to load its async module bundles (including the recorder) through your proxy instead of `cdn.mxpnl.com`, see [Tracking Via Proxy](/docs/tracking-methods/sdks/javascript#tracking-via-proxy) for the full setup.

Learn more about [EU Data Residency](/docs/privacy/eu-residency) and [India Data Residency](/docs/privacy/in-residency).

## Capturing Replays

<Warning>
  Test in a sandbox project and start with a 100% sample rate. This allows you to monitor performance, usage, and ensure your privacy rules align with your company policies.
</Warning>

You can capturing replay data using a sampling method (recommended), or customize when and where replays are captured manually using Session Replay methods provided by the SDK.

### Sampling

We recommend using the sampling method unless you need to customize when you capture replay data.

When the SDK initializes, it makes a sampling decision based on your configured sampling rate. A percentage of initializations will trigger session recording accordingly.

To enable Session Replay and set your sampling rate, set the `recording_sessions_percent` when initializing the SDK. This is the only change needed in your existing JavaScript SDK implementation to enable Session Replay.

<Note>
  To start, we recommend using an 100% sampling rate to ensure replay capture is behaving as expected, then adjust according to your specific analytics needs.
</Note>

**Example Usage**

```javascript Javascript theme={"system"}
mixpanel.init(
    "<YOUR_PROJECT_TOKEN>", 
    {
        record_sessions_percent: 100  //records 100% of all sessions
    }
);
```

### Manual Capture

To programatically start and stop replay capture, use the `start_session_recording()` and `stop_session_recording()` methods. This is optional, and can be used primarily to programmatically start and stop recording, or exclude something specific from recording.

#### Start Capturing Replay Data

Call `start_session_recording()` to force recording to begin, regardless of the `record_sessions_percent` init option.

This will have no effect if replay data collection is already in progress.

**Example Usage**

```javascript Javascript theme={"system"}
// manually trigger a replay capture
mixpanel.start_session_recording();
```

#### Pause Capturing Replay Data

Call `pause_session_recording()` to pause any active replay data collection but do not clear the active recording.

**Example Usage**

```javascript Javascript theme={"system"}
// manually pause a replay capture
mixpanel.pause_session_recording();
```

#### Resume Capturing Replay Data

Call `resume_session_recording()` to resume replay data collection.

This will have no effect if there is no non-active recording that was previously paused.

**Example Usage**

```javascript Javascript theme={"system"}
// Resume the paused replay capture.
mixpanel.resume_session_recording();
```

#### Stop Capturing Replay Data

Call `stop_session_recording()` to stop any active replay data collection.

This will have no effect if there is no replay data collection in progress.

**Example Usage**

```javascript Javascript theme={"system"}
// manually end a replay capture
mixpanel.stop_session_recording();
```

#### Example Scenarios

| Scenario                                                                  | Guidance                                                                                                                                                                                                         |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| We have a sensitive screen we don't want to capture                       | When user is about to access the sensitive screen, call `mixpanel.stop_session_recording()`. To resume recording once they leave this screen, you can resume recording with `mixpanel.start_session_recording()` |
| We only want to record certain types of users (e.g. Free plan users only) | Using your application code, determine if current user meets the criteria of users you wish to capture. If they do, then call `mixpanel.start_session_recording()` to force recording on                         |
| We only want to record users utilizing certain features                   | When user is about to access the feature you wish to capture replays for, call `mixpanel.start_session_recording()` to force recording on                                                                        |

#### Cross-Origin iFrame Recording (Requires minimum SDK version: 2.76)

Session Replay captures content from cross-origin iframes embedded within your page, delivering a unified replay experience across parent pages and embedded third-party content. To enable this feature, you must explicitly allowlist domains using record\_allowed\_iframe\_origins for security purposes.

**Example Usage**

On your parent site `www.yoursite.com`, specify the origins from which recording data is accepted:

```mixpanel.init('YOUR_PROJECT_TOKEN', { theme={"system"}
  record_sessions_percent: 100,
  record_allowed_iframe_origins: [
    'https://embedded-widget.example.com',
  ],
});
```

On the child iframe page `https://embedded-widget.example.com`, add the parent page's origin to `record_allowed_iframe_origins`:

```mixpanel.init('YOUR_PROJECT_TOKEN', { theme={"system"}
  record_sessions_percent: 100,
  record_allowed_iframe_origins: [
    'https://yoursite.com',
  ],
});
```

### Additional Configuration Options

You can customize the behavior of replay captures by using the init options outlined below.

**Example Usage**

```javascript Javascript theme={"system"}
mixpanel.init(
    "<YOUR_PROJECT_TOKEN>", 
    {
        record_sessions_percent: 1,  	//records 1% of all sessions
		record_idle_timeout_ms: 1800000 //End a replay capture after 30mins of inactivity
    }
);
```

#### Init Options

| Option                         | Description                                                                                                                                                                                                                                                          | Default                                                                                                             |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `record_block_class`           | CSS class name or regular expression for elements which will be replaced with an empty element of the same dimensions, blocking all contents.                                                                                                                        | `new RegExp('^(mp-block\|fs-exclude\|amp-block\|rr-block\|ph-no-capture)$')` <br /> (common industry block classes) |
| `record_block_selector`        | CSS selector for elements which will be replaced with an empty element of the same dimensions, blocking all contents.                                                                                                                                                | `"img, video"`                                                                                                      |
| `record_idle_timeout_ms`       | Duration of inactivity in milliseconds before ending a contiguous replay. A new replay collection will start when active again.                                                                                                                                      | `1800000`<br />(30 minutes)                                                                                         |
| `record_mask_all_text`         | When `true`, all text is masked by default. Use `record_unmask_text_selector` to selectively reveal elements.                                                                                                                                                        | `true`                                                                                                              |
| `record_mask_text_selector`    | CSS selector or array of selectors for elements to mask. Only applies when `record_mask_all_text` is `false`.                                                                                                                                                        | `undefined`                                                                                                         |
| `record_unmask_text_selector`  | CSS selector or array of selectors for elements to unmask. Only applies when `record_mask_all_text` is `true`.                                                                                                                                                       | `undefined`                                                                                                         |
| `record_mask_text_class`       | CSS class name or regular expression for elements that will have their text contents masked. Included for backward compatibility.                                                                                                                                    | `new RegExp('^(mp-mask\|fs-mask\|amp-mask\|rr-mask\|ph-mask)$')` <br /> (common industry mask classes)              |
| `record_mask_all_inputs`       | When `true`, all inputs are masked by default. Use `record_unmask_input_selector` to selectively reveal inputs. Note: [certain input types](/docs/session-replay/session-replay-privacy-controls#always-masked-inputs) are always masked regardless of this setting. | `true`                                                                                                              |
| `record_mask_input_selector`   | CSS selector or array of selectors for inputs to mask. Only applies when `record_mask_all_inputs` is `false`.                                                                                                                                                        | `undefined`                                                                                                         |
| `record_unmask_input_selector` | CSS selector or array of selectors for inputs to unmask. Only applies when `record_mask_all_inputs` is `true`.                                                                                                                                                       | `undefined`                                                                                                         |
| `record_max_ms`                | Maximum length of a single replay in milliseconds. Up to 24 hours is supported. Once a replay has reached the maximum length, a new one will begin.                                                                                                                  | `86400000`<br />(24 hours)                                                                                          |
| `record_min_ms`                | Minimum length of a single replay in milliseconds. Up to 8 seconds is supported. If a replay does not meet the minimum length, it will be discarded.                                                                                                                 | `0`<br />(0 seconds)                                                                                                |
| `record_sessions_percent`      | Percentage of SDK initializations that will qualify for replay data capture. A value of "1" = 1%.                                                                                                                                                                    | `0`                                                                                                                 |
| `record_canvas`                | When true, Mixpanel will record snapshots of `<canvas>` elements on your site at up to 15 frames per second                                                                                                                                                          | `false`                                                                                                             |
| `record_heatmap_data`          | When true, Mixpanel will capture click events during replays to populate Heatmaps. You can learn more [here](/docs/session-replay/heatmaps).                                                                                                                         | `false`                                                                                                             |
| `record_console`               | When true, Mixpanel will record console logs, warnings, and errors as part of the replay.                                                                                                                                                                            | `true`                                                                                                              |
| `record_network`               | When true, Mixpanel will record network requests as part of the replay. See [Network Recording](/docs/tracking-methods/sdks/javascript/javascript-replay#network-recording) for details.                                                                             | `false`                                                                                                             |
| `record_network_options`       | Configuration for network recording behavior, including which headers/bodies to capture. See [Network Recording Options](/docs/tracking-methods/sdks/javascript/javascript-replay#network-recording-options).                                                        | `{}`                                                                                                                |
| `remote_settings_mode`         | Setting for handling remote configuration during SDK initialization. Can be `disabled`, `fallback`, `strict`.                                                                                                                                                        | `disabled`                                                                                                          |

Note: Canvas recording (record\_canvas) utilizes [rrweb's](https://github.com/rrweb-io/rrweb) UNSAFE\_replayCanvas option, which is experimental and not fully supported. We recommend testing thoroughly before deploying to production.

**Example Usage**

```javascript theme={"system"}
// Unmask navigation and public content while keeping everything else masked
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 1,
    record_unmask_text_selector: ['.navigation', '.public-content'],
    record_unmask_input_selector: '#search-box'
});
```

```javascript theme={"system"}
// Mask only sensitive areas while showing everything else
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 1,
    record_mask_all_text: false,
    record_mask_text_selector: ['.user-data', '#billing-section'],
    record_mask_all_inputs: false,
    record_mask_input_selector: '.sensitive-input'
});
```

## Network Recording

<Note>
  Network recording is available in SDK version `v2.76.0` and above.
</Note>

Session Replay can capture network requests made during a replay, giving you visibility into API calls, resource loads, and other network activity alongside the visual playback. This is useful for debugging issues where network behavior (failed requests, slow responses, etc.) is relevant to the user experience.

Network recording is disabled by default. To enable it, set `record_network` to `true` in your init options.

**Example Usage**

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 100,
    record_network: true
});
```

By default, network recording captures timing and metadata (URL, status code, initiator type, duration) for all resource types. **No headers or request/response bodies are recorded unless you explicitly configure them.**

### Network Recording Options

For more control, use `record_network_options` to customize what gets recorded.

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 100,
    record_network: true,
    record_network_options: {
        // Only capture these resource types (default: all types)
        initiatorTypes: ['fetch', 'xmlhttprequest'],

        // Ignore requests to these URL patterns
        ignoreRequestUrls: ['https://api.example.com/health'],

        // Custom function to ignore requests based on request data
        ignoreRequestFn: function(data) {
            return data.url.includes('/internal/');
        },

        // Allowlist of headers to record (empty by default)
        recordHeaders: {
            request: ['content-type', 'authorization'],
            response: ['content-type', 'x-request-id']
        },

        // Record request/response bodies only for matching URL patterns
        recordBodyUrls: {
            request: ['https://api.example.com/submit'],
            response: ['https://api.example.com/submit']
        },

        // Capture requests that occurred before recording started
        recordInitialRequests: true
    }
});
```

#### Options Reference

| Option                  | Type                                        | Description                                                                                                                                                                                                                                        | Default                         |
| ----------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `initiatorTypes`        | `InitiatorType[]`                           | Resource types to capture. Supported types include: `fetch`, `xmlhttprequest`, `img`, `script`, `link`, `css`, `audio`, `video`, `beacon`, and [others](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/initiatorType). | All types                       |
| `ignoreRequestUrls`     | `string[]`                                  | List of URL patterns (matched as regex) to exclude from recording.                                                                                                                                                                                 | `[]`                            |
| `ignoreRequestFn`       | `(data: NetworkRequest) => boolean`         | Custom function to filter out requests. Return `true` to ignore a request. The function receives the network request data including URL, method, status, and any recorded headers.                                                                 | `() => false`                   |
| `recordHeaders`         | `{ request: string[], response: string[] }` | Allowlist of header names to record for requests and responses. Header names are case-insensitive. Only headers in this list will be captured.                                                                                                     | `{ request: [], response: [] }` |
| `recordBodyUrls`        | `{ request: string[], response: string[] }` | URL patterns (matched as regex) for which to record request and response bodies. Bodies are only recorded for `fetch` and `xmlhttprequest` initiator types.                                                                                        | `{ request: [], response: [] }` |
| `recordInitialRequests` | `boolean`                                   | When `true`, captures resource timing entries for requests that completed before recording started (e.g., initial page load resources).                                                                                                            | `false`                         |

<Warning>
  **Privacy Note:** Be mindful of what headers and bodies you choose to record. Avoid recording headers or bodies that contain sensitive information such as authentication tokens, personally identifiable information (PII), or other confidential data. Use the allowlist-based approach (`recordHeaders` and `recordBodyUrls`) to explicitly opt in to only the data you need.
</Warning>

### How It Works

Network recording uses two complementary mechanisms:

* **Performance Observer**: Captures timing data for all resource types (images, scripts, stylesheets, etc.) using the browser's [PerformanceObserver API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver). This provides URL, status code, start/end times, and initiator type.
* **Fetch & XHR monkey-patching**: For `fetch` and `xmlhttprequest` requests, the SDK wraps the native APIs to capture headers and bodies (when configured). Importantly, the SDK does not modify the original request arguments or block requests while reading response bodies — response bodies are cloned asynchronously to avoid impacting your application's performance.

## Remote Configuration

<Note>
  Available only for customers with a paid session replay add-on. Requires version 2.74.0
</Note>

By setting `remote_settings_mode` you can quickly set SDK options for your project in Mixpanel under `Settings > Organization Settings > Session Replay`.

Three modes are available:

* `disabled`: Do not use remote configuration and proceed to use the hardcoded initial options provided in `mixpanel.init`
* `fallback`: Attempt to retrieve remote configuration and proceed with those settings. If there is failure or timeout (500 ms), will use initial provided options.
* `strict`: Will prevent session replay from auto-starting unless a remote configuration was successfully retrieved.

Can use this setting to quickly update and adjust configurations to your liking.

List of currently supported remote settings:

* `record_sessions_percent`

Settings that are not yet supported, will not appear in the remote configuration. These non-included options will use the value that was initially set by the user for all `remote_settings_mode` options.

**Example Usage**

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 100,
    remote_settings_mode: 'fallback'
});
```

## Cross-Origin Iframe Recording

<Note>
  Cross-origin iframe recording requires SDK version 2.77.0 or later.
</Note>

Session Replay can capture content from cross-origin iframes embedded within your page, providing a unified replay experience across parent pages and embedded third-party content. This is useful when your application embeds widgets, checkout flows, or other cross-origin content that you want to include in your replays.

The SDK handles the communication between parent and child frames automatically using a secure handshake mechanism.

### Configuration

Both the parent page and the child iframe page must be configured to allow cross-origin recording.

#### Parent Page Setup

On your parent page, add the origins of any iframes you want to record to the `record_allowed_iframe_origins` array:

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 100,
    record_allowed_iframe_origins: [
        'https://embedded-widget.example.com',
        'https://partner-checkout.example.com'
    ]
});
```

#### Child Iframe Page Setup

On the child iframe page, add the parent page's origin to `record_allowed_iframe_origins`:

```javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
    record_sessions_percent: 100,
    record_allowed_iframe_origins: [
        'https://yoursite.com'
    ]
});
```

### Origin Format Requirements

Origins must be specified in the format `protocol://domain[:port]`. The SDK performs exact matching, so ensure your origins are formatted correctly.

| Format         | Example                    | Valid |
| -------------- | -------------------------- | ----- |
| HTTPS domain   | `https://example.com`      | ✓     |
| HTTP with port | `http://localhost:3000`    | ✓     |
| No protocol    | `example.com`              | ✗     |
| With path      | `https://example.com/page` | ✗     |
| Wildcard       | `https://*.example.com`    | ✗     |

## Replay ID

When a replay capture begins, a Replay ID is generated by the SDK and is attached as an event property (`$mp_replay_id`) to events tracked by the SDK during the capture session. Events containing the same `$mp_replay_id` will appear in the same Replay.

If you are sending any events not coming from the SDK, add the `$mp_replay_id` event property to attribute the event to a specific Replay.

You can use the `get_session_recording_properties()` method to return the Replay ID for the current replay capture. The method will return an empty object if there is no active replay capture in progress.

**Example Usage**

```javascript Javascript theme={"system"}
// return the $mp_replay_id for the currently active capture
mixpanel.get_session_recording_properties();
// {$mp_replay_id: '19221397401184-063a51e0c3d58d-17525637-1d73c0-1919139740f185'}
```

### Server-side Stitching

<Warning>
  We still recommend including the `$mp_replay_id` property on your events regardless of Server-side Stitching for guaranteed accuracy.
</Warning>

Server-Side Stitching allows you to easily watch Replays for events that were not fired from the SDK.

It works by inferring the Replay that an event belong using the Distinct ID and time property attached to the event. This is especially useful if you have events coming in from multiple sources (E.g. your server or warehouse import) and it does not make sense to pass around the value of `mixpanel.get_session_recording_properties()`.

For example, let's say a user with Distinct ID "ABC" has a Replay recorded from 1-2pm. Two hours later, an event was sent from your warehouse with a timestamp of 1:35pm with Distinct ID "ABC". Server-side Stitching will infer that the event should belong in the same Replay.

To ensure Server-Side Stitching works, call [`identify()`](/docs/tracking-methods/sdks/javascript#identify) from the client-side using our SDK with the user's `$user_id`. This guarantees that events generated from both the client-side and server-side share the same Distinct ID. Learn more about [identifying users](/docs/tracking-methods/id-management).

## Replay URL

<Note>
  Replay URLs are accessible only by authenticated users with the necessary permissions for the Mixpanel project.
</Note>

You can programatically generate URL links to view the current Replay in the Mixpanel UI using the `get_session_replay_url()` method. The method will return null if there is no Replay in progress.

This is useful for debugging or for adding metadata to other platforms. (E.g. adding replay URL to support tickets for troubleshooting)

**Example Usage**

```javascript Javascript theme={"system"}
// return the Mixpanel URL to view the current replay in the UI
mixpanel.get_session_replay_url();
// https://mixpanel.com/projects/replay-redirect?replay_id=19307d78e24394fe15-0cd98d8fd9ad1d-1f525636-4b9600-19307d78e28194fe15&distinct_id=123&token=my-project-token
```

## Heatmaps, Rage Clicks, and Dead Clicks (Web Only)

The `record_heatmap_data` option (Web only; not available on mobile) enables four types of interaction tracking during replay sessions:

1. **Click events** - Captures user clicks to populate click heatmaps
2. **Rage clicks** - Captures multiple rapid clicks on the same element (`$mp_rage_click`)
3. **Dead clicks** - Captures clicks on unresponsive elements (`$mp_dead_click`)
4. **Page Leave** - Captures when a page is "left" either by navigation or leaving the tab (`$mp_page_leave`)

These events are only captured when a session recording is in progress, and they are exempt from your plan data allowance.

Session Replay must be enabled for `record_heatmap_data` to work. Heatmaps only collect data during sessions with recorded replays. If a page has limited replay coverage, the resulting Heatmap may provide limited or less meaningful insights.

**Example Usage**

```javascript Javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
  record_sessions_percent: 1, // Session Replay must be enabled for Heatmap
  record_heatmap_data: true   // Enable Heatmap, Rage Click, and Dead Click collection
});
```

<Note>
  Events generated by `record_heatmap_data` (clicks, rage clicks, dead clicks) are exempt from your plan data allowance.
</Note>

### Alternative: Using Autocapture for Heatmaps

If you use [Autocapture](/docs/tracking-methods/autocapture) to track clicks, you can leverage these clicks to populate Heatmaps without enabling `record_heatmap_data`. Autocapture also supports rage and dead click detection.

**Example Usage**

```javascript Javascript theme={"system"}
mixpanel.init('YOUR_PROJECT_TOKEN', {
  autocapture: {
    pageview: "full-url",
    click: true, // click tracking enabled
    input: true,
    scroll: true,
    submit: true,
    capture_text_content: false,
  },
  record_sessions_percent: 1 // Session Replay enabled, recording 1% of all sessions
});
```

Clicks captured by Autocapture are billable events that are counted against your plan data allowance.

## Debugging

<Note>
  `$mp_session_record` is exempt from your plan data allowance.
</Note>

To check your implementation, select **Session Replay** from the side navigation in your Mixpanel project to see whether replays are being captured and appearing as expected. When a capture begins, a "Session Recording Checkpoint" event (`$mp_session_record`) also appears in your project; you can use this to verify that Session Replay is implemented correctly.

If you are using the [recommended sampling method](/docs/tracking-methods/sdks/javascript/javascript-replay#sampling) to capture your Replays but having trouble finding the Replays in your project, try calling `start_session_recording()` manually and see if the `$mp_session_record` event appears. If it does appear but you are still struggling to locate your Replays, you may want to increase your sampling rate.

If you are still struggling to implement, [submit a request to our Support team](https://mixpanel.com/get-support) for more assistance.

## Session Replay with a CDP

You can use Session Replay with customer data platforms (CDPs), such as [Segment](https://segment.com/) and [mParticle](https://www.mparticle.com/).

In order to use Session Replay, your app must have the [Mixpanel Javascript SDK installed](/docs/tracking-methods/sdks/javascript#installing-the-library) with [Session Replay enabled](/docs/tracking-methods/sdks/javascript/javascript-replay#capturing-replays).

Once you have included the Mixpanel SDK in your app add the following code snippets in order to connect your CDP's data stream with Mixpanel's Session Replay.

### Segment: Analytics.js

By [adding middleware to Segment's SDK](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/middleware/) we can ensure that all event calls include the session replay properties. We can also ensure that any [identify](https://segment.com/docs/connections/spec/identify/) calls are also passed to Mixpanel.

```javascript Javascript theme={"system"}
// Middleware to add Mixpanel's session recording properties to Segment events
analytics.addSourceMiddleware(({ payload, next, integrations }) => {
	if (payload.obj.type === 'track' || payload.obj.type === 'page') {
		if (window.mixpanel) {
			const segmentDeviceId = payload.obj.anonymousId;
			// -------------------------------------------
			// Comment out one of the below mixpanel.register methods depending on your ID Management Version
			// Original ID Merge
			mixpanel.register({ $device_id: segmentDeviceId, distinct_id : segmentDeviceId });
			// Simplified ID Merge
			mixpanel.register({ $device_id: segmentDeviceId, distinct_id : "$device:"+segmentDeviceId }); 
			// -------------------------------------------	
			const sessionReplayProperties = mixpanel.get_session_recording_properties();
			payload.obj.properties = {
				...payload.obj.properties,
				...sessionReplayProperties
			};
		}
	}
	if (payload.obj.type === 'identify') {
		if (window.mixpanel) {
			const userId = payload.obj.userId;
			mixpanel.identify(userId);
		}
	}
	next(payload);
});
```

### mParticle: Web SDK

mParticle offers a direct integration for Session Replay with Mixpanel. You can configure Session Replay settings directly in your mParticle connection settings, which automatically handles session replay properties on all events.

#### Direct Integration (Recommended)

To use the direct integration:

1. Ensure you have the mParticle Mixpanel Web integration enabled for your web workspace. This will load the Mixpanel JavaScript SDK and Session Replay on your site automatically via mParticle (no separate SDK install in your app code is required).
2. Configure Session Replay settings in your [mParticle Mixpanel connection settings](https://docs.mparticle.com/integrations/mixpanel/event/#connection-settings), including:

   * **Session Recording Percentage**: Percentage of SDK initializations that will qualify for replay data capture
   * **Record Heatmap Data**: Enable heatmap, rage click, and dead click collection
   * Additional privacy and configuration options as needed

The direct integration automatically includes session replay properties (`$mp_replay_id`) on all events forwarded through mParticle, without requiring any additional code changes.

### Rudderstack: Cloud Mode

Rudderstack's Javascript SDK has a `.getAnonymousId()` method which can be used to [retrieve the device\_id](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/#retrieving-anonymous-id). In the following example, we use this method to bind Rudderstack's anonymousId to Mixpanel's device\_id, as well as patching [track](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/#track) and [page](https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/supported-api/#page) event methods to include session replay properties on every Rudderstack event.

<Note>
  **Race Condition Note (RudderStack + Heatmaps):** If you are using `record_heatmap_data`, set it to `false` at init and enable it via `set_config()` only after the RudderStack anonymousId has been registered. This prevents heatmap click events from firing with Mixpanel's default `$device_id` before your custom identity binding completes, which can create orphaned anonymous profiles and inflate MTU counts.
</Note>

```javascript Javascript theme={"system"}
mixpanel.init('MIXPANEL-PROJECT-TOKEN', {
  // Set your desired sampling rate at init — the sampling decision is evaluated here.
  record_sessions_percent: 10,

// Disabled initially to prevent race condition with RudderStack ID binding.
  // Remove this line if you are not using heatmaps.
  record_heatmap_data: false,
  autocapture: false, //optional set to true if using Autocapture
  loaded: function (mixpanel) {
    window.rudderanalytics.ready(function() {
      const rudderAnonymousId = rudderanalytics.getAnonymousId();
       if (rudderAnonymousId) {
        // Idempotency guard prevents double-prefixing on repeat page loads.
        if (!rudderAnonymousId.startsWith('$device:')) {
          rudderanalytics.setAnonymousId('$device:' + rudderAnonymousId);
        }

        mixpanel.register({
          $device_id: rudderAnonymousId,
          distinct_id: '$device:' + rudderAnonymousId,
        });
        mixpanel.set_config({ record_heatmap_data: true });
      }
 
      // Patch track method to include sessionReplayProperties
      const originalTrack = rudderanalytics.track;
      rudderanalytics.track = function (eventName, eventProperties, options, callback) {
        const sessionReplayProperties = mixpanel.get_session_recording_properties();
        eventProperties = {
          ...eventProperties,
          ...sessionReplayProperties,
        };
        originalTrack(eventName, eventProperties, options, callback);
      };
 
      // Patch page method to include sessionReplayProperties
      const originalPage = rudderanalytics.page;
      rudderanalytics.page = function (category, name, properties, options, callback) {
        const sessionReplayProperties = mixpanel.get_session_recording_properties();
        properties = {
          ...properties,
          ...sessionReplayProperties,
        };
        originalPage(category, name, properties, options, callback);
      };
    });
  }
});
```

### Google Tag Manager

You can use session replay with Google Tag Manager (GTM). First, make sure you have the [Mixpanel GTM Template](/docs/tracking-methods/integrations/google-tag-manager) installed in your workspace.

Once that is added, you can add a new Mixpanel tag to your workspace which turns on Session Replay by following these instructions:

* Add a new tag, and choose the Mixpanel tag type.
* For `Project Token` fill in your Mixpanel project's token
* For `Tag Type` choose `init` from the dropdown
* For `Initialization` choose `Set Options Manually`
* In the `Option key` / `Option value` dropdown, ensure you choose `record_sessions_percent` and the value should be a number between 1 and 100.
* This is also where you can configure other [Session Replay options](/docs/tracking-methods/sdks/javascript#init-options) like `record_block_class` etc...
* For the `Triggering` section, you'll want to choose something [early in the GTM lifecycle](https://support.google.com/tagmanager/answer/7679319?hl=en); typically this is `Initialization - All Pages` or `Consent Initialization - All Pages` to ensure that Session Replay starts recording as soon as the GTM container is initialized.
* Save + Deploy this template to your website and you should be up and going with session replay

Here's a screenshot of a working session replay tag for a visual comparison:

<Frame>
  <img />
</Frame>

## Privacy

Mixpanel offers a privacy-first approach to Session Replay, including features such as data masking. Mixpanel's Session Replay privacy controls were designed to assist customers in protecting end user privacy. Read more [here](/docs/session-replay/session-replay-privacy-controls).

### User Data

By default, all text and inputs on a page are masked. You can selectively unmask elements using `record_unmask_text_selector` and `record_unmask_input_selector`, or change the default behavior using `record_mask_all_text` and `record_mask_all_inputs`.

Note that [certain sensitive input types](/docs/session-replay/session-replay-privacy-controls#always-masked-inputs) (password, email, tel, hidden, and inputs with autocomplete attributes) are always masked regardless of your configuration.

Along with other data, the SDK respects all Do Not Track (DNT) settings as well as manual opt-out for any replay data.

### Retention

User replays are stored for 30 days after the time of ingestion by default. Customers with the custom volumes of Session Replay can customize this value between 7 and 365 days as an additional paid add-on.

### Browser Storage

Session Replay stores temporary replay data in the browser using IndexedDB with dynamically generated key names prefixed with `__mprec_` (short for "Mixpanel Recording"). These keys are used for session recording batchers and are constructed dynamically, for example:

```text theme={"system"}
__mprec_<instance_name>_<project_token>_<replay_id>
```

Where:

* `__mprec_` identifies the data as Session Replay recording data
* `<instance_name>` is the Mixpanel instance name (from `getConfig('name')`)
* `<project_token>` is your Mixpanel project token
* `<replay_id>` is a unique identifier for the recording session

Each key stores temporary data required to construct a user's Session Replay and is deleted from IndexedDB after the data is successfully sent to Mixpanel.

Some consent management platforms (like Cookiebot) require cookie or storage keys to be pre-declared and may not support dynamically generated names without manual configuration. If you use a CMP, you may need to work with their support team to properly classify these keys.

## FAQ

#### Can I prevent Session Replay from recording sensitive content?

By default, all on-screen text and input elements are masked in replays. You can selectively unmask elements using `record_unmask_text_selector` and `record_unmask_input_selector`. Additionally, [certain sensitive input types](/docs/session-replay/session-replay-privacy-controls#always-masked-inputs) are always masked regardless of configuration. Consider the [manual capture example scenarios](/docs/tracking-methods/sdks/javascript/javascript-replay#example-scenarios) and [init options](/docs/tracking-methods/sdks/javascript/javascript-replay#init-options) provided above to customize the replay capture of your implementation.

#### How can I estimate how many Replays I will generate?

If you already use Mixpanel, the [Session Start events](/docs/features/sessions) are a way to estimate the rough amount of replays you might expect. This is especially true if you use timeout-based query sessions. However, because our sessions are defined at query time, we cannot guarantee these metrics will be directly correlated.

When you enable Session Replay, use the above proxy metric to determine a starting sampling percentage, which will determine how many replays will be sent. You can always adjust this as you go to calibrate to the right level.

#### How does Session Replay affect my website's performance?

Mixpanel leverages the open-source library, [rrweb](https://github.com/rrweb-io/rrweb), to power Session Replay. Both rrweb and Mixpanel are designed with the highest standards of performance in mind.

Below is a high-level overview of how the SDK will work on your website:

* Initial Snapshot: When recording starts, rrweb takes a snapshot of the entire webpage's structure (the DOM), assigning unique IDs to each element for change tracking.
* Change Detection: Asynchronously monitors any changes that occur to the DOM using MutationObserver, minimizing work so that we do not need to keep taking full snapshots.
* User Interactions: Listens for actions like clicks and mouse movements and throttles any high frequency events.
* Collection & Delivery: Mixpanel collects the recording data and sends it to our servers in batches every 10 seconds.
* Optimized Compression: Before sending, Mixpanel will compress the payload using the asynchronous CompressionStream API. This will optimize bandwidth while not blocking the UI thread.

We have tested the SDK extensively and it generally has minimal impact on how your website performs. The initial snapshot takes a bit of work, and naturally, more complex and interactive pages generate more data for rrweb and Mixpanel to handle. So, it is always a good practice to do some performance testing after you have implemented Session Replay, just to be sure everything is running smoothly.

#### Does session recording persist across page loads?

Session recording does persist across page load for SDK v2.61.0+. See [the release note](https://github.com/mixpanel/mixpanel-js/releases/tag/v2.61.0).


# Mixpanel SDKs: Node.js
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/nodejs



## Getting Started

This Mixpanel Node.js library provides many of the features in available in the [JavaScript SDK](/docs/tracking-methods/sdks/javascript). It is fully async, and intended to be used in Javascript server-side outside of the browser (such as importing past events with a script).

For the in-browser client-side library, please use the [JavaScript SDK](/docs/tracking-methods/sdks/javascript).

The [Library Source Code](https://github.com/mixpanel/mixpanel-node) and an [Example Application](https://github.com/mixpanel/mixpanel-node/blob/master/example.js) is documented in our GitHub repo.

## Installing the Library

<Note>
  The [Javascript library](/docs/tracking-methods/sdks/javascript) is named `mixpanel-browser` in NPM. This is to distinguish it from this server-side Node.js library, which is available as `mixpanel`.
</Note>

Use [npm](https://www.npmjs.com/) to install Mixpanel. Open your CLI, and run the following command in your root directory to install the library:

```bash theme={"system"}
# install Mixpanel using npm
npm install mixpanel
```

After installation, import the Mixpanel class in your code and create the Mixpanel object using the [`.init()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/mixpanel-node.d.ts#L64) method with [your project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).

```javascript Javascript theme={"system"}
// import the Mixpanel class
const Mixpanel = require('mixpanel');

// create an instance of the mixpanel object
const mp = Mixpanel.init('YOUR_PROJECT_TOKEN')
```

## Library Configuration

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/nodejs#privacy-friendly-tracking).
</Warning>

The Mixpanel object can be initialized with different configurations. See a complete list of the configuration options[here](https://github.com/mixpanel/mixpanel-node/blob/master/lib/mixpanel-node.d.ts#L17).

You can override the default configuration using the `config` argument when initializing the library.

**Example Usage**

```javascript Javascript theme={"system"}
const Mixpanel = require('mixpanel');

// initialize mixpanel with verbose enabled
const mp = Mixpanel.init('YOUR_PROJECT_TOKEN',{
    verbose: true,
  }
);
```

## Sending Events

Use [`track()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/mixpanel-node.d.ts#L67) to send an event by providing the distinct\_id, event name, and any event properties. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```javascript theme={"system"}
const Mixpanel = require('mixpanel');
const mp = Mixpanel.init('YOUR_PROJECT_TOKEN');

// track "some_event" for distinct_id 12345
// with "plan" event prop
mp.track('some_event', {
    distinct_id: '12345',
    plan: 'premium'
});
```

Mixpanel determines default geolocation data (`$city`, `$region`, `mp_country_code`) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your data center. [Learn more about best practices for geolocation.](/docs/tracking-best-practices/geolocation).

<Note>
  Note that tracking with Node in an async serverless implementation requires you to wait for the Mixpanel request to complete. The easiest way to do this would be to pass in in a callback as a 3rd parameter into `track` and return a promise that is resolved when the request is sent.
</Note>

### Importing Historical Events

The [`track()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/mixpanel-node.d.ts#L67) function is designed for real-time tracking in a server-side environment and will trigger request to the [/track API endpoint](/reference/track-event), which will validate for events with a time stamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested.**

Use the [`import()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/mixpanel-node.js#L349) function to import events that occurred more than 5 days in the past. The `import()` function is based on the [/import API endpoint](/reference/import-events).

**Example Usage**

```javascript theme={"system"}
const Mixpanel = require('mixpanel');
const mp = Mixpanel.init('YOUR_PROJECT_TOKEN');

// import an old event for distinct_id 12345
// with epoch timestamp 1698023982
// with "plan" event prop
mp.import('some_event', 1698023982, {
      distinct_id: '12345',
      plan: 'premium'
  });
```

You can also use the [mp-utils python module](https://github.com/mixpanel/mixpanel-utils) designed for scripting.

## Managing User Identity

Since the Node.js  SDK is a server-side library, IDs are not generated by the SDK. Instead, you will need to generate and manage the distinct\_id yourself and include it in your events and profile data.

Learn more about [server-side identity management](/docs/tracking-methods/id-management/identifying-users-simplified#server-side-identity-management).

## Storing User Profiles

Create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Mixpanel object contains a `people` property, that exposes the [`MixpanelPeople`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/people.js) class which contain methods for managing user profile properties. These methods will trigger requests to the [/engage API endpoint](/reference/profile-set).

Mixpanel determines default geolocation data (`$city`, `$region`, `mp_country_code`) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your data center. [Learn more about best practices for geolocation.](/docs/tracking-best-practices/geolocation).

### Setting Profile Properties

Set profile properties on a user profile by calling [`people.set()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/people.js#L41).

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```javascript theme={"system"}
// initialize Mixpanel
const Mixpanel = require('mixpanel');
const mp = Mixpanel.init('YOUR_PROJECT_TOKEN');

// create a user profile with name and plan user props
mp.people.set('sample_distinct_id', {
    name: 'sam',
    plan: 'premium',
    ip: '0' // do not update geolocation
});

// overwrite "name" user prop with "samantha"
mp.people.set('sample_distinct_id', {
    name: 'samantha',
    ip: '0'
});
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods in the `MixpanelPeople` class [here](https://github.com/mixpanel/mixpanel-node/blob/master/lib/people.js).

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title="set_once()">
    The [`people.set_once()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/people.js#L22) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```javascript theme={"system"}
    // initialize Mixpanel
    const Mixpanel = require('mixpanel');
    const mp = Mixpanel.init('YOUR_PROJECT_TOKEN');

    // create a user profile with name and plan user props
    mp.people.set('sample_distinct_id', {
        name: 'sam',
        plan: 'premium',
        ip: '0'
    });

    // will be ignored since "name" already exists
    mp.people.set_once('sample_distinct_id', {
        name: 'samantha',
        ip: '0'
    });

    //set "location" user prop since it does not exist
    mp.people.set_once('sample_distinct_id', {
        location: 'san francisco',
        ip: '0'
    });
    ```
  </Tab>

  <Tab title="append()">
    The [`people.append()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/people.js#L141) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```javascript theme={"system"}
    // initialize Mixpanel
    const Mixpanel = require('mixpanel');
    const mp = Mixpanel.init('YOUR_PROJECT_TOKEN');

    // create a user profile with name and roles user props
    mp.people.set('sample_distinct_id', {
        name: 'sam',
        roles: ['sales','engineer'],
        ip: '0'
    });

    // add "legal" to "roles"  
    // new role values are ['sales','engineer','legal']
    mp.people.append('sample_distinct__id', 'roles', 'legal');

    // .append() allows duplicates
    // new "roles" values are ['sales','engineer','legal', 'legal']
    mp.people.append('sample_distinct__id', 'roles', 'legal');
    ```
  </Tab>

  <Tab title="union()">
    The [`people.union()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/people.js#L309) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```javascript theme={"system"}
    // initialize Mixpanel
    const Mixpanel = require('mixpanel');
    const mp = Mixpanel.init('YOUR_PROJECT_TOKEN');

    // create a user profile with name and roles user props
    mp.people.set('sample_distinct_id', {
        name: 'sam',
        roles: ['sales','engineer'],
        ip: '0'
    });

    // "engineer" ignored since it already exists
    // append "legal" to "roles"
    mp.people.union('sample_distinct__id', {
      'roles': ['engineer','legal']
    });

    ```
  </Tab>

  <Tab title="increment()">
    The [`people.increment()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/people.js#L69) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```javascript theme={"system"}
    // initialize Mixpanel
    const Mixpanel = require('mixpanel');
    const mp = Mixpanel.init('YOUR_PROJECT_TOKEN');

    // create a user profile with name and age user props
    mp.people.set('sample_distinct_id', {
        name: 'sam',
        age: 25,
        ip: '0'
    });

    // increment "age" by 2
    mp.people.increment('sample_distinct_id', 'age', 2);

    // use negative number to decrement
    // decrement "age" by 5
    mp.people.increment('sample_distinct_id', 'age', -5);
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

### Sending Group Identifiers With Events

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

To send group identifiers with your events, set the `group_key` as an event property with the `group_id` as the value.

**Example Usage**

```javascript theme={"system"}
// track "some_event" with a "distinct_id"
// event is attributed to the "mixpanel" company group
mp.track('some_event', {
    'distinct_id': 'sample_distinct_id',
    'Plan Type': 'Premium',
    'company': 'mixpanel'
});
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

**Example Usage**

```javascript theme={"system"}
// track "some_event" with a "distinct_id"
// event is attributed to 2 company groups: "mp-us" and "mp-eu"
mp.track('some_event', {
    'distinct_id': 'sample_distinct_id',
    'Plan Type': 'Premium',
    'company': ['mp-us','mp-eu']
});
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `people.set()` call.

**Example Usage**

```javascript theme={"system"}
// initialize Mixpanel
const Mixpanel = require('mixpanel');
const mp = Mixpanel.init('YOUR_PROJECT_TOKEN');

// set group key "company" as a user prop
// with group id "mixpanel" as value
mp.people.set('sample_distinct_id', {
    name: 'sam',
    company: 'mixpanel',
    ip: '0'
});
```

### Setting Group Profile Properties

Create a group profile by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

The Mixpanel object contains a `groups` property, that exposes the [`MixpanelGroups`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/groups.js) class which contain methods for managing group profile properties.

To set group profile properties, use the [`groups.set()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/groups.js#L37) method, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```js JavaScript theme={"system"}
// track some event attributed to the "mixpanel" company group
mp.track('some_event', {
    'distinct_id': 'sample_distinct_id',
    'company': 'mixpanel'
});

// Create or update a the "mixpanel" company group
// setting "name" and "industry" as group props
mixpanel.groups.set('company', 'mixpanel', {
  name: 'Mixpanel',
  industry: 'Analytics',
})
```

### Other Group Profile Methods

See all of the methods under the `MixpanelGroups` class [here](https://github.com/mixpanel/mixpanel-node/blob/master/lib/groups.js).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title="set_once()">
    The [`groups.set_once()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/groups.js#L18) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```js theme={"system"}
    // set group profile for "mixpanel" company group
    mp.groups.set('company', 'mixpanel', {
      name: 'Mixpanel',
      employee_count: 100
    });

    // ignored since "name" is already exists
    mp.groups.set_once('company', 'mixpanel', {
      name: 'mp-us'
    });

    # set "location" group prop since it does not exist
    mp.groups.set_once('company', 'mixpanel', {
      location: 'us',
    });
    ```
  </Tab>

  <Tab title="unset()">
    The [`groups.unset()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/groups.js#L102) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```js theme={"system"}
    // set group profile for the "mixpanel" company group
    mp.groups.set('company', 'mixpanel', {
      name: 'Mixpanel',
      employee_count: 100
    });

    // delete "employee_count" from the group profile
    mp.groups.unset('company', 'mixpanel', 'employee_count');

    // only "name" remains as a group prop
    ```
  </Tab>

  <Tab title="union()">
    The [`groups.union()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/groups.js#L86) method append new values to a list property, excluding duplicates.

    Use this method to create a list group profile property that only contains unique values without duplicates.

    **Example Usage**

    ```js theme={"system"}
    // set group profile for the "mixpanel" company group
    mp.groups.set('company', 'mixpanel', {
      name: 'Mixpanel',
      features: ['alert','cohort','reports']
    });

    // add "data pipeline" to "features" prop
    // ignore "alert" since it is a duplicate value
    mp.groups.union('company','mixpanel', {
        features: ['data pipeline','alert']
    });
    ```
  </Tab>

  <Tab title="remove()">
    The [`groups.remove()`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/groups.js#L70) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```js theme={"system"}
    // set group profile for the "mixpanel" company group
    mp.groups.set('company','mixpanel', {
        name: 'Mixpanel',
        features: ['reports','alerts','cohorts']
    });

    // remove "alerts" from "features"
    // "features" now contain ["reports","cohorts"]
    mp.groups.remove('company','mixpanel', {
        'features': ['alerts']
    });
    ```
  </Tab>
</Tabs>

## Debug Mode

To enable debug mode, set the [`debug`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/mixpanel-node.d.ts#L19) configuration option to `true` during the library initialization.

**Example Usage**

```javascript theme={"system"}
const Mixpanel = require('mixpanel');

// enable debug logs
mixpanel.init('YOUR_PROJECT_TOKEN',{
    debug: true
});
```

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Node.js SDK have a few configurations to help you protect user data.

Since this is a server-side tracking library where you have control of the servers, your server is responsible for determining whether to send data about a particular user or not.

### EU Data Residency

Route data to Mixpanel's EU servers by setting the [`host`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/mixpanel-node.d.ts#L21) config property during the library initialization.

**Example Usage**

```javascript theme={"system"}
const Mixpanel = require('mixpanel');

// set request URLs to Mixpanel's EU domain
mixpanel.init('YOUR_PROJECT_TOKEN',{
    host: 'api-eu.mixpanel.com'
});
```

### India Data Residency

Route data to Mixpanel's EU servers by setting the [`host`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/mixpanel-node.d.ts#L21) config property during the library initialization.

**Example Usage**

```javascript theme={"system"}
const Mixpanel = require('mixpanel');

// set request URLs to Mixpanel's India domain
mixpanel.init('YOUR_PROJECT_TOKEN', {
    host: 'api-in.mixpanel.com'
});
```

### Disable Geolocation

The Node.js SDK parse the request IP address to generate geolocation properties for events and profiles. You may want to disable them to prevent the unintentional setting of your data's geolocation to the location of your server that is sending the request, or to prevent geolocation data from being tracked entirely.

To disable geolocation, set the [`geolocate`](https://github.com/mixpanel/mixpanel-node/blob/master/lib/mixpanel-node.d.ts#L25) config property to `false` during the library initialization.

You can also disable geolocation for individual requests by setting the `ip` to `0`.

**Example Usage**

```javascript theme={"system"}
const Mixpanel = require('mixpanel');

// Initialize Mixpanel with geolocation parsing disabled
const mp = Mixpanel.init('<YOUR_TOKEN>', { geolocate: false });

// track an event without geolocation parsing
// by setting ip to 0
mp.track('event name', {
    distinct_id: 'sample_distinct_id',
    ip: '0'
});

// set profile properties without geolocation parsing
// by setting ip to 0
mp.people.set('sample_distinct_id', {
    name: 'sam',
    plan: 'premium',
    ip: '0'
});
```

## Release History

[See all releases.](https://github.com/mixpanel/mixpanel-node/releases)


# Implement Feature Flags (Node.js)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/nodejs/nodejs-flags



## Overview

This developer guide will assist you in configuring your server-side Node.js platform for [Feature Flags](/docs/featureflags) using the [Mixpanel Node.js SDK](/docs/tracking-methods/sdks/nodejs). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

## Prerequisites

Before implementing [Feature Flags](/docs/featureflags), ensure:

* You are on an Enterprise subscription plan and have the [Mixpanel Node.js SDK](https://github.com/mixpanel/mixpanel-node) installed. If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK. The minimum supported version is [v0.20.0](https://www.npmjs.com/package/mixpanel)
* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Flag Evaluation Scenarios

There are two scenarios available for using the Node.js SDK for feature flagging: Local Evaluation and Remote Evaluation.

For local evaluation, the SDK will poll Mixpanel servers for feature flag configurations. Assignment of user contexts to variants will be done locally within the SDK. This mode is recommended for low latency since there is no network call made at assignment time.

For remote evaluation, the SDK will make a network call to Mixpanel servers at assignment time. This mode is recommended for use cases where you want to leverage Mixpanel cohorts for user targeting or sticky variants for persistent variant assignments.

In either case there is also the capability to evaluate all flags for a given user context at once, to avoid needing to make multiple calls to get individual flag variants for the same user. This is particularly useful for remote evaluation to avoid incurring additional network calls.

## Local Evaluation

<Warning>
  Targeting by Mixpanel cohorts and sticky variants are not supported in Local Evaluation mode.
</Warning>

* The SDK is configured with a `local_flags_config` object that specifies parameters:

  1. `api_host` - If your project is in the EU/IN region, this should be set to route to `api-eu.mixpanel.com`/`api-in.mixpanel.com` respectively.
  2. `enable_polling` - This should be set to `true` to enable polling for new flag configurations.
  3. `polling_interval_in_seconds` - This is the interval in seconds at which the SDK will poll Mixpanel servers for feature flag configurations.
* The SDK will continue to poll for the lifetime of the SDK instance or until stopped.

```javascript theme={"system"}
const Mixpanel = require('mixpanel');

const mixpanel = Mixpanel.init('YOUR_PROJECT_TOKEN', {
    local_flags_config: {
        api_host: 'api.mixpanel.com',
        enable_polling: true,
        polling_interval_in_seconds: 60
    }
});

// If enable_polling is set to false, this will fetch definitions only once for the lifetime of the SDK.
await mixpanel.local_flags.startPollingForDefinitions();

// This should be the 'key' of the feature flag from Mixpanel's UX.
const flagKey = 'sample-flag';

// This is the fallback variant to return if the user context is not in a rollout group for the flag.
const fallbackValue = 'control';

// Current user context for evaluation.
// At minimum, this needs to include the user's distinct_id.
// If any of your feature flags use a Variant Assignment Key other than 'distinct_id', this should also include those keys for evaluation. For example, 'company_id' below
// If any of your feature flags use Runtime targeting, this should also include 'custom_properties' for evaluation
const userContext = {
    distinct_id: '1234',
    company_id: 'X',
    custom_properties: {
        platform: 'node'
    }
};

// Gets the assigned variant for the flag for the given user context.
// This will return the fallback_variant if the user context is not in an assignment group for the flag.
const variantValue = mixpanel.local_flags.getVariantValue(flagKey, fallbackValue, userContext);
```

## Remote Evaluation

* The SDK is configured with a `remote_flags_config` object to use remote evaluation.

```javascript theme={"system"}
const Mixpanel = require('mixpanel');

const mixpanel = Mixpanel.init('YOUR_PROJECT_TOKEN', {
    remote_flags_config: {
        api_host: 'api.mixpanel.com',
        request_timeout_in_seconds: 5
    }
});

// getVariantValue usage is the same as for local evaluation, but will make a network call to Mixpanel servers at assignment time.
const variantValue = await mixpanel.remote_flags.getVariantValue(flagKey, fallbackValue, userContext);
```

## Suppress automatic exposure tracking

To suppress automatic exposure tracking, pass `false` as the optional 4th parameter, then manually call `trackExposureEvent` when you're ready to expose the user to the variant. This applies to both local and remote evaluation.

```javascript theme={"system"}
// Local evaluation - pass false to suppress automatic exposure tracking
const variantValue = mixpanel.local_flags.getVariantValue(flagKey, fallbackValue, userContext, false);

// Manually track exposure when you're ready to expose the user to the variant
mixpanel.local_flags.trackExposureEvent(flagKey, selectedVariant, userContext);
```

```javascript theme={"system"}
// Remote evaluation - pass false to suppress automatic exposure tracking
const variantValue = await mixpanel.remote_flags.getVariantValue(flagKey, fallbackValue, userContext, false);

// Manually track exposure when you're ready to expose the user to the variant
mixpanel.remote_flags.trackExposureEvent(flagKey, selectedVariant, userContext);
```

## Evaluate all flags at once

Below is a remote evaluation sample of evaluating all flags for a given user context at once.

```javascript theme={"system"}
const Mixpanel = require('mixpanel');

const userContext = {
    distinct_id: '1234',
};

const mixpanel = Mixpanel.init('YOUR_PROJECT_TOKEN', {
    remote_flags_config: {
        api_host: 'api.mixpanel.com',
        request_timeout_in_seconds: 5
    }
});

// Returns a dictionary, mapping flag keys to assigned variants ONLY for flags that the user context is in an assignment group for.
// By default, this will not track an exposure event.
const variants = await mixpanel.remote_flags.getAllVariants(userContext);

// Given a flag key and the selected variant for that key, manually track an exposure event for a given flag and assigned variant, after exposing the user to the variant
mixpanel.remote_flags.trackExposureEvent(flagKey, selectedVariant, userContext);
```


# OpenFeature Provider (Node.js)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/nodejs/nodejs-openfeature



## Overview

This guide covers using Mixpanel's [Feature Flags](/docs/featureflags) through the [OpenFeature](https://openfeature.dev/) standard with the Mixpanel Node.js OpenFeature provider. OpenFeature provides a vendor-agnostic API for feature flag evaluation, allowing you to switch between providers without changing your application code.

For the native Mixpanel SDK approach, see the [Feature Flags (Node.js)](/docs/tracking-methods/sdks/nodejs/nodejs-flags) guide.

## Prerequisites

* Enterprise subscription plan with Feature Flags enabled
* Node.js 10 or higher
* Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Installation

```bash theme={"system"}
npm install @mixpanel/openfeature-server-provider @openfeature/server-sdk mixpanel
```

## Quick Start

```typescript theme={"system"}
import { OpenFeature } from "@openfeature/server-sdk";
import { MixpanelProvider } from "@mixpanel/openfeature-server-provider";

// 1. Create and register the provider with local evaluation
const provider = MixpanelProvider.createLocal("YOUR_PROJECT_TOKEN");
await OpenFeature.setProviderAndWait(provider);

// 2. Get a client and evaluate flags
const client = OpenFeature.getClient();
const showNewFeature = await client.getBooleanValue("new-feature-flag", false, {
  distinct_id: "user-123",
});

if (showNewFeature) {
  console.log("New feature is enabled!");
}
```

## Initialization

### Local Evaluation (Recommended)

<Warning>
  Targeting by Mixpanel cohorts and sticky variants are not supported in Local Evaluation mode.
</Warning>

```typescript theme={"system"}
const provider = MixpanelProvider.createLocal("YOUR_PROJECT_TOKEN");
```

### Remote Evaluation

```typescript theme={"system"}
const provider = MixpanelProvider.createRemote("YOUR_PROJECT_TOKEN");
```

### Using an Existing Mixpanel Instance

```typescript theme={"system"}
import Mixpanel from "mixpanel";

const mixpanel = Mixpanel.init("YOUR_PROJECT_TOKEN", {
  local_flags_config: {},
});
const localFlags = mixpanel.local_flags!;
localFlags.startPollingForDefinitions();

const provider = new MixpanelProvider(localFlags);
```

## Usage

### Flag Types and Evaluation Methods

| Mixpanel Flag Type | Variant Values                          | OpenFeature Method                                                                 |
| ------------------ | --------------------------------------- | ---------------------------------------------------------------------------------- |
| Feature Gate       | `true` / `false`                        | `getBooleanValue()`                                                                |
| Experiment         | boolean, string, number, or JSON object | `getBooleanValue()`, `getStringValue()`, `getNumberValue()`, or `getObjectValue()` |
| Dynamic Config     | JSON object                             | `getObjectValue()`                                                                 |

```typescript theme={"system"}
const client = OpenFeature.getClient();
const context = { distinct_id: "user-123" };

// Feature Gate
const isFeatureOn = await client.getBooleanValue("new-checkout", false, context);

// Experiment with string variants
const buttonColor = await client.getStringValue("button-color-test", "blue", context);

// Experiment with number variants
const maxItems = await client.getNumberValue("max-items", 10, context);

// Dynamic Config
const featureConfig = await client.getObjectValue("homepage-layout", {}, context);
```

### Evaluation Context

```typescript theme={"system"}
// Global context
OpenFeature.setContext({ environment: "production" });

// Per-evaluation context (merged with and overrides global context)
const value = await client.getBooleanValue("premium-feature", false, {
  distinct_id: "user-123",
  email: "user@example.com",
  plan: "premium",
});
```

<Note>
  Unlike some providers, `targetingKey` is not used as a special bucketing key. It is passed as another context property. Mixpanel's server-side configuration determines which properties are used for targeting and bucketing.
</Note>

### Full Resolution Details

```typescript theme={"system"}
const details = await client.getBooleanDetails("my-feature", false, {
  distinct_id: "user-123",
});

console.log(details.value);
console.log(details.variant);
console.log(details.reason);
console.log(details.errorCode);
```

### Accessing the Underlying Mixpanel Instance

```typescript theme={"system"}
const mixpanel = provider.mixpanel;
if (mixpanel) {
  mixpanel.track("button_clicked", { distinct_id: "user-123" });
}
```

### Shutdown

```typescript theme={"system"}
await OpenFeature.close();
```

## Error Handling

| Error Code           | When                                                                       |
| -------------------- | -------------------------------------------------------------------------- |
| `PROVIDER_NOT_READY` | Flags evaluated before the local provider has finished loading definitions |
| `FLAG_NOT_FOUND`     | The requested flag does not exist in Mixpanel                              |
| `TYPE_MISMATCH`      | The flag value type does not match the requested type                      |

## Troubleshooting

### Flags Always Return Default Values

1. **Provider not ready:** Use `setProviderAndWait()` to ensure flags are ready before evaluation.
2. **Invalid project token:** Verify the token matches your Mixpanel project.
3. **Flag not configured:** Verify the flag exists and is enabled.

### Type Mismatch Errors

Verify the flag's value type matches your evaluation method. Use `getObjectValue()` for JSON objects.


# Mixpanel SDKs: PHP
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/php



## Getting Started

The Mixpanel PHP library is designed to be used for scripting, or in circumstances when a client can't or won't run client side scripts

The [Full API Reference](https://mixpanel.github.io/mixpanel-php/), [Library Source Code](https://github.com/mixpanel/mixpanel-php), and [example scripts](https://github.com/mixpanel/mixpanel-php/tree/master/examples) are documented in our Github repo.

## Installing the Library

<Note>
  Note: Our library requires PHP 5.0 or greater.
</Note>

<Tabs>
  <Tab title="Composer">
    You can get the library using [Composer](http://getcomposer.org/) by including the following in your project's `composer.json` requirements and running composer update:

    ```json theme={"system"}
    "require": {
        ...
        "mixpanel/mixpanel-php" : "2.*"
        ...
    }
    ```

    Once the library is installed, create an instance of the Mixpanel class with the [`getInstance()`](https://mixpanel.github.io/mixpanel-php/classes/Mixpanel.html#method_getInstance) method using [your project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).

    ```php theme={"system"}
    <?php
    // import dependencies
    require 'vendor/autoload.php';

    // create an instance of the Mixpanel class
    $mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

    ?>
    ```
  </Tab>

  <Tab title="Manual">
    If you're not using Composer for your package management, you can browse and download the library [from GitHub](https://github.com/mixpanel/mixpanel-php), extract the zip file to a directory called "mixpanel-php" in your project root, then import the library.

    ```php theme={"system"}
    <?php
    // import Mixpanel
    require 'mixpanel-php/lib/Mixpanel.php';

    // create an instance of the Mixpanel class
    $mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

    ?>
    ```
  </Tab>
</Tabs>

### Library Configuration

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/php#privacy-friendly-tracking).
</Warning>

The Mixpanel class can be initialized with different configurations. See a complete list of the configuration options and default values [here](https://mixpanel.github.io/mixpanel-php/classes/Mixpanel.html).

You can override the default configuration using the [`$options`](https://mixpanel.github.io/mixpanel-php/classes/Base_MixpanelBase.html#property__options) constructor argument when creating the Mixpanel instance.

**Example Usage**

```php theme={"system"}
<?php
// import dependencies
require 'vendor/autoload.php';
 
// create an instance of the Mixpanel class
$mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN", array(
    "max_batch_size" => 100,    // set the maximum batch size to 100
    "debug"          => true    // enable debug mode
    ));

?>
```

## Sending Events

Track events using the [`track()`](https://mixpanel.github.io/mixpanel-php/classes/Producers_MixpanelEvents.html#method_track) method on the Mixpanel class. The `track()` method accepts two arguments (`$event` string and `$properties` array) to generate an event payload, then triggers a request to the [/track API endpoint](/reference/track-event) to ingest the event to your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```php theme={"system"}
<?php
// import dependencies
require 'vendor/autoload.php';
 
// create an instance of the Mixpanel class
$mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

// Send a "button clicked" event containing 2 event properties
$mp->track("button clicked", array(
  "label"       => "sign-up", // "label" prop is set to "sign-up"
  "distinct_id" => "SOME_ID"  // "distinct_id" prop is set to "SOME_ID"
));

//by default, no distinct_id is included on events unless specified in the properties
//you can call identify so it's included in events during that script execution
?>
```

Mixpanel determines default geolocation data (`$city`, `$region`, `mp_country_code`) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your data center. [Learn more about Geolocation best practices](/docs/tracking-best-practices/geolocation).

### Importing Historical Events

The PHP SDK is a tracking SDK designed for real-time tracking in a server-side environment. Calling the `track()` method triggers a request to our [/track API endpoint](/reference/track-event), which will validate for events with a timestamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested.**

For bulk import of historical events older than 5 days, we will need to use the [/import API endpoint](/reference/import-events) which is optimized for scripting and supports ingesting historical data. We recommend the [Python SDK](/docs/tracking-methods/sdks/python) (see the [`.import_data()`](https://mixpanel.github.io/mixpanel-python/#primary-interface) function) and [mixpanel-utils module](https://github.com/mixpanel/mixpanel-utils) (see the [`import_events()`](https://github.com/mixpanel/mixpanel-utils?tab=readme-ov-file#import-events) function) which both leverages the /import API for event ingestion.

## Managing User Identity

Mixpanel groups events sent with different distinct\_ids, presenting them in reports as different user event streams. You can connect events with different distinct\_ids, ultimately attributing them to one user. You will want to check [which version of ID management you have enabled within Project Settings -> Identity Merge](/docs/tracking-methods/id-management#identity-merge-apis).

<Tabs>
  <Tab title="Original API">
    If you have [Original ID Merge enabled](/docs/tracking-methods/id-management#identity-merge-apis), send your anonymous events with an anonymous ID that you generate. Then merge your anonymous ID and your chosen user ID by calling the [`identify()`](https://mixpanel.github.io/mixpanel-php/classes/Producers_MixpanelEvents.html#method_identify) method once they are known (typically at registration and login). This will send an [`$identify`](/docs/tracking-methods/id-management/identifying-users-original#identify) event containing both IDs and merge them under one identity cluster.

    Learn more about [server-side ID management for project on Original ID Merge API](/docs/tracking-methods/id-management/identifying-users-original#server-side-identity-management).

    **Example Usage**

    ```php theme={"system"}
    <?php
    // import dependencies
    require 'vendor/autoload.php';

    // create an instance of the Mixpanel class
    $mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

    // send an "$identify" event to merge "USER_ID" and "ANON_ID" together
    $mp->identify('USER_ID','ANON_ID');

    ?>
    ```
  </Tab>

  <Tab title="Simplified API">
    If you have [Simplified ID Merge](/docs/tracking-methods/id-management#identity-merge-apis) enabled, send your event anonymous events with an anonymous ID set to the `$device_id`. Then call [`identify()`](https://mixpanel.github.io/mixpanel-php/classes/Producers_MixpanelEvents.html#method_identify) while providing your chosen user ID once they are known (typically at registration and login). This will set your chosen user ID as the `$user_id` for events moving forward.

    When a `$user_id` and a `$device_id` is detected in the same event for the first time, it triggers a merge of the 2 IDs.

    Learn more about [server-side ID management for project on Original ID Merge API](/docs/tracking-methods/id-management/identifying-users-simplified#server-side-identity-management).

    **Example Usage**

    ```php theme={"system"}
    <?php
    // import dependencies
    require 'vendor/autoload.php';

    // create an instance of the Mixpanel class
    $mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

    // calling identify will attach the "USER_ID"
    // as the $user_id event property to all events moving forward
    $mp->identify("USER_ID");

    // when a $user_id/$device_id pair is detected in the same event for the first time,
    // a merge is triggered to map the 2 IDs together.
    $mp->track("sign-up", array(
    '$device_id' => "ANON_ID",
    '$user_id' => "USER_ID"
    ));

    ?>
    ```
  </Tab>
</Tabs>

## Storing User Profiles

Once your users are identified, create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The PHP SDK provides a few methods for setting profile properties, which will trigger requests to the [/engage API endpoint](/reference/profile-set).

Mixpanel determines default geolocation data (`$city`, `$region`, `mp_country_code`) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your data center. [Learn more about best practices for geolocation](/docs/tracking-best-practices/geolocation).

### Setting Profile Properties

The Mixpanel class has a public property called [`$people`](https://mixpanel.github.io/mixpanel-php/classes/Mixpanel.html#property_people) that exposes an instance of [`Producers_MixpanelPeople`](https://mixpanel.github.io/mixpanel-php/classes/Producers_MixpanelPeople.html) that you can use to make profile updates.

Use the [`people->set()`](https://mixpanel.github.io/mixpanel-php/classes/Producers_MixpanelPeople.html#method_set) method to create properties on a user record. If the profile does not exist, it will be created using the properties defined in the method. If the properties already exist, they will be overwritten.

**Example Usage**

```php theme={"system"}
<?php
// import dependencies
require 'vendor/autoload.php';
 
// create an instance of the Mixpanel class
$mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

// set "name" user property
$mp->people->set("USER_ID", array(
    'name'       => "Sam",
), $ip = 0);   // set $ip to 0 to prevent profile geolocation update

// overwrite "name" user property
$mp->people->set("USER_ID", array(
    'name'       => "Samantha",
), $ip = 0);
..
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](https://mixpanel.github.io/mixpanel-php/classes/Producers_MixpanelPeople.html).

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title="setOnce()">
    The [`setOnce()`](https://mixpanel.github.io/mixpanel-php/classes/Producers_MixpanelPeople.html#method_setOnce) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```php theme={"system"}
    // create an instance of the Mixpanel class
    $mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

    // set "name" user property
    $mp->people->set("USER_ID", array(
        'name'       => "Sam",
    ), $ip = 0);


    # will be ignored since "name" already exists
    $mp->people->setOnce("USER_ID", array(
        'name'       => "Samantha",
    ), $ip = 0);

    # set "location" user prop since it does not exist
    $mp->people->setOnce("USER_ID", array(
        'location'       => "us",
    ), $ip = 0);
    ```
  </Tab>

  <Tab title="append()">
    The [`append()`](https://mixpanel.github.io/mixpanel-php/classes/Producers_MixpanelPeople.html#method_append) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```php theme={"system"}
    // create an instance of the Mixpanel class
    $mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

    // set profile properties for user "1234"
    $mp->people->set("1234", array(
        'name'       => "Sam",
        'roles'      => array("sales","engineer")
    ), $ip = 0);


    // add "legal" to "roles"  
    // new role values are ['sales','engineer','legal']
    $mp->people->append("1234", "roles", "legal")

    // .append() allows duplicates
    // new "roles" values are ['sales','engineer','legal', 'legal']
    $mp->people->append("1234", "roles", "legal")
    ```
  </Tab>

  <Tab title="increment()">
    The [`increment()`](https://mixpanel.github.io/mixpanel-php/classes/Producers_MixpanelPeople.html#method_increment) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```php theme={"system"}
    // create an instance of the Mixpanel class
    $mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

    // set profile properties for user "1234"
    $mp->people->set("1234", array(
        'name'       => "Sam",
        'age'        => 25
    ), $ip = 0);

    // increment "age" by 2
    $mp->people->increment("1234", "age", 2);

    // use negative number to decrement
    // decrement "age" by 5
    $mp->people->increment("1234", "age", -5);
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

### Sending Group Identifiers With Events

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

To send group identifiers with your events, set the `group_key` as an event property with the `group_id` as the value.

**Example Usage**

```php theme={"system"}
<?php
// import dependencies
require 'vendor/autoload.php';
 
// create an instance of the Mixpanel class
$mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

// Send "some_event" containing the "company" group_key and "mixpanel" group_id
$mp->track("some_event", array(
  "company"       => "mixpanel",
  "distinct_id" => "SOME_ID"
));
?>
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

**Example Usage**

```php theme={"system"}
<?php
// import dependencies
require 'vendor/autoload.php';
 
// create an instance of the Mixpanel class
$mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

// Send "some_event" containing the "company" group_key with "mp-us" and "mp-eu" group_id
$mp->track("some_event", array(
  "company"       => array("mp-us","mp-eu")
  "distinct_id" => "SOME_ID"
));
?>
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `set()` call.

**Example Usage**

```php theme={"system"}
<?php
// import dependencies
require 'vendor/autoload.php';
 
// create an instance of the Mixpanel class
$mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN");

// set group key "company" as a user prop
// with group id "mixpanel" as value
$mp->people->set("USER_ID", array(
    'company'       => "mixpanel",
), $ip = 0);   // set $ip to 0 to prevent profile geolocation update
..
```

## Debug Mode

To enable debug mode, set the `debug` configuration option to `true` when initializing the Mixpanel class.

**Example Usage**

```php theme={"system"}
<?php
// import dependencies
require 'vendor/autoload.php';
 
// create an instance of the Mixpanel class
$mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN", array(
    "debug" => true //set debug to true
    ));

?>
```

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The PHP SDK have a few configurations to help you protect user data.

Since this is a server-side tracking library where you have control of the servers, your server is responsible for determining whether to send data about a particular user or not.

### EU Data Residency

Route data to Mixpanel's EU servers by setting a `host` configuration during initialization.

**Example Usage**

```php theme={"system"}
<?php
// import dependencies
require "vendor/autoload.php";

// create an instance of the Mixpanel class
$mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN", array(
    "host" => "api-eu.mixpanel.com" // set host name for api calls to EU domain
    ));

?>
```

### India Data Residency

Route data to Mixpanel's India servers by setting a `host` configuration during initialization.

```php theme={"system"}
<?php
// import dependencies
require "vendor/autoload.php";

// create an instance of the Mixpanel class
$mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN", array(
    "host" => "api-in.mixpanel.com" // set host name for api calls to India domain
    ));

?>
```

### Disable Geolocation

The PHP SDK parse the request IP address to generate geolocation properties for events and profiles. You may want to disable them to prevent the unintentional setting of your data's geolocation to the location of your server that is sending the request, or to prevent geolocation data from being tracked entirely.

To disable geolocation, set the `$ip` of your profile updates to `0` and set your `events_endpoint` to `/track?ip=0` when initializing the Mixpanel instance.

**Example Usage**

```php theme={"system"}
<?php
// create an instance of the Mixpanel class
$mp = Mixpanel::getInstance("YOUR_PROJECT_TOKEN", array(
    "events_endpoint" => "/track?ip=0" // disable geolocation parsing for events
));

// set user props without geolocation parsing
$mp->people->set("USER_ID", array(
    'name'       => "Samantha",
), $ip = 0);
?>
```

## Scaling your Server-Side Tracking

The PHP library stores all events and profile updates in an in-memory queue, that is flushed automatically when the instance of [Mixpanel](http://mixpanel.github.io/mixpanel-php/classes/Mixpanel.html) is destroyed, or when the queue reaches a configurable threshold size (by default, 1000 items). You can also force the instance to send on demand by calling [flush](http://mixpanel.github.io/mixpanel-php/classes/Mixpanel.html#method_flush).

At flush time, the messages are processed by an implementation of the [ConsumerStrategies\_AbstractConsumer](http://mixpanel.github.io/mixpanel-php/classes/ConsumerStrategies_AbstractConsumer.html) class that determines how the messages will be written. The default settings use [ConsumerStrategies\_CurlConsumer](http://mixpanel.github.io/mixpanel-php/classes/ConsumerStrategies_CurlConsumer.html), which uses cURL to write the messages over SSL to Mixpanel.

As your application scales, you may want to separate the IO for communicating with Mixpanel out of the processes that observe your events. You can write your events and updates to a file or a distributed queue by writing your own custom consumer.

To create a [custom consumer](https://github.com/mixpanel/mixpanel-php/blob/master/examples/consumers/ObConsumer.php), you'll want to extend ConsumerStrategies\_AbstractConsumer and implement the persist method. Then you'll want to [register it with the Mixpanel class](https://github.com/mixpanel/mixpanel-php/blob/master/examples/custom_consumer.php) and specify it for use.

```php theme={"system"}
<?php
// Here's a simple consumer that just writes the events to
// send out to the client.
class MyLoggingConsumer extends ConsumerStrategies_AbstractConsumer {
    public function persist($batch) {
        echo "<pre>";
        echo "Would send batch:\n";
        echo json_encode($batch) . "\n";
        echo "</pre>"
        return true;
    }
}

$mp = new Mixpanel("MIXPANEL_PROJECT_TOKEN", array(
    // Provide the name of your consumer class to the Mixpanel constructor
    "consumers" => array("logger" => "MyLoggingConsumer"),

    // Now tell the Mixpanel instance to use your class
    "consumer" => "logger"
));

// This event will be sent to the client in a <pre> tag
$mp->track("test_event", array("color" => "blue"));
```

## Release History

[See all releases.](https://github.com/mixpanel/mixpanel-php/releases)


# Mixpanel SDKs: Python
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/python



## Getting Started

The Mixpanel Python library is designed to be used for scripting, or in circumstances when a user isn't directly interacting with your application on the web or a mobile device.

The [Full API Reference](http://mixpanel.github.io/mixpanel-python), [Library Source Code](https://github.com/mixpanel/mixpanel-python), and an [Example Script](https://github.com/mixpanel/mixpanel-python/tree/master/demo) is documented in our GitHub repo.

## Installing the Library

You can get the library using [pip](https://pypi.org/project/pip/).

```shell theme={"system"}
# install the Mixpanel module
pip install mixpanel
```

Once the library is installed, import the Mixpanel object from the module, then initialize the object using [your project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).

```py theme={"system"}
# import Mixpanel object from the module
from mixpanel import Mixpanel

# initialize Mixpanel
mp = Mixpanel("YOUR_PROJECT_TOKEN")
```

### Library Configuration

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/python#privacy-friendly-tracking).
</Warning>

The Mixpanel instance can be customized with different configurations using a custom `consumer`. Learn more about the consumer and the available parameters [here](https://mixpanel.github.io/mixpanel-python/#built-in-consumers).

**Example Usage**

```py theme={"system"}
# initialize Mixpanel
mp = mixpanel.Mixpanel(
  "YOUR_PROJECT_TOKEN",
  # use custom consumer where retry limit is set to 2
  consumer=mixpanel.Consumer(retry_limit=2),
)
```

## Sending Events

Use [`track()`](http://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.track) to send an event by providing the distinct\_id, event name, and any event properties. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```python theme={"system"}
# import Mixpanel
from mixpanel import Mixpanel

# initialize Mixpanel
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# Track 'some_event' with "plan" event prop
# With distinct_id set to '12345'
mp.track('12345', 'some_event', {
    'plan': 'premium',
    'ip': 192.168.0.1
})
```

To track any geolocation data (`$city`, `$region`, `mp_country_code`), you will need to set the location property values in the event. [Learn more about best practices for geolocation.](/docs/tracking-best-practices/geolocation)

### Importing Historical Events

The [`track()`](http://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.track) function is designed for real-time tracking in a server-side environment and will trigger request to the [/track API endpoint](/reference/track-event), which will validate for events with a time stamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested.**

Use the [`import_data()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.import_data) function to import events that occurred more than 5 days in the past. The `import_data()` function is based on the [/import API endpoint](/reference/import-events).

**Example Usage**

```py theme={"system"}
# initialize Mixpanel
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# import event that is old
mp.import_data(
	api_key='', # deprecated but required
	distinct_id='sample_distinct_id', 
	event_name='some_event',
    timestamp=1634528073,
	properties = {'some_property': 'some value'},
	api_secret = 'project_api_secret' # used to authenticate request
	)
```

You can also use the [mp-utils python module](https://github.com/mixpanel/mixpanel-utils) designed for scripting.

## Managing User Identity

Since the Python SDK is a server-side library, IDs are not generated by the SDK. Instead, you will need to generate and manage the distinct\_id yourself and include it in your events and profile data.

Learn more about [server-side identity management](/docs/tracking-methods/id-management/identifying-users-simplified#server-side-identity-management).

## Storing User Profiles

Create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Python SDK provides a few functions for setting profile properties, which will trigger requests to the [/engage API endpoint](/reference/profile-set).

To track any geolocation data (`$city`, `$region`, `$country_code`) for profile updates, you will need to set the location property values. [Learn more about best practices for geolocation.](/docs/tracking-best-practices/geolocation)

### Setting Profile Properties

Set profile properties on a user profile by calling the [`people_set()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.people_set) method.

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```python theme={"system"}
# initialize Mixpanel
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# create a user profile with name and email props
mp.people_set('sample_distinct_id', {
    'name' : 'sam',
    '$email' : 'sam@example.com',
}, meta = {
    '$ignore_time' : True, # do not update $last_seen
    '$ip' : 0}) # do not update geolocation

# update name property with new value
mp.people_set('sample_distinct_id', {
    'name' : 'samantha'
}, meta = {'$ignore_time' : True,'$ip' : 192.168.0.1})
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](https://mixpanel.github.io/mixpanel-python).

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title="people_set_once()">
    The [`people_set_once()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.people_set_once) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```python theme={"system"}
    mp = Mixpanel('YOUR_PROJECT_TOKEN')

    # set profile properties for user "1234"
    mp.people_set('1234', {
    'name':'sam'
    }, meta={'$ip':0})

    # will be ignored since "name" already exists
    mp.people_set_once('1234', {
    'name':'samantha'
    }, meta={'$ip':0})

    # set "location" user prop since it does not exist
    mp.people_set_once('1234', {
    'location':'us'
    }, meta={'$ip':0})
    ```
  </Tab>

  <Tab title="people_append()">
    The [`people_append()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.people_append) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```python theme={"system"}
    mp = Mixpanel('YOUR_PROJECT_TOKEN')

    # set profile properties for user "1234"
    mp.people_set('1234', {
        'name': 'sam',
        'roles': ['sales','engineer']
    }, meta={'$ip':0})

    # add "legal" to "roles"  
    # new role values are ['sales','engineer','legal']
    mp.people_append('1234', {
        'roles': 'legal'
    }, meta={'$ip':0})

    # .append() allows duplicates
    # new "roles" values are ['sales','engineer','legal', 'legal']
    mp.people_append('1234', {
        'roles': 'legal'
    }, meta={'$ip':0})
    ```
  </Tab>

  <Tab title="people_union()">
    The [`people_union()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.people_union) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```python theme={"system"}
    mp = Mixpanel('YOUR_PROJECT_TOKEN')

    # set profile properties for user "1234"
    mp.people_set('1234', {
        'name': 'sam',
        'roles': ['sales','engineer']
    }, meta={'$ip':0})

    # "engineer" ignored since it already exists
    # append "legal" to "roles"
    mp.people_union('1234', {
        'roles': ['engineer','legal']
    }, meta={'$ip':0})
    ```
  </Tab>

  <Tab title="people_increment()">
    The [`people_increment()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.people_increment) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```python theme={"system"}
    mp = Mixpanel('YOUR_PROJECT_TOKEN')

    # set profile properties for user "1234"
    mp.people_set('1234', {
        'name': 'sam',
        'age': 25
    }, meta={'$ip':0})

    # increment "age" by 2
    mp.people_increment('1234', {'age':2})

    # use negative number to decrement
    # decrement "age" by 5
    mp.people_increment('1234', {'age',-5});
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

### Sending Group Identifiers With Events

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

To send group identifiers with your events, set the `group_key` as an event property with the `group_id` as the value.

**Example Usage**

```python theme={"system"}
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# track "some_event" with a "distinct_id"
# event is attributed to the "mixpanel" company group
mp.track('sample_distinct_id', 'some_event', {
    'Plan Type' : 'Premium', 
    'company' : 'mixpanel'})
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

**Example Usage**

```python theme={"system"}
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# track "some_event" with a "distinct_id"
# event is attributed to 2 company groups: "mp-us" and "mp-eu"
mp.track('sample_distinct_id', 'some_event', {
    'Plan Type' : 'Premium', 
    'company' : ['mp-us','mp-eu']})
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `people_set()` call.

**Example Usage**

```python theme={"system"}
# initialize Mixpanel
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# set group key "company" as a user prop
# with group id "mixpanel" as value
mp.people_set('sample_distinct_id', {
    'name' : 'sam',
    'company' : 'mixpanel',
}, meta = {'$ignore_time' : True,'$ip' : 0})
```

### Setting Group Profile Properties

Create a group profile by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

To set group profile properties, use the [`group_set()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.group_set) function, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```py Python theme={"system"}
mp = Mixpanel('YOUR_PROJECT_TOKEN')

# create group profile for the "mixpanel" company group
# set "Company Type" and "$name" group profile properties
mp.group_set('company', 'mixpanel', {
    'Company Type': 'Analytics',
     '$name': 'Mixpanel'})
```

### Other Group Profile Methods

See all of the methods under the Group class [here](https://mixpanel.github.io/mixpanel-python/).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title="group_set_once()">
    The [`group_set_once()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.group_set) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```python theme={"system"}
    mp = Mixpanel('YOUR_PROJECT_TOKEN')

    # set group profile for "mixpanel" company group
    mp.group_set('company','mixpanel', {
        'name': 'Mixpanel',
        'employee_count': 100
    })

    # ignored since "name" is already exists
    mp.group_set_once('company','mixpanel', {
        'name': 'mp-us',
    })

    # set "location" group prop since it does not exist
    mp.group_set_once('company','mixpanel', {
        'location': 'us',
    })
    ```
  </Tab>

  <Tab title="group_unset()">
    The [`group_unset()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.group_unset) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```python theme={"system"}
    mp = Mixpanel('YOUR_PROJECT_TOKEN')

    # set group profile for the "mixpanel" company group
    mp.group_set('company','mixpanel', {
        'name': 'Mixpanel',
        'employee_count': 100
    })

    # delete "employee_count" from the group profile
    mp.group_unset('company','mixpanel', [
        'employee_count'
    ])

    # only "name" remains as a group prop
    ```
  </Tab>

  <Tab title="group_union()">
    The [`group_union()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.group_union) method append new values to a list property, excluding duplicates.

    Use this method to create a list group profile property that only contains unique values without duplicates.

    **Example Usage**

    ```python theme={"system"}
    mp = Mixpanel('YOUR_PROJECT_TOKEN')

    # set group profile for the "mixpanel" company group
    mp.group_set('company','mixpanel', {
        'name': 'Mixpanel',
        'features': ['reports','alerts','cohorts']
    })

    # add "data pipeline" to "features" prop
    # ignore "alert" since it is a duplicate value
    mp.group_union('company','mixpanel', {
        'features': ['data pipeline','alerts']
    })
    ```
  </Tab>

  <Tab title="group_remove()">
    The [`group_remove()`](https://mixpanel.github.io/mixpanel-python/#mixpanel.Mixpanel.group_remove) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```python theme={"system"}
    mp = Mixpanel('YOUR_PROJECT_TOKEN')

    # set group profile for the "mixpanel" company group
    mp.group_set('company','mixpanel', {
        'name': 'Mixpanel',
        'features': ['reports','alerts','cohorts']
    })

    # remove "alerts" from "features"
    # "features" now contain ["reports","cohorts"]
    mixpanel.group_remove('company','mixpanel', {
        'features': ['alerts']
    })
    ```
  </Tab>
</Tabs>

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Python SDK have a few configurations to help you protect user data.

Since this is a server-side tracking library where you have control of the servers, your server is responsible for determining whether to send data about a particular user or not.

### EU Data Residency

Route data to Mixpanel's EU servers by using a custom `Consumer` with an `api_host` set to the EU domain.

**Example Usage**

```py theme={"system"}
from mixpanel import Mixpanel

# use custom consumer with URLs set to Mixpanel's EU domain
mp_eu = Mixpanel(
  "YOUR_PROJECT_TOKEN",
  consumer=mixpanel.Consumer(api_host="api-eu.mixpanel.com"),
)
```

### India Data Residency

Route data to Mixpanel's India servers by using a custom `Consumer` with an `api_host` set to the India domain.

**Example Usage**

```py theme={"system"}
from mixpanel import Mixpanel

# use custom consumer with URLs set to Mixpanel's India domain
mp_in = Mixpanel(
  "YOUR_PROJECT_TOKEN",
  consumer=mixpanel.Consumer(api_host="api-in.mixpanel.com"),
)
```

### Geolocation

The Python SDK sets the request IP address to `0` for events and profiles, meaning by default you are not tracking geolocation properties, unless explicitly included in the event or profile update.

## Release History

[See all releases.](https://github.com/mixpanel/mixpanel-python/releases)


# Implement Feature Flags (Python)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/python/python-flags



## Overview

This developer guide will assist you in configuring your server-side Python platform for [Feature Flags](/docs/featureflags) using the [Mixpanel Python SDK](/docs/tracking-methods/sdks/python). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

## Prerequisites

Before implementing [Feature Flags](/docs/featureflags), ensure:

* You are on an Enterprise subscription plan  and have the appropriate version of the SDK installed (minimum supported version is [`v5.1.0`](https://github.com/mixpanel/mixpanel-python). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK.
* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Flag Evaluation Scenarios

There are two scenarios available for using the python SDK for feature flagging, Local Evaluation and Remote Evaluation.

For local evaluation, the SDK will poll Mixpanel servers for feature flag configurations. Assignment of user contexts to variants will be done locally within the SDK. This mode is recommended for low latency since there is no network call made at assignment time.

For remote evaluation, the SDK will make a network call to Mixpanel servers at assignment time. This mode is recommended for use cases where you want to leverage Mixpanel cohorts for user targeting or sticky variants for persistent variant assignments.

In either case there is also the capability to evaluate all flags for a given user context at once, to avoid needing to make multiple calls to get individual flag variants for the same user. This is particularly useful for remote evaluation to avoid incurring additional network calls.

## Local Evaluation

<Warning>
  Targeting by Mixpanel cohorts and sticky variants are not supported in Local Evaluation mode.
</Warning>

* The SDK is configured with a `LocalFlagsConfig` object that specifies parameters:

  1. `api_host` - If you project is in the EU/IN region, this should be set to route to `https://api-eu.mixpanel.com`/`https://api-in.mixpanel.com` respectively.
  2. `enable_polling` - This should be set to `True` to enable local evaluation.
  3. `poll_interval` - This is the interval in seconds at which the SDK will poll Mixpanel servers for feature flag configurations.
* The SDK will continue to poll for the lifetime of the SDK instance or until stopped.

```python theme={"system"}
import mixpanel

local_config = mixpanel.LocalFlagsConfig(api_host="https://api.mixpanel.com", enable_polling=True, poll_interval=60)

mp = mixpanel.Mixpanel("YOUR_PROJECT_TOKEN", local_flags_config=local_config)

# If enable_polling is set to false, this will fetch definitions only once for the lifetime of the SDK.
mp.local_flags.start_polling_for_definitions()

# This should be the 'key' of the feature flag from Mixpanel's UX.
flag_key = "sample-flag"

# This is the fallback variant to return if the user context is not in a rollout group for the flag.
fallback_variant = "control"

# Current user context for evaluation.
# At minimum, this needs to include the user's distinct_id.
# If any of your feature flags use a Variant Assignment Key other than 'distinct_id', this should also include those keys for evaluation. For example, 'company_id' below
# If any of your feature flags use Runtime targeting, this should also include 'custom_properties' for evaluation
user_context = {
    "distinct_id": "1234",
    "company_id": "X",
    "custom_properties": {
        "platform": "python"
    }
}

# Gets the assigned variant for the flag for the given user context.
# This will return the fallback_variant if the user context is not in an assignment group for the flag.
variant_value = mp.local_flags.get_variant_value(flag_key, fallback_variant, user_context)
```

## Remote Evaluation

* The SDK is configured with a `RemoteFlagsConfig` object to use remote evaluation.

### Get a specific variant

```python theme={"system"}
import mixpanel

remote_config = mixpanel.RemoteFlagsConfig(api_host=API_HOST, request_timeout_in_seconds=5)

mp = mixpanel.Mixpanel(PROJECT_TOKEN, remote_flags_config=remote_config)

# get_variant_value usage is the same as for local evaluation, but will make a network call to Mixpanel servers at assignment time.
variant_value = mp.remote_flags.get_variant_value(flag_key, fallback_variant, user_context)
```

## Suppress automatic exposure tracking

By default, `get_variant_value()` automatically tracks an exposure event. Note that `get_variant_value()` does not expose a `report_exposure` parameter — to suppress automatic exposure tracking, call `get_variant()` directly with `report_exposure=False`, then manually track the exposure when you're ready to expose the user to the variant. This applies to both local and remote evaluation.

```python theme={"system"}
from mixpanel import SelectedVariant

# Local evaluation - suppress automatic exposure tracking with report_exposure=False
fallback = SelectedVariant(variant_value=fallback_variant)
variant = mp.local_flags.get_variant(flag_key, fallback, user_context, report_exposure=False)
variant_value = variant.variant_value

# Manually track exposure when you're ready to expose the user to the variant
mp.local_flags.track_exposure_event(flag_key, variant, user_context)
```

```python theme={"system"}
from mixpanel import SelectedVariant

# Remote evaluation - suppress automatic exposure tracking with report_exposure=False
fallback = SelectedVariant(variant_value=fallback_variant)
variant = mp.remote_flags.get_variant(flag_key, fallback, user_context, reportExposure=False)
variant_value = variant.variant_value

# Manually track exposure when you're ready to expose the user to the variant
mp.remote_flags.track_exposure_event(flag_key, variant, user_context)
```

### Evaluate all flags at once

Below is a remote evaluation sample of evaluating all flags for a given user context at once.

```python theme={"system"}
import mixpanel

user_context = {
    "distinct_id": "1234",
}

remote_config = mixpanel.RemoteFlagsConfig(api_host=API_HOST, request_timeout_in_seconds=5)
mp = mixpanel.Mixpanel(PROJECT_TOKEN, remote_flags_config=remote_config)

# Returns a dictionary, mapping flag keys to assigned variants ONLY for flags that the user context is in an assignment group for.
# By default, this will not track an exposure event.
variants = mp.remote_flags.get_all_variants(user_context)

# Given a flag key and the selected variant for that key, manually track an exposure event for a given flag and assigned variant, after exposing the user to the variant
mp.remote_flags.track_exposure_event(flagKey, selected_variant, user_context)
```


# OpenFeature Provider (Python)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/python/python-openfeature



## Overview

This guide covers using Mixpanel's [Feature Flags](/docs/featureflags) through the [OpenFeature](https://openfeature.dev/) standard with the Mixpanel Python OpenFeature provider. OpenFeature provides a vendor-agnostic API for feature flag evaluation, allowing you to switch between providers without changing your application code.

For the native Mixpanel SDK approach, see the [Feature Flags (Python)](/docs/tracking-methods/sdks/python/python-flags) guide.

## Prerequisites

* Enterprise subscription plan with Feature Flags enabled
* Python 3.9 or higher
* Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Installation

```bash theme={"system"}
pip install mixpanel-openfeature openfeature-sdk
```

## Quick Start

```python theme={"system"}
from mixpanel_openfeature import MixpanelProvider
from mixpanel.flags.types import LocalFlagsConfig
from openfeature import api

# 1. Create and register the provider with local evaluation
provider = MixpanelProvider.from_local_config(
    "YOUR_PROJECT_TOKEN",
    LocalFlagsConfig(token="YOUR_PROJECT_TOKEN"),
)
api.set_provider(provider)

# 2. Get a client and evaluate flags
client = api.get_client()
show_new_feature = client.get_boolean_value("new-feature-flag", False)

if show_new_feature:
    print("New feature is enabled!")
```

## Initialization

The provider supports three initialization methods depending on your evaluation strategy.

### Local Evaluation (Recommended)

Evaluates flags locally using cached flag definitions polled from Mixpanel. This minimizes latency since there is no network call at evaluation time.

<Warning>
  Targeting by Mixpanel cohorts and sticky variants are not supported in Local Evaluation mode.
</Warning>

```python theme={"system"}
from mixpanel_openfeature import MixpanelProvider
from mixpanel.flags.types import LocalFlagsConfig

provider = MixpanelProvider.from_local_config(
    "YOUR_PROJECT_TOKEN",
    LocalFlagsConfig(token="YOUR_PROJECT_TOKEN"),
)
```

### Remote Evaluation

Evaluates flags by making a request to Mixpanel's servers for each evaluation. Use this when you need real-time flag values or cohort-based targeting.

```python theme={"system"}
from mixpanel_openfeature import MixpanelProvider
from mixpanel.flags.types import RemoteFlagsConfig

provider = MixpanelProvider.from_remote_config(
    "YOUR_PROJECT_TOKEN",
    RemoteFlagsConfig(token="YOUR_PROJECT_TOKEN"),
)
```

### Using an Existing Mixpanel Instance

If your application already has a `Mixpanel` instance configured for tracking, you can wrap its flags provider:

```python theme={"system"}
from mixpanel import Mixpanel
from mixpanel.flags.types import LocalFlagsConfig
from mixpanel_openfeature import MixpanelProvider

mp = Mixpanel("YOUR_PROJECT_TOKEN", local_flags_config=LocalFlagsConfig(token="YOUR_PROJECT_TOKEN"))
mp.local_flags.start_polling_for_definitions()

provider = MixpanelProvider(mp.local_flags)
```

## Usage

### Flag Types and Evaluation Methods

| Mixpanel Flag Type | Variant Values                          | OpenFeature Method                                                                                               |
| ------------------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Feature Gate       | `True` / `False`                        | `get_boolean_value()`                                                                                            |
| Experiment         | boolean, string, number, or JSON object | `get_boolean_value()`, `get_string_value()`, `get_integer_value()`, `get_float_value()`, or `get_object_value()` |
| Dynamic Config     | JSON object                             | `get_object_value()`                                                                                             |

```python theme={"system"}
client = api.get_client()

# Feature Gate
is_feature_on = client.get_boolean_value("new-checkout", False)

# Experiment with string variants
button_color = client.get_string_value("button-color-test", "blue")

# Experiment with numeric variants
max_items = client.get_integer_value("max-items", 10)
threshold = client.get_float_value("score-threshold", 0.5)

# Dynamic Config
feature_config = client.get_object_value("homepage-layout", {"layout": "default"})
```

### Evaluation Context

Pass context to provide user attributes for targeting:

```python theme={"system"}
from openfeature.evaluation_context import EvaluationContext

context = EvaluationContext(
    targeting_key="user-123",
    attributes={
        "email": "user@example.com",
        "plan": "premium",
        "beta_tester": True,
    },
)

value = client.get_boolean_value("premium-feature", False, context)
```

<Note>
  Unlike some providers, `targetingKey` is not used as a special bucketing key. It is passed as another context property. Mixpanel's server-side configuration determines which properties are used for targeting and bucketing.
</Note>

### Full Resolution Details

```python theme={"system"}
details = client.get_boolean_details("my-feature", False)

print(details.value)        # The resolved value
print(details.variant)      # The variant key from Mixpanel
print(details.reason)       # Why this value was returned
print(details.error_code)   # Error code if evaluation failed
```

### Accessing the Underlying Mixpanel Instance

When using `from_local_config` or `from_remote_config`, you can access the Mixpanel instance for tracking:

```python theme={"system"}
mp = provider.mixpanel
```

### Shutdown

```python theme={"system"}
provider.shutdown()
```

## Error Handling

The provider uses OpenFeature's standard error codes:

| Error Code           | When                                                                   |
| -------------------- | ---------------------------------------------------------------------- |
| `PROVIDER_NOT_READY` | Flags evaluated before local provider has finished loading definitions |
| `FLAG_NOT_FOUND`     | The requested flag does not exist in Mixpanel                          |
| `TYPE_MISMATCH`      | The flag value type does not match the requested type                  |

## Troubleshooting

### Flags Always Return Default Values

1. **Provider not ready (local evaluation):** Flag definitions are polled asynchronously. Allow time for the initial fetch to complete.
2. **Invalid project token:** Verify the token matches your Mixpanel project.
3. **Flag not configured:** Verify the flag exists and is enabled in your Mixpanel project.

### Type Mismatch Errors

1. Verify the flag's value type in Mixpanel matches your evaluation method (e.g., string `"true"` requires `get_string_value()`, not `get_boolean_value()`).
2. Use `get_object_value()` for JSON objects.
3. Integer evaluation accepts whole-number `float` values. Float evaluation accepts any numeric type.


# Mixpanel SDKs: React Native
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/react-native



## Getting Started

Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=reactnative).

The [Full API Reference](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html), [Library Source Code](https://github.com/mixpanel/mixpanel-react-native), and an [Example Application](https://github.com/mixpanel/mixpanel-react-native/tree/master/Samples) is documented in our GitHub repo.

## Installing the Library

After [setting up your development environment for React Native](https://reactnative.dev/docs/environment-setup), navigate to your app's root directory and install the Mixpanel React Native SDK. The library requires React Native v0.6+.

```bash theme={"system"}
npm install mixpanel-react-native
```

Then navigate to your application's iOS folder, and install the dependencies. (Note you do not need to update your Podfile to add Mixpanel.)

```bash theme={"system"}
pod install
```

<Note>
  Since Xcode 12.5, there is a known swift compile issue, please refer to [this workaround](https://github.com/mixpanel/mixpanel-react-native/issues/43#issuecomment-829599732). However the compile issue has been resolved in Xcode 13.2.1+, there is no extra step required as long as you upgrade to Xcode 13.2.1+.
</Note>

After installation, import the `Mixpanel` class from the SDK, create an instance of Mixpanel using your [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens), then initialize by calling [`.init()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#:~:text=init\(token%2C%20trackAutomaticEvents%2C%20Optional\)).

```javascript theme={"system"}
//import Mixpanel class from the SDK
import { Mixpanel } from 'mixpanel-react-native';

// create an instance of Mixpanel using your project token
// disable legacy autotrack mobile events
const trackAutomaticEvents = false;
const mixpanel = new Mixpanel('YOUR_PROJECT_TOKEN', trackAutomaticEvents);

//initialize Mixpanel
await mixpanel.init();
```

### Library Configuration

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/react-native#privacy-friendly-tracking).
</Warning>

The `Mixpanel` constructor accepts up to four arguments: your project token, `trackAutomaticEvents`, an optional `useNative` flag (defaults to `true`), and an optional storage adapter for JavaScript mode. Additional runtime configuration is passed to `init()`.

```javascript theme={"system"}
import { Mixpanel } from 'mixpanel-react-native';

const trackAutomaticEvents = false; // disable legacy autotrack mobile events

// create an instance of Mixpanel using your project token
const mixpanel = new Mixpanel('YOUR_PROJECT_TOKEN', trackAutomaticEvents);

// initialize Mixpanel with the full configuration
await mixpanel.init(
  false,                              // optOutTrackingDefault
  { data_source: 'MP-React' },        // superProperties
  'https://api.mixpanel.com',         // serverURL (see Privacy-Friendly Tracking)
  false,                              // useGzipCompression
  { enabled: false }                  // featureFlagsOptions (see Feature Flags)
);
```

The fifth argument, `featureFlagsOptions`, configures Feature Flags. Pass `{ enabled: true }` and optional `context` and `persistence` fields to opt in. See [Feature Flags](/docs/tracking-methods/sdks/react-native/react-native-flags) for the full configuration reference.

### Javascript Mode

The Mixpanel React Native SDK supports React Native for Web and other platforms utilizing React Native that do not support iOS and Android directly via Javascript Mode.

To enable Javascript Mode:

1. Install [`AsyncStorage`](https://react-native-async-storage.github.io/async-storage/) which is used to persist data. If this is unavailable in your target environment, you can import/define a different storage class. Please refer to [`this documentation.`](https://github.com/mixpanel/mixpanel-react-native/tree/master?tab=readme-ov-file#expo-and-react-native-for-web-support-302-and-above)

```bash theme={"system"}
npm install @react-native-async-storage/async-storage
```

2. Initializing the Mixpanel object with `useNative` set to `false`.

```javascript theme={"system"}
//import Mixpanel class from the SDK
import { Mixpanel } from 'mixpanel-react-native';

const trackAutomaticEvents = false; //disable legacy mobile autotrack
const useNative = false;  //disable Native Mode, use Javascript Mode

// create new Mixpanel class
const mixpanel = new Mixpanel(
  'YOUR_PROJECT_TOKEN',
  trackAutomaticEvents,
  useNative
  );

// initialize Mixpanel
await mixpanel.init();
```

When using Javascript Mode:

* [Legacy Automatically Tracked Events](/docs/tracking-methods/sdks/android#legacy-automatically-tracked-events) are not supported
* Javascript Mode does not have the same default properties as Native Mode
* Data does not automatically flush when the app is backgrounded. Be sure to call [`.flush()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#flush) more frequently for key events

## Sending Events

Use the [`.track()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#track) method to send an event by providing the event name and any event properties. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```javascript theme={"system"}
// track "some_event" with "some property" set to "some_value"
mixpanel.track('some_event', {
  some_property: 'some_value'
});
```

### Timing Events

You can track the time it took for an action to occur, such as an image upload or a comment post, using [`.timeEvent()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#timeEvent). This will mark the "start" of your action, which will be timed until you finish with a track call. The time duration is then recorded in the "Duration" property.

**Example Usage**

```javascript theme={"system"}
// start the timer for the event "Image Upload"
mixpanel.timeEvent("Image Upload");

// 20 seconds later...

// track "Image Upload" event
// "Duration" event property set to 20
mixpanel.track("Image Upload");
```

### Flushing Events

To preserve battery life and customer bandwidth, the Mixpanel library doesn't send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background.

Call [`.flush()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#flush) manually if you want to force a flush at a particular moment.

**Example Usage**

```javascript Javascript theme={"system"}
// flush queued events immediately
mixpanel.flush();
```

**Flush Batch Size**

By default, Mixpanel will flush events immediately if a batch reaches 50 events. Use the [`.setFlushBatchSize()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#setFlushBatchSize) method to adjust the batch size limit for flushing.

**Example Usage**

```javascript Javascript theme={"system"}
// flush if event batch size reaches 100
mixpanel.setFlushBatchSize(100);
```

#### Importing Historical Events

The React Native SDK is a tracking SDK designed for real-time tracking in a client-side environment. Calling `track()` triggers a request to our [/track API endpoint](/reference/track-event), which will validate for events with a timestamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested**.

For bulk import of historical events older than 5 days, we will need to use the [/import API endpoint](/reference/import-events) which is optimized for scripting and supports ingesting historical data. We recommend the [Python SDK](/docs/tracking-methods/sdks/python) (see the [`.import_data()`](https://mixpanel.github.io/mixpanel-python/#primary-interface) function) and [mixpanel-utils module](https://github.com/mixpanel/mixpanel-utils) (see the [`import_events()`](https://github.com/mixpanel/mixpanel-utils?tab=readme-ov-file#import-events) function) which both leverages the /import API for event ingestion.

## Setting Super Properties

Super properties are global event properties that you define once and apply to all events.

To register super properties, call [`.registerSuperProperties()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#registerSuperProperties).

Use [`.registerSuperPropertiesOnce()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#registerSuperPropertiesOnce) to register super properties without overwriting existing values.

**Example Usage**

```javascript theme={"system"}
// register "name" as a super property
mixpanel.registerSuperProperties({
    name: 'Sam',
});
 
// register "city" as an additional super property
// ignore "name" since it already exists
mixpanel.registerSuperPropertiesOnce({
    name: 'Samantha',
    city: 'San Francisco'
});
 
// track a "registration" event
// the event will include the "name" property set to "Sam"
// and "city" set to "San Francisco"
mixpanel.track('registration');
```

If you have properties you'd like all events to include, you can also set the super properties when initializing the Mixpanel object by passing them as the second argument to `.init()`.

**Example Usage**

```javascript theme={"system"}
// define super properties as a key-value pair
const superProperties = {
  name: 'Sam',
  city: 'San Francisco'
};

const trackAutomaticEvents = false;

// create new Mixpanel class
const mixpanel = new Mixpanel('YOUR_PROJECT_TOKEN', trackAutomaticEvents);

// initialize Mixpanel with the super properties
await mixpanel.init(false, superProperties);

// track "some_event"
// "name" and "city" added as event properties
mixpanel.track('some_event');
```

Our mobile libraries store your super properties in local storage. They will persist so long as the app is installed (between launches and updates). Uninstalling the app will remove that customers super properties.

See more methods related to super properties in the complete library reference [here](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html).

## Managing User Identity

You can handle the identity of a user using the [`.identify()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#identify) and [`.reset()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#reset) methods. Learn more about [identity management](/docs/tracking-methods/id-management/identity-management) and [identifying users](/docs/tracking-methods/id-management/identifying-users).

### Identify

<Warning>
  We recommend against calling `.identify()` for anonymous visitors to your site.
</Warning>

Call [`.identify()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#identify) when you know the identity of the current user, passing in their user ID as an argument. This is typically at account registration and at log in.

**Example Usage**

```javascript theme={"system"}
// your user signs in and tracks a sign in event
mixpanel.track('sign in');
 
// upon sign in, identify the user with their ID
// ensure future events sent from the user have distinct_id 12345
mixpanel.identify('12345');
```

### Call Reset at Logout

Call [`.reset()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#reset) to clear data attributed to a user when they logout. This will clear the local storage and allows you to handle [multiple users on a single device](/docs/tracking-methods/id-management/identifying-users-simplified#multiple-users-one-device).

**Example Usage**

```javascript Javascript theme={"system"}
// your user logs out and tracks a log out event
mixpanel.track('log out');

// clear local storage and generate new distinct_id
mixpanel.reset();
```

## Storing User Profiles

Once your users are identified, create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The React Native SDK provides a few methods for setting profile properties under the [`People`](https://mixpanel.github.io/mixpanel-react-native/People.html) class accessible via [`.getPeople()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#getPeople). These methods will trigger requests to the [/engage API endpoint](/reference/profile-set).

### Setting Profile Properties

<Note>
  You must call `.identify()` before setting profile properties in order to associate the profile properties you set with the target user. If identify is not called, the profile update will be queued for ingestion until an identify call is made.
</Note>

Set profile properties on a user profile by calling the [`.getPeople().set()`](https://mixpanel.github.io/mixpanel-react-native/People.html#set) method.

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```javascript Javascript theme={"system"}
// You must call identify to associate the profile update with the user
// Create "plan" profile prop for user "12345"
mixpanel.identify('12345');
mixpanel.getPeople().set('plan', 'Premium');

// We only need to call identify once per page load
// Update "plan" from "Premium" to "Enterprise"
mixpanel.getPeople().set('plan', 'Enterprise');

// set multiple profile props at once
// by passing an object
let properties = {'plan':'Premium','company':'mixpanel'};
mixpanel.getPeople().set(properties);
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](https://mixpanel.github.io/mixpanel-react-native/People.html).

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title=".setOnce()">
    The [`.getPeople().setOnce()`](https://mixpanel.github.io/mixpanel-react-native/People.html#setOnce) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```javascript theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    let properties = {name: 'Sam'};
    mixpanel.getPeople().set(properties);

    // will be ignored since "name" already exists
    mixpanel.getPeople().setOnce('name', 'Samantha');

    // "email" will be set since it does not exist
    mixpanel.getPeople().setOnce('email', 'test@mail.com');
    ```
  </Tab>

  <Tab title=".append()">
    The [`.getPeople().append()`](https://mixpanel.github.io/mixpanel-react-native/People.html#append) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```javascript theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    let properties = {
        name: 'Sam',
        roles: ['sales','engineer']
    }
    mixpanel.getPeople().set(properties);

    // add "legal" to "roles"
    // new "roles" value is ['sales','engineer','legal']
    mixpanel.getPeople().append('roles', 'legal');

    // .append() allows duplicates
    // new "roles" value is ['sales','engineer','legal','legal']
    mixpanel.getPeople().append('roles', 'legal');
    ```
  </Tab>

  <Tab title=".union()">
    The [`.getPeople().union()`](https://mixpanel.github.io/mixpanel-react-native/People.html#union) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```javascript theme={"system"}
    // set profile properties for user "1234"
    mixpanel.identify('1234');
    let properties = {
        name: 'Sam',
        roles: ['sales','engineer']
    }
    mixpanel.getPeople().set(properties);


    // add "engineer" to "roles"
    // will be ignored since "engineer" already exists in "roles"
    mixpanel.getPeople().union('roles', 'engineer');

    // add "legal" to "roles" since it does not exist
    mixpanel.getPeople().union('roles', 'legal');
    ```
  </Tab>

  <Tab title=".increment()">
    The [`.getPeople().increment()`](https://mixpanel.github.io/mixpanel-react-native/People.html#increment) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```javascript theme={"system"}
      // set profile properties for user "1234"
      mixpanel.identify('1234');
      let properties = {
          name: 'Sam',
          age: 25,
      }

      // increment "age" by 2
      mixpanel.getPeople().increment('age',2);
      
      // use negative number to decrement
      // decrement "age" by 5
      mixpanel.getPeople().increment('age',-5);
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel [Group Analytics](/docs/data-structure/group-analytics) is a paid add-on that allows behavioral data analysis by groups (e.g. company, team), as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

The React Native SDK provides a few method for adding individual users to a group and setting group profile properties.

### Adding Users to a Group

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

Call the [`.setGroup()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#setGroup) method to register the current user to a group, which would add the `group_key` as an event property set to the `group_id` value to all events moving forward.

```javascript Javascript theme={"system"}
// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');
 
// track "some_event"
// event property "company" = ["mixpanel"] is added automatically
mixpanel.track('some_event');
 
// alternatively you can manually set the group key on each event
mixpanel.track('some_event',{
    company: ['mixpanel']
});
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

Call [`.addGroup()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#addGroup) to add additional `group_id`s to an existing list.

**Example Usage**

```javascript theme={"system"}
// assign the current user to the "mixpanel" company group
// events will contain 'company' prop set to ["mixpanel"]
mixpanel.setGroup('company', 'mixpanel');

// add "mp-us" as an additional company group
// new "company" value is ["mixpanel","mp-us"]
mixpanel.addGroup('company', 'mp-us');

// track "some_event"
// event property "company" = ["mixpanel","mp-us"] is added automatically
mixpanel.track('some_event');
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `getPeople().set()` call.

**Example Usage**

```javascript Javascript theme={"system"}
// You must call identify to associate the profile update with the user
// Create "plan" profile prop for user "12345"
mixpanel.identify('12345');
mixpanel.getPeople().set('plan', 'Premium');

// set group key "company" as a user prop
// with group id "mixpanel" as value
mixpanel.getPeople().set('company', 'mixpanel');
```

### Setting Group Profile Properties

Create a group profiles by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

To set group profile properties, specify the group that needs to be updated by calling [`.getGroup()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#getGroup), then set the group properties by chaining the [`.set()`](https://mixpanel.github.io/mixpanel-react-native/MixpanelGroup.html#set) method, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```javascript theme={"system"}
// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');

// specify the target group using the group_key and group_id
// set "size" as a group profile prop to 100
mixpanel.getGroup('company','mixpanel').set('size',100);
```

### Other Group Profile Methods

See all of the methods under the Group class [here](https://mixpanel.github.io/mixpanel-react-native/MixpanelGroup.html).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title=".setOnce()">
    The [`.getGroup().setOnce()`](https://mixpanel.github.io/mixpanel-react-native/MixpanelGroup.html#setOnce) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```javascript theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    let properties = {
        name: 'Mixpanel',
    };
    mixpanel.getGroup('company','mixpanel').set(properties);

    // ignored since "name" is already exists
    mixpanel.getGroup('company','mixpanel').setOnce({
        name: 'mp'
    });

    // set "location" group prop since it does not exist
    mixpanel.getGroup('company','mixpanel').setOnce({
      location: 'us'
    });
    ```
  </Tab>

  <Tab title=".unset()">
    The [`.getGroup().unset()`](https://mixpanel.github.io/mixpanel-react-native/MixpanelGroup.html#unset) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```javascript theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    let properties = {
        name: 'Mixpanel',
        employee_count: 100
    };
    mixpanel.getGroup('company','mixpanel').set(properties);

    // delete "employee_count" from the group profile
    mixpanel.getGroup('company','mixpanel').unset('employee_count');

    // only "name" remains as group profile prop
    ```
  </Tab>

  <Tab title=".union()">
    The [`.getGroup().union()`](https://mixpanel.github.io/mixpanel-react-native/MixpanelGroup.html#union) method append new values to a list property, excluding duplicates.

    Use this method to create a list group profile property that only contains unique values without duplicates.

    **Example Usage**

    ```javascript theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    let properties = {
        name: 'Mixpanel',
        features: ['reports','alerts','cohorts'],
    };
    mixpanel.getGroup('company','mixpanel').set(properties);

    // add "data pipeline" to the "features" prop
    // ignore "alert" since it is a duplicate value
    mixpanel.getGroup('company','mixpanel').union('features', [
        'data pipeline',
        'alert'
        ]);

    //remove "alert" from "features"
    mixpanel.getGroup('company','mixpanel').remove('features', 'alert');
    ```
  </Tab>

  <Tab title=".remove()">
    The [`.getGroup().remove()`](https://mixpanel.github.io/mixpanel-react-native/MixpanelGroup.html#remove) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```javascript theme={"system"}
    // assign the current user to the "mixpanel" company group
    mixpanel.setGroup('company', 'mixpanel');

    // set group profile properties
    let properties = {
        name: 'Mixpanel',
        features: ['reports','alerts','cohorts'],
    };
    mixpanel.getGroup('company','mixpanel').set(properties);

    //remove "alert" from "features"
    // features now contain ["reports","cohorts"]
    mixpanel.getGroup('company','mixpanel').remove('features', 'alert');
    ```
  </Tab>
</Tabs>

## Feature Flags

Feature Flags let you control the rollout of features, run A/B experiments, and change application behavior without shipping new code. They work in both native mode (iOS and Android) and JavaScript mode (React Native Web).

Enable feature flags by passing `featureFlagsOptions` with `enabled: true` to `.init()`, then evaluate flags on `mixpanel.flags`.

```javascript theme={"system"}
await mixpanel.init(
  false,
  {},
  undefined,
  undefined,
  { enabled: true }
);

// Evaluate a flag once flags are ready. Records a $experiment_started exposure event.
const variantValue = await mixpanel.flags.getVariantValue('my-feature-flag', 'control');
```

See the [Feature Flags (React Native)](/docs/tracking-methods/sdks/react-native/react-native-flags) guide for the full API, including runtime targeting, persistence policies, sync evaluation, and context updates.

## Autocapture

The Mixpanel React Native SDK provides methods on the `autocapture` object to help you track common user interactions with minimal instrumentation. These methods fire standardized events that are recognized by the Mixpanel platform.

### Screen View & Screen Leave

React Native apps use JavaScript-driven navigators like React Navigation or Expo Router, each handling screen transitions differently. This makes it impractical for the SDK to automatically detect screen boundaries. Instead, you hook `trackScreenView` and `trackScreenLeave` into your app's navigation, giving you full control over what counts as a screen and when transitions happen.

Track screen navigations using `trackScreenView` and `trackScreenLeave`. These methods fire the following events:

| Method               | Mixpanel Event   |
| -------------------- | ---------------- |
| `trackScreenView()`  | `$mp_page_view`  |
| `trackScreenLeave()` | `$mp_page_leave` |

Both events automatically include `current_page_title` (the screen name) and `$mp_autocapture: true`.

<Tabs>
  <Tab title="React Navigation">
    Use `onReady` and `onStateChange` on the `NavigationContainer` to track screen transitions:

    ```tsx theme={"system"}
    const navigationRef = useNavigationContainerRef();
    const previousRouteRef = useRef<string | undefined>();

    <NavigationContainer
      ref={navigationRef}
      onReady={() => {
        const route = navigationRef.getCurrentRoute()?.name;
        previousRouteRef.current = route;
        if (route) mixpanel.autocapture.trackScreenView(route);
      }}
      onStateChange={() => {
        const current = navigationRef.getCurrentRoute()?.name;
        const previous = previousRouteRef.current;

        if (current !== previous) {
          if (previous) mixpanel.autocapture.trackScreenLeave(previous);
          if (current) mixpanel.autocapture.trackScreenView(current);
        }
        previousRouteRef.current = current;
      }}
    />
    ```
  </Tab>
</Tabs>

#### Passing Custom Properties

Both methods accept an optional properties object. For example, forwarding UTM params from a deep link:

```tsx theme={"system"}
const url = new URL(deepLinkUrl);
const utmProps = {
  utm_source: url.searchParams.get("utm_source"),
  utm_medium: url.searchParams.get("utm_medium"),
  utm_campaign: url.searchParams.get("utm_campaign"),
};
mixpanel.autocapture.trackScreenView("PromoScreen", utmProps);
```

## Session Replay

Session Replay records the mobile UI of your React Native app so you can see what your users saw. Recording ships as a separate package, `@mixpanel/react-native-session-replay`, and installs alongside the main `mixpanel-react-native` SDK.

```bash theme={"system"}
npm install @mixpanel/react-native-session-replay
```

See the [Session Replay (React Native)](/docs/tracking-methods/sdks/react-native/react-native-replay) guide for platform setup, configuration options, and privacy masking APIs.

## Debug Mode

To enable debug mode, call the [.setLoggingEnabled()](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#setLoggingEnabled) with `true`, then run your iOS project with Xcode or android project with Android Studio. The logs will be available in the console.

**Example Usage**

<Note>
  Remove this parameter before going into production.
</Note>

```javascript theme={"system"}
// enable debug log in the console
mixpanel.setLoggingEnabled(true);
```

Learn more about [debugging](/docs/tracking-best-practices/debugging).

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The React Native SDK provide methods to help you protect user data.

Learn more about [Privacy](/docs/privacy/overview).

### Opt Out of Tracking

The React Native SDK is initialized with tracking enabled by default. Use the [`.optOutTracking()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#optOutTracking) method to opt the user out of data tracking and local storage for the current Mixpanel instance.

**Example Usage**

```javascript theme={"system"}
//send "some_event"
mixpanel.track('some_event');

// opt user out of tracking
// SDK is prevented from sending any data
mixpanel.optOutTracking();

// this track call will not work
mixpanel.track('some_other_event');
```

**Opt Out by Default**

You can initialize the library with users opted out of tracking by default by passing `optOutTrackingDefault` as the first argument to `.init()`. Once the user is ready to be tracked, call [`.optInTracking()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#optInTracking) to start tracking.

**Example Usage**

```javascript theme={"system"}
//import Mixpanel class from the SDK
import { Mixpanel } from 'mixpanel-react-native';

const trackAutomaticEvents = false;
const optOutTrackingDefault = true; // opt users out of tracking by default

// create new Mixpanel class
const mixpanel = new Mixpanel('YOUR_PROJECT_TOKEN', trackAutomaticEvents);

// initialize Mixpanel with opt-out-by-default
await mixpanel.init(optOutTrackingDefault);

// this track call will not work
mixpanel.track('some_event');

//opt user in to tracking
mixpanel.optInTracking();

// send "some_other_event"
mixpanel.track('some_other_event');
```

### EU Data Residency

Route data to Mixpanel's EU servers by setting the `serverURL` to `https://api-eu.mixpanel.com`.

The recommended approach is to pass the `serverURL` to `.init()` so it is set before any events are sent. The `.init()` method accepts the `serverURL` as its third argument (available in SDK v3.3.0 and above).

Learn more about [EU Data Residency](/docs/privacy/eu-residency).

**Example Usage**

```javascript theme={"system"}
// set the server URL at initialization to use Mixpanel's EU domain
mixpanel.init(false, {}, 'https://api-eu.mixpanel.com');
```

Alternatively, you can call `.setServerURL()` to change the `serverURL` after initializing the client.

```javascript theme={"system"}
// set the Mixpanel instance to send data using Mixpanel's EU domain
mixpanel.setServerURL('https://api-eu.mixpanel.com');
```

### India Data Residency

Route data to Mixpanel's India servers by setting the `serverURL` to `https://api-in.mixpanel.com`.

The recommended approach is to pass the `serverURL` to `.init()` so it is set before any events are sent. The `.init()` method accepts the `serverURL` as its third argument (available in SDK v3.3.0 and above).

Learn more about [India Data Residency](/docs/privacy/in-residency).

**Example Usage**

```javascript theme={"system"}
// set the server URL at initialization to use Mixpanel's India domain
mixpanel.init(false, {}, 'https://api-in.mixpanel.com');
```

Alternatively, you can call `.setServerURL()` to change the `serverURL` after initializing the client.

```javascript theme={"system"}
// set the Mixpanel instance to send data using Mixpanel's India domain
mixpanel.setServerURL('https://api-in.mixpanel.com');
```

### Disable Geolocation

The React Native SDK parse the request IP address to generate geolocation properties for events and profiles. To disable geolocation, call the [`setUseIpAddressForGeolocation()`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#setUseIpAddressForGeolocation) method with a value of `false`.

Learn more about [geolocation](/docs/tracking-best-practices/geolocation).

**Example Usage**

```javascript theme={"system"}
 // disable IP address for geolocation parsing
mixpanel.setUseIpAddressForGeolocation(false);
```

## Tracking Via Proxy

You can route events from Mixpanel's SDKs via a proxy in your own domain, which can reduce the likelihood of ad-blockers impacting your tracking.

<Frame>
  <img alt="image" />
</Frame>

There are two steps: setting up a proxy server and pointing our JavaScript SDK at your server.

**Step 1: Set up a proxy server**

The simplest way is to use our [sample nginx config](https://github.com/mixpanel/tracking-proxy). This config redirects any calls made to your proxy server to Mixpanel.

**Step 2: Point our React Native SDK at your server**

When initializing, replace `<YOUR_PROXY_DOMAIN>` with your proxy server's domain and pass it as the third argument to `.init()`.

```javascript theme={"system"}
const serverURL = '<YOUR_PROXY_DOMAIN>';  // your proxy domain
const trackAutomaticEvents = false;

// create an instance of Mixpanel using your project token
const mixpanel = new Mixpanel('YOUR_PROJECT_TOKEN', trackAutomaticEvents);

// initialize Mixpanel and route events through the proxy
await mixpanel.init(false, {}, serverURL);
```

## Release History

[See All Releases](https://github.com/mixpanel/mixpanel-react-native/releases).


# Implement Feature Flags (React Native)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/react-native/react-native-flags



## Overview

This developer guide will assist you in configuring your React Native application for Feature Flags using the [Mixpanel React Native SDK](/docs/tracking-methods/sdks/react-native). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

Feature Flags in the React Native SDK work across iOS, Android, and React Native Web platforms.

For complete React Native SDK documentation, see the [React Native SDK guide](/docs/tracking-methods/sdks/react-native).

## Prerequisites

Before implementing Feature Flags, ensure:

* You are on an Enterprise subscription plan and have the latest version of the SDK installed (minimum supported version is [`v3.5.0`](https://github.com/mixpanel/mixpanel-react-native/releases)). If not, install with `npm install mixpanel-react-native`.
* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).
* For iOS native apps, run `cd ios && pod install` after installing the SDK.

<Note>
  **Data Residency:** Use the server URL that matches your Mixpanel project's data residency region:

  * **US** (default): `https://api.mixpanel.com`
  * **EU**: `https://api-eu.mixpanel.com`
  * **India**: `https://api-in.mixpanel.com`
</Note>

## Execution Modes

The React Native SDK operates in two modes that affect how feature flags are evaluated:

| Mode           | Platforms        | How It Works                                                     |
| -------------- | ---------------- | ---------------------------------------------------------------- |
| **Native**     | iOS, Android     | Bridges to the native Swift and Android SDKs for flag evaluation |
| **JavaScript** | React Native Web | Uses a pure JavaScript implementation (aligned with mixpanel-js) |

The mode is determined by the `useNative` parameter in the `Mixpanel` constructor:

```javascript theme={"system"}
import { Mixpanel } from 'mixpanel-react-native';

// Native mode (default for bare React Native apps)
const mixpanel = new Mixpanel("YOUR_PROJECT_TOKEN", true);

// JavaScript mode (for React Native Web)
const mixpanel = new Mixpanel("YOUR_PROJECT_TOKEN", true, false);
```

## Flag Initialization

Initializing the SDK with feature flags enabled requires passing `featureFlagsOptions` with `enabled: true` to the `init()` method. This enables making an outbound request to Mixpanel servers with the current user context.

The server will assign the user context to a variant for each feature flag according to how they are configured in the Mixpanel UX.

The response will include an assigned variant for each flag that the user context is in a rollout group for. If a flag is not returned, it most likely signifies that the user was excluded by filtering rules or the rollout percentage for the flag.

**Example Usage**

```javascript theme={"system"}
import { Mixpanel } from 'mixpanel-react-native';

// For native apps (iOS/Android)
const mixpanel = new Mixpanel("YOUR_PROJECT_TOKEN", true);

// For React Native Web, use JavaScript mode:
// const mixpanel = new Mixpanel("YOUR_PROJECT_TOKEN", true, false);

await mixpanel.init(
  false,                       // optOutTrackingDefault
  {},                          // superProperties
  "https://api.mixpanel.com",  // serverURL (see Data Residency above)
  true,                        // useGzipCompression
  { enabled: true }            // featureFlagsOptions
);
```

If your flag is configured with a Variant Assignment Key other than `distinct_id` or `device_id` for any of the feature flags in your project, then the call to initialize feature flags must include those keys.

For example, for a Variant Assignment Key `company_id`, you would set up the SDK as follows:

```javascript theme={"system"}
await mixpanel.init(
  false,
  {},
  undefined,
  undefined,
  {
    enabled: true,
    context: {
      company_id: "X",
    },
  }
);
```

If you are using Runtime Targeting in any of the feature flags in your project, then any properties that you use in targeting should be included in a `custom_properties` node within the context:

```javascript theme={"system"}
await mixpanel.init(
  false,
  {},
  undefined,
  undefined,
  {
    enabled: true,
    context: {
      company_id: "X",
      custom_properties: {
        platform: "react-native",
      },
    },
  }
);
```

## Flag Persistence

By default (`networkOnly`), the SDK fetches fresh flag assignments and waits for the network response before variant calls complete. You can enable persistence to cache assignments so they are available immediately on subsequent launches. In JavaScript mode, persistence uses the same AsyncStorage adapter as the rest of the SDK. In native mode, persistence is handled by the underlying iOS and Android SDKs.

Configure a `persistence.variantLookupPolicy` on `featureFlagsOptions`:

**`networkFirst`**. The SDK waits for the network on every launch. If the network call fails, the persisted value is returned as a fallback. Async getter calls block until the fetch completes (or the fallback is resolved).

```javascript theme={"system"}
await mixpanel.init(
  false,
  {},
  undefined,
  undefined,
  {
    enabled: true,
    persistence: {
      variantLookupPolicy: "networkFirst",
    },
  }
);

// Waits for the network. Falls back to the persisted value if the network is unavailable.
const value = await mixpanel.flags.getVariantValue("my-feature-flag", "control");
```

**`persistenceUntilNetworkSuccess`**. Persisted variants are returned immediately on launch. Each getter call while serving persisted data triggers a background network fetch (deduplicated, only one fetch runs at a time). If the fetch fails, persisted data continues to be served and the next getter call retries the fetch. Once a fetch succeeds, the in-memory state updates and subsequent calls no longer trigger background fetches.

```javascript theme={"system"}
await mixpanel.init(
  false,
  {},
  undefined,
  undefined,
  {
    enabled: true,
    persistence: {
      variantLookupPolicy: "persistenceUntilNetworkSuccess",
    },
  }
);

// Returns persisted variants immediately. Background fetches retry until a
// network success replaces the persisted state.
const value = await mixpanel.flags.getVariantValue("my-feature-flag", "control");
```

To customize the TTL (default is 24 hours), pass `persistenceTtlMs` in milliseconds:

```javascript theme={"system"}
await mixpanel.init(
  false,
  {},
  undefined,
  undefined,
  {
    enabled: true,
    persistence: {
      variantLookupPolicy: "networkFirst",
      persistenceTtlMs: 12 * 60 * 60 * 1000, // 12 hours
    },
  }
);
```

### Variant source

Every variant returned by `getVariant` / `getVariantSync` carries a `variant_source` field indicating where the value came from: `"network"`, `"persistence"`, or `"fallback"`. Variants served from persistence also include `persisted_at_in_ms`, the epoch timestamp in milliseconds when the variant set was persisted.

```javascript theme={"system"}
const fallback = { key: "control", value: "control" };
const variant = await mixpanel.flags.getVariant("my-feature-flag", fallback);

console.log(variant.value);
console.log(variant.variant_source); // "network" | "persistence" | "fallback"

if (variant.variant_source === "persistence") {
  console.log(`Persisted at: ${new Date(variant.persisted_at_in_ms).toISOString()}`);
}
```

### `$experiment_started` properties

When a variant is served, the `$experiment_started` exposure event includes:

* `$variant_source`. Either `"network"` or `"persistence"`.
* `$persisted_at_in_ms`. Epoch milliseconds when the variant set was persisted (persistence only).

<Note>
  Persistence is scoped to the current `distinct_id`. Calling `identify()` with a new ID or calling `reset()` clears persisted flag state and triggers a fresh fetch.
</Note>

## Flag Reload

Following initialization, you can reload feature flag assignments in several ways:

### Reload via identify

After a user logs in or out of your application and you call `identify`, a feature flag reload will be triggered.

```javascript theme={"system"}
const updatedDistinctId = "user-123";
await mixpanel.identify(updatedDistinctId);
```

### Manual Reload

You can manually reload flags at any time:

```javascript theme={"system"}
await mixpanel.flags.loadFlags();
```

### Update Context

`updateContext` is available in both native and JavaScript modes. It updates the feature flags context after initialization and triggers a reload with the new values.

```javascript theme={"system"}
// Default is merge with the existing context.
await mixpanel.flags.updateContext({
  company_id: "Y",
  custom_properties: {
    platform: "mobile",
  },
});
```

In JavaScript mode, pass `{ replace: true }` to replace the context entirely instead of merging.

```javascript theme={"system"}
await mixpanel.flags.updateContext(
  { company_id: "Z" },
  { replace: true }
);
```

<Note>
  In **native mode**, the SDK always merges the new context with the existing context. The `{ replace: true }` option is accepted for API parity but has no effect on native.
</Note>

## Flag Evaluation

The SDK provides both asynchronous (Promise-based) and synchronous methods for evaluating flags.

### Async Evaluation (Recommended)

Async methods return Promises that resolve once flags are ready. This is the recommended approach as it handles the case where flags may not yet be loaded.

**Experiment Flags: Get Variant Value**

```javascript theme={"system"}
// Fetch the variant value once flags are ready and track an exposure event
// if the user context is in a rollout group for the feature flag.
const fallback = "control"; // used if the user doesn't match any rollout rules
const variantValue = await mixpanel.flags.getVariantValue("my-feature-flag", fallback);

if (variantValue === "variant_a") {
  showExperienceForVariantA();
} else if (variantValue === "variant_b") {
  showExperienceForVariantB();
} else {
  showDefaultExperience();
}
```

**Feature Gates: Check if Flag is Enabled/Disabled**

```javascript theme={"system"}
const isEnabled = await mixpanel.flags.isEnabled("my-boolean-flag", false);

if (isEnabled) {
  showNewFeature();
} else {
  showOldFeature();
}
```

**Get Full Variant Object**

Use `getVariant` to retrieve the full variant object, which includes metadata like `experiment_id`:

```javascript theme={"system"}
const variant = await mixpanel.flags.getVariant("my-feature-flag", {
  key: "control",
  value: "standard",
});

console.log(`Variant: ${variant.key}, Value: ${variant.value}`);
if (variant.experiment_id) {
  console.log(`Part of experiment: ${variant.experiment_id}`);
}
```

### Sync Evaluation

Synchronous methods return values immediately without waiting. Use these when you need to evaluate flags in render paths or other synchronous contexts.

<Warning>
  Sync methods return the fallback value if flags have not finished loading. Always check `areFlagsReady()` before relying on sync results.
</Warning>

```javascript theme={"system"}
if (mixpanel.flags.areFlagsReady()) {
  const variantValue = mixpanel.flags.getVariantValueSync("my-feature-flag", "control");
  const isEnabled = mixpanel.flags.isEnabledSync("my-boolean-flag", false);

  // Full variant object
  const variant = mixpanel.flags.getVariantSync("my-feature-flag", {
    key: "control",
    value: "standard",
  });
}
```

### Get All Flag Assignments

You can retrieve all feature flag assignments at once. These methods do **not** trigger `$experiment_started` exposure events.

**Synchronous**

`getAllVariantsSync()` returns a JavaScript `Map` keyed by feature name. If flags have not been loaded yet, it returns an empty `Map`.

```javascript theme={"system"}
const allFlags = mixpanel.flags.getAllVariantsSync();

for (const [flagName, variant] of allFlags) {
  console.log(`${flagName}: ${variant.value}`);
}
```

**Asynchronous**

`getAllVariants` returns a Promise resolving to a `Map`. If flags have not been loaded yet, it will attempt to fetch them before returning. On failure, it resolves to an empty `Map` rather than rejecting.

```javascript theme={"system"}
const flags = await mixpanel.flags.getAllVariants();
flags.forEach((variant, flagName) => {
  console.log(`${flagName}: ${variant.value}`);
});
```

## Exposure Events

Calling `isEnabled`, `isEnabledSync`, `getVariantValue`, `getVariantValueSync`, `getVariant`, or `getVariantSync` triggers tracking an exposure event, `$experiment_started`, to your Mixpanel project if the user context is in a rollout group for the feature flag. The exposure event is deduplicated per feature name for the lifetime of the SDK instance.

`getAllVariants` and `getAllVariantsSync` do not fire exposure events.

## Method Name Aliases

The React Native SDK supports both camelCase and snake\_case method names, aligned with mixpanel-js conventions:

| camelCase               | snake\_case                |
| ----------------------- | -------------------------- |
| `areFlagsReady()`       | `are_flags_ready()`        |
| `getVariant()`          | `get_variant()`            |
| `getVariantSync()`      | `get_variant_sync()`       |
| `getVariantValue()`     | `get_variant_value()`      |
| `getVariantValueSync()` | `get_variant_value_sync()` |
| `isEnabled()`           | `is_enabled()`             |
| `isEnabledSync()`       | `is_enabled_sync()`        |
| `getAllVariants()`      | `get_all_variants()`       |
| `getAllVariantsSync()`  | `get_all_variants_sync()`  |
| `loadFlags()`           | `load_flags()`             |
| `updateContext()`       | `update_context()`         |

## Frequently Asked Questions

### What if I'm not receiving any flags on SDK initialization?

1. **Check your project token**:

* Ensure you're using the correct project token from your [Mixpanel project settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).

2. **Review flag configuration**:

* Make sure your feature flag is enabled.
* Check the flag's rollout percentage. User contexts that are not assigned to the rollout percentage will not receive flags.
* If you are using a targeting cohort, verify on the Mixpanel 'Users' page that the user's `distinct_id` is a member of that cohort.

3. **Review SDK parameters**:

* Ensure `featureFlagsOptions` with `enabled: true` is passed to `init()`.
* If using a custom Variant Assignment Key, ensure it is included in the `context` object.
* If using Runtime Targeting, ensure all properties used in targeting are included in the `custom_properties` object within `context`.

4. **Check flags readiness**: Use `areFlagsReady()` to check if flags have been loaded before using sync evaluation methods.
5. **Enable debug logging**: Call `mixpanel.setLoggingEnabled(true)` to see detailed information about flag requests and responses.

### Which mode should I use?

* **Bare React Native apps** (iOS/Android): Use **native mode** (`new Mixpanel(token, true)`) for best performance, as it delegates to the optimized native SDKs.
* **React Native Web**: Use **JavaScript mode** (`new Mixpanel(token, true, false)`).


# Implement Session Replay (React Native)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/react-native/react-native-replay



Mixpanel's React Native Session Replay SDK enables you to capture and analyze user interactions in your mobile applications. Built as a Turbo Module for React Native's New Architecture, it provides native implementations for both iOS and Android with a unified JavaScript API.

## Features

* **📱 Cross-Platform Support** - Unified API for iOS and Android
* **🎥 Session Recording** - Capture user interactions and screen recordings
* **🔒 Privacy-First** - Built-in data masking for sensitive information
* **⚡ High Performance** - Native implementation with minimal JavaScript bridge overhead
* **🎯 Selective Recording** - Configurable sampling rates and recording controls
* **🚀 New Architecture Ready** - Built as a Turbo Module with full type safety
* **🛡️ Granular Privacy Controls** - Auto-masking and manual masking via wrapper components

## Requirements

* React Native >= 0.70
* iOS >= 13.0
* Android API Level >= 21
* New Architecture support (backward compatible with old architecture)

## Installation

```sh theme={"system"}
npm install @mixpanel/react-native-session-replay
```

or

```sh theme={"system"}
yarn add @mixpanel/react-native-session-replay
```

### Platform Setup

#### iOS

The SDK dependencies are automatically added via CocoaPods. Your project must target iOS 13 or later.

```sh theme={"system"}
cd ios && pod install
```

#### Android

Dependencies are automatically added through Gradle. Requirements:

* Minimum Android SDK 21+
* Kotlin support enabled

## Quick Start

Here's a minimal example to get started with Session Replay:

```typescript theme={"system"}
import {
  MPSessionReplay,
  MPSessionReplayConfig,
  MPSessionReplayMask,
} from "@mixpanel/react-native-session-replay";

// Initialize session replay
const config = new MPSessionReplayConfig({
  wifiOnly: false,
  recordingSessionsPercent: 100,
  autoStartRecording: true,
  autoMaskedViews: [MPSessionReplayMask.Image, MPSessionReplayMask.Text],
  flushInterval: 5,
  enableLogging: true,
});

await MPSessionReplay.initialize(token, distinctId, config).catch((error) => {
  console.error("Initialization error:", error);
});

// Control recording
await MPSessionReplay.startRecording();
await MPSessionReplay.stopRecording();

// Check recording status
const recording = await MPSessionReplay.isRecording();
```

## Data Residency

<Info>
  Available in React Native Session Replay SDK version `1.3.0` and later.
</Info>

If your Mixpanel project lives in the EU or India data center, or you route all Mixpanel traffic through a self-hosted proxy, set `serverURL` on `MPSessionReplayConfig`. The SDK exposes a `MPDataResidency` constant set with the managed region URLs so you don't have to hardcode them.

| Region       | `MPDataResidency` constant | URL                           |
| ------------ | -------------------------- | ----------------------------- |
| US (default) | `MPDataResidency.US`       | `https://api.mixpanel.com`    |
| EU           | `MPDataResidency.EU`       | `https://api-eu.mixpanel.com` |
| India        | `MPDataResidency.IN`       | `https://api-in.mixpanel.com` |

**Example Usage**

```typescript theme={"system"}
import {
  MPSessionReplay,
  MPSessionReplayConfig,
  MPDataResidency,
} from "@mixpanel/react-native-session-replay";

const config = new MPSessionReplayConfig({
  recordingSessionsPercent: 100,
  serverURL: MPDataResidency.EU,
});

await MPSessionReplay.initialize(token, distinctId, config);
```

You can also pass any fully-qualified HTTPS URL — useful when routing replay traffic through a self-hosted proxy:

```typescript theme={"system"}
const config = new MPSessionReplayConfig({
  serverURL: "https://mixpanel-proxy.yourcompany.com",
});
```

Learn more about [EU Data Residency](/docs/privacy/eu-residency) and [India Data Residency](/docs/privacy/in-residency).

## Configuration

The `MPSessionReplayConfig` class provides comprehensive control over session replay behavior:

```typescript theme={"system"}
const config = new MPSessionReplayConfig({
  wifiOnly: boolean,                // Default: true
  autoStartRecording: boolean,      // Default: true
  recordingSessionsPercent: number, // Default: 100 (range: 0-100)
  autoMaskedViews: MPSessionReplayMask[], // Default: all types
  flushInterval: number,            // Default: 10 (seconds)
  enableLogging: boolean,           // Default: false
});
```

### Configuration Options

| Option                     | Type                              | Default    | Description                                                                                                   |
| -------------------------- | --------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
| `wifiOnly`                 | boolean                           | `true`     | Only transmit recordings over WiFi                                                                            |
| `autoStartRecording`       | boolean                           | `true`     | Automatically start recording on initialization                                                               |
| `recordingSessionsPercent` | number                            | `100`      | Percentage of sessions to record (0-100)                                                                      |
| `autoMaskedViews`          | MPSessionReplayMask\[]            | All types  | View types to automatically mask                                                                              |
| `flushInterval`            | number                            | `10`       | Interval in seconds to flush recordings                                                                       |
| `enableLogging`            | boolean                           | `false`    | Enable debug logging                                                                                          |
| `remoteSettingsMode`       | MPSessionReplayRemoteSettingsMode | `Disabled` | Setting for handling remote configuration during SDK initialization. Can be `Disabled`/ `Fallback`/ `Strict`. |

### Auto-Masked View Types

The `MPSessionReplayMask` enum defines view types that can be automatically masked:

```typescript theme={"system"}
enum MPSessionReplayMask {
  Text = "text", // Text inputs and labels
  Web = "web", // WebView content
  Map = "map", // Map views (iOS only)
  Image = "image", // Image components
}
```

**Example - Custom Auto-Masking:**

```typescript theme={"system"}
import {
  MPSessionReplayConfig,
  MPSessionReplayMask,
} from "mixpanel-react-native-session-replay";

// Only mask text inputs and images
const config = new MPSessionReplayConfig({
  autoMaskedViews: [MPSessionReplayMask.Text, MPSessionReplayMask.Image],
});
```

## API Reference

### initialize

Initialize the Session Replay SDK with your configuration.

```typescript theme={"system"}
initialize(
  token: string,
  distinctId: string,
  config: MPSessionReplayConfig
): Promise<void>
```

**Parameters:**

* `token` (required) - Your Mixpanel project token
* `distinctId` (required) - User identifier for the session
* `config` (required) - Session replay configuration

**Validation:**

* Token must be a non-empty string
* distinctId must be a non-empty string
* recordingSessionsPercent must be between 0 and 100

**Example:**

```typescript theme={"system"}
const config = new MPSessionReplayConfig({
  autoStartRecording: true,
  enableLogging: __DEV__, // Enable logging in development
});

try {
  await MPSessionReplay.initialize("YOUR_TOKEN", "user-123", config);
  console.log("Session Replay initialized");
} catch (error) {
  console.error("Failed to initialize:", error);
}
```

### startRecording

Start recording user interactions.

```typescript theme={"system"}
startRecording(): Promise<void>
```

**Example:**

```typescript theme={"system"}
await MPSessionReplay.startRecording();
```

### stopRecording

Stop recording user interactions.

```typescript theme={"system"}
stopRecording(): Promise<void>
```

**Example:**

```typescript theme={"system"}
await MPSessionReplay.stopRecording();
```

### isRecording

Check if session recording is currently active.

```typescript theme={"system"}
isRecording(): Promise<boolean>
```

**Returns:** Boolean indicating recording status

**Example:**

```typescript theme={"system"}
const recording = await MPSessionReplay.isRecording();
if (recording) {
  console.log("Session is being recorded");
}
```

### identify

Update the user identifier for the current recording session.

```typescript theme={"system"}
identify(distinctId: string): Promise<void>
```

**Parameters:**

* `distinctId` (required) - New user identifier

**Example:**

```typescript theme={"system"}
// Update user ID after authentication
await MPSessionReplay.identify("authenticated-user-456");
```

## Remote Configuration

<Note>
  Available in React Native Session Replay SDK version `1.2.0` and later. Requires a paid Session Replay add-on.
</Note>

You can set the `remote_settings_mode` for your project in Mixpanel under `Settings > Organization Settings > Session Replay`. Using this, you can quickly set SDK options remotely without needing to update your app. This allows you to adjust recording settings, such as sampling rates, on the fly based on your needs.

Three modes are available:

* `Disabled`: Do not use remote configuration and proceed to use the hardcoded initial options provided by the user during initialization. This is the default behavior.
* `Fallback`: Attempt to retrieve remote configuration and proceed with those settings. If there is failure or timeout (500 ms), we will use the previously cached remote settings (if one exists from the last successful fetch). If no existing remote settings are cached, we will use the values from the SDK initialization config.
* `Strict`: Requires successful remote configuration fetch for SDK initialization. If there is failure or timeout (500 ms), SDK initialization will fail and the Session Replay features will be unavailable for that app launch.

You can use this setting to quickly update and adjust configurations to your liking.

List of currently supported remote settings:

* `recordingSessionsPercent`

Settings not yet supported by remote configuration will use the value provided during initialization, or the default value if none was provided

## Privacy & Data Masking

Session Replay provides two approaches to protect sensitive data: automatic masking and manual masking.

### Automatic Masking

Configure which view types are automatically masked during initialization:

```typescript theme={"system"}
const config = new MPSessionReplayConfig({
  autoMaskedViews: [
    MPSessionReplayMask.Text, // Masks all text inputs
    MPSessionReplayMask.Image, // Masks all images
    MPSessionReplayMask.Web, // Masks all WebViews
    MPSessionReplayMask.Map, // Masks map views (iOS only)
  ],
});
```

**Default Behavior:** All view types are masked by default for maximum privacy.

### Manual Masking with MPSessionReplayView

Use the `MPSessionReplayView` wrapper component for granular control over what gets masked:

```typescript theme={"system"}
import { MPSessionReplayView } from 'mixpanel-react-native-session-replay';

// Mask sensitive content
<MPSessionReplayView sensitive={true}>
  <TextInput
    value={password}
    onChangeText={setPassword}
    secureTextEntry
  />
  <Text>Social Security Number: {ssn}</Text>
</MPSessionReplayView>

// Explicitly mark content as safe (not masked)
<MPSessionReplayView sensitive={false}>
  <Text>Public information that should always be visible</Text>
</MPSessionReplayView>
```

### Complete Masking Example

```typescript theme={"system"}
import React, { useState } from "react";
import { View, TextInput, Image, Text } from "react-native";
import { MPSessionReplayView } from "mixpanel-react-native-session-replay";
import { WebView } from "react-native-webview";

function ProfileScreen() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");

  return (
    <View>
      {/* Public information - not masked */}
      <Text>Welcome to Your Profile</Text>

      {/* Sensitive user data - masked */}
      <MPSessionReplayView sensitive={true}>
        <View>
          <Text>Email: {email}</Text>
          <TextInput
            value={email}
            onChangeText={setEmail}
            placeholder="email@example.com"
          />

          <Text>Password:</Text>
          <TextInput
            value={password}
            onChangeText={setPassword}
            secureTextEntry
          />

          <Image source={{ uri: profilePhotoUrl }} />
        </View>
      </MPSessionReplayView>

      {/* WebView masked by default if Web type is in autoMaskedViews */}
      <WebView source={{ uri: "https://example.com/terms" }} />
    </View>
  );
}
```


# Mixpanel SDKs: Ruby
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/ruby



## Getting Started

The Mixpanel Ruby library is designed to be used for scripting, or in circumstances when a user isn't directly interacting with your application on the web or a mobile device.

The [Full API Reference](http://mixpanel.github.io/mixpanel-ruby), [Library Source Code](https://github.com/mixpanel/mixpanel-ruby), and an [Example Script](https://github.com/mixpanel/mixpanel-ruby/tree/master/demo) is documented in our GitHub repo.

See our [server](/docs/quickstart/connect-your-data?sdk=ruby) quickstart for how to get started with the Ruby SDK.

## Installing the Library

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/ruby#privacy-friendly-tracking).
</Warning>

To install the library, call the following in your command line to install the `mixpanel-ruby` gem:

```bash theme={"system"}
# install mixpanel ruby sdk with gem
gem install mixpanel-ruby
```

After the installation, import the gem and create an instance of the `Mixpanel::Tracker` class to start using the library in your code:

```ruby theme={"system"}
# import the mixpanel gem
require 'mixpanel-ruby'

# create an instance of the Mixpanel class
tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")
```

## Sending Events

Use [`track()`](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/Events.html#method-i-track) to send an event by providing the distinct\_id, event name, and any event properties. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```ruby theme={"system"}
# create an instance of the Mixpanel class
require 'mixpanel-ruby'
tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")

# track "some_event" for distinct_id 12345
# with "plan" event prop
tracker.track('12345', 'some_event', {
    'plan' => 'Premium'
})
```

Mixpanel determines default geolocation data (`$city`, `$region`, `mp_country_code`) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your data center. [Learn more about best practices for geolocation.](/docs/tracking-best-practices/geolocation).

### Importing Historical Events

The [`track()`](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/Events.html#method-i-track) function is designed for real-time tracking in a server-side environment and will trigger request to the [/track API endpoint](/reference/track-event), which will validate for events with a time stamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested.**

Use the [`import()`](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/Events.html#method-i-import) function to import events that occurred more than 5 days in the past. The `import()` function is based on the [/import API endpoint](/reference/import-events).

**Example Usage**

```ruby theme={"system"}
# create an instance of the Mixpanel class
require 'mixpanel-ruby'
tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")

# track "some_event" for distinct_id 12345
# with "plan" event prop
tracker.import("API_KEY", "12345", "Welcome Email Sent", {
    'Email Template' => 'Pretty Pink Welcome',
    'User Sign-up Cohort' => 'July 2013',
    'time' => 1369353600,
})
```

You can also use the [mp-utils python module](https://github.com/mixpanel/mixpanel-utils) designed for scripting.

## Managing User Identity

Since the Ruby SDK is a server-side library, IDs are not generated by the SDK. Instead, you will need to generate and manage the distinct\_id yourself and include it in your events and profile data.

Learn more about [server-side identity management](/docs/tracking-methods/id-management/identifying-users-simplified#server-side-identity-management).

## Storing User Profiles

Once your users are identified, create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Ruby SDK provides a few methods for setting profile properties, which will trigger requests to the [/engage API endpoint](/reference/profile-set).

Mixpanel determines default geolocation data (`$city`, `$region`, `mp_country_code`) using the IP address on the incoming request. As all server-side calls will likely originate from the same IP (that is, the IP of your server), this can have the unintended effect of setting the location of all of your users to the location of your data center. [Learn more about best practices for geolocation.](/docs/tracking-best-practices/geolocation).

### Setting Profile Properties

Instances of [`Mixpanel::Tracker`](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/Tracker.html) have a property called `people` that is an instance of [`Mixpanel::People`](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/People.html), which contain methods for managing user profile properties.

Set profile properties on a user profile by calling [`people.set()`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/People.html#method-i-set).

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```ruby theme={"system"}
# create an instance of the Mixpanel class
require 'mixpanel-ruby'
tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")

# create a user profile with name and email props
tracker.people.set('sample_distinct_id', {
    'name'       => 'Sam',
    '$email'     => 'sam@example.com'
}, ip = 0); # do not update geolocation

# update name property from "sam" to "samantha"
tracker.people.set('sample_distinct_id', {
    'name'       => 'Samantha'
}, ip = 0);
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/People.html).

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title="set_once()">
    The [`set_once()`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/People.html#method-i-set_once) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```ruby theme={"system"}
    # create an instance of the Mixpanel class
    require 'mixpanel-ruby'
    tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")

    # set profile properties for user "1234"
    tracker.people.set('1234', {
    'name'  => 'Sam'
    }, ip = 0);


    # will be ignored since "name" already exists
    tracker.people.set_once('1234', {
    'name'  => 'Samantha'
    }, ip = 0);

    # set "location" user prop since it does not exist
    tracker.people.set_once('1234', {
    'location'  => 'us'
    }, ip = 0);
    ```
  </Tab>

  <Tab title="append()">
    The [`append()`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/People.html#method-i-append) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```ruby theme={"system"}
    # create an instance of the Mixpanel class
    require 'mixpanel-ruby'
    tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN");

    # set profile properties for user "1234"
    tracker.people.set('1234', {
    'name'  => 'Sam',
    'roles' => ['sales','engineer']
    }, ip = 0);


    # add "legal" to "roles"  
    # new role values are ['sales','engineer','legal']
    tracker.people.append("1234", {
    'roles' => 'legal'
    }, ip = 0);

    # .append() allows duplicates
    # new "roles" values are ['sales','engineer','legal', 'legal']
    tracker.people.append("1234", {
    'roles' => 'legal'
    }, ip = 0);
    ```
  </Tab>

  <Tab title="union()">
    The [`union()`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/People.html#method-i-union) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```ruby theme={"system"}
    # create an instance of the Mixpanel class
    require 'mixpanel-ruby'
    tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")

    # set profile properties for user "1234"
    tracker.people.set('1234', {
    'name'  => 'Sam',
    'roles' => ['sales','engineer']
    }, ip = 0);

    # "engineer" ignored since it already exists
    # append "legal" to "roles"
    tracker.people.union("1234", {
    'roles' => ['engineer','legal']
    }, ip = 0);
    ```
  </Tab>

  <Tab title="increment()">
    The [`increment()`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/People.html#method-i-increment) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```ruby theme={"system"}
    # create an instance of the Mixpanel class
    require 'mixpanel-ruby'
    tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")

    # set profile properties for user "1234"
    tracker.people.set('1234', {
    'name'  => 'Sam',
    'age' => 25
    }, ip = 0);

    # increment "age" by 2
    tracker.people.increment('1234', {
    'age'  => 2,
    }, ip = 0);

    # use negative number to decrement
    # decrement "age" by 5
    tracker.people.increment('1234', {
    'age'  => -5,
    }, ip = 0);
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

### Sending Group Identifiers With Events

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

To send group identifiers with your events, set the `group_key` as an event property with the `group_id` as the value.

**Example Usage**

```ruby theme={"system"}
# track "some_event" with "sample_distinct_id"
# event is attributed to the "mixpanel" company group
Tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")
tracker.track("sample_distinct_id", “some_event”, {
  "company" => "mixpanel"
})
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

**Example Usage**

```ruby theme={"system"}
# track "some_event" with a "distinct_id"
# event is attributed to 2 company groups: "mp-us" and "mp-eu"
Tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")
tracker.track("sample_distinct_id", “some_event”, {
  "company" => ["mp-us","mp-eu"]
})
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `.people.set()` call.

**Example Usage**

```ruby theme={"system"}
# create an instance of the Mixpanel class
require 'mixpanel-ruby'
tracker = Mixpanel::Tracker.new("YOUR_PROJECT_TOKEN")

# set group key "company" as a user prop
# with group id "mixpanel" as value
tracker.people.set('sample_distinct_id', {
    'name'       => 'Sam',
    'company'     => 'mixpanel'
}, ip = 0);
```

### Setting Group Profile Properties

Create a group profile by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

Instances of [`Mixpanel::Tracker`](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/Tracker.html) have a property called `groups` that is an instance of [`Mixpanel::Groups`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/Groups.html), which contain methods for managing group profile properties.

To set group profile properties, use the [`groups.set()`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/Groups.html#method-i-set) method, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```ruby theme={"system"}
# create group profile for the "mixpanel" company group
# set "Company Type" and "$name" group profile properties
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)
tracker.groups.set('company', 'mixpanel', {
  '$name' => 'Mixpanel',
  'Company Type' => 'Analytics',
})
```

### Other Group Profile Methods

See all of the methods under the Groups class [here](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/Groups.html).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title="set_once()">
    The [`set_once()`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/Groups.html#method-i-set_once) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```ruby theme={"system"}
    tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

    # set group profile for "mixpanel" company group
    tracker.groups.set('company', 'mixpanel', {
      'name' => 'Mixpanel',
      'employee_count' => 100
    })

    # ignored since "name" is already exists
    tracker.groups.set_once('company', 'mixpanel', {
      'name' => 'mp-us',
    })

    # set "location" group prop since it does not exist
    tracker.groups.set_once('company', 'mixpanel', {
      'location' => 'us',
    })
    ```
  </Tab>

  <Tab title="unset()">
    The [`unset()`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/Groups.html#method-i-unset) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```ruby theme={"system"}
    tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

    # set group profile for the "mixpanel" company group
    tracker.groups.set('company', 'mixpanel', {
      'name' => 'Mixpanel',
      'employee_count' => 100
    })

    # delete "employee_count" from the group profile
    tracker.groups.unset('company', 'mixpanel', 'employee_count')

    # only "name" remains as a group prop
    ```
  </Tab>

  <Tab title="union()">
    The [`union()`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/Groups.html#method-i-union) method append new values to a list property, excluding duplicates.

    Use this method to create a list group profile property that only contains unique values without duplicates.

    **Example Usage**

    ```ruby theme={"system"}
    tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

    # set group profile for the "mixpanel" company group
    tracker.groups.set('company', 'mixpanel', {
      'name' => 'Mixpanel',
      'features' => ['alert','cohort','reports']
    })

    # add "data pipeline" to "features" prop
    # ignore "alert" since it is a duplicate value
    tracker.groups.union('company','mixpanel', {
        'features' => ['data pipeline','alert']
    })
    ```
  </Tab>

  <Tab title="remove()">
    The [`remove()`](https://mixpanel.github.io/mixpanel-ruby/Mixpanel/Groups.html#method-i-remove) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```ruby theme={"system"}
    tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

    # set group profile for the "mixpanel" company group
    mp.groups.set('company','mixpanel', {
        'name' => 'Mixpanel',
        'features' => ['reports','alerts','cohorts']
    })

    # remove "alerts" from "features"
    # "features" now contain ["reports","cohorts"]
    mixpanel.groups.remove('company','mixpanel', {
        'features' => ['alerts']
    })
    ```
  </Tab>
</Tabs>

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Ruby SDK have a few configurations to help you protect user data.

Since this is a server-side tracking library where you have control of the servers, your server is responsible for determining whether to send data about a particular user or not.

### EU Data Residency

Route data to Mixpanel's EU servers by using a custom [consumer](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/Consumer.html):

**Example Usage**

```ruby theme={"system"}
require 'mixpanel-ruby'

eu_consumer = Mixpanel::Consumer.new(
    'https://api-eu.mixpanel.com/track', #set track request URL
    'https://api-eu.mixpanel.com/engage', #set profile request URL
    'https://api-eu.mixpanel.com/groups', #set group request URL
)

# initialize Mixpanel with your custom consumer
tracker = Mixpanel::Tracker.new(YOUR_PROJECT_TOKEN) do |type, message|
    eu_consumer.send!(type, message)
end
```

### India Data Residency

Route data to Mixpanel's India servers by using a custom [consumer](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/Consumer.html):

**Example Usage**

```ruby theme={"system"}
require 'mixpanel-ruby'

in_consumer = Mixpanel::Consumer.new(
    'https://api-in.mixpanel.com/track', #set track request URL
    'https://api-in.mixpanel.com/engage', #set profile request URL
    'https://api-in.mixpanel.com/groups', #set group request URL
)

# initialize Mixpanel with your custom consumer
tracker = Mixpanel::Tracker.new(YOUR_PROJECT_TOKEN) do |type, message|
    in_consumer.send!(type, message)
end
```

### Disable Geolocation

The Ruby SDK parse the request IP address to generate geolocation properties for events and profiles. You may want to disable them to prevent the unintentional setting of your data's geolocation to the location of your server that is sending the request, or to prevent geolocation data from being tracked entirely.

To disable geolocation, set the `ip` of your events and profile updates to `0`.

**Example Usage**

```ruby theme={"system"}
require 'mixpanel-ruby'
tracker = Mixpanel::Tracker.new(YOUR_MIXPANEL_TOKEN)

# track "some_event" without geolocation parsing
tracker.track('sample_distinct_id', 'some_event', {
    'plan' => 'Premium'
}, ip=0)

# set age property without geolocation parsing
tracker.people.set('1234', {
    'age'  => -5,
    }, ip = 0);
```

## Release History

[See all releases.](https://github.com/mixpanel/mixpanel-ruby/releases)


# Implement Feature Flags (Ruby)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/ruby/ruby-flags



## Overview

This developer guide will assist you in configuring your server-side Ruby platform for [Feature Flags](/docs/featureflags) using the [Mixpanel Ruby SDK](/docs/tracking-methods/sdks/ruby). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

## Prerequisites

Before implementing [Feature Flags](/docs/featureflags), ensure:

* You are on an Enterprise subscription plan and have the [Mixpanel Ruby SDK](https://github.com/mixpanel/mixpanel-ruby) installed. If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK. The minimum supported version is [v3.0.0](https://rubygems.org/gems/mixpanel-ruby)
* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Flag Evaluation Scenarios

There are two scenarios available for using the Ruby SDK for feature flagging: Local Evaluation and Remote Evaluation.

For local evaluation, the SDK will poll Mixpanel servers for feature flag configurations. Assignment of user contexts to variants will be done locally within the SDK. This mode is recommended for low latency since there is no network call made at assignment time.

For remote evaluation, the SDK will make a network call to Mixpanel servers at assignment time. This mode is recommended for use cases where you want to leverage Mixpanel cohorts for user targeting or sticky variants for persistent variant assignments.

In either case there is also the capability to evaluate all flags for a given user context at once, to avoid needing to make multiple calls to get individual flag variants for the same user. This is particularly useful for remote evaluation to avoid incurring additional network calls.

## Local Evaluation

<Warning>
  Targeting by Mixpanel cohorts and sticky variants are not supported in Local Evaluation mode.
</Warning>

* The SDK is configured with a `local_flags_config` hash that specifies parameters:

  1. `api_host` - If your project is in the EU/IN region, this should be set to route to `api-eu.mixpanel.com`/`api-in.mixpanel.com` respectively.
  2. `enable_polling` - This should be set to `true` to enable polling for new flag configurations.
  3. `polling_interval_in_seconds` - This is the interval in seconds at which the SDK will poll Mixpanel servers for feature flag configurations.
* The SDK will continue to poll for the lifetime of the SDK instance or until stopped.

```ruby theme={"system"}
require 'mixpanel-ruby'

local_config = {
  api_host: 'api.mixpanel.com',
  enable_polling: true,
  polling_interval_in_seconds: 60
}

tracker = Mixpanel::Tracker.new('YOUR_PROJECT_TOKEN', local_flags_config: local_config)

# If enable_polling is set to false, this will fetch definitions only once for the lifetime of the SDK.
tracker.local_flags.start_polling_for_definitions!

# This should be the 'key' of the feature flag from Mixpanel's UX.
flag_key = 'sample-flag'

# This is the fallback variant to return if the user context is not in a rollout group for the flag.
fallback_variant = 'control'

# Current user context for evaluation.
# At minimum, this needs to include the user's distinct_id.
# If any of your feature flags use a Variant Assignment Key other than 'distinct_id', this should also include those keys for evaluation. For example, 'company_id' below
# If any of your feature flags use Runtime targeting, this should also include 'custom_properties' for evaluation
user_context = {
  'distinct_id' => '1234',
  'company_id' => 'X',
  'custom_properties' => {
    'platform' => 'ruby'
  }
}

# Gets the assigned variant for the flag for the given user context.
# This will return the fallback_variant if the user context is not in an assignment group for the flag.
variant_value = tracker.local_flags.get_variant_value(flag_key, fallback_variant, user_context)

# Check if a feature is enabled (returns boolean)
if tracker.local_flags.is_enabled?('new_feature', user_context)
  # Feature is enabled
else
  # Feature is disabled
end
```

## Remote Evaluation

* The SDK is configured with a `remote_flags_config` hash to use remote evaluation.

### Get a specific variant

```ruby theme={"system"}
require 'mixpanel-ruby'

remote_config = {
  api_host: 'api.mixpanel.com',
  request_timeout_in_seconds: 10
}

tracker = Mixpanel::Tracker.new('YOUR_PROJECT_TOKEN', remote_flags_config: remote_config)

# get_variant_value usage is the same as for local evaluation, but will make a network call to Mixpanel servers at assignment time.
variant_value = tracker.remote_flags.get_variant_value(flag_key, fallback_variant, user_context)

# is_enabled? also works with remote flags
if tracker.remote_flags.is_enabled?('beta_feature', user_context)
  # Feature is enabled
else
  # Feature is disabled
end
```

### Evaluate all flags at once

Below is a remote evaluation sample of evaluating all flags for a given user context at once.

```ruby theme={"system"}
require 'mixpanel-ruby'

user_context = {
  'distinct_id' => '1234'
}

remote_config = {
  api_host: 'api.mixpanel.com',
  request_timeout_in_seconds: 10
}

tracker = Mixpanel::Tracker.new('YOUR_PROJECT_TOKEN', remote_flags_config: remote_config)

# Returns a hash, mapping flag keys to assigned variants ONLY for flags that the user context is in an assignment group for.
# By default, this will not track an exposure event.
variants = tracker.remote_flags.get_all_variants(user_context)

# Given a flag key and the selected variant for that key, manually track an exposure event for a given flag and assigned variant, after exposing the user to the variant
tracker.remote_flags.track_exposure_event(flag_key, selected_variant, user_context)
```


# OpenFeature Provider (Ruby)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/ruby/ruby-openfeature



## Overview

This guide covers using Mixpanel's [Feature Flags](/docs/featureflags) through the [OpenFeature](https://openfeature.dev/) standard with the Mixpanel Ruby OpenFeature provider. OpenFeature provides a vendor-agnostic API for feature flag evaluation, allowing you to switch between providers without changing your application code.

For the native Mixpanel SDK approach, see the [Feature Flags (Ruby)](/docs/tracking-methods/sdks/ruby/ruby-flags) guide.

## Prerequisites

* Enterprise subscription plan with Feature Flags enabled
* Ruby 3.1.0 or higher
* Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Installation

Add to your `Gemfile`:

```ruby theme={"system"}
gem 'mixpanel-ruby-openfeature'
gem 'openfeature-sdk'
gem 'mixpanel-ruby'
```

Then run:

```bash theme={"system"}
bundle install
```

## Quick Start

```ruby theme={"system"}
require 'mixpanel-ruby'
require 'mixpanel/openfeature'

# 1. Create the provider with local evaluation
provider = Mixpanel::OpenFeature::Provider.from_local(
  'YOUR_PROJECT_TOKEN',
  { poll_interval: 300 }
)

# 2. Register the provider with OpenFeature
OpenFeature::SDK.configure do |config|
  config.set_provider(provider)
end

# 3. Get a client and evaluate flags
client = OpenFeature::SDK.build_client

show_new_feature = client.fetch_boolean_value(flag_key: 'new-feature-flag', default_value: false)

if show_new_feature
  puts 'New feature is enabled!'
end
```

## Initialization

### Local Evaluation (Recommended)

Downloads flag definitions and evaluates them locally with no per-evaluation network requests.

<Warning>
  Targeting by Mixpanel cohorts and sticky variants are not supported in Local Evaluation mode.
</Warning>

```ruby theme={"system"}
provider = Mixpanel::OpenFeature::Provider.from_local(
  'YOUR_PROJECT_TOKEN',
  { poll_interval: 300 }
)
```

### Remote Evaluation

Sends each flag check to Mixpanel's servers.

```ruby theme={"system"}
provider = Mixpanel::OpenFeature::Provider.from_remote(
  'YOUR_PROJECT_TOKEN',
  {}
)
```

### Using an Existing Tracker

```ruby theme={"system"}
tracker = Mixpanel::Tracker.new('YOUR_PROJECT_TOKEN', nil, local_flags_config: { poll_interval: 300 })
tracker.local_flags.start_polling_for_definitions!

provider = Mixpanel::OpenFeature::Provider.new(tracker.local_flags)
```

## Usage

### Flag Types and Evaluation Methods

| Mixpanel Flag Type | Variant Values                          | OpenFeature Method                                                                         |
| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------ |
| Feature Gate       | `true` / `false`                        | `fetch_boolean_value`                                                                      |
| Experiment         | boolean, string, number, or JSON object | `fetch_boolean_value`, `fetch_string_value`, `fetch_number_value`, or `fetch_object_value` |
| Dynamic Config     | JSON object                             | `fetch_object_value`                                                                       |

```ruby theme={"system"}
client = OpenFeature::SDK.build_client

# Feature Gate
is_feature_on = client.fetch_boolean_value(flag_key: 'new-checkout', default_value: false)

# Experiment with string variants
button_color = client.fetch_string_value(flag_key: 'button-color-test', default_value: 'blue')

# Experiment with number variants
max_items = client.fetch_number_value(flag_key: 'max-items', default_value: 10)

# Dynamic Config
feature_config = client.fetch_object_value(
  flag_key: 'homepage-layout',
  default_value: { 'layout' => 'grid', 'items_per_row' => 3 }
)
```

### Evaluation Context

```ruby theme={"system"}
context = OpenFeature::SDK::EvaluationContext.new(
  targeting_key: 'user-123',
  email: 'user@example.com',
  plan: 'premium'
)

value = client.fetch_boolean_value(
  flag_key: 'premium-feature',
  default_value: false,
  evaluation_context: context
)
```

<Note>
  Unlike some providers, `targetingKey` is not used as a special bucketing key. It is passed as another context property. Mixpanel's server-side configuration determines which properties are used for targeting and bucketing.
</Note>

### Full Resolution Details

```ruby theme={"system"}
details = client.fetch_boolean_details(flag_key: 'my-feature', default_value: false)

puts details.value
puts details.variant
puts details.reason
puts details.error_code
```

### Accessing the Mixpanel Tracker

```ruby theme={"system"}
provider.mixpanel.track('user-123', 'Page View', { 'page' => '/home' })
```

### Rails Integration

```ruby theme={"system"}
# config/initializers/openfeature.rb
provider = Mixpanel::OpenFeature::Provider.from_local(
  ENV['MIXPANEL_TOKEN'],
  { poll_interval: 300 }
)

OpenFeature::SDK.configure do |config|
  config.set_provider(provider)
end

at_exit { provider.shutdown }
```

### Shutdown

```ruby theme={"system"}
provider.shutdown
```

## Error Handling

| Error Code           | When                                                          |
| -------------------- | ------------------------------------------------------------- |
| `PROVIDER_NOT_READY` | Flags evaluated before the provider has finished initializing |
| `FLAG_NOT_FOUND`     | The requested flag does not exist in Mixpanel                 |
| `TYPE_MISMATCH`      | The flag value type does not match the requested type         |

## Troubleshooting

### Flags Always Return Default Values

1. **Provider not ready:** Flag definitions are fetched asynchronously. Allow time for the initial fetch.
2. **Invalid project token:** Verify the token matches your Mixpanel project.
3. **Flag not configured:** Verify the flag exists and is enabled.

### Type Mismatch Errors

Verify the flag's value type matches your evaluation method. Use `fetch_object_value` for JSON objects.


# Mixpanel SDKs: iOS (Swift)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/swift



## Getting Started

Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=swift).

The [Full API Reference](https://mixpanel.github.io/mixpanel-swift/), [Library Source Code](https://github.com/mixpanel/mixpanel-swift), and an [Example Application](https://github.com/mixpanel/mixpanel-swift/tree/master/MixpanelDemo/MixpanelDemo) are documented in our GitHub repo.

## Installing the Library

You can install the Swift library by using CocoaPods, Carthage, or Swift Package Manager.

<Tabs>
  <Tab title="Swift Package Manager">
    1. In Xcode, select File > Add Packages...
    2. Enter the package URL for [this repository](https://github.com/mixpanel/mixpanel-swift) and select version v2.8.0 or above.
  </Tab>

  <Tab title="CocoaPods">
    1. Install CocoaPods by typing the following in your command line:

    ```bash theme={"system"}
    # install CocoaPods
    gem install cocoapods
    ```

    2. After installing CocoaPods, create a local CocoaPods spec mirror by running the following:

    ```bash theme={"system"}
    # Create CocoaPods spec mirror
    pod setup
    ```

    3. Then navigate to your Xcode project directory and create a Podfile by running the following:

    ```bash theme={"system"}
    # create Podfile in project directory
    pod init
    ```

    4. Open the Podfile that was generated and add the Mixpanel library to your dependencies:

    ```ruby Ruby theme={"system"}
    target 'MyApp' do
      pod 'Mixpanel-swift'
    end
    ```

    5. Install the Mixpanel library and create a new Xcode workspace by running the following in the Xcode project directory:

    ```bash theme={"system"}
    // install library in your dependencies
    pod install
    ```
  </Tab>

  <Tab title="Carthage">
    Mixpanel supports [Carthage](https://github.com/Carthage/Carthage#quick-start) to package your dependencies as a framework. Include the following dependency in your Cartfile:

    ```bash theme={"system"}
    # add Mixpanel library to your dependencies
    github "mixpanel/mixpanel-swift"
    ```
  </Tab>
</Tabs>

After installing the library, import `Mixpanel` into `AppDelegate.swift` and initialize Mixpanel within [`application:didFinishLaunchingWithOptions:`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622921-application) using your [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).

```swift Swift theme={"system"}
/// import Mixpanel class from the library
import Mixpanel

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    ...
    /// initialize Mixpanel using your project token
    let options = MixpanelOptions(token: "YOUR_PROJECT_TOKEN")
    Mixpanel.initialize(options: options)
    ...
}
```

<span />

### SDK Configuration Using MixpanelOptions

<Warning>
  **Data Residency:** For projects with EU or India data residency, you must configure the SDK to use the correct [regional endpoint](#data-residency). Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/swift#privacy-friendly-tracking)
</Warning>

Configure the Mixpanel SDK using [`MixpanelOptions`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelOptions.html) to customize tracking behavior, data residency, privacy settings, and more.

#### Configuration Reference

| Config Option                | Description                                                                                                                                                               | Default                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `token`                      | Your Mixpanel project token (required)                                                                                                                                    | N/A                                  |
| `serverURL`                  | Custom API endpoint. **Required** for [EU](#eu-data-residency) or [India](#india-data-residency) data residency. Takes precedence over `proxyServerConfig.serverUrl`      | US (`https://api.mixpanel.com`)      |
| `flushInterval`              | Interval in seconds between automatic flush operations. Set to `0` to disable. See [Flushing Events](#flushing-events)                                                    | `60`                                 |
| `trackAutomaticEvents`       | Auto-track app lifecycle events. **Not recommended** — see [Legacy Automatically Tracked Events](#legacy-automatically-tracked-events)                                    | `false`                              |
| `optOutTrackingByDefault`    | Start with tracking disabled for GDPR compliance. See [Opt Out of Tracking](#opt-out-of-tracking)                                                                         | `false`                              |
| `useIPAddressForGeoLocation` | Enable IP-based geolocation. See [Disable Geolocation](#disable-geolocation)                                                                                              | `true`                               |
| `useUniqueDistinctId`        | Use device IDFV instead of random UUID. See [Custom Device ID Generation](#custom-device-id-generation)                                                                   | `false`                              |
| `instanceName`               | Unique identifier for multi-instance setups                                                                                                                               | Project token                        |
| `deviceIdProvider`           | Custom closure for device ID generation (requires v5.2.0+). See [Custom Device ID Generation](#custom-device-id-generation)                                               | `nil`                                |
| `superProperties`            | Properties automatically added to all events. Can also be set at runtime. See [Setting Super Properties](#setting-super-properties)                                       | `nil`                                |
| `featureFlagOptions`         | Feature flags configuration (prefetch behavior and custom context). See [Feature Flags Initialization](/docs/tracking-methods/sdks/swift/swift-flags#flag-initialization) | `FeatureFlagOptions(enabled: false)` |
| `proxyServerConfig`          | Proxy configuration with headers and query params                                                                                                                         | `nil`                                |
| `useGzipCompression`         | Enable gzip compression for network requests                                                                                                                              | `true`                               |

<Note>
  **Best Practice:** Configure all settings (especially `serverURL` for data residency) during initialization using `MixpanelOptions`. This ensures all SDK components (events, profiles, feature flags) use the correct configuration from the start, avoiding potential race conditions.
</Note>

After initialization, you can further customize the instance using methods on [`MixpanelInstance`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html).

**Common Configuration Example**

```swift Swift theme={"system"}
import Mixpanel

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    ...
    /// Configure Mixpanel for EU data residency
    let options = MixpanelOptions(
        token: "YOUR_PROJECT_TOKEN",
        serverURL: "https://api-eu.mixpanel.com",
        flushInterval: 15
    )
    Mixpanel.initialize(options: options)

    /// Enable debug logging after initialization
    Mixpanel.mainInstance().loggingEnabled = true
    ...
}
```

See detailed explanations of each option in the sections below.

## Sending Events

Use [`.track(event:properties:)`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC5track5event10propertiesySSSg_SDySSAA0A4Type_pGSgtF) to send an event by providing the event name and any event properties. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```swift Swift theme={"system"}
/// track "some_event" 
/// with "plan" event prop set to "Premium"
Mixpanel.mainInstance().track(event: "some_event",
    properties:["Plan": "Premium"])
```

### Timing Events

You can track the time it took for an action to occur, such as an image upload or a comment post, using [`.time(event:)`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:FC8Mixpanel16MixpanelInstance4timeFT5eventSS_T_). This will mark the "start" of your action, which you can then finish with a track call. The time duration is then recorded in the "Duration" property.

```swift Swift theme={"system"}
/// start the timer for the event "Image Upload"
Mixpanel.mainInstance().time(event: "Image Upload")

/// 20 seconds later...

/// track "Image Upload" event with "Duration" event prop set to 20
Mixpanel.mainInstance().track(event: "Image Upload")
```

### Flushing Events

To preserve battery life and customer bandwidth, the Mixpanel library doesn't send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background.

Call [`.flush()`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC5flush16performFullFlush10completionySb_yycSgtF) manually if you want to force a flush at a particular moment.

**Example Usage**

```swift Swift theme={"system"}
/// flush batched events for ingestion immediately
Mixpanel.mainInstance().flush()
```

#### Configuring Flush Interval

The default flush interval is 60 seconds. You can customize this using the [`flushInterval`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelOptions.html) option in `MixpanelOptions` (see [Configuration Reference](#configuration-reference)). Set to `0` to disable automatic flushing entirely (requires manual `.flush()` calls).

**Recommended: Configure During Initialization**

```swift Swift theme={"system"}
/// Set flush interval to 120 seconds during initialization
let options = MixpanelOptions(
    token: "YOUR_PROJECT_TOKEN",
    flushInterval: 120  // Flush every 2 minutes
)
Mixpanel.initialize(options: options)
```

**Alternative: Update After Initialization** You can also update the flush interval dynamically using [`flushInterval`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC13flushIntervalSdvp).

```swift Swift theme={"system"}
/// Change flush interval at runtime
Mixpanel.mainInstance().flushInterval = 120
```

#### Importing Historical Events

The Swift SDK is a tracking SDK designed for real-time tracking in a client-side environment. Calling [`.track(event:properties:)`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC5track5event10propertiesySSSg_SDySSAA0A4Type_pGSgtF) triggers a request to our [/track API endpoint](/reference/track-event), which will validate for events with a timestamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested**.

For bulk import of historical events older than 5 days, we will need to use the [/import API endpoint](/reference/import-events) which is optimized for scripting and supports ingesting historical data. We recommend the [Python SDK](/docs/tracking-methods/sdks/python) (see the [`.import_data()`](https://mixpanel.github.io/mixpanel-python/#primary-interface) function) and [mixpanel-utils module](https://github.com/mixpanel/mixpanel-utils) (see the [`import_events()`](https://github.com/mixpanel/mixpanel-utils?tab=readme-ov-file#import-events) function) which both leverages the /import API for event ingestion.

## Setting Super Properties

Super properties are global event properties that you define once and apply to all events. You can set super properties during SDK initialization or at runtime.

### Setting Super Properties During Initialization

You can set initial super properties using the [`superProperties`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelOptions.html) option in `MixpanelOptions` (see [Configuration Reference](#configuration-reference)).

**Example Usage**

```swift Swift theme={"system"}
let options = MixpanelOptions(
    token: "YOUR_PROJECT_TOKEN",
    superProperties: [
        "app_version": "1.2.3",
        "platform": "iOS"
    ]
)
Mixpanel.initialize(options: options)

/// track "some_event"
/// "app_version" and "platform" are automatically added as event props
Mixpanel.mainInstance().track(event: "some_event")
```

### Setting Super Properties at Runtime

To register super properties at runtime, call [`.registerSuperProperties(_:)`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC23registerSuperPropertiesyySDySSAA0A4Type_pGF).

Use [`.registerSuperPropertiesOnce(_:)`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC27registerSuperPropertiesOnce_12defaultValueySDySSAA0A4Type_pG_AaF_pSgtF) to register super properties without overwriting existing values.

**Example Usage**

```swift Swift theme={"system"}
/// register a "name" super property
Mixpanel.mainInstance().registerSuperProperties(["name": "Sam"])

/// track "some_event"
/// "name" is automatically added as an event prop
Mixpanel.mainInstance().track(event: "some_event")
```

**Best Practice: Batch Multiple Properties**

Creating properties involves an async operation to local storage. If you need to create multiple properties at once, it's best to send a single call to the register function with all properties at once, to avoid possible issues with race conditions overwriting each other.

**Example Usage**

```swift Swift theme={"system"}
Mixpanel.mainInstance().registerSuperProperties([
    "superProp0": "value1",
    "superProp1": "value2",
    "superProp2": "value3",
    "superProp3": 1,
    "superProp4": 2,
    "superProp5": 3
])

Mixpanel.mainInstance().track(event: "test")
```

See more methods related to super properties in the complete library reference [here](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html).

## Managing User Identity

You can handle the identity of a user using the [`.identify()`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC8identify10distinctId9usePeople10completionySS_SbyycSgtF) and [`.reset()`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC5reset10completionyyycSg_tF) methods. Learn more about [identity management](/docs/tracking-methods/id-management/identity-management) and [identifying users](/docs/tracking-methods/id-management/identifying-users).

### Identify

<Warning>
  We recommend against calling `.identify()` for anonymous visitors to your site.
</Warning>

Call [`.identify()`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC8identify10distinctId9usePeople10completionySS_SbyycSgtF) when you know the identity of the current user, passing in their user ID as an argument. This is typically at account registration and at log in.

```swift Swift theme={"system"}
/// your user signs in and tracks a sign in event
Mixpanel.mainInstance().track(event: "sign in")

/// upon sign in, identify the user with their ID
/// ensure future events sent from the user have distinct_id 12345
Mixpanel.mainInstance().identify(distinctId: "12345");
```

### Call Reset on Logout

Call [`.reset()`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC5reset10completionyyycSg_tF) to clear data attributed to a user when they logout. This will clear the local storage and allows you to handle [multiple users on a single device](/docs/tracking-methods/id-management/identifying-users-simplified#multiple-users-one-device).

**Example Usage**

```swift Swift theme={"system"}
/// your user signs out and tracks a log out event
Mixpanel.mainInstance().track(event: "log out")

/// upon logout, call reset to clear local storage
/// new distinct_id is generated for events moving forward
Mixpanel.mainInstance().reset()
```

<Note>
  Since v2.7.7, Mixpanel stopped using the IFA (ID for Advertisers) as a distinct\_id. Calls to `.reset()` will generate a new random UUID unless you've configured custom device ID behavior. See [Custom Device ID Generation](#custom-device-id-generation) for details on using IDFV or implementing custom device ID logic.
</Note>

### Custom Device ID Generation

The Swift SDK provides two ways to customize device ID generation (see [Configuration Reference](#configuration-reference)):

1. **`useUniqueDistinctId`** - Use device IDFV (Identifier for Vendor) instead of random UUID
2. **`deviceIdProvider`** - Custom closure for implementing your own device ID generation logic

<Warning>
  Customizing device ID generation is an architectural decision that should be made at project inception. Changing this after deployment can cause user identity management issues.
</Warning>

#### Using Device IDFV

Set [`useUniqueDistinctId`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelOptions.html) to `true` to use the device's IDFV instead of a random UUID. The IDFV persists across app updates but changes when the app is uninstalled and reinstalled.

**Example Usage**

```swift Swift theme={"system"}
let options = MixpanelOptions(
    token: "YOUR_PROJECT_TOKEN",
    useUniqueDistinctId: true  // Use IDFV instead of UUID
)
Mixpanel.initialize(options: options)
```

<Note>
  You can also enable IDFV by setting `MIXPANEL_UNIQUE_DISTINCT_ID` in build settings `Active Compilation Conditions` on the Mixpanel framework target. When using IDFV, the ID will not change when you call `.reset()`, but will change upon app uninstalls/reinstalls.
</Note>

#### Custom Device ID Provider

<Note>
  The `deviceIdProvider` option requires Swift SDK [v5.2.0](https://github.com/mixpanel/mixpanel-swift/releases/tag/v5.2.0) or later.
</Note>

For advanced use cases, use the [`deviceIdProvider`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelOptions.html) closure to implement custom device ID generation logic. This allows you to control where device IDs are stored and whether they persist across `.reset()` calls.

If the provider returns `nil` or an empty string, the SDK will fall back to generating a default device ID (UUID or IDFV based on `useUniqueDistinctId`).

**Example Usage**

```swift Swift theme={"system"}
// create a device ID provider
let options = MixpanelOptions(
    token: "YOUR_PROJECT_TOKEN",
    deviceIdProvider: {
        return getYourCustomDeviceId()
    }
)

let mixpanel = Mixpanel.initialize(options: options)
```

**Persistent vs Ephemeral IDs**

Returning the same value each time the provider is called creates a persistent device ID that survives `.reset()` calls. Returning different values generates a new device ID on each reset.

```swift Swift theme={"system"}
// persistent ID - survives reset() calls
let options = MixpanelOptions(
    token: "YOUR_PROJECT_TOKEN",
    deviceIdProvider: {
        return getStoredDeviceId() // returns same value every time
    }
)

// ephemeral ID - changes on reset() calls
let options = MixpanelOptions(
    token: "YOUR_PROJECT_TOKEN",
    deviceIdProvider: {
        return generateNewDeviceId() // returns new value each time
    }
)
```

## Storing User Profiles

Once your users are identified, create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Swift SDK provides a few methods for setting profile properties under the [`People`](https://mixpanel.github.io/mixpanel-swift/Classes/People.html) class accessible via [`.people()`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC6peopleAA6PeopleCSgvp). These methods will trigger requests to the [/engage API endpoint](/reference/profile-set).

### Setting Profile Properties

<Note>
  You must call `.identify()` before setting profile properties in order to associate the profile properties you set with the target user. If identify is not called, the profile update will be queued for ingestion until an identify call is made.
</Note>

You can set properties on a user profile with [`people.set(property:to:)`](https://mixpanel.github.io/mixpanel-swift/Classes/People.html#/s:FC8Mixpanel6People3setFT8propertySS2toPs9AnyObject__T_).

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```swift Swift theme={"system"}
/// You must call identify to associate the profile update with the user
Mixpanel.mainInstance().identify(distinctId: "12345")

/// Set user's "Plan" profile prop to "Premium"
Mixpanel.mainInstance().people.set(properties: ["plan":"Premium", "$email":"joe.doe@example.com"])

/// Update "plan" to "Enterprise"
Mixpanel.mainInstance().people.set(properties: ["plan":"Enterprise"])
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](https://mixpanel.github.io/mixpanel-swift/Classes/People.html)

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title="setOnce()">
    The [`setOnce(properties:)`](https://mixpanel.github.io/mixpanel-swift/Classes/People.html#/s:8Mixpanel6PeopleC7setOnce10propertiesySDySSAA0A4Type_pG_tF) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```swift Swift theme={"system"}
    /// set profile properties for user "12345"
    Mixpanel.mainInstance().identify(distinctId: "12345")
    Mixpanel.mainInstance().people.set(properties: ["name":"Sam"])

    /// will be ignored since "name" already exists
    Mixpanel.mainInstance().people.setOnce(properties: ["name":"Samantha"])

    /// set "location" property since it does not exist
    Mixpanel.mainInstance().people.setOnce(properties: ["location":"us"])
    ```
  </Tab>

  <Tab title="append()">
    The [`append(properties:)`](https://mixpanel.github.io/mixpanel-swift/Classes/People.html#/s:8Mixpanel6PeopleC6append10propertiesySDySSAA0A4Type_pG_tF) method appends values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```swift Swift theme={"system"}
    /// set profile properties for user "12345"
    Mixpanel.mainInstance().identify(distinctId: "12345")
    Mixpanel.mainInstance().people.set(properties: [
        "roles":["sales","engineer"]
        ])


    /// add "legal" to "roles"
    /// new "roles" values are ['sales','engineer','legal']
    Mixpanel.mainInstance().people.append(properties: [
        "roles":"legal"
        ])

    /// append() allows duplicates
    // new "roles" values are ['sales','engineer','legal','legal']
    Mixpanel.mainInstance().people.append(properties: [
        "roles":"legal"
        ])
    ```
  </Tab>

  <Tab title="union()">
    The [`union(properties:)`](https://mixpanel.github.io/mixpanel-swift/Classes/People.html#/s:8Mixpanel6PeopleC5union10propertiesySDySSAA0A4Type_pG_tF) method appends new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```swift Swift theme={"system"}
    /// set profile properties for user "12345"
    Mixpanel.mainInstance().identify(distinctId: "12345")
    Mixpanel.mainInstance().people.set(properties: [
        "roles":["sales","engineer"]
        ])

    /// will be ignored since "engineer" already exists in "roles"
    Mixpanel.mainInstance().people.union(properties: [
        "roles":"engineer"
        ])

    /// add "legal" to "roles"
    /// "roles" = ['sales','engineer','legal']
    Mixpanel.mainInstance().people.union(properties: [
        "roles":"legal"
        ])
    ```
  </Tab>

  <Tab title="increment()">
    The [`increment(property:by:)`](https://mixpanel.github.io/mixpanel-swift/Classes/People.html#/s:8Mixpanel6PeopleC9increment8property2byySS_SdtF) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```swift Swift theme={"system"}
    /// set profile properties for user "12345"
    Mixpanel.mainInstance().identify(distinctId: "12345")
    Mixpanel.mainInstance().people.set(properties: ["age":25])

    /// increment "age" by 2
    Mixpanel.mainInstance().people.increment(property: "age", by: 2)

    /// use negative number to decrement
    /// decrement "age" by 5
    Mixpanel.mainInstance().people.increment(property: "age", by: -5)
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

The Swift SDK provides a few methods for adding individual users to a group and setting group profile properties.

### Adding Users to a Group

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

Call the [`setGroup(groupKey:groupIDs:)`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC8setGroup8groupKey0E2IDySS_AA0A4Type_ptF) to register the current user to a group, which would add the `group_key` as an event property set to the `group_id` value to all events moving forward.

**Example Usage**

```swift Swift theme={"system"}
/// assign the current user to the "mixpanel" company group
Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])

/// track "some_event"
/// event prop "company" = ["mixpanel"] is added automatically
Mixpanel.mainInstance().track(event: "some_event")


/// alternatively you can define the group key manually
Mixpanel.mainInstance().track(event: "some_event", properties: [
    "company": ["mixpanel"]])
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

Call [`addGroup(groupKey:groupID:)`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC8addGroup8groupKey0E2IDySS_AA0A4Type_ptF) to add additional `group_id`s to an existing group key property.

**Example Usage**

```swift Swift theme={"system"}
/// assign the current user to the "mixpanel" company group
Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])

/// add "mp-us" as an additional company group
Mixpanel.mainInstance().addGroup(groupKey: "company", groupID: "mp-us")

/// track "some_event"
/// event prop "company" = ["mixpanel","mp-us"] is added automatically
Mixpanel.mainInstance().track(event: "some_event")
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `.people.set()` call.

**Example Usage**

```swift Swift theme={"system"}
/// You must call identify to associate the profile update with the user
Mixpanel.mainInstance().identify(distinctId: "12345")

/// set group key "company" as a user prop
/// with group id "mixpanel" as value
Mixpanel.mainInstance().people.set(properties: ["company":"mixpanel", "$email":"joe.doe@example.com"])
```

### Setting Group Profile Properties

Create a group profiles by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as "ARR", "employee\_count", and "subscription".

To set group profile properties, specify the group that needs to be updated by calling [`getGroup(groupKey:groupID:)`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC8getGroup8groupKey0E2IDAA0D0CSS_AA0A4Type_ptF), then set the group properties by chaining the [`set(properties:)`](https://mixpanel.github.io/mixpanel-swift/Classes/Group.html#/s:8Mixpanel5GroupC3set10propertiesySDySSAA0A4Type_pG_tF) method, which will trigger a request to the [/groups API endpoint](/reference/group-set-property).

**Example Usage**

```swift Swift theme={"system"}
/// assign the current user to the "mixpanel" company group
Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])

/// specify the target group using the group_key and group_id using getGroup()
/// set "industry" as a group profile prop to "analytics" using set()
Mixpanel.mainInstance().getGroup(groupKey: "Company", groupID: “mixpanel”).set(properties: [
    "industry": "analytics"
])
```

### Other Group Profile Methods

See all of the methods under the MixpanelGroup class [here](https://mixpanel.github.io/mixpanel-swift/Classes/Group.html).

A few commonly used group methods are highlighted below:

<Tabs>
  <Tab title="setOnce()">
    The [`setOnce(properties:)`](https://mixpanel.github.io/mixpanel-swift/Classes/Group.html#/s:8Mixpanel5GroupC7setOnce10propertiesySDySSAA0A4Type_pG_tF) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set group profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```swift Swift theme={"system"}
    /// assign the current user to the "mixpanel" company group
    Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])

    /// set group profile properties
    Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).set(properties: [
        "name": "Mixpanel"])

    /// ignored since "name" already exists
    Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).setOnce(properties: [
        "name": "mp"])

    /// set "country" group prop since it does not exist
    Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).setOnce(properties: [
        "country": "us"])
    ```
  </Tab>

  <Tab title="unset()">
    The [`unset(property:)`](https://mixpanel.github.io/mixpanel-swift/Classes/Group.html#/s:8Mixpanel5GroupC5unset8propertyySS_tF) method removes a group property from a group profile.

    Use this method to delete unwanted group profile properties from a specific group profile.

    **Example Usage**

    ```swift Swift theme={"system"}
    /// assign the current user to the "mixpanel" company group
    Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])

    /// set group profile properties
    Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).set(properties: [
        "name": "Mixpanel",
        "employee_count": 100
    ])

    /// delete "employee_count" from the group profile
    Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).unset(properties: "employee_count")

    /// The group only has the "name" property remaining
    ```
  </Tab>

  <Tab title="union()">
    The [`union(key:values:)`](https://mixpanel.github.io/mixpanel-swift/Classes/Group.html#/s:8Mixpanel5GroupC5union3key6valuesySS_SayAA0A4Type_pGtF) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```swift Swift theme={"system"}
    /// assign the current user to the "mixpanel" company group
    Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])

    /// set group profile properties
    Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).set(properties: [
        "name": "Mixpanel",
        "features": ["reports","alerts","cohorts"]
    ])

    /// add "data pipeline" to "features" prop
    /// ignore "alerts" since it is a duplicate value
    Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).union(key: "features",
        values: ["data pipeline","alerts"])
    ```
  </Tab>

  <Tab title="remove()">
    The [`remove(key:value:)`](https://mixpanel.github.io/mixpanel-swift/Classes/Group.html#/s:8Mixpanel5GroupC6remove3key5valueySS_AA0A4Type_ptF) method removes a value from a list-valued group profile property.

    Use this method to remove specific values from a list without affecting all of the other values in the list.

    **Example Usage**

    ```swift Swift theme={"system"}
    /// assign the current user to the "mixpanel" company group
    Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])

    /// set group profile properties
    Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).set(properties: [
        "name": "Mixpanel",
        "features": ["reports","alerts","cohorts"]
    ])

    /// remove "alerts" from "features"
    Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).remove(
        key: "features", value: "alerts")

    /// "features" = ["reports","cohorts"]
    ```
  </Tab>
</Tabs>

## Autocapture

The Mixpanel Swift SDK provides methods on the `autocapture` object to help you track common user interactions with minimal instrumentation. These methods fire standardized events that are recognized by the Mixpanel platform.

### Screen View & Screen Leave

Modern iOS apps use a variety of UI frameworks — UIKit with view controllers, SwiftUI with `NavigationStack`, or a mix of both. Each defines and transitions between "screens" differently, making it impractical for the SDK to automatically detect screen boundaries across all setups. Instead, you hook `trackScreenView` and `trackScreenLeave` into your app's navigation, giving you full control over what counts as a screen and when transitions happen.

Track screen navigations using `trackScreenView` and `trackScreenLeave`. These methods fire the following events:

| Method               | Mixpanel Event   |
| -------------------- | ---------------- |
| `trackScreenView()`  | `$mp_page_view`  |
| `trackScreenLeave()` | `$mp_page_leave` |

Both events automatically include `current_page_title` (the screen name) and `$mp_autocapture: true`.

<Tabs>
  <Tab title="Manual">
    Call these methods from any view controller or SwiftUI view:

    ```swift theme={"system"}
    Mixpanel.mainInstance().autocapture.trackScreenView(screenName: "HomeScreen")
    Mixpanel.mainInstance().autocapture.trackScreenLeave(screenName: "HomeScreen")
    ```
  </Tab>

  <Tab title="UIKit (Swizzling)">
    Swizzle `viewDidAppear` and `viewWillDisappear` once at launch to track every view controller automatically:

    ```swift theme={"system"}
    // In AppDelegate.didFinishLaunchingWithOptions:
    Mixpanel.initialize(token: "YOUR_TOKEN", trackAutomaticEvents: true)
    UIViewController.setupAutomaticScreenTracking()
    ```

    ```swift theme={"system"}
    extension UIViewController {
        static func setupAutomaticScreenTracking() {
            swizzle(#selector(viewDidAppear(_:)), with: #selector(mp_viewDidAppear(_:)))
            swizzle(#selector(viewWillDisappear(_:)), with: #selector(mp_viewWillDisappear(_:)))
        }

        @objc private func mp_viewDidAppear(_ animated: Bool) {
            mp_viewDidAppear(animated)
            let name = String(describing: type(of: self))
            guard !name.hasPrefix("UI"), !name.hasPrefix("_") else { return }
            Mixpanel.mainInstance().autocapture.trackScreenView(screenName: name)
        }

        @objc private func mp_viewWillDisappear(_ animated: Bool) {
            mp_viewWillDisappear(animated)
            let name = String(describing: type(of: self))
            guard !name.hasPrefix("UI"), !name.hasPrefix("_") else { return }
            Mixpanel.mainInstance().autocapture.trackScreenLeave(screenName: name)
        }

        private static func swizzle(_ original: Selector, with swizzled: Selector) {
            guard let m1 = class_getInstanceMethod(UIViewController.self, original),
                  let m2 = class_getInstanceMethod(UIViewController.self, swizzled)
            else { return }
            method_exchangeImplementations(m1, m2)
        }
    }
    ```
  </Tab>
</Tabs>

#### Passing Custom Properties

Both methods accept an optional `properties` parameter. For example, forwarding UTM params from a deep link:

```swift theme={"system"}
let queryItems = urlComponents.queryItems
let utmProps: Properties = [
    "utm_source": queryItems?.first(where: { $0.name == "utm_source" })?.value ?? "",
    "utm_medium": queryItems?.first(where: { $0.name == "utm_medium" })?.value ?? "",
    "utm_campaign": queryItems?.first(where: { $0.name == "utm_campaign" })?.value ?? ""
]
Mixpanel.mainInstance().autocapture.trackScreenView(
    screenName: "PromoScreen", properties: utmProps
)
```

## Session Replay

Install the [Session Replay SDK for Swift](/docs/tracking-methods/sdks/swift/swift-replay) to record replay data. Learn more about [Session Replay](/docs/session-replay) and [implementing Session Replay on iOS](/docs/tracking-methods/sdks/swift/swift-replay).

## Debugging and Logging

### Enable SDK logs

Enable debug mode by setting the [`loggingEnabled`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC14loggingEnabledSbvp) configuration to `true`.

**Example Usage**

```swift Swift theme={"system"}
/// enable debug log
Mixpanel.mainInstance().loggingEnabled = true
```

Learn more about [debugging](/docs/tracking-best-practices/debugging).

### Network Failover

Configure a backup host for automatic failover when the primary API endpoint is unreachable. The default primary endpoint is `api.mixpanel.com` (or your configured custom endpoint for EU/India data residency or proxy server). This can be used as a troubleshooting fallback when network calls to the Mixpanel endpoint are blocked or unreachable.

**Setup**

```swift Swift theme={"system"}
let mixpanel = Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN")
mixpanel.backupHost = "api-backup.mixpanel.com"
```

The SDK automatically retries failed requests to the backup host, preserving the same URL path, authentication, and headers as the primary.

**How It Works**

Failover triggers:

* Network failures (connection timeout, DNS errors)
* Non 4xx HTTP status codes

No failover for:

* Client errors (HTTP 4xx) - indicates invalid request
* Successful responses (HTTP 200 OK)
* Parse errors

This works with proxy server setups as well - if the proxy fails, the backup will be tried.

**Requirements**

Your backup host must:

* Support the same API endpoints (`/track/`, `/engage/`, `/groups/`)
* Accept the same authentication mechanism as the primary host
* Use the same URL scheme and port as configured for the primary host

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Swift SDK provides methods to help you protect user data.

Learn more about [Privacy](/docs/privacy/overview).

### Opt Out of Tracking

The Swift SDK is initialized with tracking enabled by default. Use the [`optOutTracking()`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC14optOutTrackingyyF) method to opt the user out of data tracking and local storage for the current Mixpanel instance.

**Example Usage**

```swift Swift theme={"system"}
/// send "some_event"
Mixpanel.mainInstance().track(event: "some_event")

/// opt user out of tracking
/// SDK is prevented from sending any data
Mixpanel.mainInstance().optOutTracking()

/// this track call will not work
Mixpanel.mainInstance().track(event: "some_event")
```

#### Opt Out by Default

For GDPR compliance, you can initialize the SDK with users opted out of tracking by default using the [`optOutTrackingByDefault`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelOptions.html) option (see [Configuration Reference](#configuration-reference)). Once the user consents to tracking, call [`optInTracking()`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC13optInTracking10distinctId10propertiesySSSg_SDySSAA0A4Type_pGSgtF) to start tracking.

**Example Usage**

```swift Swift theme={"system"}
/// create Mixpanel instance with users opted out of tracking by default
/// SDK is prevented from sending data
let options = MixpanelOptions(
    token: "YOUR_PROJECT_TOKEN",
    optOutTrackingByDefault: true
)
Mixpanel.initialize(options: options)

/// this track call will not work
Mixpanel.mainInstance().track(event: "some_event")

/// opt user into tracking
Mixpanel.mainInstance().optInTracking()

/// send "some_event"
Mixpanel.mainInstance().track(event: "some_event")
```

### Data Residency

<Note>
  Setting `serverURL` during initialization ensures all requests (events, profiles, and feature flags) use the correct endpoint from the start.
</Note>

#### EU Data Residency

Route data to Mixpanel's EU servers by setting the [`serverURL`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelOptions.html) option to `https://api-eu.mixpanel.com` during initialization (see [Configuration Reference](#configuration-reference)).

**Example Usage**

```swift Swift theme={"system"}
/// Initialize Mixpanel with EU data residency
let options = MixpanelOptions(
    token: "YOUR_PROJECT_TOKEN",
    serverURL: "https://api-eu.mixpanel.com"
)
Mixpanel.initialize(options: options)
```

#### India Data Residency

Route data to Mixpanel's India servers by setting the [`serverURL`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelOptions.html) option to `https://api-in.mixpanel.com` during initialization (see [Configuration Reference](#configuration-reference)).

**Example Usage**

```swift Swift theme={"system"}
/// Initialize Mixpanel with India data residency
let options = MixpanelOptions(
    token: "YOUR_PROJECT_TOKEN",
    serverURL: "https://api-in.mixpanel.com"
)
Mixpanel.initialize(options: options)
```

### Disable Geolocation

The Swift SDK parses the request IP address to generate geolocation properties for events and profiles. To disable geolocation and prevent IP-based tracking, set [`useIPAddressForGeoLocation`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelOptions.html) to `false` (see [Configuration Reference](#configuration-reference)).

You can configure this during initialization or change it after:

**Recommended: Configure During Initialization**

```swift Swift theme={"system"}
let options = MixpanelOptions(
    token: "YOUR_PROJECT_TOKEN",
    useIPAddressForGeoLocation: false
)
Mixpanel.initialize(options: options)
```

**Alternative: Update After Initialization**

```swift Swift theme={"system"}
/// Disable IP-based geolocation at runtime
Mixpanel.mainInstance().useIPAddressForGeoLocation = false
```

## Legacy Automatically Tracked Events

Mixpanel's SDKs have a legacy feature to automatically collect common mobile events. **We don't recommend enabling this**, as these events rely on client-side state and can be unreliable.

The [`trackAutomaticEvents`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelOptions.html) option is set to `false` by default (see [Configuration Reference](#configuration-reference)). You only need to explicitly set this if you want to enable automatic event tracking.

See below table for automatic events tracked by the Swift SDK when `trackAutomaticEvents` is enabled:

| Raw Name          | Display Name          | Description                                                                                                                                                                                                                                                                                                                                           |
| ----------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \$ae\_first\_open | First App Open        | Tracks the first time the user has opened the app. This event is retriggered if the user reinstalls the app or clears local storage. A user property First App Open Date (`$ae_first_app_open_date`) is tracked to indicate the date when app was first opened.                                                                                       |
| \$ae\_updated     | App Updated           | Executes when a user updates the app from the previous version. A Version Updated (`$ae_updated_version`) property is tracked to store the new app version.                                                                                                                                                                                           |
| \$ae\_session     | App Session           | Executes when a user spends more than 10 seconds in the app. A Session Length (`$ae_session_length`) property is tracked to reflect the number of seconds user spent in the session. In addition, there are two user properties tracked: Total App Sessions (`$ae_total_app_sessions`) and Total App Session Length (`$ae_total_app_session_length`). |
| \$ae\_iap         | In App Purchase (IAP) | Executes when a user conducts an in-app purchase through your app. Mixpanel provides three properties for this event: Product Name (`$ae_iap_name`), Product Quantity (`$ae_iap_quantity`), and Product Price (`$ae_iap_price`).                                                                                                                      |

## Release History

[See All Releases](https://github.com/mixpanel/mixpanel-swift/releases).


# Implement Feature Flags (Swift)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/swift/swift-flags



## Overview

This developer guide will assist you in configuring your iOS/macOS platform for Feature Flags using the [Mixpanel Swift SDK](/docs/tracking-methods/sdks/swift). Feature Flags allow you to control the rollout of your features, conduct A/B testing, and manage application behavior without deploying new code.

For complete Swift SDK documentation, see the [Swift SDK guide](/docs/tracking-methods/sdks/swift).

## Prerequisites

Before implementing Feature Flags, ensure:

* You are on an Enterprise subscription plan and have the latest version of the SDK installed (minimum supported version is [`v5.1.3`](https://github.com/mixpanel/mixpanel-swift/releases/tag/v5.1.3)). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK.
* You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Flag Initialization

Initializing the SDK with feature flags enabled requires passing a `FeatureFlagOptions` configuration to `MixpanelOptions`. This enables making an outbound request to Mixpanel servers with the current user context. The server will assign the user context to a variant for each feature flag according to how they are configured in the Mixpanel UX.

The response will include an assigned variant for each flag that the user context is in a rollout group for. If a flag is not returned, it most likely signifies that the user was either not in the rollout percentage for a flag or in the configured targeting cohort.

**Example Usage**

```swift theme={"system"}
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(enabled: true)
))
```

If your flag is configured with a Variant Assignment Key other than `distinct_id` or `device_id` for any of the feature flags in your project, then the call to initialize feature flags must include those keys.

For example, for a Variant Assignment Key, `company_id`, you would setup the SDK as follows:

```swift theme={"system"}
let options = MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(enabled: true, context: [
        "company_id": "X"
    ])
)
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: options)
```

If you are using Runtime Targeting in any of the feature flags in your project, then any properties that you use in targeting should be included in a `custom_properties` node within the context:

```swift theme={"system"}
let options = MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(enabled: true, context: [
        "company_id": "X",
        "custom_properties": [
            "platform": "ios"
        ]
    ])
)
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: options)
```

## Flag Persistence

Minimum supported SDK version: [`v6.4.0`](https://github.com/mixpanel/mixpanel-swift/releases/tag/v6.4.0)

By default (`networkOnly`), the SDK fetches fresh flag assignments and waits for the network response before variant calls complete. You can enable persistence to persist assignments to UserDefaults so they are available immediately on subsequent launches.

Configure a `variantLookupPolicy` on `FeatureFlagOptions`:

**`networkFirst`** — The SDK waits for the network on every launch. If the network call fails, the persisted value is returned as a fallback. Async getter calls block until the fetch completes (or the fallback is resolved).

```swift theme={"system"}
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(
        enabled: true,
        variantLookupPolicy: .networkFirst()
    )
))

// getVariantValue waits for the network. Falls back to persisted value if network fails.
Mixpanel.mainInstance().flags.getVariantValue("my-feature-flag", fallbackValue: "control") { value in
    // value is from the network response, or from persistence if the network was unavailable
}
```

**`persistenceUntilNetworkSuccess`** — Persisted variants are returned immediately on launch. Each getter call while serving persisted data triggers a background network fetch (deduplicated — only one fetch runs at a time). If the fetch fails, persisted data continues to be served and the next getter call retries the fetch. Once a fetch succeeds, the in-memory state updates and subsequent calls no longer trigger background fetches.

```swift theme={"system"}
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(
        enabled: true,
        variantLookupPolicy: .persistenceUntilNetworkSuccess()
    )
))

// getVariantValue returns immediately from persistence. Each call triggers a background fetch
// until a network response succeeds and replaces the persisted state.
Mixpanel.mainInstance().flags.getVariantValue("my-feature-flag", fallbackValue: "control") { value in
    // value is from persistence; background fetch retries on each call until network succeeds
}
```

To customize the TTL (default: 24 hours), pass a `TimeInterval`:

```swift theme={"system"}
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: MixpanelOptions(
    featureFlagOptions: FeatureFlagOptions(
        enabled: true,
        variantLookupPolicy: .networkFirst(persistenceTtl: 12 * 3600) // 12 hours
    )
))
```

### Variant source

Every `MixpanelFlagVariant` carries a `source` property indicating where the value came from: `.network`, `.persistence(persistedAt:)`, or `.fallback`. Use `getVariant()` to receive the full variant object.

```swift theme={"system"}
let fallback = MixpanelFlagVariant(key: "control", value: "control")
Mixpanel.mainInstance().flags.getVariant("my-feature-flag", fallback: fallback) { variant in
    let value = variant.value
    let source = variant.source // .network, .persistence(persistedAt:), or .fallback
}
```

### `$experiment_started` properties

When a variant is served, the `$experiment_started` exposure event includes:

* `$variant_source` — `"network"` or `"persistence"`
* `$persisted_at_in_ms` — epoch ms when the variant set was persisted *(persistence only)*
* `$ttl_in_ms` — the configured TTL in ms *(persistence only)*

<Note>
  Persisted variants are tied to the current `distinct_id`. Calling `identify()` with a new ID or calling `reset()` clears persisted data and triggers a fresh fetch.
</Note>

## Flag Reload

Following initialization, you can reload feature flag assignments in a couple of ways:

1. After a user logs in or out of your application and you call `identify`, a feature flag reload will be triggered.

```swift theme={"system"}
let updatedDistinctId = ""
Mixpanel.mainInstance().identify(distinctId: updatedDistinctId)
```

2. To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags.

```swift theme={"system"}
Mixpanel.mainInstance().flags.loadFlags()
```

3. To update the feature flags context after initialization and trigger a reload with the new values, use `setContext`. This completely replaces the previously set custom context.

```swift theme={"system"}
Mixpanel.mainInstance().flags.setContext([
    "company_id": "Y",
    "custom_properties": [
        "platform": "ios"
    ]
]) {
    // Flags have been re-fetched with the new context
}
```

4. Calling `reset()` clears all feature flag assignments from memory and triggers a new fetch for the updated `distinct_id`. Requires SDK version [`v6.4.0`](https://github.com/mixpanel/mixpanel-swift/releases/tag/v6.4.0) or later.

```swift theme={"system"}
Mixpanel.mainInstance().reset()
// Flags are cleared immediately. A new fetch begins for the anonymous distinct_id.
```

## Deferred Flag Loading

By default, feature flags are automatically fetched when the app first enters the foreground (`prefetchFlags` defaults to `true`). If your workflow requires calling `identify()` before the first flag fetch — for example, to ensure flags are evaluated against the correct user — you can defer automatic loading by setting `prefetchFlags` to `false`:

```swift theme={"system"}
let options = MixpanelOptions(
    token: "YOUR_TOKEN",
    featureFlagOptions: FeatureFlagOptions(enabled: true, prefetchFlags: false)
)
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", options: options)

// Flags will not be fetched until identify() or loadFlags() is called
Mixpanel.mainInstance().identify(distinctId: "user-123")
```

When `prefetchFlags` is set to `false`, flags will not be loaded until you explicitly call `identify()` or `Mixpanel.mainInstance().flags.loadFlags()`.

## Flag Evaluation

Lookup the assigned value for a feature flag. This action triggers tracking an exposure event, `$experiment_started` to your Mixpanel project.

### Asynchronous Flag Variant Retrieval

**Experiment Flags: Get Variant Value**

```swift theme={"system"}
// Get just the flag value asynchronously
Mixpanel.mainInstance().flags.getVariantValue("my-feature-flag", fallbackValue: "control") { value in
    DispatchQueue.main.async {
        // Use flag value in your application logic
        if let stringValue = value as? String {
            switch stringValue {
            case "variant_a":
                showExperienceForVariantA()
            case "variant_b":
                showExperienceForVariantB()
            default:
                showDefaultExperience()
            }
        }
    }
}
```

**FeatureGates: Check if Flag is Enabled/Disabled**

```swift theme={"system"}
// Check if a boolean flag is enabled asynchronously
Mixpanel.mainInstance().flags.isEnabled("my-boolean-flag", fallbackValue: false) { isEnabled in
    DispatchQueue.main.async {
        if isEnabled {
            showNewFeature()
        } else {
            showOldFeature()
        }
    }
}
```

### Synchronous Flag Variant Retrieval

**Experiment Flags: Get Variant Value**

```swift theme={"system"}
// Get just the flag value synchronously
let flagValue = Mixpanel.mainInstance().flags.getVariantValueSync("my-feature-flag", fallbackValue: "control")

// Use flag value in your application logic
if flagValue as? String == "variant_a" {
    showExperienceForVariantA()
} else if flagValue as? String == "variant_b" {
    showExperienceForVariantB()
} else {
    showDefaultExperience()
}
```

**Feature Gates: Check if Flag is Enabled/Disabled**

```swift theme={"system"}
// Check if a boolean flag is enabled
let isEnabled = Mixpanel.mainInstance().flags.isEnabledSync("my-boolean-flag", fallbackValue: false)

if isEnabled {
    showNewFeature()
} else {
    showOldFeature()
}
```

### Get All Flag Assignments

You can retrieve all feature flag assignments at once. These methods do **not** trigger `$experiment_started` tracking events.

**Synchronous**

`getAllVariantsSync()` returns a `[String: MixpanelFlagVariant]` dictionary containing all current flag assignments. If flags have not been loaded yet, it returns an empty dictionary.

```swift theme={"system"}
let allFlags = Mixpanel.mainInstance().flags.getAllVariantsSync()

for (flagName, variant) in allFlags {
    print("\(flagName): \(variant.value)")
}
```

**Asynchronous**

`getAllVariants(completion:)` returns a `[String: MixpanelFlagVariant]` dictionary via a completion handler. If flags have not been loaded yet, it will attempt to fetch them before returning.

```swift theme={"system"}
Mixpanel.mainInstance().flags.getAllVariants { allFlags in
    for (flagName, variant) in allFlags {
        print("\(flagName): \(variant.value)")
    }
}
```

## Frequently Asked Questions

### What if I'm not receiving any flags on SDK initialization?

1. **Check your project token**:

* Ensure you're using the correct project token from your [Mixpanel project settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

2. **Review flag configuration**:

* Make sure your feature flag is enabled
* Check the flag's rollout percentage

  * User contexts that are not assigned to the rollout percentage will not receive flags
* If you are using a targeting cohort, verify on the mixpanel 'Users' page that the user's `distinct_id` is a member of that cohort.

3. **Review SDK parameters**:

* Ensure `FeatureFlagOptions(enabled: true)` is passed to `MixpanelOptions` via the `featureFlagOptions` parameter
* If using a custom Variant Assignment Key, ensure it is included in the `FeatureFlagOptions` `context` parameter
* If using Runtime Targeting, ensure all properties used in targeting are included in the `custom_properties` object within the `FeatureFlagOptions` context

4. **Check flags readiness**: Use `areFlagsReady()` to check if flags have been loaded before making synchronous calls
5. **Enable debug mode**: Set up logging to see detailed information about flag requests and responses


# OpenFeature Provider (Swift)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/swift/swift-openfeature



## Overview

This guide covers using Mixpanel's [Feature Flags](/docs/featureflags) through the [OpenFeature](https://openfeature.dev/) standard with the Mixpanel Swift OpenFeature provider. OpenFeature provides a vendor-agnostic API for feature flag evaluation, allowing you to switch between providers without changing your application code.

For the native Mixpanel SDK approach, see the [Feature Flags (Swift)](/docs/tracking-methods/sdks/swift/swift-flags) guide.

## Prerequisites

* Enterprise subscription plan with Feature Flags enabled
* iOS 14.0+ / tvOS 14.0+ / macOS 11.0+ / watchOS 7.0+
* Swift 5.5+
* Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens)

## Installation

Add the following to your `Package.swift`:

```swift theme={"system"}
dependencies: [
    .package(url: "https://github.com/mixpanel/mixpanel-swift-openfeature", from: "0.1.0"),
]
```

Then add `MixpanelOpenFeature` as a dependency of your target:

```swift theme={"system"}
.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "MixpanelOpenFeature", package: "mixpanel-swift-openfeature"),
    ]
),
```

## Quick Start

```swift theme={"system"}
import Mixpanel
import MixpanelOpenFeature
import OpenFeature

// 1. Create and register the provider
let options = MixpanelOptions(token: "YOUR_PROJECT_TOKEN")
let provider = MixpanelOpenFeatureProvider(options: options)
await OpenFeatureAPI.shared.setProviderAndWait(provider: provider)

// 2. Get a client and evaluate flags
let client = OpenFeatureAPI.shared.getClient()
let showNewFeature = client.getBooleanValue(key: "new-feature-flag", defaultValue: false)

if showNewFeature {
    print("New feature is enabled!")
}
```

### Using an Existing Mixpanel Instance

```swift theme={"system"}
let flags = Mixpanel.mainInstance().flags
let provider = MixpanelOpenFeatureProvider(flags: flags)
await OpenFeatureAPI.shared.setProviderAndWait(provider: provider)
```

<Warning>
  This provider does **not** call `mixpanel.identify()` or `mixpanel.track()`. If you need to update the logged-in user or use [Runtime Events](/docs/featureflags/runtime-events) for targeting, call these methods on the **same Mixpanel instance** that was passed to the provider.
</Warning>

```swift theme={"system"}
// When using init(options:), access via provider.mixpanel
provider.mixpanel?.identify(distinctId: "user-123")
provider.mixpanel?.track(event: "Purchase", properties: ["amount": 49.99])

// When using init(flags:), use the original instance
let mixpanelInstance = Mixpanel.mainInstance()
let provider = MixpanelOpenFeatureProvider(flags: mixpanelInstance.flags)
mixpanelInstance.identify(distinctId: "user-123")
```

## Usage

### Flag Types and Evaluation Methods

| Mixpanel Flag Type | Variant Values                          | OpenFeature Method                                                                                      |
| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Feature Gate       | `true` / `false`                        | `getBooleanValue()`                                                                                     |
| Experiment         | boolean, string, number, or JSON object | `getBooleanValue()`, `getStringValue()`, `getIntegerValue()`, `getDoubleValue()`, or `getObjectValue()` |
| Dynamic Config     | JSON object                             | `getObjectValue()`                                                                                      |

```swift theme={"system"}
let client = OpenFeatureAPI.shared.getClient()

// Feature Gate
let isFeatureOn = client.getBooleanValue(key: "new-checkout", defaultValue: false)

// Experiment with string variants
let buttonColor = client.getStringValue(key: "button-color-test", defaultValue: "blue")

// Experiment with numeric variants
let maxItems = client.getIntegerValue(key: "max-items", defaultValue: 10)
let threshold = client.getDoubleValue(key: "score-threshold", defaultValue: 0.5)

// Dynamic Config
let featureConfig = client.getObjectValue(
    key: "homepage-layout",
    defaultValue: Value.structure(["layout": .string("grid"), "itemsPerRow": .integer(3)])
)
```

### Evaluation Context

Context must be set globally via `OpenFeatureAPI.shared.setEvaluationContext()`:

```swift theme={"system"}
let ctx = MutableContext(
    targetingKey: "user-123",
    structure: MutableStructure(attributes: [
        "email": .string("user@example.com"),
        "plan": .string("premium"),
    ])
)
await OpenFeatureAPI.shared.setEvaluationContext(evaluationContext: ctx)
```

### Runtime Properties

Pass `custom_properties` in the evaluation context for [Runtime Properties](/docs/featureflags) targeting:

```swift theme={"system"}
let ctx = MutableContext(
    structure: MutableStructure(attributes: [
        "custom_properties": .structure([
            "tier": .string("enterprise"),
            "seats": .integer(50),
        ]),
    ])
)
await OpenFeatureAPI.shared.setEvaluationContext(evaluationContext: ctx)
```

<Note>
  Unlike some providers, `targetingKey` is not used as a special bucketing key. It is passed as another context property. Mixpanel's server-side configuration determines which properties are used for targeting and bucketing.
</Note>

### Full Resolution Details

```swift theme={"system"}
let details = client.getBooleanDetails(key: "my-feature", defaultValue: false)

print(details.value)
print(details.variant)
print(details.reason)
print(details.errorCode)
```

## Error Handling

| Error Code           | When                                                          |
| -------------------- | ------------------------------------------------------------- |
| `PROVIDER_NOT_READY` | Flags evaluated before the provider has finished initializing |
| `FLAG_NOT_FOUND`     | The requested flag does not exist in Mixpanel                 |
| `TYPE_MISMATCH`      | The flag value type does not match the requested type         |

To avoid `PROVIDER_NOT_READY`, use `setProviderAndWait`:

```swift theme={"system"}
await OpenFeatureAPI.shared.setProviderAndWait(provider: provider)
```

## Troubleshooting

### Flags Always Return Default Values

1. **Provider not ready:** Use `setProviderAndWait` to ensure initialization completes.
2. **Network issues:** Check for failed requests to Mixpanel's flags API.
3. **Flag not configured:** Verify the flag exists and is enabled in your Mixpanel project.

### Flags Not Updating After Context Change

When you update the OpenFeature context, the provider fetches new flag values:

```swift theme={"system"}
let newCtx = MutableContext(
    structure: MutableStructure(attributes: ["plan": .string("premium")])
)
await OpenFeatureAPI.shared.setEvaluationContext(evaluationContext: newCtx)
```

If flags still aren't updating, verify your targeting rules in Mixpanel use the context properties you're setting.


# Implement Session Replay (iOS)
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/swift/swift-replay



## Overview

This developer guide will assist you in configuring your Swift app for [Session Replay](/docs/session-replay) using the [Session Replay SDK (Swift)](/docs/tracking-methods/sdks/swift/swift-replay). Learn more about [viewing captured Replays in your project here](/docs/session-replay).

<Note>
  **iOS 26+ with Xcode 26: SwiftUI Automasking Issue — Fixed in [v1.2.1](https://github.com/mixpanel/mixpanel-ios-session-replay-package/releases/tag/v1.2.1)**

  The iOS 26 "Liquid Glass" rendering changes that affected automasking in Session Replay for SwiftUI apps have been addressed in v1.2.1. Upgrade to v1.2.1 to get the fix.

  **Who was affected:** SwiftUI apps using automasking for text or images, built with Xcode 26, and running on iOS 26+.

  **If you are on v1.2.0:** Session Replay is disabled by default for apps built with Xcode 26+ running on iOS 26+. Upgrade to v1.2.1 and enable session replay by setting `config.enableSessionReplayOniOS26AndLater = true` during SDK initialization.

  **If you re-enabled Session Replay on v1.2.0:** Upgrade to v1.2.1 to get the fix.

  **If you disabled automasking as a workaround:** Upgrade to v1.2.1 and enable the automasking config.

  While the iOS 26 "Liquid Glass" fix is now available, we still recommend thoroughly testing session replays in your app before pushing to production. We also encourage explicitly masking sensitive views rather than relying solely on the SDK's automasking.

  **Note:** The `enableSessionReplayOniOS26AndLater` flag is still used by SDK in v1.2.1 but will be removed in a future minor version.
</Note>

## Best Practices

Session Replay provides powerful insights into user behavior, but it also introduces risks, especially on mobile. These risks are not unique to Mixpanel; they are common across the entire session replay product category. Because SDKs run on end-user devices and screen content may include sensitive data, we recommend implementing / testing Session Replay carefully. Be especially cautious with masking, edge-case testing, and rollout strategies. For more information on risk categories and best practices, read more [here](/docs/session-replay#best-practices)

## Prerequisite

You are already a Mixpanel customer and have the latest version of the [Mixpanel Swift SDK](/docs/tracking-methods/sdks/swift) installed (minimum supported version is [`v4.3.1`](https://github.com/mixpanel/mixpanel-swift/releases/tag/v4.3.1)). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK.

## Installation

To capture Session Replays in your app, add the [Session Replay SDK](/docs/tracking-methods/sdks/swift/swift-replay) using Swift Package Manager directly in Xcode:

1. In Xcode, go to File → **Add Package Dependencies…**
2. Paste the GitHub URL: `https://github.com/mixpanel/mixpanel-ios-session-replay-package`
3. Follow the prompts to select the latest version and add the package to your project.

### Initialize

You should have the main Mixpanel Swift SDK installed (minimum version `v4.3.1`), if not, please refer to [Prerequisite](/docs/tracking-methods/sdks/swift/swift-replay#prerequisite).

Add the following code to your **SwiftUI** or **UIKit** app.

**SwiftUI**

```swift Swift theme={"system"}
import Mixpanel
import MixpanelSessionReplay
 
struct SessionReplayDemoApp: App {
    @State private var isActive = true
    @Environment(\.scenePhase) private var scenePhase
 
    var body: some Scene {
        WindowGroup {
            ...
        }
        .onChange(of: scenePhase) {
            if scenePhase == .active {
                let config = MPSessionReplayConfig(wifiOnly: false, enableLogging: true)
                MPSessionReplay.initialize(
                        token: Mixpanel.mainInstance().apiToken,
                        distinctId: Mixpanel.mainInstance().distinctId,
                        config: config
                )
            }
        }
}
```

**UIKit**

```swift Swift theme={"system"}
import Foundation
import UIKit
 
import Mixpanel
import MixpanelSessionReplay
 
class AppDelegate: UIResponder, UIApplicationDelegate {
 
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
        Mixpanel.initialize(token: token, trackAutomaticEvents: true)
        Mixpanel.mainInstance().loggingEnabled = true
 
        let config = MPSessionReplayConfig(wifiOnly: false, enableLogging: true)
        MPSessionReplay.initialize(
                token: Mixpanel.mainInstance().apiToken,
                distinctId: Mixpanel.mainInstance().distinctId,
                config: config
        )
    }
}
```

## Data Residency

<Info>
  Available in Session Replay SDK version `1.5.1` and later.
</Info>

If your Mixpanel project lives in the EU or India data center, or you route all Mixpanel traffic through a self-hosted proxy, set the `serverURL` on `MPSessionReplayConfig`. The SDK exposes a `DataResidency` enum with the managed region URLs so you don't have to hardcode them.

| Region       | `DataResidency` constant | URL                           |
| ------------ | ------------------------ | ----------------------------- |
| US (default) | `DataResidency.us`       | `https://api.mixpanel.com`    |
| EU           | `DataResidency.eu`       | `https://api-eu.mixpanel.com` |
| India        | `DataResidency.in`       | `https://api-in.mixpanel.com` |

**Example Usage**

```swift Swift theme={"system"}
import MixpanelSessionReplay

let config = MPSessionReplayConfig(
    wifiOnly: false,
    serverURL: DataResidency.eu
)
MPSessionReplay.initialize(
    token: Mixpanel.mainInstance().apiToken,
    distinctId: Mixpanel.mainInstance().distinctId,
    config: config
)
```

You can also pass any fully-qualified HTTPS URL — useful when routing replay traffic through a self-hosted proxy:

```swift Swift theme={"system"}
let config = MPSessionReplayConfig(
    serverURL: "https://mixpanel-proxy.yourcompany.com"
)
```

Learn more about [EU Data Residency](/docs/privacy/eu-residency) and [India Data Residency](/docs/privacy/in-residency).

## Capturing Replays

<Warning>
  Test in a sandbox project and start with a 100% sampling rate. This allows you to monitor performance, usage, and ensure your privacy rules align with your company policies.
</Warning>

You can capture replay data using a sampling method (recommended), or customize when and where replays are captured manually using methods provided by the Session Replay Swift SDK.

### Sampling

We recommend using our sampling functionality unless you need custom logic to decide when to record sessions.

To enable Session Replay and set your sampling rate, create a `MPSessionReplayConfig` object and set the `recordingSessionsPercent` with a value between `0.0` and `100.0`. At `0.0` no sessions will be recorded, at `100.0` (default) all sessions will be recorded.

To start, we recommend using an 100% sampling rate to ensure replay capture is behaving as expected, then adjust according to your specific analytics needs.

Upon initialization, recording starts automatically if the sampling check passes.

**Example Usage**

```swift Swift theme={"system"}
// records 100% of all sessions
MPSessionReplayConfig(recordingSessionsPercent: 100.0)
```

### Manual Recording

To programatically start and stop replay capture, use the `.startRecording()` and `.stopRecording()` methods.

#### Start Recording Replay Data

Calling `.startRecording()` will force recording to begin regardless of the `recordingSessionsPercent` sampling check.

Recording automatically stops when the app goes into the background. If `autoStartRecording` is `true` (default) recording automatically re-starts when the app comes back to the foreground.

Calling `.startRecording()` has no effect while recording is already in progress. **Example Usage**

```swift Swift theme={"system"}
// manually force recording to begin for 100% of sessions
MPSessionReplay.getInstance()?.startRecording()
```

```swift Swift theme={"system"}
// manually force recording to begin with a 50% sampling rate
MPSessionReplay.getInstance()?.startRecording(sessionsPercent: 50.0)
```

#### Stop Recording Replay Data

Call `.stopRecording()` to stop any active replay data collection. The SDK automatically stops recording when the app goes to the background.

Calling `.stopRecording()` has no effect when there is no recording in progress.

**Example Usage**

```swift Swift theme={"system"}
// manually end a replay capture
MPSessionReplay.getInstance()?.stopRecording()
```

#### Manual Screenshot Capture

You can also manually trigger the capture of individual screenshots by calling `.captureScreenshot()`:

**Example Usage**

```swift Swift theme={"system"}
// manually capture screenshots
MPSessionReplay.getInstance()?.captureScreenshot()

// manually capture screenshots triggered by a touch event
MPSessionReplay.getInstance()?.captureScreenshot(withTouchEvent: touchEvent)
```

#### Example Use Cases for Manual Capture

| Scenario                                                                  | Guidance                                                                                                                                                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| We have a sensitive screen we don't want to capture                       | When user is about to access the sensitive screen, call `.stopRecording()`. To resume recording once they leave this screen, you can resume recording with `.startRecording()` |
| We only want to record certain types of users (e.g. Free plan users only) | Using your application code, determine if current user meets the criteria of users you wish to capture. If they do, then call `.startRecording()` to begin recording           |
| We only want to users utilizing certain features                          | When user is about to access the feature you wish to capture replays for, call `.startRecording()` to begin recording                                                          |

### Additional Configuration Options

Upon initialization you can provide a `MPSessionReplayConfig` object to customize your replay capture.

Currently, there are seven config options:

| Option                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                   | Default                       |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `wifiOnly`                           | When `true`, replay events will only be flushed to the server when the device has a WiFi connection. If there is no wifi, flushes are skipped and the events remain in the in-memory queue until wifi is restored (or until the queue reaches its limit and the oldest events are evicted to make room for newer events). <br /> When `false`, replay events will be flushed with any network connection, including cellular. | `true`                        |
| `autoMaskedViews`                    | This is a `Set` of enum options for the types of views that should be masked by the SDK automatically.                                                                                                                                                                                                                                                                                                                        | `[.image, .text, .web, .map]` |
| `autoStartRecording`                 | This is a boolean value that determines whether or not recording begins automatically upon initialization and when returning to the foreground. <br /> **Deprecated in v1.3.0:** Use `recordingSessionsPercent` set to `0.0` to disable automatic recording.                                                                                                                                                                  | `true`                        |
| `recordingSessionsPercent`           | This is a value between `0.0` and `100.0` (default) that controls the sampling rate for automatically triggered session replays. <br /> At `0.0` no sessions will be recorded. At `100.0` all sessions will be recorded.                                                                                                                                                                                                      | `100.0`                       |
| `flushInterval`                      | Specifies the flush interval (in seconds) at which session replay events are sent to the Mixpanel server.                                                                                                                                                                                                                                                                                                                     | `10`                          |
| `enableLogging`                      | This is a boolean value that determines whether or not debugging logs are printed to the console.                                                                                                                                                                                                                                                                                                                             | `false`                       |
| `remoteSettingsMode`                 | Setting for handling remote configuration during SDK initialization. Can be `.disabled`, `.fallback`, `.strict`.                                                                                                                                                                                                                                                                                                              | `.disabled`                   |
| `enableSessionReplayOniOS26AndLater` | Forces Session Replay to be enabled on iOS 26+, bypassing compatibility checks. Session Replay is disabled by default for apps built with Xcode 26+ running on iOS 26+ due to SwiftUI automasking issues. See the warning callout above for details.                                                                                                                                                                          | `false`                       |

**autoMaskedViews Example Usage**

```swift Swift theme={"system"}
// mask images only
MPSessionReplayConfig(autoMaskedViews: [.image])

// disable auto masking
MPSessionReplayConfig(autoMaskedViews: [])
```

Alternatively:

```swift Swift theme={"system"}
// mask images only
MPSessionReplay.getInstance()?.autoMaskedViews = [.image]

// disable auto masking
MPSessionReplay.getInstance()?.autoMaskedViews = []
```

**enableSessionReplayOniOS26AndLater Example Usage**

```swift Swift theme={"system"}
let config = MPSessionReplayConfig(
    autoMaskedViews: [],  // Disable automasking if using SwiftUI
    wifiOnly: false
)
config.enableSessionReplayOniOS26AndLater = true

MPSessionReplay.initialize(
    token: Mixpanel.mainInstance().apiToken,
    distinctId: Mixpanel.mainInstance().distinctId,
    config: config
)
```

#### Identity Management

The Mixpanel distinct ID for the current user can be passed into the initializer and changed at runtime by calling the `.identify(distinctId:)` method:

**Example Usage**

```swift Swift theme={"system"}
// initialize the main Mixpanel tracking SDK
Mixpanel.initialize(token: token, trackAutomaticEvents: true)

// initialize the session replay SDK with the project token and distinct ID from above
MPSessionReplay.initialize(
        token: Mixpanel.mainInstance().apiToken,
        distinctId: Mixpanel.mainInstance().distinctId,
)
```

To change the distinct ID later:

```swift Swift theme={"system"}
// for example when the user logs out
func logout() {
    // reset the main Mixpanel tracking SDK to generate a new distinct ID
    Mixpanel.mainInstance().reset()
    let newDistinctId = Mixpanel.mainInstance().getDistinctId()
    // change session replay distinct ID
    MPSessionReplay.getInstance()?.identify(distinctId: newDistinctId)
}
```

#### Manual Flushing

You can flush any currently queued session replay events at any time by calling `.flush()`:

```swift Swift theme={"system"}
MPSessionReplay.getInstance()?.flush()
```

## Remote Configuration

<Note>
  Available only for customers with a paid session replay add-on.
</Note>

By setting `remote_settings_mode` you can quickly set SDK options for your project in Mixpanel under `Settings > Organization Settings > Session Replay`.

Three modes are available:

* `.disabled`: Do not use remote configuration and proceed to use the SDK initialization config provided in `MPSessionReplay.initialize`
* `.fallback`: Attempt to retrieve remote configuration and proceed with those settings. If there is failure or timeout (500 ms), will use previously cached remote settings (from last successful fetch) or the SDK initialization config.
* `.strict`: Requires successful remote configuration fetch for SDK initialization.

Can use this setting to quickly update and adjust configurations to your liking.

List of currently supported remote settings:

* `recordingSessionsPercent`

Settings that are not yet supported, will not appear in the remote configuration. These non-included options will use the value from the SDK initialization config.

## Replay ID

When a replay capture begins, a Replay ID is generated by the SDK and is attached as an event property (`$mp_replay_id`) to events tracked by the Mixpanel SDK during the capture session. Events containing the same `$mp_replay_id` will appear in the same Replay.

If you are sending any events not coming from the Mixpanel SDK, add the `$mp_replay_id` event property to attribute the event to a specific Replay.

You can use the `getReplayId()` method to return the Replay ID for the current replay capture. The method will return an empty object if there is no active replay capture in progress.

**Example Usage**

```swift Swift theme={"system"}
// return the $mp_replay_id for the currently active capture
MPSessionReplay.getInstance()?.getReplayId()
// {$mp_replay_id: '19221397401184-063a51e0c3d58d-17525637-1d73c0-1919139740f185'}
```

### Server-Side Stitching

Server-Side Stitching allows you to easily watch Replays for events that were not fired from the SDK.

It works by inferring the Replay that an event belong using the Distinct ID and time property attached to the event. This is especially useful if you have events coming in from multiple sources.

For example, let's say a user with Distinct ID “ABC” has a Replay recorded from 1-2pm. Two hours later, an event was sent from your warehouse with a timestamp of 1:35pm with Distinct ID “ABC”. Server-Side Stitching will infer that the event should belong in the same Replay.

To ensure Server-Side Stitching works, call [`identify()`](/docs/tracking-methods/sdks/swift#identify) from the client-side using our SDK with the user's `$user_id`. This guarantees that events generated from both the client-side and server-side share the same Distinct ID. Learn more about [identifying users](/docs/tracking-methods/id-management).

## Debugging

<Note>
  `$mp_session_record` is exempt from your plan data allowance.
</Note>

To check your implementation, select **Session Replay** from the side navigation in your Mixpanel project to see whether replays are being captured and appearing as expected. When a capture begins, a "Session Recording Checkpoint" event (`$mp_session_record`) also appears in your project; you can use this to verify that Session Replay is implemented correctly.

If you are using the [recommended sampling method](/docs/tracking-methods/sdks/swift/swift-replay#sampling) to capture your Replays but having trouble finding the Replays in your project, try calling `.startRecording()` manually and see if the `$mp_session_record` event appears. If it does appear but you are still struggling to locate your Replays, you may want to increase your sampling rate.

***

### Troubleshooting

If you are still struggling with either of the following common issues:

* Replays are not showing up in my project
* Replays are not displaying my UI correctly

Please [submit a request to our Support team](https://mixpanel.com/get-support) and include the following information:

* Whether your issue is with iOS, Android, or both
* Your Session Replay (SR) code snippet
* Where you initialize the Mobile Session Replay SDK
* Any relevant logs
* (If applicable) A link to a replay showing the issue
* (If applicable) A screenshot of the UI or a description of the expected behavior

### Logging

Developers can enable or disable logging with the `enableLogging` option of the `MPSessionReplayConfig` object or via the `loggingEnabled` property of the main `MPSessionReplay` instance.

**Example Usage**

```swift Swift theme={"system"}
let token = Mixpanel.mainInstance().apiToken
let distinctId = Mixpanel.mainInstance().distinctId
let config = MPSessionReplayConfig(wifiOnly: false, enableLogging: true) // enable debug logging
MPSessionReplay.initialize(token: token, distinctId: distinctId, config: config)
```

Alternatively:

```swift Swift theme={"system"}
MPSessionReplay.getInstance()?.loggingEnabled = true
```

## Privacy

Mixpanel offers a privacy-first approach to Session Replay, including features such as data masking. Mixpanel's Session Replay privacy controls were designed to assist customers in protecting end user privacy. Read more [here](/docs/session-replay/session-replay-privacy-controls).

### User Data

The Mixpanel SDK will always mask all input text fields. To protect end-user privacy, input text fields cannot be unmasked.

By default, all text, images, WKWebViews and MKMapViews are also masked.

You can unmask these elements at your own discretion using the [`autoMaskedViews` config option described above](/docs/tracking-methods/sdks/swift/swift-replay#additional-configuration-options).

#### Mark Views as Sensitive

If your app is SwiftUI-based or UIKit-based, all `UITextField` and `UILabel` components are masked by default. `UITextField` cannot be unmasked, while `UILabels` can be unmasked

You can also mark any views as sensitive using `mpReplaySensitive`. Views marked as "sensitive" will always be masked.

**Example Usage**

```swift Swift theme={"system"}
// Mark any view as sensitive

// SwiftUI
Image("family photo")
	.mpReplaySensitive(true)
 
// UIKit
let ccView = CreditCardUIView()
ccView.mpReplaySensitive = true
```

Set `mpReplaySensitive` to `false` to mark any view as "safe". Views marked as "safe" will never be masked.

**Example Usage**

```swift Swift theme={"system"}
// Mark any view as safe

// SwiftUI
BackgroundImage()
    .mpReplaySensitive(false)
 
//UIKit
let bgImage = BackgroundImage()
bgImage.mpReplaySensitive = false
```

### Retention

By default, Mixpanel retains Session Replays for 30 days from the date the replay is ingested and becomes available for viewing within Mixpanel. Customers on our [Enterprise plan](https://mixpanel.com/pricing/) can customize this retention period between 7 days and 360 days. Once a replay is expired, there is no way to view that replay.

## Known Product Limitations

* SwiftUI apps have limited support for automatic masking of sensitive views. If your app uses SwiftUI, manually mark sensitive views and test thoroughly to ensure masking is working as expected.
* At this time, webview masking is all-or-none. Embedded webviews in your mobile app can only be masked entirely or not at all. This may reduce the value of Session Replay for apps with many webviews. Be sure to test thoroughly to confirm your masking configuration meets your privacy requirements.

\=======

## FAQ

#### How does Session Replay work in iOS?

Session Replay observes user interactions within your app, capturing UI hierarchy changes and storing them as images, which are then sent to Mixpanel. Mixpanel reconstructs these images, applying recorded events as an end-user completes them.

Within Mixpanel's platform, you can view a reconstruction of your end-user's screen as they navigate your app.

However, Session Replay is not a literal video recording of your end-user's screen; end-user actions are not video-recorded.

#### Can I prevent Session Replay from recording sensitive content?

The Mixpanel SDK will always mask all inputs. By default, all text, images, and WebViews on a page.

Additionally, you can customize how you leverage our SDK to fully control (1) where to record and (2) whom to record. Consider the [manual capture example scenarios](/docs/tracking-methods/sdks/swift/swift-replay#example-use-cases-for-manual-capture), [SDK configuration options](/docs/tracking-methods/sdks/swift/swift-replay#additional-configuration-options), and [manual view masking example](/docs/tracking-methods/sdks/swift/swift-replay#mark-views-as-sensitive) provided above to customize the replay capture of your implementation.

#### How can I estimate how many Replays I will generate?

If you already use Mixpanel, the [Session Start events](/docs/features/sessions) are a way to estimate the rough amount of replays you might expect. This is especially true if you use timeout-based query sessions. However, because our sessions are defined at query time, we cannot guarantee these metrics will be directly correlated.

When you enable Session Replay, use the above proxy metric to determine a starting sampling percentage, which will determine how many replays will be sent. You can always adjust this as you go to calibrate to the right level.

#### How does Session Replay affect my app's performance?

There is no impact on your app's performance when there are no user interactions or nothing changes on the screen. When there are user interactions, we expect negligible impact on CPU usage and memory consumption. There is no impact on disk I/O because Session Replay does not write anything to your disk.

In our own testing, the overhead is unnoticeable, however this testing was not exhaustive, and you may discover the recording overhead may negatively impact your mobile application performance depending on your application specifications. If you experience any performance degradations after installing Session Replay, please [reach out to our Support team](https://mixpanel.com/get-support).

#### How Does Session Replay affect my app's bandwidth consumption?

The bandwidth impact of Session Replay depends on the setting of the [`wifiOnly` parameter](/docs/tracking-methods/sdks/swift/swift-replay#additional-configuration-options).

By default, `wifiOnly` is set to `true`, which means replay events are only flushed to the server when the device has a wifi connection. If there is no wifi, flushes are skipped, and the events remain in the in-memory queue until WiFi is restored. This ensures no additional cellular data is used, preventing users from incurring additional data charges.

When `wifiOnly` is set to `false`, replay events are flushed with any available network connection, including cellular. In this case, the amount of cellular data consumed depends on the intensity of user interactions and the typical session length of your app. Users may incur additional data charges if large amounts of data are transmitted over cellular connections.

#### How does Session Replay for mobile work if my app is offline?

Session Replay for mobile does not work in offline mode.

#### Does it work in SwiftUI/UIKit apps?

[Yes.](/docs/tracking-methods/sdks/swift/swift-replay#initialize)

#### Does it support Obj-C based app?

Yes, Objective-C and Swift are fully interoperable.

#### Does Mobile Session Replay work with my CDP?

Yes — but only if the Mixpanel Session Replay SDK is installed client-side.

Mobile Session Replay is compatible with CDPs like Segment and mParticle, but you must integrate the Mixpanel Session Replay SDK directly in your mobile app. Without it, replays won’t be captured.

Key Considerations:

* If you’re using Segment server-side, session replays will not be recorded, since the SDK isn’t running in the app.
* For Segment’s client-side Analytics-Swift SDK, you can use Segment’s Plugin Architecture to enrich events with the \$mp\_replay\_id property, ensuring they’re linked to their replays.
* The Mixpanel Session Replay SDK is separate from the standard Mixpanel tracking SDK. You do not need the regular SDK, but the Replay SDK must be configured with a distinct\_id and project token.
* Events can be linked to replays either by:

  * Manually attaching the current replay ID to each event
  * Using server-side stitching after the fact


# Mixpanel SDKs: Unity
Source: https://docs.mixpanel.com/docs/tracking-methods/sdks/unity



## Getting Started

Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=unity).

The [Full API Reference](http://mixpanel.github.io/mixpanel-unity/api-reference/annotated.html), [Library Source Code](https://github.com/mixpanel/mixpanel-unity), and an [Example Application](https://github.com/mixpanel/mixpanel-unity#examples) is documented in our GitHub repo.

<Warning>
  Unity SDK does not currently support Simplified ID Merge.
</Warning>

## Installing the Library

<Warning>
  For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about [Privacy-Friendly Tracking](/docs/tracking-methods/sdks/unity#privacy-friendly-tracking).
</Warning>

This library can be installed using the unity package manager system with git. We support Unity 2018.3 and above. For older versions of Unity, you need to have .NET 4.x Equivalent selected as the scripting runtime version in your editor settings.

To install the library in your Unity project, declare it as a dependency in the `./Packages/manifest.json` file of your project:

```json JSON theme={"system"}
{
  ...
  "dependencies": {
    //add latest library version
    "com.mixpanel.unity": "https://github.com/mixpanel/mixpanel-unity.git#master",
    //point to specific library version
    "com.mixpanel.unity": "https://github.com/mixpanel/mixpanel-unity.git#v3.5.1",
  }
  ...
}
```

Then open Unity and the library should download automatically along with any other packages declared in your dependencies.

<Note>
  Alternatively you can go to the [releases page](https://github.com/mixpanel/mixpanel-unity/releases) and download the `.unitypackage` file and manually install the package using Unity.
</Note>

After installing the package, open the unity project settings menu for Mixpanel (Edit -> Project Settings -> Mixpanel), then enter [your project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens) into the Token and Debug Token input fields within the inspector to initialize Mixpanel:

<Frame>
  <img alt="image" />
</Frame>

Please note if you prefer to initialize Mixpanel manually, you can select the Manual Initialization in the settings and call [`Mixpanel.Init()`](https://github.com/mixpanel/mixpanel-unity/blob/ec303c5bdacd00303a8b814a9806cfb05882c719/Mixpanel/MixpanelAPI.cs#L27) to initialize.

Once you've initialized the library with your project token, import Mixpanel into your code using the `mixpanel` namespace to start using it:

```csharp theme={"system"}
// import mixpanel package to your code
using mixpanel;

// start using library methods
Mixpanel.Track("event_name");
```

## Sending Events

Use [`Mixpanel.Track()`](http://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel.html#a6a0f4b79670d7bbd50c849af2b12a8e1) to send an event by providing the event name and any event properties. This will trigger a request to the [/track API endpoint](/reference/track-event) to ingest the event into your project.

<Note>
  The [/track endpoint](/reference/track-event) will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.
</Note>

**Example Usage**

```csharp theme={"system"}
// define event properties
var props = new Value();
props["location"] = "us";
props["Plan"] = "Premium";

//track "some_event" with your event props
Mixpanel.Track("some_event", props);
```

### Timing Events

You can track the time it took for an action to occur, such as an image upload or a comment post, using [`Mixpanel.StartTimedEvent()`](http://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel.html#ab1a62f4c9b0e28915dfdc57e7810bc78) This will mark the "start" of your action, which you can then finish with a track call. The time duration is then recorded in the "Duration" property.

**Example Usage**

```csharp theme={"system"}
// start the timer for the event "Image Upload"
Mixpanel.StartTimedEvent("Image Upload");

// 20 seconds later...

// track "Image Upload" event with Duration event prop set to 20
Mixpanel.Track("Image Upload");
```

### Flushing Events

To preserve battery life and customer bandwidth, the Mixpanel library doesn’t send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background.

Call Mixpanel.Flush() manually if you want to force a flush at a particular moment.

**Example Usage**

```csharp theme={"system"}
Upload queued data to the Mixpanel server
Mixpanel.Flush();
```

**Flush Interval** You can update the default flush interval from 60 seconds to another interval by setting a new `Flush Interval` value in Edit -> Project Settings -> Mixpanel.

#### Importing Historical Events

The Unity SDK is a tracking SDK designed for real-time tracking in a client-side environment. Calling `Mixpanel.Track()` triggers a request to our [/track API endpoint](/reference/track-event), which will validate for events with a timestamp that is within the last 5 days of the request. **Events older than 5 days will not be ingested**.

For bulk import of historical events older than 5 days, we will need to use the [/import API endpoint](/reference/import-events) which is optimized for scripting and supports ingesting historical data. We recommend the [Python SDK](/docs/tracking-methods/sdks/python) (see the [`.import_data()`](https://mixpanel.github.io/mixpanel-python/#primary-interface) function) and [mixpanel-utils module](https://github.com/mixpanel/mixpanel-utils) (see the [`import_events()`](https://github.com/mixpanel/mixpanel-utils?tab=readme-ov-file#import-events) function) which both leverages the /import API for event ingestion.

## Setting Super Properties

Super properties are global event properties that you define once and apply to all events.

To make things easier, you can register these properties as **super properties**. If you do, we will automatically include them with all tracked events. Super properties are saved to device storage, and will persist across invocations of your app. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference).

To register super properties, call [`Mixpanel.Register()`](http://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel.html#acf2fccd7625dfb2a15ef54fcaf8ddfe4).

Use [`Mixpanel.RegisterOnce()`](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel.html#a148783e1cfca22df973a6a6b0eba1641) to register super properties without overwriting existing values.

**Example Usage**

```csharp theme={"system"}
// register "name" as a super property
Mixpanel.Register("name", "Sam");

// track "some_event"
// "name" event prop is included in the event
Mixpanel.track("some_event");

// ignored since "name" already exists
Mixpanel.RegisterOnce("name", "Samantha");
```

Our libraries store your super properties in local storage. They will persist so long as the app is installed (between launches and updates). Uninstalling the app will remove the super properties.

See more methods related to super properties in the complete library reference [here](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel.html).

## Managing User Identity

You can handle the identity of a user using the [`Mixpanel.Identify()`](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel.html#a4636a50f2f4e36895f56a6101e527720) and [`Mixpanel.Reset()`](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel.html#af80b55f985b94780ec983dc6c1210d6b) methods. Learn more about [identity management](/docs/tracking-methods/id-management/identity-management) and [identifying users](/docs/tracking-methods/id-management/identifying-users).

### Identify

<Warning>
  We recommend against calling `Mixpanel.Identify()` for anonymous visitors to your site.
</Warning>

Call [`Mixpanel.Identify()`](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel.html#a4636a50f2f4e36895f56a6101e527720) when you know the identity of the current user, passing in their user ID as an argument. This is typically at account registration and at log in.

**Example Usage**

```csharp theme={"system"}
// user logs in and tracks a sign in event
 Mixpanel.Track('sign in');

// upon sign in, identify the user with their ID
// ensure future events sent from the user have distinct_id 12345
Mixpanel.Identify('12345');
```

### Call Reset at Logout

Call [`Mixpanel.Reset()`](http://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel.html#af80b55f985b94780ec983dc6c1210d6b) to clear data attributed to a user when they logout. This will clear the local storage and allows you to handle [multiple users on a single device](/docs/tracking-methods/id-management/identifying-users-simplified#multiple-users-one-device).

**Example Usage**

```csharp theme={"system"}
// your user logs out and tracks a log out event
Mixpanel.Track('log out');
 
// clear local storage and generate new distinct_id
Mixpanel.Reset();
```

## Storing User Profiles

Once your users are identified, create [user profiles](/docs/data-structure/user-profiles) by setting profile properties to describe them. Example profile properties include "name", "email", "company", and any other demographic details about the user.

The Unity SDK provides a few methods for setting profile properties under the [`People`](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel_1_1_people.html) class. These methods will trigger requests to the [/engage API endpoint](/reference/profile-set).

### Setting Profile Properties

<Note>
  You must call `.identify()` before setting profile properties in order to associate the profile properties you set with the target user. If identify is not called, the profile update will be queued for ingestion until an identify call is made.
</Note>

Set profile properties on a user profile by calling the [`Mixpanel.People.Set`](http://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel_1_1_people.html#aa8eaa02cc76fc8ad1076b00ca1772dc6) method.

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

**Example Usage**

```csharp theme={"system"}
// You must call identify to associate the profile update with the user
// Sets user's "Plan" attribute to "Premium"
Mixpanel.Identify("12345");
Mixpanel.People.Set("Plan", "Premium");
 
// Update "plan" from "Premium" to "Enterprise"
Mixpanel.People.Set("Plan", "Enterprise");
```

### Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods [here](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel_1_1_people.html)

A few commonly used people methods are highlighted below:

<Tabs>
  <Tab title=".SetOnce()">
    The [`.People.SetOnce()`](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel_1_1_people.html#a4f4dab80df0a2095e1901ca0262a41c3) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

    Use this method if you want to set profile properties without the risk of overwriting existing data.

    **Example Usage**

    ```csharp theme={"system"}
    // set profile properties for user "1234"
    Mixpanel.Identify('1234');
    Mixpanel.People.Set('name':'sam');

    // will be ignored since "name" already exists
    Mixpanel.People.SetOnce('name', 'samantha');

    // set "location" group prop since it does not exist
    Mixpanel.People.SetOnce('location', 'us');
    ```
  </Tab>

  <Tab title=".Append()">
    The [`.People.Append()`](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel_1_1_people.html#ace6b6040fef2bb51f07f911b71c3e685) method append values to a list profile property.

    Use this method to add additional values to an existing list property instead of redefining the entire list.

    **Example Usage**

    ```csharp theme={"system"}
    // set profile properties for user "1234"
    Mixpanel.Identify('1234');
    var roles = new string[] {'sales','engineer'};
    Mixpanel.People.Set({
        'name':'sam',
        'roles': roles
    });

    // add "legal" to "roles"  
    // new role values are ['sales','engineer','legal']
    Mixpanel.People.Append('roles', 'legal');

    // .append() allows duplicates
    // new "roles" values are ['sales','engineer','legal', 'legal']
    Mixpanel.People.Append('roles', 'legal');
    ```
  </Tab>

  <Tab title=".Union()">
    The [`.People.Union()`](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel_1_1_people.html#a5c19ffb9ca7f705e06e9c0de15a84e31) method append new values to a list property, excluding duplicates.

    Use this method to create a list profile property that only contains unique values without duplicates.

    **Example Usage**

    ```csharp theme={"system"}
    // set profile properties for user "1234"
    Mixpanel.Identify('1234');
    var roles = new string[] {'sales','engineer'};
    Mixpanel.People.Set({
        'name':'sam',
        'roles': roles
    });

    // append "engineer" to "roles"
    // will be ignored since "engineer" already exists in "roles"
    Mixpanel.People.Union('roles', 'engineer');

    // append "legal" to "roles"
    // new role values are ['sales','engineer','legal']
    Mixpanel.People.Union('roles', 'legal');
    ```
  </Tab>

  <Tab title=".Increment()">
    The [`.People.Increment()`](https://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel_1_1_people.html#ab32b74ea1d409527d689ae9cdf9c3bf1) method increments a numeric property by a whole number.

    Use this method to add to or subtract from your numeric property based on its current value.

    **Example Usage**

    ```csharp theme={"system"}
    // set profile properties for user "1234"
    Mixpanel.Identify('1234');
    Mixpanel.People.Set({
        'name':'sam',
        'age': 25
    });

    // increment "age" by 2
    Mixpanel.People.Increment('age',2);

    // use negative number to decrement
    // decrement "age" by 5
    Mixpanel.People.Increment('age',-5);
    ```
  </Tab>
</Tabs>

## Group Analytics

<Note>
  Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first.
</Note>

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the `group_key` and `group_id`.

* `group_key` is the event property that connects event data to a group. (e.g. `company`)
* `group_id` is the identifier for a specific group. (e.g. `mixpanel`,`company_a`,`company_b`, etc.)

### Sending Group Identifiers With Events

[All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group.

To send group identifiers with your events, set the `group_key` as an event property with the `group_id` as the value.

**Example Usage**

```csharp theme={"system"}
// set group key "company" as event prop
// with "mixpanel" as value
var props = new Value();
props["company"] = "mixpanel";

//track "some_event" with your event props
// this event is associated with the mixpanel company group
Mixpanel.Track("some_event", props);
```

**Multiple Groups**

[An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values.

**Example Usage**

```csharp theme={"system"}
// set group key "company" as event prop
// with "mp-eu" and "mp-us" as value
var props = new Value();
var companies = new string[] {"mp-eu","mp-us"};
props["company"] = companies;

//track "some_event" with your event props
// this event is associated with the mp-eu and mp-us company group
Mixpanel.Track("some_event", props);
```

### Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the `group_key` and `group_id` as a user profile property using the `People.Set()` call.

**Example Usage**

```csharp theme={"system"}
// set group key "company" as a user prop
// with group id "mixpanel" as value
Mixpanel.Identify("12345");
Mixpanel.People.Set("company", "mixpanel");
```

## Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Unity SDK provide methods to help you protect user data.

Learn more about [Privacy](/docs/privacy/overview).

### Opt Out of Tracking

The Unity SDK is initialized with tracking enabled by default. Use the `.OptOutTracking()` method to opt the user out of data tracking and local storage for the current Mixpanel instance.

**Example Usage**

```csharp theme={"system"}
//send "some_event"
Mixpanel.Track("some_event");

// opt user out of tracking
// SDK is prevented from sending any data
Mixpanel.OptOutTracking();

// this track call will not work
Mixpanel.Track("some_event");
```

**Opt Out By Default**

You can initialize the library with users opted out of tracking by default using the `IsTracking` configuration. Once the user is ready to be tracked, call `.optInTracking()` to start tracking.

**Example Usage**

```csharp theme={"system"}
// turn off tracking
MixpanelStorage.IsTracking = false;

//opt back into tracking
Mixpanel.OptInTracking();
```

### EU Data Residency

Route data to Mixpanel's EU servers by setting the `API Host Address` to `https://api-eu.mixpanel.com/` when configuring the library under the unity project settings menu for Mixpanel (Edit -> Project Settings -> Mixpanel).

### India Data Residency

Route data to Mixpanel's EU servers by setting the `API Host Address` to `https://api-in.mixpanel.com/` when configuring the library under the unity project settings menu for Mixpanel (Edit -> Project Settings -> Mixpanel).

## Release History

[See all releases.](https://github.com/mixpanel/mixpanel-unity/releases)


# Warehouse Connectors
Source: https://docs.mixpanel.com/docs/tracking-methods/warehouse-connectors

Sync data from your data warehouse into Mixpanel

<Note>
  Organizations on a paid *event-based* plan receive Warehouse Connector as a free add-on when they update or renew their plan. Learn more on our [pricing page](https://mixpanel.com/pricing/).
</Note>

With Warehouse Connectors, you can sync data from data warehouses like Snowflake, BigQuery, Databricks, Redshift, and Postgres to Mixpanel. By unifying business data with product usage events, you can answer many more questions in Mixpanel:

* What percentage of our Enterprise revenue uses the features we shipped last year?
* Did our app redesign reduce support tickets?
* Which account demographics have the best retention?
* We spent \$50,000 on a marketing campaign, did the users we acquired stick around a month later?

Mixpanel's [Mirror](#mirror) sync mode keeps the data in Mixpanel fully in sync with any changes that occur in the warehouse, including updating historical events that are deleted or modified in your warehouse.

In this guide, we'll walk through how to set up Warehouse Connectors. The integration is completely codeless, but you will need someone with access to your DWH to help with the initial setup.

## Getting Started

<Note>
  To set up Warehouse Connectors, you must have an admin or owner project role. Learn more about [Roles and Permissions](/docs/orgs-and-projects/roles-and-permissions).
</Note>

### Step 1: Connect a warehouse

Navigate to [Project Settings → Warehouse Sources](https://mixpanel.com/report/settings/%23project%2F%24project_id%24%2Fwarehousesources/). Select your warehouse and follow the instructions to connect it. Note: you only need to do this once.

<Tabs>
  <Tab title="BigQuery">
    <Frame>
      <iframe />
    </Frame>

    The BigQuery connector works by giving a Mixpanel-managed service account permission to read from BigQuery in your GCP project. You will need:

    * Your GCP Project ID, which you can find in the URL of Google Cloud Console (`https://console.cloud.google.com/bigquery?project=YOUR_GCP_PROJECT`).
    * Your unique Mixpanel service account ID, which is generated the first time you create a BigQuery connection in the Mixpanel UI (e.g. `project-?????@mixpanel-warehouse-1.iam.gserviceaccount.com`).
    * A new, empty `mixpanel` dataset in your BigQuery instance (if you are using [Mirror](#mirror)).

    ```jsx theme={"system"}
      CREATE SCHEMA `<gcp-project>`.`mixpanel`
        OPTIONS (
          description = 'Mixpanel connector staging dataset',
          location = '<same-as-the-tables-to-be-synced>',
        );
    ```

    Grant the Mixpanel service the following permissions:

    * `roles/bigquery.jobUser` - Allows Mixpanel to run BigQuery jobs to unload data.

      ```jsx theme={"system"}
      gcloud projects add-iam-policy-binding --member serviceAccount:<mixpanel-service-account> --role roles/bigquery.jobUser
      ```
    * `roles/bigquery.dataViewer` on the datasets and/or tables to sync. Gives Mixpanel read-only access to the datasets.

      ```jsx theme={"system"}
      GRANT `roles/bigquery.dataViewer`
        ON SCHEMA `<gcp-project>`.`<dataset-to-be-synced>`
        TO "<mixpanel-service-account>"
      ```
    * `roles/bigquery.dataOwner` on the `mixpanel` dataset. Gives Mixpanel read-write access to the `mixpanel` dataset.

      ```jsx theme={"system"}
      GRANT `roles/bigquery.dataOwner`
        ON SCHEMA `<gcp-project>`.`mixpanel`
        TO "<mixpanel-service-account>"
      ```

    JSON columns mapped in BigQuery containing multiple properties are subject to a hard limit of 1MB per record. This limitation is imposed by Google Cloud's handling of JSON objects and applies during the intermediate step where data is written to the GCS bucket.

    ### VPC Service Controls

    IP allowlists are [not supported](https://docs.cloud.google.com/vpc-service-controls/docs/use-access-levels#limitations_of_using_access_levels_with) for BigQuery because Mixpanel's infrastructure runs on GCP, and inter-project communication in Google Cloud routes through internal Google IPs rather than public IPs. Instead, configure an ingress rule to allow access based on other attributes such as the project or service account. The service account is `project-<your-project-id>@mixpanel-warehouse-1.iam.gserviceaccount.com`. The Mixpanel project is `745258754925` for US, `848893383328` for EU, and `1054291822741` for IN. In addition, you may need to configure an egress rule to write data to `mixpanel-warehouse-1` project `435324298685`.
  </Tab>

  <Tab title="Snowflake">
    <Frame>
      <iframe />
    </Frame>

    To connect to Snowflake, you will need:

    * Your [Snowflake account identifier](https://docs.snowflake.com/user-guide/admin-account-identifier), which you can find in the URL of your Snowflake account (`https://YOUR_ACCOUNT_NAME.snowflakecomputing.com/`).
    * A dedicated Mixpanel user account and role. The user account can use either key-pair or password authentication. If using key-pair authentication, Mixpanel will generate a secure key-pair during the connection process. The public key will be provided during the setup process, and the private key will be encrypted and stored securely.

      ```jsx theme={"system"}
      CREATE ROLE MIXPANEL_ROLE;
      # one of
      CREATE USER MIXPANEL PASSWORD='?????' DEFAULT_ROLE=MIXPANEL_ROLE;
      CREATE USER MIXPANEL RSA_PUBLIC_KEY='<mixpanel-provided-key>' DEFAULT_ROLE=MIXPANEL_IMPORT_ROLE;
      # then
      GRANT ROLE MIXPANEL_ROLE TO USER MIXPANEL;
      ```
    * A Snowflake [WAREHOUSE](https://docs.snowflake.com/en/sql-reference/sql/create-warehouse) Mixpanel will use to unload data. We recommend creating a dedicated warehouse for Mixpanel to avoid impacting other workloads.

      ```jsx theme={"system"}
      CREATE WAREHOUSE MIXPANEL_WAREHOUSE WITH
        WAREHOUSE_SIZE = XSMALL # consider increasing for larger datasets
        AUTO_SUSPEND = 60
        AUTO_RESUME = TRUE
        INITIALLY_SUSPENDED = TRUE;
      GRANT USAGE ON MIXPANEL_WAREHOUSE TO ROLE MIXPANEL_ROLE;
      GRANT MONITOR ON MIXPANEL_WAREHOUSE TO ROLE MIXPANEL_ROLE;
      ```
    * A Snowflake [STORAGE INTEGRATION](https://docs.snowflake.com/en/sql-reference/sql/create-storage-integration) Mixpanel will use to unload data. This integration can optionally restrict STORAGE\_ALLOWED\_LOCATIONS to the unique Mixpanel-managed bucket created to receive data for this connection.

      ```jsx theme={"system"}
      CREATE STORAGE INTEGRATION MIXPANEL_STORAGE_INTEGRATION
        TYPE = EXTERNAL_STAGE
        STORAGE_PROVIDER = 'GCS'
        ENABLED = TRUE
        STORAGE_ALLOWED_LOCATIONS = ("<mixpanel-provided-bucket-name>"); # optional
      GRANT USAGE ON INTEGRATION MIXPANEL_STORAGE_INTEGRATION TO MIXPANEL_ROLE;
      ```
    * A new, empty `MIXPANEL` [SCHEMA](https://docs.snowflake.com/en/sql-reference/sql/create-schema) the Mixpanel user has the `USAGE` and `CREATE STREAM` permission for (if you are using [Mirror](#mirror)).

      ```jsx theme={"system"}
      CREATE SCHEMA <database>.MIXPANEL;
      GRANT USAGE ON DATABASE <database> TO ROLE MIXPANEL_ROLE;
      GRANT USAGE ON SCHEMA <database>.MIXPANEL TO ROLE MIXPANEL_ROLE;
      GRANT CREATE STREAM ON SCHEMA <database>.MIXPANEL TO ROLE MIXPANEL_ROLE;
      ```
    * The Mixpanel user needs the `USAGE` and `SELECT` permissions to have read-only access to any tables and views you plan to sync. Adjust this example to fine-tune permissions.

      ```jsx theme={"system"}
      GRANT USAGE ON DATABASE <database> TO ROLE MIXPANEL_ROLE;
      GRANT USAGE ON ALL SCHEMAS IN DATABASE <database> TO ROLE MIXPANEL_ROLE;
      GRANT USAGE ON FUTURE SCHEMAS IN DATABASE <database> TO ROLE MIXPANEL_ROLE;
      GRANT SELECT ON ALL TABLES IN DATABASE <database> TO ROLE MIXPANEL_ROLE;
      GRANT SELECT ON FUTURE TABLES IN DATABASE <database> TO ROLE MIXPANEL_ROLE;
      GRANT SELECT ON ALL VIEWS IN DATABASE <database> TO ROLE MIXPANEL_ROLE;
      GRANT SELECT ON FUTURE VIEWS IN DATABASE <database> TO ROLE MIXPANEL_ROLE;
      GRANT SELECT ON ALL MATERIALIZED VIEWS IN DATABASE <database> TO ROLE MIXPANEL_ROLE;
      GRANT SELECT ON FUTURE MATERIALIZED VIEWS IN DATABASE <database> TO ROLE MIXPANEL_ROLE;
      ```

    ### IP Allowlist

    If you are using [Snowflake Network policy](https://docs.snowflake.com/en/user-guide/network-policies) to restrict access to your instance, you might need to add the following IP addresses to the allowed list.

    **US**

    ```jsx theme={"system"}
    34.31.112.201
    35.184.21.33
    35.225.176.74
    ```

    **EU**

    ```jsx theme={"system"}
    34.147.68.192
    35.204.164.122
    35.204.177.251
    ```

    **IN**

    ```jsx theme={"system"}
    34.47.224.29
    34.93.42.83
    35.244.19.238
    ```

    * Some users report seeing the following error `ErrorMessage=SQL compilation error: Cannot unload to an inlined external location. Please create a stage first and unload to the stage instead.`. To resolve this error, you may set the following account security setting:

    ```jsx theme={"system"}
    ALTER ACCOUNT SET PREVENT_UNLOAD_TO_INLINE_URL = FALSE;
    ```

    See the [Snowflake documentation on this setting](https://docs.snowflake.com/en/sql-reference/parameters#prevent-unload-to-inline-url) before making the change.
  </Tab>

  <Tab title="Databricks">
    <Frame>
      <iframe />
    </Frame>

    <Note>
      The connection to Databricks only supports connecting directly to clusters or jobs compute. Connecting directly to SQL warehouses is not supported.
    </Note>

    Complete the following steps to get your Databricks connector up and running:

    ### Step 1: Set up authentication

    Mixpanel connects to Databricks using a service principal. You can authenticate with either a personal access token or OAuth (recommended).

    **Option A: Service Principal OAuth (Recommended)**

    OAuth M2M (machine-to-machine) authentication uses a client ID and client secret instead of a token. OAuth secrets can be managed and rotated without affecting other integrations.

    1. [Create the service principal](https://docs.databricks.com/en/admin/users-groups/service-principals.html#manage-service-principals-in-your-account) in your Databricks account if it doesn't already exist.
    2. Generate an OAuth secret for the service principal:

       * In your Databricks workspace, navigate to **Settings** → **Identity and access** → **Service principals**.
       * Click on the service principal you want to use.
       * Go to the **Secrets** tab.
       * Click **Generate secret**.
       * Copy the **Client ID** and **Secret** immediately — the secret won't be shown again.
    3. Save both the Client ID and Secret — you'll need them when connecting in Mixpanel.

    **Option B: Personal Access Token**

    1. [Create the service principal](https://docs.databricks.com/en/admin/users-groups/service-principals.html#manage-service-principals-in-your-account) in your Databricks account if it doesn't already exist.
    2. Generate a token for the service principal using the Databricks CLI:

    ```bash theme={"system"}
    databricks configure --token
    databricks token-management create-obo-token <application_id_of_service_principal> --lifetime-seconds 31536000 --comment "Mixpanel warehouse connector service principal token"
    ```

    3. Save the generated token — you'll need it when connecting in Mixpanel.

    ### Step 2: Grant permissions

    The user or service principal you're connecting with needs the following permissions. The exact permissions depend on which compute type you plan to use.

    **Compute permissions:**

    | Permission                     | All-Purpose Compute                   | Jobs Compute |
    | ------------------------------ | ------------------------------------- | ------------ |
    | `CAN ATTACH TO` on the cluster | Required                              | Not needed   |
    | `CAN RESTART` on the cluster   | Required if the cluster auto-suspends | Not needed   |
    | Cluster creation permissions   | Not needed                            | Required     |

    For all-purpose compute, the cluster must be a **shared** compute resource, not a single-user cluster (unless the service principal created the cluster).

    You can set these in Databricks under **Compute → your cluster → Edit Permissions**.

    **Data permissions:**

    Grant read access to the catalogs and schemas you want to sync to Mixpanel. You can do this in Databricks under **Catalog → your catalog → Permissions → Grant**, and select the **Data Reader** role.

    Mixpanel also needs file-level permissions to read table data and write intermediate results to cloud storage. Run the following SQL in a Databricks notebook or SQL editor:

    ```sql theme={"system"}
    GRANT SELECT ON ANY FILE TO `<application_id_or_username>`;
    GRANT MODIFY ON ANY FILE TO `<application_id_or_username>`;
    ```

    ### Step 3: Connect in Mixpanel

    1. Navigate to **Project Settings**, then select **Warehouse Sources**.
    2. Click on `+ Add Connection` and select **Databricks**.
    3. Fill out the following fields, then click **Create Source**:

       * **Server Hostname** — The hostname of your Databricks workspace. Find this in your workspace URL, or under your cluster's [JDBC/ODBC settings](https://docs.databricks.com/en/integrations/jdbc-odbc-bi.html#step).
       * **Authentication** — Choose one of the following:

         * **Personal Access Token** — The service principal token from Option A above.
         * **OAuth Client ID** and **OAuth Client Secret** — The client credentials from Option B above.
       * **Compute Type** — Select your preferred compute option:

         * **All-Purpose Compute** — Uses an existing cluster. Faster sync start times, but the cluster stays running after the sync completes until it times out. Best for development.
         * **Jobs Compute (Beta)** — Creates a dedicated job for each sync. You're only billed for the exact job duration, making it more cost-effective. Syncs take \~5-6 minutes longer to start due to cluster spin-up, and data preview in the Mixpanel UI is not supported. Best for production.
       * **HTTP Path** — For all-purpose compute, the HTTP path of your cluster. Find this under your cluster's [JDBC/ODBC settings](https://docs.databricks.com/en/integrations/jdbc-odbc-bi.html#step).
    4. Confirm that the credentials are validated and the source is added.

    ### IP Allowlist

    If you are using [IP Access List](https://docs.databricks.com/en/security/network/front-end/ip-access-list.html) to restrict access to your instance, you might need to add the following IP addresses to the allowed list.

    **US**

    ```jsx theme={"system"}
    34.31.112.201
    35.184.21.33
    35.225.176.74
    ```

    **EU**

    ```jsx theme={"system"}
    34.147.68.192
    35.204.164.122
    35.204.177.251
    ```

    **IN**

    ```jsx theme={"system"}
    34.47.224.29
    34.93.42.83
    35.244.19.238
    ```
  </Tab>

  <Tab title="Redshift">
    <Frame>
      <iframe />
    </Frame>

    Complete the following steps to get your Redshift connector up and running:

    1. Navigate to **Project Settings**, then select **Warehouse Sources**.
    2. Click on `+ Add Connection` and select **Redshift**.
    3. You should see a new page to create your Redshift connector. In the first view, fill out the following fields before clicking  `Next`:

       * **AWS Account ID**  - This is the AWS account ID that can be found in the dropdown in the AWS Redshift Console.
       * **Cluster ID**  - This is the name of the Redshift cluster.
    4. In the second view, you will need to add the following.

       * **AWS Region** - The region code in which your Redshift cluster resides.
       * **S3 Staging Bucket** - This is the name of S3 staging bucket you need to create. We'll use it to extract data from your Redshift tables before importing the data into Mixpanel.
       * Copy the command generated below in the AWS CLI to create the S3 Staging Bucket with the name you specified.
       * **Database Name** - Input the name of the Database where the tables you want to import are stored.
       * (Optional) **Policy Name** - This is an optional name for the policy, which contains role permissions that you need to grant the Mixpanel Service Account. After inputting a policy name, you can either copy-paste the JSON in the AWS UI or copy-paste the inline command line version that we generate and run in the AWS CLI.
       * **Role Name** - Input the name of the role. After inputting a role name, you can either copy-paste the JSON in the AWS UI or copy-paste the inline command line version that we generate and run in the AWS CLI. Running this command grants the Mixpanel Service Account the necessary permissions to read and export data from your Redshift tables.
       * Finally, attach the policy you created to the role you created by copy-pasting the command in the AWS CLI.
       * Then, click `Create Source`.
    5. In the third view, you should see a confirmation that your source was created. To establish the source connection, we need to ping your Redshift instance to actually create the service account user.

       * **Grant Access to Schema** - Enter the name of the schema you want to grant Mixpanel access to.
       * Copy the command generated and run it in your Redshift worksheet. Once that command is run successfully, the connection will be established, and you will be able to send data from Redshift tables to Mixpanel.

    ### IP Allowlist

    If you are using [AWS PrivateLink](https://docs.aws.amazon.com/redshift/latest/mgmt/security-private-link.html) to restrict access to your instance, you might need to add the following IP addresses to the allowed list.

    **US**

    ```jsx theme={"system"}
    34.31.112.201
    35.184.21.33
    35.225.176.74
    ```

    **EU**

    ```jsx theme={"system"}
    34.147.68.192
    35.204.164.122
    35.204.177.251
    ```

    **IN**

    ```jsx theme={"system"}
    34.47.224.29
    34.93.42.83
    35.244.19.238
    ```
  </Tab>

  <Tab title="Postgres">
    Complete the following steps to get your Postgres connector up and running:

    1. Navigate to **Project Settings**, then select **Warehouse Sources**.
    2. Click on `+ Add Connection` and select **Postgres**.
    3. You should see a new page to create your Postgres connector. Fill out the following fields:

       * **Server Hostname**  - This is the hostname or IP address of your Postgres database.
       * **Port**  - This is the port your database server is listening to. The default is `5432`.
       * **Database** - This is the name of the database you want to connect to.
       * **User Name** - This is the username you want to connect with. The user should have read-only permissions on your Postgres instance, as Mixpanel only needs to read data. Follow the principle of least privilege by granting access only to the specific schemas and tables you intend to sync.
       * **Password** - This is the password for the user you want to connect with.
       * **Postgres SSL Mode** - To keep your data secure, Mixpanel requires encryption for Postgres connections. You can choose between two SSL [modes](https://www.postgresql.org/docs/current/libpq-ssl.html):

         * **verify-full** (default, recommended) - Verifies both the server certificate and that the hostname matches the certificate.
         * **verify-ca** - Verifies the server certificate against a trusted certificate authority.
       * **Server CA Certificate** (Optional) - If your cloud provider doesn't use a public certificate registry (e.g., Google Cloud SQL, Supabase), you can upload a CA bundle as a PEM file to authenticate your server.
       * **SSH Tunnel** (Optional) - If you need to connect through an SSH tunnel, enable and configure the following:

         * **Bastion Hostname** - The hostname of your SSH server.
         * **Bastion Port** - The port your SSH server is listening on.
         * **SSH Username** - The username for SSH authentication.
         * **SSH Private Key** - Paste the contents of your private key file. At this time, only non-encrypted private keys are supported.
       * Then, click `Create Source`.

    <Warning>
      The Postgres connector only supports IPv4 connections. If you are using a database provider like Supabase, you may need to explicitly use an IPv4 connection.
    </Warning>

    ### IP Allowlist

    If you are using network policies or firewall rules to restrict access to your Postgres instance, you might need to add the following IP addresses to the allowed list.

    **US**

    ```jsx theme={"system"}
    34.170.209.182
    34.59.17.26
    35.226.128.70
    34.132.69.227
    ```

    **EU**

    ```jsx theme={"system"}
    34.6.165.244
    34.13.194.46
    ```

    **IN**

    ```jsx theme={"system"}
    34.14.173.30
    35.244.32.37
    ```
  </Tab>
</Tabs>

***

### Step 2: Load a warehouse table

Navigate to [Project Settings → Warehouse Data](https://mixpanel.com/report/settings/%23project%2F%24project_id%24%2Fwarehousedata/) and click +Event Table.

Select a table or view representing an event from your warehouse and tell Mixpanel about the table. Once satisfied with the preview, click Run, and we’ll establish the sync. The initial load may take a few minutes depending on the size of the table; we show you progress as it’s happening.

🎉 Congrats, you’ve loaded your first warehouse table into Mixpanel! From this point onward, the table will be kept in sync with Mixpanel. You can now use this event throughout Mixpanel’s interface.

## Table Types

Mixpanel’s [Data Model](/docs/how-it-works/concepts) consists of 4 types: Events, User Profiles, Group Profiles, and Lookup Tables. Each has properties, which are arbitrary JSON. Warehouse Connectors lets you turn any table or view in your warehouse into one of these 4 types of tables, provided they match the required schema.

### Events

An event is something that happens at a point in time. It’s akin to a “fact” in dimensional modeling or a log in a database. Events have properties, which describe the event. Learn more about Events [here](/docs/data-structure/events-and-properties).

Here’s an example table that illustrates what can be loaded as events in Mixpanel. The most important fields are the timestamp (when) and the user ID (who) — everything else is optional.

| Timestamp           | User ID                                       | Item  | Brand  | Amount | Type     |
| ------------------- | --------------------------------------------- | ----- | ------ | ------ | -------- |
| 2024-01-04 11:12:00 | [alice@example.com](mailto:alice@example.com) | shoes | nike   | 99.23  | in-store |
| 2024-01-12 11:12:00 | [bob@example.com](mailto:bob@example.com)     | socks | adidas | 4.56   | online   |

Here are more details about the schema we expect for events:

| Column            | Required | Type              | Description                                                                                                                                                        |
| ----------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Event Name        | Yes      | String            | The name of the event. E.g.: Purchase Completed or Support Ticket Filed. Note: you can specify this value statically, it doesn’t need to be a column in the table. |
| Time              | Yes      | Timestamp         | The time at which the event occurred.                                                                                                                              |
| User ID           | No       | String or Integer | The unique identifier of the user who performed the event. E.g.: 12345 or [grace@example.com](mailto:grace@example.com).                                           |
| Device ID         | No       | String or Integer | An identifier for anonymous users, useful for tracking pre-login data. Learn more [here](/docs/tracking-methods/id-management/identifying-users)                   |
| JSON Properties   | No       | JSON or Object    | A field that contains key-value properties in JSON format. If provided, Mixpanel will flatten this field out into properties.                                      |
| All other columns | No       | Any               | These can be anything. Mixpanel will auto-detect these columns and attach them to the event as properties.                                                         |

### User Profiles

A User Profile is a table that describes your users. It’s akin to a “dimension” in dimensional modeling or a relational table in a database. Learn more about User Profiles [here](/docs/data-structure/user-profiles).

Here’s an example table that illustrates what can be loaded as user profiles in Mixpanel. The only important column is the User ID, which is the primary key of the table.

| User ID | Email                                         | Name         | Subscription Tier |
| ------- | --------------------------------------------- | ------------ | ----------------- |
| 12345   | [grace@example.com](mailto:grace@example.com) | Grace Hopper | Pro               |
| 45678   | [bob@example.com](mailto:bob@example.com)     | Bob Noyce    | Free              |

While Profiles typically only store the state of a user *as of now*, Profile History enables storing the state of a user *over time*. The distinction between the value a property of the profile has now vs the value it had at the time of an event allows you to do very powerful analysis.

#### Profile History tables

<Note>
  Profile History tables are only available to organizations on an Enterprise plan.
</Note>

To create an import of regular user profiles, pick the “Standard” Type when creating a user table import.

<Frame>
  <img alt="Standard user table" />
</Frame>

When creating a User Profile (or Group Profile) sync, set the Table Type to “History Table”. We expect tables to be modeled as an SCD (Slowly Changing Dimensions) Type 2 table. You will need to supply a Start Time column in the sync configuration. Mixpanel will infer a row's end time if a new row with a more recent start time for the same user is detected.

<Frame>
  <img alt="Historic user property table" />
</Frame>

Preview from a sample profile history value table

<Frame>
  <img alt="Profile History table sample" />
</Frame>

Source table requirements:

* The source table for user/group history is expected to be modeled as an SCD (Slowly Changing Dimension) Type 2 table. This means that the table must maintain all the history over time that you want to use for analysis.
* History tables are supported only with Mirror Sync mode. Follow these [docs](/docs/tracking-methods/warehouse-connectors#mirror) to set up your source table to be mirror-compatible.
* The table should have a Timestamp/Date type column signifying the time that the properties on the row become active. This column will need to be supplied as `Start Time`  in the sync configuration.
* The following data types are NOT supported:

  * Lists (eg, Snowflake’s ARRAY)
  * Objects (e,g Snowflake’s OBJECT)

### Group Profiles

A Group Profile is a table that describes an entity (most often an Account, if you’re a B2B company). They are functionally identical to User Profiles, just used for other non-User entities. Group Profiles are only available if you have the Group Analytics add-on. Learn more about Group Analytics [here](/docs/data-structure/advanced/group-analytics).

Here’s an example table that illustrates what can be loaded as group profiles in Mixpanel. The only important column is the Group Key, which is the primary key of the table.

| Group Key | Name   | Domain    | ARR   | Subscription Tier |
| --------- | ------ | --------- | ----- | ----------------- |
| 12345     | Notion | notion.so | 45000 | Enterprise        |
| 45678     | Linear | linear.so | 2000  | Pro               |

Group Profile History value and setup are similar to the User Profile History section elaborated above

Generally, group profile history values can only be used for queries within that same group. To power user-mode queries that use a group profile history property, the latest value of the ingested property will be used instead. Following ingestion, there may be a delay before the latest value is available in queries.

### Lookup Tables

A Lookup Table is useful for enriching Mixpanel properties (e.g., content, SKUs, currencies) with additional metadata. Learn more about Lookup Tables [here](/docs/data-structure/lookup-tables). Note the limits of lookup tables indicated [here](/docs/data-structure/lookup-tables#when-shouldnt--i-use-lookup-tables).

Here is an example table that illustrates what can be loaded as a lookup table in Mixpanel. The only important column is the ID, which is the primary key of the table that is eventually mapped to a Mixpanel property

| ID    | Song Name | Artist    | Genre      |
| ----- | --------- | --------- | ---------- |
| 12345 | One Dance | Drake     | Pop        |
| 45678 | Voyager   | Daft Punk | Electronic |

## Sync Modes

Warehouse Connectors regularly check warehouse tables for changes to load into Mixpanel. The Sync Mode determines which changes Mixpanel will reflect.

* **Mirror** will keep Mixpanel perfectly in sync with the data in the warehouse. This includes syncing new data, modifying historical data, and deleting data that was removed from the warehouse. **Mirror** is supported for Snowflake, BigQuery, Databricks, and Redshift.
* **Append** will load new rows in the warehouse into Mixpanel, but will ignore modifications to existing rows or rows that were deleted from the warehouse. We recommend using **Mirror** over **Append** for supported warehouses.
* **Full** will reload the entire table to Mixpanel each time it runs rather than tracking changes between runs. Full syncs are only supported for Lookup Tables, User Profiles, and Group Profiles.
* **One-Time** will load the data from your warehouse into Mixpanel *once* with no ability to send incremental changes later. This is only recommended where the warehouse is being used as a temporary copy of the data being moved to Mixpanel from some other source, and the warehouse copy will not be updated later.

### Mirror

Mirror syncs work by having the warehouse compute which rows have been inserted, modified, or deleted and sending this list of changes to Mixpanel. Change tracking is configured differently depending on the source warehouse. Mirror is supported for Snowflake, Databricks, BigQuery, and Redshift sources.

<Note>
  For User tables, Mirror Sync is available only when you select the Profile History table type. Mirror Sync is not available for the Standard table type.
</Note>

<Tabs>
  <Tab title="BigQuery">
    Mirror takes BigQuery [table snapshots](https://cloud.google.com/bigquery/docs/table-snapshots-intro) and runs queries to compute the change stream between two snapshots. Snapshots are stored in the `mixpanel` dataset created in [Step 1](#step-1-connect-a-warehouse).

    **Considerations when using Mirror with BigQuery:**

    * Mirror is not supported on views in BigQuery.
    * If two rows in BigQuery are identical across *all* columns, the checksums Mirror computes for each row will be the same, and Mixpanel will consider them the same row, causing only one copy to appear in Mixpanel. We recommend ensuring that one of your columns is a unique row ID to avoid this.
    * The table snapshots managed by Mixpanel are always created to expire after 21 days. This ensures that the snapshots are deleted even if Mixpanel loses access to them unexpectedly. Make sure that the sync does not go longer than 21 days without running, as each sync run needs access to the previous sync run's snapshot (under normal conditions, Mirror maintains only one snapshot per sync and removes the older run's snapshot as soon as it has been used by the subsequent sync run).

    **How changes are detected:**

    Changed rows are detected by checksumming the values of all columns except trailing NULL-valued columns. For example, in the following table would use these per-row checksums:

    | ID    | Song Name | Artist    | Genre      | **Computed checksum**                                   |
    | ----- | --------- | --------- | ---------- | ------------------------------------------------------- |
    | 12345 | One Dance | Drake     | NULL       | `CHECKSUM(12345, 'One Dance', 'Drake')`                 |
    | 45678 | Voyager   | Daft Punk | Electronic | `CHECKSUM(45678, 'Voyager', 'Daft Punk', 'Electronic')` |
    | 83921 | NULL      | NULL      | Classical  | `CHECKSUM(83921, NULL, NULL, 'Classical')`              |

    Trailing NULL values are excluded from the checksum to ensure that adding new columns does not change the checksum of existing rows. For example, if a new column is added to the example table:

    ```jsx theme={"system"}
    ALTER TABLE songs ADD COLUMN Tag STRING NULL;
    ```

    It would not change the computed checksums:

    | ID    | Song Name | Artist    | Genre      | Tag  | Computed checksum                                       |
    | ----- | --------- | --------- | ---------- | ---- | ------------------------------------------------------- |
    | 12345 | One Dance | Drake     | NULL       | NULL | `CHECKSUM(12345, 'One Dance', 'Drake')`                 |
    | 45678 | Voyager   | Daft Punk | Electronic | NULL | `CHECKSUM(45678, 'Voyager', 'Daft Punk', 'Electronic')` |
    | 83921 | NULL      | NULL      | Classical  | NULL | `CHECKSUM(83921, NULL, NULL, 'Classical')`              |

    Until values are written to the new column:

    | ID    | Song Name | Artist    | Genre      | Tag  | Computed checksum                                               |
    | ----- | --------- | --------- | ---------- | ---- | --------------------------------------------------------------- |
    | 12345 | One Dance | Drake     | NULL       | tag1 | `CHECKSUM(12345, 'One Dance', 'Drake', NULL, 'tag1')`           |
    | 45678 | Voyager   | Daft Punk | Electronic | tag2 | `CHECKSUM(45678, 'Voyager', 'Daft Punk', 'Electronic', 'tag2')` |
    | 83921 | NULL      | NULL      | Classical  | NULL | `CHECKSUM(83921, NULL, NULL, 'Classical')`                      |

    **Handling schema changes when using Mirror with BigQuery:**

    Adding new, default-NULL columns to Mirror-tracked tables/views is fully supported, as described in the previous section.

    ```jsx theme={"system"}
    ALTER TABLE <table> ADD COLUMN <column> STRING NULL;
    ```

    If you have a JSON column in the table/view which you map to `JSON Properties` in the import setup, as the whole JSON object for that column is used to calculate the checksum for the row, **any changes to the JSON object will result in a change to the checksum**, even if the change is to add new keys with null values. As such, consider conditional formatting when building the JSON object to only update it when a new non-null value is available for a row.

    We recommend avoiding other types of schema changes on large tables. Other schema changes may cause the checksum of every row to change, effectively re-sending the entire table to Mixpanel. For example, if we were to remove the Genre column in the example above, the checksum of every row would be different:

    | ID    | Song Name | Artist    | Tag  | Computed checksum                                 |
    | ----- | --------- | --------- | ---- | ------------------------------------------------- |
    | 12345 | One Dance | Drake     | tag1 | `CHECKSUM(12345, 'One Dance', 'Drake', 'tag1')`   |
    | 45678 | Voyager   | Daft Punk | tag2 | `CHECKSUM(45678, 'Voyager', 'Daft Punk', 'tag2')` |
    | 83921 | NULL      | NULL      | NULL | `CHECKSUM(83921)`                                 |

    **Handling partitioned tables:**

    When syncing [time partitioned](https://cloud.google.com/bigquery/docs/partitioned-tables#date_timestamp_partitioned_tables) or [ingestion-time partitioned](https://cloud.google.com/bigquery/docs/partitioned-tables#ingestion_time) tables, Mirror will use partition metadata to skip processing partitions that have not changed between sync runs. This will make the computation of the change stream much more efficient on large partitioned tables where only a small percentage of partitions are updated between runs. For example, in a day-partitioned table with two years of data, where only the last five days of data are normally updated, only five partitions' worth of data will be scanned each time the sync runs.
  </Tab>

  <Tab title="Snowflake">
    Mirror uses [Snowflake Streams](https://docs.snowflake.com/en/user-guide/streams-intro) to track changes to Snowflake tables or views. The only requirement to use Mirror on a Snowflake table or view is to enable [change tracking](https://docs.snowflake.com/en/user-guide/streams-manage):

    ```jsx theme={"system"}
    ALTER TABLE <table> SET CHANGE_TRACKING = TRUE;
    # or
    ALTER VIEW <view> SET CHANGE_TRACKING = TRUE;
    ```

    Mixpanel will create and manage the necessary STREAM objects in the `MIXPANEL` schema created in [Step 1](#step-1-connect-a-warehouse).

    **Considerations when using Mirror with Snowflake:**

    * Snowflake Streams only maintain change tracking metadata for a limited number of days determined by the larger of [DATA\_RETENTION\_TIME\_IN\_DAYS and MAX\_DATA\_EXTENSION\_TIME\_IN\_DAYS](https://docs.snowflake.com/en/user-guide/streams-manage#avoiding-stream-staleness) (default is 14 days for MAX\_DATA\_EXTENSION\_TIME\_IN\_DAYS). Make sure that the Mixpanel sync does not go longer than this number of days without running. Mixpanel recommends leaving the default of 14 days to ensure that if Mixpanel loses access to the warehouse unexpectedly (e.g., a credentials change), there is time to correct the issue.
    * Snowflake Streams do not work if a table is deleted and re-created with the same name. If using a tool like DBT to model data in Snowflake, make sure to use an [incremental model](https://docs.getdbt.com/docs/build/incremental-models) so that DBT does not replace the table each time it runs.
    * Snowflake streams don't capture changes when a column is deleted or renamed, so deletion of columns won't be synced to Mixpanel.
    * Snowflake has specific requirements when using [Streams on Views](https://docs.snowflake.com/en/user-guide/streams-intro#streams-on-views) that must be met when using Mirror with views.
    * While Snowflake Streams are a very efficient way of tracking changes, there are some performance implications when using [Streams on VIEWs that contain JOINs](https://docs.snowflake.com/en/user-guide/streams-intro#join-results-behavior). If you find yourself needing such a JOIN in event data, we recommend considering if syncing the joined data as [User Profiles](#user-profiles), [Group Profiles](#group-profiles), or a [Lookup Table](#lookup-tables) would work instead.

    **Handling schema changes when using Mirror with Snowflake:** Adding new, default-NULL columns to Mirror-tracked tables/views is fully supported.

    ```jsx theme={"system"}
    ALTER TABLE <table> ADD COLUMN <column> VARCHAR DEFAULT NULL;
    ```

    We recommend avoiding other types of schema changes. Snowflake streams only reflect changes to tables from DML statements. DDL statements that logically modify data (e.g., adding new columns with default values, dropping existing columns, or renaming columns) will be reflected in future data sent to Mixpanel, but the Stream will not update historical data with changes caused by DDL statements.
  </Tab>

  <Tab title="Databricks">
    Mirror uses Databricks [Change Data Feed](https://docs.databricks.com/en/delta/delta-change-data-feed.html) to track changes to Databricks tables. The only requirement to use Mirror on a Databricks table is to enable [change data feed](https://docs.databricks.com/en/delta/delta-change-data-feed.html#enable-change-data-feed) on those entities.

    ```jsx theme={"system"}
    ALTER TABLE <table> SET TBLPROPERTIES (delta.enableChangeDataFeed = true);
    ```

    **Considerations when using Mirror with Databricks:**

    * Mirror is not supported on views in Databricks
    * Databricks Change Data Feed only maintains change history for a limited number of days determined by [delta.logRetentionDuration](https://docs.databricks.com/en/delta/history.html#retrieve-delta-table-history) (default is 30 days). Make sure that the Mixpanel sync does not go longer than this number of days without running. Mixpanel recommends leaving the default of 30 days to ensure that if Mixpanel loses access to the warehouse unexpectedly (e.g., a credentials change), there is time to correct the issue.
    * Databricks Change Data Feed does not work if a table is deleted and re-created with the same name. If using a tool like DBT to model data in Databricks, make sure to use an [incremental model](https://docs.getdbt.com/docs/build/incremental-models) so that DBT does not replace the table each time it runs.
    * While Databricks Change Data Feed works with adding new columns to the table, there are certain limitations when it comes to dropping columns or renaming columns that use [column mappings](https://docs.databricks.com/en/delta/delta-change-data-feed.html#change-data-feed-limitations-for-tables-with-column-mapping-enabled). In such scenarios, Mixpanel recommends deleting the sync (along with the data) and re-creating the sync.
  </Tab>

  <Tab title="Redshift">
    Mirror takes Redshift table snapshots and runs queries to compute the change stream between two snapshots using the computed MD5 hash value for each row. Snapshots are stored in a staging schema created in [Step 1](#step-1-connect-a-warehouse).

    * If two rows in the Redshift table are identical across *all* columns, the md5 hash value Mirror computes for each row will be the same, and Mixpanel will consider them the same row, causing only one copy to appear in Mixpanel. We recommend ensuring that one of your columns is a unique row ID to avoid this.
    * The table snapshots managed by Mixpanel are automatically cleaned up. Under normal conditions, Mirror maintains only one snapshot per sync and removes the older run's snapshot as soon as it has been used by the subsequent sync run. These snapshots will incur some additional storage cost.

    **How changes are detected:**

    Changed rows are detected by computing the MD5 hash for concatenated values of all columns except trailing NULL-valued columns. For example, in the following table would use these per-row MD5:

    | **ID** | **Song Name** | **Artist** | **Genre**  | **Computed checksum**                              |
    | ------ | ------------- | ---------- | ---------- | -------------------------------------------------- |
    | 12345  | One Dance     | Drake      | NULL       | `MD5(12345, 'One Dance', 'Drake')`                 |
    | 45678  | Voyager       | Daft Punk  | Electronic | `MD5(45678, 'Voyager', 'Daft Punk', 'Electronic')` |
    | 83921  | NULL          | NULL       | Classical  | `MD5(83921, NULL, NULL, 'Classical')`              |

    Trailing NULL values are excluded from the checksum to ensure that adding new columns does not change the checksum of existing rows. For example, if a new column is added to the example table:

    ```sql theme={"system"}
    ALTER TABLE songs ADD COLUMN Tag STRING NULL;
    ```

    It would not change the computed checksums:

    | **ID** | **Song Name** | **Artist** | **Genre**  | **Tag** | **Computed checksum**                              |
    | ------ | ------------- | ---------- | ---------- | ------- | -------------------------------------------------- |
    | 12345  | One Dance     | Drake      | NULL       | NULL    | `MD5(12345, 'One Dance', 'Drake')`                 |
    | 45678  | Voyager       | Daft Punk  | Electronic | NULL    | `MD5(45678, 'Voyager', 'Daft Punk', 'Electronic')` |
    | 83921  | NULL          | NULL       | Classical  | NULL    | `MD5(83921, NULL, NULL, 'Classical')`              |

    Until values are written to the new column:

    | **ID** | **Song Name** | **Artist** | **Genre**  | **Tag** | **Computed checksum**                                      |
    | ------ | ------------- | ---------- | ---------- | ------- | ---------------------------------------------------------- |
    | 12345  | One Dance     | Drake      | NULL       | tag1    | `MD5(12345, 'One Dance', 'Drake', NULL, 'tag1')`           |
    | 45678  | Voyager       | Daft Punk  | Electronic | tag2    | `MD5(45678, 'Voyager', 'Daft Punk', 'Electronic', 'tag2')` |
    | 83921  | NULL          | NULL       | Classical  | NULL    | `MD5(83921, NULL, NULL, 'Classical')`                      |

    **Handling schema changes when using Mirror with BigQuery:**

    Adding new, default-NULL columns to Mirror-tracked tables/views is fully supported as described in the previous section.

    ```sql theme={"system"}
    ALTER TABLE <table> ADD COLUMN <column> STRING NULL;
    ```

    We recommend avoiding other types of schema changes on large tables. Other schema changes may cause the hash value of every row to change, effectively re-sending the entire table to Mixpanel. For example, if we were to remove the Genre column in the example above, the checksum of every row would be different:

    | **ID** | **Song Name** | **Artist** | **Tag** | **Computed checksum**                        |
    | ------ | ------------- | ---------- | ------- | -------------------------------------------- |
    | 12345  | One Dance     | Drake      | tag1    | `MD5(12345, 'One Dance', 'Drake', 'tag1')`   |
    | 45678  | Voyager       | Daft Punk  | tag2    | `MD5(45678, 'Voyager', 'Daft Punk', 'tag2')` |
    | 83921  | NULL          | NULL       | NULL    | `MD5(83921)`                                 |

    **Considerations when using Mirror  with Redshift:**

    * Currently, only the add-column schema update is supported.
    * Geography, Geometry, Varbyte, and hllsketch are not supported currently. If you have a use case that requires support for any of these columns, please contact us for a feature request.
    * Any new tables created after the permissions are granted are not automatically accessible by Mixpanel. Please re-grant the necessary permissions to be able to set up Mirror on the tables.
    * `_mp_row_hash` and `_mp_change_type` are reserved column names used for tracking the computed hash value for each row, and updating the type of the row. Please ensure that this doesn’t conflict with the column names of the table.
  </Tab>
</Tabs>

***

### Append

Append syncs require an Insert Time column in your table. Mixpanel remembers the maximum Insert Time it saw in the previous run of the sync and looks for only rows that have an Insert Time greater than that. This is useful and efficient for append-only tables (usually events) that have a column indicating when the data was appended.

Each time an Append sync runs, it will query the source table with a `WHERE <insert_time_column> > <previous_max_insert_time>` clause. This means that records added with an append time value before the `<previous_max_insert_time>` from the previous run can be missed (not imported) as they would be considered already ingested. The `<insert_time_column>` value should always reflect when the value was made available for Mixpanel to query and ingest.

**Considerations when using Append with large BigQuery tables:**

In an un-partitioned BigQuery table, the `<insert_time_column>` filtering results in a full scan of all data in the source table each time the sync runs. To minimize BigQuery costs we recommend [partitioning the source table by the `<insert_time_column>`](https://cloud.google.com/bigquery/docs/partitioned-tables#date_timestamp_partitioned_tables). Doing so will ensure that each incremental sync run [only scans the most recent partitions](https://cloud.google.com/bigquery/docs/partitioned-tables).

To understand the potential savings, consider a 100 GB source table with 100 days of data (approximately 1 GB of data per day):

* If this table is not partitioned and is synced daily, the Append sync will scan the whole table (100 GB of data) each time it runs, or 3,000 GB of data per month.
* If this table is partitioned by day and is synced daily with an Append sync, the Append sync only scans the current day and the previous day's partitions (2 GB of data) each time it runs, or 60 GB of data per day, a 50x improvement over the un-partitioned table.

Note: [BigQuery's ingestion time partitions](https://cloud.google.com/bigquery/docs/partitioned-tables#ingestion_time) **are not supported** in Append mode.

***

### Full

Full syncs periodically make a snapshot of the source table and sync it entirely to Mixpanel. If a row has new properties in your warehouse, the corresponding profile in Mixpanel will be overridden with those new properties. This mode is available for all tables except events.

## Sync Frequency

Mixpanel offers a variety of sync frequency options to cater to different data integration needs. These options allow you to choose how often your data is synchronized from your data warehouse to Mixpanel, ensuring your data is up-to-date and accurate.

### Standard Sync Frequency Options

<Note>
  GA4 tables support only a daily sync frequency.
</Note>

* Hourly: Data is synchronized every hour, providing near real-time updates to your Mixpanel project.
* Daily: Data synchronization occurs once a day, ideal for daily reporting and analytics.
* Weekly: Data is synchronized once a week, suitable for less frequent reporting needs.

### Advanced Sync Frequency Option: Trigger via API

For more advanced synchronization needs, Mixpanel offers the ability to trigger syncs via API. This option generates a PUT URL that customers can use in their code to orchestrate Mixpanel sync jobs with other jobs, such as Fivetran pipelines or dbt jobs. By using this API trigger option, you can ensure 100% accuracy by aligning Mixpanel syncs with other critical data operations.

To use the API trigger option:

1. Select Advanced>Trigger Via API under Sync Frequency in the table sync creation UI.
2. After creating the sync, we will generate a PUT URL for you.
3. Integrate this URL into your existing workflows or scripts.
4. Authenticate the request with a Mixpanel Service Account. More information on setting up and using Mixpanel Service Accounts can be found [here](/reference/service-accounts).
5. Trigger the sync job programmatically, ensuring it runs in coordination with other data processes.

This flexibility allows you to maintain precise control over when and how your data is updated in Mixpanel, ensuring your analytics are always based on the latest information.

Note: If your table sync is set up with Mirror mode, you will need to run a sync job at least every 2 weeks to ensure our snapshots do not get deleted. We rate-limit the number of syncs via API to 5 per hour.

## FAQ

### What tables are valuable to load into Mixpanel?

Anything that is event-based (has a user\_id and timestamp) and that you want to analyze in Mixpanel. Examples, by data source are:

* CRM: Opportunity Created, Opportunity Closed
* Support: Ticket Created, Ticket Closed
* Billing: Subscription Created, Subscription Upgraded, Subscription Canceled, Payment Made
* Application Database: Sign-up, Purchased Item, Invited Teammate

We also recommend loading your user and account tables to enrich events with demographic attributes about the users and accounts who performed them.

### How fast do syncs transfer data?

Syncs have a throughput of \~30K events+updates/second or \~100M events+updates/hour.

### What is the best way to start bringing in event data?

We recommend starting with a subset of data in a materialized view to test the import process. This allows you to ensure that relevant columns are correctly formatted and the data appears as expected in Mixpanel. Once the data is imported, run a few reports to verify that you can accurately gain insight into your team’s KPIs with the way your data is formatted.

After validating your use case, navigate to the imported table and select "Delete Import" to hard delete the subset data. This step ensures that you can then import the entire table without worrying about duplicate data.

### I already track data to Mixpanel via SDK or CDP, can I still use Warehouse Connectors?

Yes! You can send some events (eg, web and app data) directly via our SDKs and send other data (eg, user profiles from CRM or logs from your backend) from your warehouse and analyze them together in Mixpanel.

Please do note that warehouse connectors enforce strict\_mode validation by default, and any events and historical profiles with time set in the future will be dropped. We will reject events with time values that are before 1971-01-01 or more than 1 hour in the future as measured on our servers. We recommend that the customer filter such events and refresh such events when they are no longer set in the future.

### How do I filter for events coming to Mixpanel via Warehouse Connector Sync in my reports?

We add a couple of hidden properties, `$warehouse_import_id` and `$warehouse_type`, on every event ingested through warehouse connectors. You can add filters and breakdowns on that property in any Mixpanel report. You can find the Warehouse import ID of a sync in the Sync History tab shown as `Mixpanel Import ID`.

### Does Mixpanel automatically flatten nested data from warehouse tables?

Automatic flattening is only available for GA4 tables. For other tables, you’ll need to manually flatten the data via queries before import.

### What should I do if my BigQuery import query is too large or takes too long?

Consider breaking the data into smaller chunks if you’re working with large datasets. You can do this by creating views in BigQuery that only include the data you want to import — for example, limiting it to the past 6 months or 1 year.

Note: The 20-hour query limit is a Mixpanel restriction, not a BigQuery one, to help keep the system stable for all users.

### Why is mirror mode required for profile history syncs?

Mirror mode allows Mixpanel to detect changes in your data warehouse and update historical profile data in Mixpanel accordingly. This is essential for maintaining an accurate history of user profiles. When you use the Mirror mode, Mixpanel data automatically syncs with your warehouse by accurately reflecting all changes, including additions, updates, or deletions. You can learn more about the Mirror mode and its benefits in this [blog post](https://mixpanel.com/blog/mirror-product-analytics-data-warehouse-sync/)

### Why am I seeing events in my project with the name of my profile table?

Events with the same name as the table/view used for historical profile imports are auto-generated by the WH import process. These are hidden by default and are not meant to be queried directly. Billing for historical imports is done using mirror pricing (link to question below).

## Billing FAQ

### What actions impact billing for warehouse connectors?

Billing varies by operation type and connector mode. The tables below explain how each action affects your monthly event volume:

**Billing for Event Syncs:**

| **Event Operation**   | **Sync Type** | **Supported** | **Billed** |
| --------------------- | ------------- | ------------- | ---------- |
| **Events**            | One time      | ✅             | ✅          |
|                       | Append        | ✅             | ✅          |
|                       | Mirror        | ✅             | ✅          |
| **Updates & deletes** | One time      | ❌             | ❌          |
|                       | Append        | ❌             | ❌          |
|                       | Mirror        | ✅             | ✅          |

The above table applies if your account uses ingestion time billing. If your account is on legacy event timestamp billing:

* **Event inserts** are billed only if the event timestamp is in the current billing month. Events with timestamps in previous months are not billed.
* **Updates and deletes** are always billed at ingestion time, regardless of the event timestamp on the original event. More details on ingestion time vs. event timestamp billing can be found in [this section](/docs/pricing#are-monthly-events-calculated-based-on-ingestion-time-or-event-timestamp).

If you’re planning on backfilling a significant amount of historical events and need help understanding how it will impact your costs, please reach out to your Mixpanel account manager or [contact support](https://mixpanel.com/get-support).

**Note on Updates**: If you already have an event in Mixpanel, for example, Event A with properties a,b,c,d, but want to:

* **Update the value** of property d, or
* **Add a new property** or column e with a non-NULL value

This will count as an update event for each row in the sync.

If your warehouse workflow **drops and recreates tables**, Mirror will treat this as a full delete and re-insert, with each row counted as a billable event. Mirror looks at the data already ingested into Mixpanel and uses warehouse-specific logic to identify changes made within your warehouse platform. In the case of a full table delete, Mixpanel will register each deleted row as a billable event, and the same applies when the table is recreated.

If instead your workflow updates existing tables—by appending, updating, or deleting specific rows or columns—only the affected rows will be billed, as shown in the table above.

**Note on Backfills**: You can also backfill using `Append` mode if you create a new sync. But for an ongoing sync, you cannot backfill for older days within the existing sync once the `insert_time` has moved past.

**Billing for User/Group Profiles Syncs**

| **Profile Operation**             | **Mode** | **Sync Type** | **Supported** | **Billed** |
| --------------------------------- | -------- | ------------- | ------------- | ---------- |
| **Set/update profile properties** | Standard | Full sync     | ✅             | ❌          |
|                                   | Standard | Append        | ✅             | ❌          |
|                                   | History  | Mirror        | ✅             | ✅          |
| **Remove profile properties**     | Standard | Full sync     | ❌             | ❌          |
|                                   | Standard | Append        | ❌             | ❌          |
|                                   | History  | Mirror        | ✅             | ✅          |

You can monitor these different operations in your billing page, where they'll appear as separate line items: Events - Updates, Events - Deletes, User - Updates, and User - Deletes.

**Billing for historical table imports:**

Historical tables can be imported only in mirror mode. Mirror-mode pricing updates apply to all rows imported for profile history tables. This means:

* Historical profile updates DO count towards billing. Imports through standard profile tables do not.
* Every row counts as a mirror event and is [billed as such](../pricing#i-am-using-the-warehouse-add-on-for-ingesting-data-how-does-this-impact-billing).
* If you update/delete existing rows in your table, [mirror billing](../pricing#i-am-using-the-warehouse-add-on-for-ingesting-data-how-does-this-impact-billing) will be applied, including for backfills.

For MTU plans, the events and updates/deletes don't directly affect the MTU tally unless the volume of events and updates pushes the threshold for the guardrail (by default, 1000 events per user); once the threshold for the guardrail is crossed, events and updates from profile history tables will also count towards billing.

### When should I use Mirror vs. Append mode?

**Use Mirror mode when:**

* You want to maintain a replica of your warehouse data in Mixpanel
* You want to automatically sync updates and deletes from your warehouse
* You need to track the history of user profile changes over time (with History mode)

**Use Append mode when:**

* You only need to add new data without updating existing records
* You have a workflow that frequently drops and recreates tables

For large-scale changes that might significantly impact billing, we recommend consulting with your Account Manager before proceeding.

### What will be the cost impact of this on my DWH?

The DWH cost of using a warehouse connector will vary based on the source warehouse and sync type used. Our connectors use warehouse-specific change tracking to compute modified rows in the warehouse and send only changed data to Mixpanel.

There are 3 aspects of DWH cost: network egress, storage, and compute.

* **Network Egress**: All data is transferred using gzip compression. Assuming an egress rate of \$0.08 per GB and 100 compressed bytes per event, this is a cost of less than \$0.01 per million events. [Mirror](#mirror) and [Append](#append) syncs will only transfer new or modified rows each time they run. [Full](#full) syncs will transfer all rows every time they run. We recommend using Full syncs only for small tables and running them less frequently.
* **Storage**: [Append](#append) and [Full](#full) syncs do not store any additional data in your warehouse, so there are no extra storage costs. [Mirror](#mirror) tracks changes using warehouse-specific functionality that can affect warehouse storage costs:

  * Snowflake: Mirror uses [Snowflake Streams](https://docs.snowflake.com/en/user-guide/streams-intro). Snowflake Streams will [retain historical data](https://docs.snowflake.com/en/user-guide/streams-intro#billing-for-streams) until it is consumed from the stream. As long as the warehouse connector runs regularly, data will be consumed regularly and only retained between runs.
  * BigQuery: Mirror uses [table snapshots](https://cloud.google.com/bigquery/docs/table-snapshots-intro). Mirror keeps one snapshot per table to track the contents of the table from the last run. BigQuery table snapshots have no cost when they are first created, as they share the underlying storage with the source table. However, as the source table changes, [the cost of storing changes is attributed to the table snapshot](https://cloud.google.com/bigquery/docs/table-snapshots-intro#storage_costs). Each time the connector runs, the current snapshot is replaced with a new snapshot of the latest state of the table. The storage cost is the amount of changes being tracked between the snapshot and source table between runs.
  * Databricks: Mirror uses Databricks [Change Data Feed](https://docs.databricks.com/en/delta/delta-change-data-feed.html) and all the changes are retained in Databricks for the [delta.logRetentionDuration](https://docs.databricks.com/en/delta/history.html#retrieve-delta-table-history). Configure that window accordingly to keep storage costs low.
* **Compute**:

  * Mirror on Snowflake: [Snowflake Streams](https://docs.snowflake.com/en/user-guide/streams-intro) natively track changes; the compute cost of querying for these changes is normally proportional to the amount of changed data.
  * Mirror on BigQuery: Each time the connector runs, it checksums all rows in the source table and compares them to a [table snapshot](https://cloud.google.com/bigquery/docs/table-snapshots-intro) from the previous run. For large tables, we highly recommend [partitioning](https://cloud.google.com/bigquery/docs/partitioned-tables) the source table. When the source table is partitioned, the connector will skip checksumming any partitions that have not been modified since the last run. For more details, see the BigQuery-specific instructions in [Mirror](#mirror).
  * Mirror on Databricks: Databricks [Change Data Feed](https://docs.databricks.com/en/delta/delta-change-data-feed.html) natively tracks changes to the tables or views, and the compute cost of querying these changes is normally proportional to the amount of changed data. Mixpanel recommends using a smaller compute cluster and setting Auto Terminate after 10 minutes of idle time on the compute cluster.
  * Append: All Append syncs run a query filtered on `insert_time_column > [last-run-time]`; the compute cost is the cost of this query. Partitioning or clustering based on `insert_time_column` will greatly improve the performance of this query.
  * Full: Full syncs are always a full table scan of the source table to export it.

### Will I be charged for failed imports or errors?

No, you will only be charged for events that are successfully imported into Mixpanel. Events that fail validation or encounter errors during the import process will not count toward your billable data points.

### How can I monitor my data usage with warehouse connectors?

You can track your data usage in Mixpanel by navigating to Organization Settings > Usage and viewing the "Data Points" section. Use the "Data Source" filter to specifically view warehouse connector imports.


# Users
Source: https://docs.mixpanel.com/docs/users

Explore your user base in Mixpanel

<Frame>
  <img alt="/Screen_Shot_2022-07-12_at_4.43.34_PM.png" />
</Frame>

Mixpanel's Users page allows you to filter users and gain a deeper understanding of how they interact with your website or application. By filtering your users into groups called cohorts, you can import these cohorts into other reports and perform analyses on those specific users.

If you want to import User Profiles into Mixpanel, see our [User Profiles guide](/docs/data-structure/user-profiles).

### Use Case

Mixpanel's Users page aggregates and organizes a collection of user profiles. This facilitates a granular view into the behavior of individual users or groups of users. The Users page can be used to:

* Count users based on behavior.
* Explore their unique history.
* Update user profiles.
* Create cohorts of groups of users.

## Basic Features

You can select **User Profiles** or **All Users** in the Users page. If you select **User Profiles**, the page will only show users that have at least one user profile property set. If you select **All Users**, the page will show all users who have completed any event.

<Frame>
  <img alt="/Screen_Shot_2022-07-12_at_11.55.17_AM.png" />
</Frame>

By clicking the name of a user in the User tables, you can explore that user's unique history by examining their user profile. Learn more about the Users Profiles [here](/docs/data-structure/user-profiles).

### Cohorts

A cohort is a group of users who share a certain set of properties or have performed a particular combination or frequency of events. You can create a cohort on the Users page by generating filtering criteria. Once a cohort is created, you can save it and use it to group and filter data in other Mixpanel reports.

Learn more about Cohorts [here](/docs/users/cohorts).

<Frame>
  <iframe />
</Frame>

### Modifying Table Columns

You may wish to change what data is displayed in the Users table. You can do so by clicking on **Edit Columns** and selecting / deselecting the profile properties you wish to display on the User table

<Frame>
  <img alt="/Screen_Shot_2022-07-12_at_2.22.57_PM.png" />
</Frame>

## FAQ

### How do I create a Cohort out of a list of user IDs?

To create a Cohort from a list of user IDs that cannot be easily identified by a specific behavior or user property, use a CSV import to bulk update user profiles with a new user property. Then, use that property to isolate and define the Cohort.

Follow [this guide](/docs/users/cohorts#creating-a-cohort-via-a-csv) to create a Cohort using a CSV file.

### How do I download User Profiles in Mixpanel?

To download your user profiles from the Users page, simply click the **Export icon.** This will download all the profile data being displayed in the current report - to download more properties, edit your columns to select more properties. You can choose to filter the list or select individual profiles to download instead of downloading the full list.

<Frame>
  <img alt="/Screen_Shot_2022-07-12_at_2.26.45_PM.png" />
</Frame>


# Cohorts
Source: https://docs.mixpanel.com/docs/users/cohorts

Group users by demographic and behavior

Cohorts are groups of users that share a certain set of properties or who perform a similar sequence of events. Mixpanel lets you visually define cohorts, view the list of users that comprise them, compare them in your analysis, and share them with the rest of your company.

Here are some examples of cohorts you can create in Mixpanel:

* US Users: Users who are from the US
* New Users: Users who signed up in the past month
* Power Users: Users who used your app on 5 out of the last 7 days
* Dropped-Off Users: Users who signed up, but did not come back the following week

## Creating Cohorts

You can create cohorts via any of our report visualizations or explicitly using the cohort builder.

### Creating a Cohort via a Report

Click any bar or point in an Insights, Funnels, or Retention report and select "View Users". The side panel will show the list of users that belong to that bar or point you selected. You can save that group of users as a cohort.

### Creating a Cohort via the Cohort Builder

The [Cohort Builder](https://mixpanel.com/report/users) lets you define cohorts based on a precise set of conditions. These conditions are either of the form "Users who did `<event>` more/less than `<some threshold>`" or "Users where `<profile property>` is equal to/more/less than `<value>`". You can save these conditions as the definition for your Cohort.

Below are a few examples:

**Filter by users who watched more than 10 videos in the last 7 days**

<Frame>
  <img alt="/cohort_example_1.gif" />
</Frame>

**Filter to only users who watched a video for the very first time in the past 30 days**

<Frame>
  <img alt="/cohort_example_2.gif" />
</Frame>

**Chaining cohorts together using the AND/OR operators**

<Frame>
  <img alt="/cohort_example_3.gif" />
</Frame>

You can also access the builder directly from the query builder in any of our reports, by clicking Create Custom > Cohort. This will create a temporary cohort that only persists for your analysis session.

#### Note on cohorts whose filters contain user properties

Because user profile properties only store the most recent value, cohorts involving user profile properties will use the current value for those properties (even if the value changed over time).

For example, suppose the cohort’s filter criteria is: users where user\[“City”] == “SF” and “Did Event: Order Ride 3 times in Last 7 days”.

Mixpanel computes the above over the last 30 days and then groups the set of users who have property user\[“City”] == “SF” as of right now and intersect that with the daily cohort of users who did Order Ride 3 times in the last 7 days.

### Creating a Cohort via Lexicon

Cohorts can also be created and managed in [Lexicon](/docs/data-governance/lexicon). In Lexicon, you can see all your saved cohorts alongside your other saved definitions like metrics, custom events, and custom properties.

### Creating a Cohort with Changing User Properties

With historical user or group properties, you can optionally Add Time and Measurement to specify the time-range over which to search for the property value

<Frame>
  <img alt="image" />
</Frame>

This brings up time selector options.

<Frame>
  <img alt="image" />
</Frame>

To go back to the default of using the latest value of the historical property, you can Remove Time and Measurement.

<Frame>
  <img alt="image" />
</Frame>

### Creating a Cohort via a CSV

You can create a Cohort by uploading a CSV. This method is useful when grouping Mixpanel users who cannot be easily identified through specific behaviors or user properties. (e.g. when you have a list of distinct\_ids to include in a Cohort and they were randomly selected)

We will [use the CSV to update users in bulk](/docs/data-structure/user-profiles#bulk-import-from-csv) by adding a user property that indicates their Cohort membership. Afterward, we will use this property to define the Cohort.

For example, if you have a list of 1,000 distinct\_id values to group into a Cohort, create a CSV file with two columns: one containing the distinct\_id values and another containing a user property value that identifies cohort membership (e.g. `inCohort == "yes"`). Exclude column headers from the CSV, as you will define them during the upload process in the CSV upload wizard within the UI.

<Frame>
  <img alt="cohort_csv1.png" />
</Frame>

After you create the CSV, go to the **Users** tab, click **Add/Edit Profile**, select **Import from CSV**, and upload your file.

<Frame>
  <img alt="cohort_csv2.png" />
</Frame>

Next, define the property names for each column in the CSV uploaded. Assign "\$distinct\_id" as the property name for the column containing the distinct\_id values, and choose a property name for the column containing the user property value. Once you verify that the column assignment is correct, click **Import Profiles**.

<Frame>
  <img alt="cohort_csv3.png" />
</Frame>

<Warning>
  If your CSV includes a `$distinct_id` value that does not match an existing user in your project, the system will create a new user with that distinct\_id.
</Warning>

Finally, use the newly uploaded user property to define your Cohort.

<Frame>
  <img alt="cohort_csv4.png" />
</Frame>

Note that Cohorts created using this method are static; they will not update over time, as the associated user property remains unchanged.

## Using Cohorts in Analysis

You can visualize how cohorts size over time, use cohorts to filter your reports, or compare how cohorts perform a metric.

### Visualizing Cohort Size Over Time

In Insights, you can define a metric based on the size of a cohort over time. This is useful to understand how key subsets of your user base (like your Power Users) are trending over time. Select a cohort from the "Events and Cohorts" menu in the Insights report; this will generate a line chart that shows the size of the cohort over time. Each point is the size of the cohort as of the end of that time interval.

### Filtering by a Cohort

You can use cohorts to filter any of your analysis by selecting a cohort from the filter menu. For example, if you're focused on Onboarding, you can filter all your analyses to the New Users cohort, which might be defined as users who signed up in the past 7 days.

### Comparing Cohorts

You can compare the behavior of different cohorts by selecting a cohort from the breakdown menu. For example, you can use this to see how engagement compares for Power Users vs All Users.

When breaking down metrics by multiple cohorts, events are evaluated independently against each cohort. Consider an insights report that counts all events broken down by 3 cohorts, 'Power Users in North America', 'Power Users in Europe', and 'All Power Users'. An event belonging to a power user in North America, would contribute to the sum for buckets, `In 'Power Users in North America'`, `In 'All Power Users'`, and `Not In 'Power Users in Europe'`.

## How Cohorts are Computed

<Note>
  **Note:** To ensure timely results from queries, newly imported or changed historical events timestamped more than 30 days ago might be part of your existing cohort analysis only after 12 hours from their import/change.
</Note>

Cohorts are computed dynamically at the time that you use them in a query. Suppose you make a funnels report that filters down to the New Users cohort. Under the hood, Mixpanel does the following:

1. Run a query to compute the set of users who are in the cohort as of right now (the time that the query is run).
2. Run a query to compute the set of users who converted in the funnel, filtering down to the list produced in Step 1.

This has a few implications. First, it means every time you run a query that uses the cohort, the cohort is freshly computed vs being a static snapshot of users. Second, it means that the set of users who are in the cohort are users that are in the cohort as of *right now*; it's *not* a rolling window of users that have ever been in the cohort.

### Cohorts and Time

A common question that customers want to answer is how certain user behavior impact downstream behavior. Should you use cohorts or funnels to answer the question of how many users watch a comedy video and then subscribe? Cohorts and filters will give you different answers.

For example, consider this report: [https://mixpanel.com/s/4AuMRi](https://mixpanel.com/s/4AuMRi)

For the cohort on Jan 1, I'm looking at the users who watched a comedy video in the last 30 days before Dec 25 and who then subscribed over the same period of time. However, for the funnel on Dec 25, I'm looking at the users who watched a comedy video on Dec 25, and who have then also subscribed anytime within the next 30 day period from Dec 25. This means that if a user subsequently subscribes on Jan 3, the funnel chart can change to take that conversion into account. In this case, if you care about the conversion window, i.e. the amount of time that a user has in order to count as a conversion, using funnels would give you a more accurate answer.

## Manage Your Cohorts

You can view and manage all cohorts created by you or your teammates within your project by navigating to [**Lexicon**](/docs/data-governance/lexicon) and selecting **Cohorts** from the left-hand sidebar.

### Saving and Sharing Cohorts

<Note>
  Growth and Enterprise plan users can save an unlimited number of cohorts. Free plan users can create cohorts but cannot save them. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

You can manage Cohort sharing permissions by navigating to **Lexicon > Cohorts**, clicking the “…” button next to the desired Cohort, and selecting **"Share"** to open the sharing and permissions modal.

By default, Cohorts you create are visible only to you. You can choose to share Cohorts with specific individuals or with your entire organization, making them discoverable to others.

We recommend sharing a core set of cohorts across your organization to ensure alignment on key definitions of user behavior that are important to your business (for example, New Users or Power Users). We also recommend adding clear descriptions to these cohorts to provide context and promote shared understanding across your team.

### Exporting Cohorts

You can download the list of users in any Cohort as a CSV via the Cohort Builder. You can also push Cohorts to native 3rd-party destinations like Segment or Braze using [Cohort Sync](/docs/cohort-sync), or to any other destinations using [Custom Webhooks](/docs/cohort-sync/webhooks).

### Verifying Cohorts

<Note>
  Customers on an Enterprise plan can access the Verified Data feature. See our [pricing page](https://mixpanel.com/pricing/) for more details.
</Note>

Cohorts can be verified to signal that they are trustworthy and ready for broad use across your team — for example, a shared definition of "Power Users" that your whole org can rely on. This makes it easier for teammates to discover the right cohort for their analysis and avoid duplicating definitions that already exist.

**How it Works**

1. Navigate to **Lexicon > Cohorts**.
2. Select up to 100 cohorts using the checkboxes, then click **Verify**. You can also verify a single cohort from the **"..."** overflow menu, or by clicking the verified icon in the edit modal.
3. Verified cohorts display a badge in the Cohorts table (showing who verified it and when) and appear under a **Verified** section in query builders. You can also filter the Cohorts table by verification status.

To verify a cohort, you need verification permissions and edit access to that cohort. To un-verify, follow the same steps on an already-verified cohort.

### Deleting Unused Cohorts

You can delete any Cohorts from your project by navigating to **Lexicon > Cohorts**, clicking the “…” button next to the Cohort you wish to delete, and click **"Delete"**.

## FAQ

### How can I create cohorts based on dropped-off or retained users?

There are two ways to create such cohorts.

The first way would be to create a Funnels report and click the respective segments in order to find the retained/dropped-off users. You can then click “View Users”, followed by “Create Cohort”. Here is a Funnels report to play with: [https://mixpanel.com/s/8JY6o](https://mixpanel.com/s/8JY6o)

The second way would be to use the Users page to create cohorts. For example, if you would like to find users who “watch video” and *then* “like video”. You can create the cohort in the Users page. Here is the cohort for reference: [https://mixpanel.com/project/3187764/view/3699044/app/users#T9bjQw9kLb7c](https://mixpanel.com/project/3187764/view/3699044/app/users#T9bjQw9kLb7c)

If you would like to find those who have dropped off, you could switch “did” to “did not do”. Here is the cohort for reference: [https://mixpanel.com/project/3187764/view/3699044/app/users#Umm8E4JZxLSe](https://mixpanel.com/project/3187764/view/3699044/app/users#Umm8E4JZxLSe)

### I created two cohorts, Cohort AA: for users watched videos the last 30 days, and Cohort B: for users who liked videos in the last 30 days. I want to find out the users who did not watch videos AND did not like videos in the last 30 days. How do I create such a cohort?

You can do so by using the “AND” operator. Here is a cohort for reference: [https://mixpanel.com/project/3187764/view/3699044/app/users#Tc76sqFRzbao](https://mixpanel.com/project/3187764/view/3699044/app/users#Tc76sqFRzbao)

If you were to select multiple cohorts in the filter ([example](https://mixpanel.com/project/3187764/view/3699044/app/users#wPx5FmFoiHtD)), we will filter by cohort A OR cohort B. Therefore, it is still possible for the following cases to occur:

* User is not in Cohort A (fulfils the criteria), but is in Cohort B
* User is not in Cohort B (fulfils the criteria), but is in Cohort A

### How do I create a cohort based on users who did the same event in different time intervals?

If you want to filter for users that have done an event on X time units within a given timeframe, you can filter for the event, change 'Total Events' to 'Aggregate Property --> Distinct Count', then select the property 'Time' and the time unit you wish to filter for. You can then indicate the number of time units and the time frame as needed. This will show you e.g. the number of users who did an event on 5 different days within the last 2 months.


# What is Mixpanel?
Source: https://docs.mixpanel.com/docs/what-is-mixpanel



Mixpanel will help you better understand your customers and answer questions about your product. It enables you to track how users engage with your product and analyze this data with interactive reports that let you query and visualize the results with just a few clicks.

Mixpanel is built on three key concepts: [**Events**](#events), [**Users**](#users), and [**Properties**](#properties).

<Frame>
  <iframe />
</Frame>

## Concepts

Before you get started, you should know three Mixpanel concepts:

* **Events** are actions that happen in your product
* **Users** are the people who use your product
* **Properties** are the attributes of your users and events

### Events

An event is a data point that represents an interaction between a user and your product. Events can be a wide range of interactions.

Imagine you run a cafe where customers can purchase a coffee via an app. Each purchase is an event that can be tracked in Mixpanel.

<Frame>
  <img alt="image" />
</Frame>

### Users

On the other side of an event is a user — the specific individual who completed an interaction with your product.

Each user has a unique identifier that you can use to track their activity. This identifier can be an email address, a username, or a unique ID. Mixpanel uses a unique ID to identify users.

<Frame>
  <img alt="image" />
</Frame>

### Properties

You can track additional information about **users** and **events**. These details are called **properties**.

An **Event Property** describes an event. For a coffee purchase, the event would be *Purchased Item* and the event properties could be *type* (in this case a Coffee) and *price* (in this case \$2.50).

<Frame>
  <img alt="image" />
</Frame>

A **User Property** describes a User. This could be their name, email, age, etc.

<Frame>
  <img alt="image" />
</Frame>

Properties allow you to create groups of users (aka [cohorts](/docs/users/cohorts)) and also enable you to filter for certain events or users. These powerful features make it easy to identify trends and new customer insights.

## Next Steps

Now that you understand the basics, **we recommend planning the first events you would like to track**. This will help you understand what you need to get started. Choosing these events should take no more than 5 minutes.

#### Already Know What You Want to Track?

If you already know the events you want to track, you can skip planning and start by installing Mixpanel.


# What to Track
Source: https://docs.mixpanel.com/docs/what-to-track



In this guide, we provide guidance on what to track and how to track it.

## Start With 2 Events

We recommend starting with just 2 events, which can provide a lot of value with little effort:

* **Sign Up** - Tracking Sign Up is a quick way to understand your product's growth; by counting the number of Sign Ups, you can answer "How many new users am I acquiring every day, week, and month?".
* **Value Moment** - Tracking a value moment can help you assess how well your product is doing. You can answer questions like "How many users experience value in my product each day/week/month?" or "How many users come back (retain) and experience the moment again?".

### Choose a Value Moment

Value moments are often the use of important features or taking a critical action. Here are some examples:

* **Social**: Post Created, Friend Added
* **E-Commerce**: Purchase Completed, Review Submitted
* **Media**: Video Watched, Article Read
* **SaaS**: Document Created, Call Started

We recommend keeping your event names short and descriptive. We like to use the Object-Action convention, as you can see in the examples above.

### Include Properties

Properties add context to the event. We recommend these properties for your two events:

**Sign Up**

* **Source** (e.g Referral, Organic, Paid)
* **Country** (e.g. United States, Vietnam, Germany)
* **OS** (e.g. Windows, iOS, Android)

**Value Moment**

* Up to you! This will depend greatly on your value moment:

  * A "Video Watched" event may benefit from a "Duration" property
  * A "Message Liked" event may benefit from a "Message Type" property
* Ask yourself: What is the most important information related to your value moment?

## We Recommend Server-Side Tracking

Adblockers and browsers are making it harder and harder to track users on the client-side. If you want to make sure the data you're collecting is accurate, you'll want to do most of your tracking server-side.

**Frontend event tracking (especially on the web) loses between 15% and 30% of events**. If you're only tracking on the client-side, you're missing out on a lot of data, even if you're using a reverse proxy.

Want to learn more? [Read our full guide](/docs/tracking-methods/choosing-the-right-method/) on choosing the right method for tracking.

<hr />

<div>
  <div>
    <h2>Next Steps</h2>

    <p>
      Once you've chosen a few events to track first, you're ready to set up
      Mixpanel.
    </p>

    <br />

    <ExtendedButton title="Start Quickstart Guide" />
  </div>
</div>


# Benchmarks & Analytics Maturity
Source: https://docs.mixpanel.com/guides/benchmarks



Understand performance benchmarks and assess your organization’s analytics maturity. Whether you’re setting goals, comparing performance against peers, or looking for ways to advance your analytics practice, these resources will help guide your next steps.

## Benchmarks

See performance baselines across conversion, retention, and engagement. Use these as north stars to calibrate goals and identify outliers.

<CardGroup>
  <Card title="Digital Analytics Benchmarks" href="https://mixpanel.com/content/benchmarks-2026?utm_source=guides&utm_medium=website&utm_campaign=2026-state-of-digital-analytics&utm_content=2026-State-of-Digital-Analytics" />
</CardGroup>

## Benchmarks by Industry

Drill into industry-specific norms to set context-rich targets.

<CardGroup>
  <Card title="AI" href="https://mixpanel.com/content/benchmarks-2026?utm_source=guides&utm_medium=website&utm_campaign=2026-state-of-digital-analytics-ai&utm_content=2026-State-of-Digital-Analytics#ai" />

  <Card title="B2B" href="https://mixpanel.com/content/benchmarks-2026?utm_source=guides&utm_medium=website&utm_campaign=2026-state-of-digital-analytics-b2b&utm_content=2026-State-of-Digital-Analytics#b2b" />

  <Card title="Ecommerce" href="https://mixpanel.com/content/benchmarks-2026?utm_source=guides&utm_medium=website&utm_campaign=2026-state-of-digital-analytics-ecom&utm_content=2026-State-of-Digital-Analytics#ecom" />
</CardGroup>

<CardGroup>
  <Card title="Fintech" href="https://mixpanel.com/content/benchmarks-2026?utm_source=guides&utm_medium=website&utm_campaign=2026-state-of-digital-analytics-fintech&utm_content=2026-State-of-Digital-Analytics#fintech" />

  <Card title="Payments" href="https://mixpanel.com/content/benchmarks-2026?utm_source=guides&utm_medium=website&utm_campaign=2026-state-of-digital-analytics-payments&utm_content=2026-State-of-Digital-Analytics#payments" />

  <Card title="Media & Entertainment" href="https://mixpanel.com/content/benchmarks-2026?utm_source=guides&utm_medium=website&utm_campaign=2026-state-of-digital-analytics-media&utm_content=2026-State-of-Digital-Analytics#media" />
</CardGroup>

<CardGroup>
  <Card title="Mobile Gaming" href="https://mixpanel.com/content/benchmarks-2026?utm_source=guides&utm_medium=website&utm_campaign=2026-state-of-digital-analytics-mobile-gaming&utm_content=2026-State-of-Digital-Analytics#mobile-gaming" />

  <Card title="iGaming" href="https://mixpanel.com/content/benchmarks-2026?utm_source=guides&utm_medium=website&utm_campaign=2026-state-of-digital-analytics-igaming&utm_content=2026-State-of-Digital-Analytics#igaming" />
</CardGroup>

## Analytics Maturity

Assess where your org sits on the analytics maturity curve and chart the next moves to unlock impact.

<CardGroup>
  <Card title="Analytics Maturity" href="https://mixpanel.com/content/product-analytics-strategy/get-started/" />
</CardGroup>


# Board Templates
Source: https://docs.mixpanel.com/guides/board-templates



Explore curated Board templates designed to solve common product questions. Click any card below to launch a live, interactive demo in a new tab.

<div>
  <a href="https://mixpanel.com/project/?show-template-selector=true">
    Ready to build? Create a Board
    <span>→</span>
  </a>
</div>

<div>
  Templates are pre-built dashboards designed around a specific use case or industry.
  Instead of starting from a blank canvas, you start with a proven framework
  built on industry best practices that you can adapt to your needs.
</div>

### Essential Boards

Foundational views to monitor product health, user retention, and core growth metrics at a glance.

<BoardTemplates />

### Industry-Specific Boards

Custom-built frameworks optimized for E-commerce, SaaS, and Finance workflows.

<BoardTemplates />

<hr />

### Board Template FAQs

<AccordionGroup>
  <Accordion title="How do I use these templates in my own project?">
    The tiles above are **interactive previews** designed for exploration. To use a template with your own data, navigate to your Mixpanel project and choose one of two paths:

    * **The Template Selector:** Click the [Ready to build? Create a Board →](https://mixpanel.com/project/?show-template-selector=true) button to launch the configuration wizard.
    * **From a New Board:** Create a new Board (via **+ Create New** > **Board**) and select a framework from the **Start from a Template** section.
  </Accordion>

  <Accordion title="Can I customize a template after it's created?">
    Yes. Think of a template as a starting point, not a fixed structure. You can add reports, change conversion window settings, or adjust event properties to match your specific tracking schema.
  </Accordion>

  <Accordion title="Are templates free to use?">
    Yes. Every template is available to all Mixpanel users, including those on the Free plan.
  </Accordion>
</AccordionGroup>


# Mixpanel Glossary
Source: https://docs.mixpanel.com/guides/glossary



Use this glossary to get familiar with the concepts that power Mixpanel—from data tracking and privacy to growth metrics and product strategy.

Browse by category, or jump directly to the [A-Z list](#a-z-glossary).

***

## Browse by Category

<Accordion title="Expand to view categories">
  <AccordionGroup>
    <Accordion title="Analysis & Visualization Terms">
      * [Annotation](#annotation)
      * [Board](#board)
      * [Formula](#formula)
    </Accordion>

    <Accordion title="Business Models & Key Metrics">
      * [Business to Business (B2B)](#business-to-business-b2b)
      * [Business to Consumer (B2C)](#business-to-consumer-b2c)
      * [Daily Active Users (DAU)](#daily-active-users-dau)
      * [Weekly Active Users (WAU)](#weekly-active-users-wau)
      * [Monthly Active Users (MAU)](#monthly-active-users-mau)
      * [Month-over-Month (MOM)](#month-over-month-mom)
      * [Quarter-over-Quarter (QoQ)](#quarter-over-quarter-qoq)
      * [Year-over-Year (YoY)](#year-over-year-yoy)
      * [Net Promoter Score (NPS)](#net-promoter-score-nps)
      * [Marketing Qualified Lead (MQL)](#marketing-qualified-lead-mql)
      * [Sales Qualified Lead (SQL)](#sales-qualified-lead-sql)
      * [Stickiness](#stickiness)
    </Accordion>

    <Accordion title="Compliance & Privacy Terms">
      * [General Data Protection Regulation (GDPR)](#general-data-protection-regulation-gdpr)
      * [Health Insurance Portability and Accountability Act (HIPAA)](#health-insurance-portability-and-accountability-act-hipaa)
      * [Business Associate Agreement (BAA)](#business-associate-agreement-baa)
      * [Personally Identifying Information (PII)](#personally-identifying-information-pii)
      * [Protected Health Information (PHI)](#protected-health-information-phi)
    </Accordion>

    <Accordion title="Data & Technical Terms">
      * [Autocapture](#autocapture)
      * [Identity Management](#identity-management)
      * [Ingestion](#ingestion)
      * [Software Development Kit (SDK)](#software-development-kit-sdk)
      * [First-party Cookies](#first-party-cookies)
      * [Third-party Cookies](#third-party-cookies)
    </Accordion>

    <Accordion title="Data Management Terms">
      * [Data Lake](#data-lake)
      * [Data Warehouse](#data-warehouse)
      * [Groups](#groups)
      * [Session](#session)
    </Accordion>

    <Accordion title="Product Development Terms">
      * [Feature Flag](#feature-flag)
      * [Minimum Viable Product (MVP)](#minimum-viable-product-mvp)
      * [Multivariate Test](#multivariate-test)
    </Accordion>

    <Accordion title="Product & User Lifecycle Terms">
      * [Active User](#active-user)
      * [New User](#new-user)
      * [Dormant User](#dormant-user)
      * [Bounce Rate](#bounce-rate)
    </Accordion>
  </AccordionGroup>
</Accordion>

***

## A-Z Glossary

### Active User

A user who interacts with your product within a defined period, [measured via event-based tracking](/docs/data-structure/events-and-properties) as Daily Active Users (DAU), Weekly Active Users (WAU), or Monthly Active Users (MAU).

### Annotation

Contextual notes added to reports to [mark key events](/docs/features/annotations)—such as releases, campaigns, or anomalies—directly on the timeline.

### Autocapture

A low-code feature that [automatically collects](/docs/tracking-methods/autocapture) standard user interactions—such as page views, clicks, form submissions, and scrolls—without the need for manual instrumentation.

### Business Associate Agreement (BAA)

A legal contract that [defines how vendors handle Protected Health Information (PHI)](https://mixpanel.com/legal/mixpanel-hipaa/) in compliance with HIPAA regulations.

### Business to Business (B2B)

A commercial model where products or services are sold to other companies rather than individual consumers.

### Business to Consumer (B2C)

A commercial model where products or services are sold directly to individual consumers rather than companies.

### Board

A collaborative workspace that [centralizes saved reports and metrics](/docs/boards) into a single view for real-time monitoring.

### Bounce Rate

A metric tracking the percentage of [sessions with only a single page view](/docs/features/sessions#what-are-the-average-number-of-pages-visited-per-session), often used to indicate low engagement or friction in the onboarding experience.

### Daily Active Users (DAU)

A metric tracking the number of distinct users who engage with your product in a single day, used to [measure daily engagement and growth](https://mixpanel.com/blog/daily-active-users/).

### Data Lake

A centralized repository that stores raw, unstructured data at scale, offering flexibility but requiring transformation before it can be utilized for analysis.

### Data Warehouse

A system optimized for storing structured data, which can be [ingested directly into Mixpanel](/docs/tracking-methods/warehouse-connectors) for fast analysis and reporting.

### Dormant User

A user who engaged in a previous period but has not performed a key action in the current one, often [identified via cohort analysis](https://mixpanel.com/blog/cohort-analysis/) as targets for reactivation campaigns.

### Feature Flag

A configuration tool that [toggles feature availability](/docs/featureflags) for specific segments, enabling targeted rollouts and A/B testing without code deployment.

### First-party Cookies

A data file stored directly by the website the user is visiting, essential for maintaining persistent user identity and session continuity without relying on external trackers.

### Formula

A custom expression that [modifies or combines data series](/docs/reports/insights#formulas)—such as dividing total revenue by user count—to calculate derived metrics and ratios.

### General Data Protection Regulation (GDPR)

A comprehensive European Union regulation governing personal data privacy, supported in Mixpanel via [dedicated compliance tools](https://mixpanel.com/legal/mixpanel-gdpr/) for processing and deletion.

### Groups

A data structure that [aggregates user activity by entity](/docs/data-structure/group-analytics)—such as companies, teams, or devices—to analyze performance at the group level rather than the individual user level.

### Health Insurance Portability and Accountability Act (HIPAA)

A United States federal law mandating the security and privacy of Protected Health Information (PHI), accommodated via [HIPAA-compliant plans](https://mixpanel.com/legal/mixpanel-hipaa/) for customers handling medical data.

### Identity Management

The process of associating events with specific users by [resolving unique identifiers](/docs/tracking-methods/id-management), typically using the `identify()` method to merge anonymous activity into a unified profile across devices.

### Ingestion

The transmission of event data into the analytics platform, accepted via [client-side SDKs](/docs/tracking-methods/sdks), the [Ingestion API](/reference/ingestion-api), or [partner integrations](/docs/tracking-methods/integrations).

### Marketing Qualified Lead (MQL)

A prospect who has demonstrated sufficient engagement or fit to be [handed off to sales](https://mixpanel.com/blog/marketing-qualified-leads/) for further qualification.

### Minimum Viable Product (MVP)

The most basic version of a product released to validate core assumptions and test concepts with real users before full-scale development.

### Monthly Active Users (MAU)

A metric tracking the number of distinct users who engage with a product within a 30-day window, used to [assess long-term growth trends](https://mixpanel.com/blog/mau/).

### Month-over-Month (MoM)

A comparative metric that measures the percentage change in performance between the current month and the previous one to identify growth momentum or seasonality.

### Multivariate Test

An experimentation method that [evaluates multiple variable combinations simultaneously](/docs/experiments)—rather than just two versions—to determine how different elements interact to influence user behavior.

### Net Promoter Score (NPS)

A standard loyalty metric that gauges customer satisfaction by asking users to rate their likelihood of recommending the product on a typical scale of 0 to 10.

### New User

A user who is recorded for the first time within a specific time window—such as a signup week or first session—tracked to measure acquisition success and onboarding efficacy.

### Protected Health Information (PHI)

Health-related data linked to a specific individual, which is [protected under HIPAA](https://mixpanel.com/legal/mixpanel-hipaa/) and requires a Business Associate Agreement (BAA) for processing by vendors.

### Personally Identifying Information (PII)

Any data that can directly or indirectly distinguish a specific individual—such as names, emails, or IPs—often requiring [specific privacy configurations](/docs/privacy/protecting-user-data) to ensure data security.

### Quarter-over-Quarter (QoQ)

A comparative metric that measures the percentage change in performance between one fiscal quarter and the previous one to gauge short-term business momentum.

### Sales Qualified Lead (SQL)

A prospect who has been vetted by the sales team as ready for direct engagement, typically having graduated from the Marketing Qualified Lead (MQL) stage based on strong intent or fit.

### Session

A set of continuous user interactions, [grouped into a single visit](/docs/features/sessions) based on a time-out window or specific start and end events.

### Software Development Kit (SDK)

A package of code libraries that simplifies the process of [sending event data](/docs/tracking-methods/sdks) from client-side or server-side applications to the analytics platform.

### Stickiness

A measurement of engagement frequency that [calculates how often users return](/docs/reports/retention) to perform key actions within a specific interval, used to assess habit formation and product utility.

### Third-party Cookies

Data files set by external domains for advertising or cross-site tracking, which are [distinct from the first-party approach](https://mixpanel.com/blog/cookies-consent-and-the-gdpr-the-role-of-privacy-in-a-product-analytics-strategy/) prioritized by modern analytics to ensure privacy and reliability.

### Weekly Active Users (WAU)

A metric tracking the number of distinct users who engage with a product within a seven-day window, often monitored to [measure weekly engagement habits](https://mixpanel.com/blog/mau/).

### Year-over-Year (YoY)

A comparative metric that measures performance against the same period in the previous year to identify long-term trends while controlling for seasonality.


# Mixpanel and the Continuous Innovation Loop
Source: https://docs.mixpanel.com/guides/guides-by-topic/continuous-innovation



The **Observe → Analyze → Decide → Act (OADA)** loop is the framework behind how great teams use Mixpanel to continuously innovate.

<Frame>
  <img alt="OADA Loop diagram" />
</Frame>

This loop represents the cycle teams follow to turn data into action by first observing what users do, then analyzing why it happens, deciding what to do next, and finally acting on those insights to drive better outcomes.

Each phase represents a key moment in the product decision cycle–—and Mixpanel provides the tools to complete that loop faster with every iteration.

<Note>
  **Why it matters:** Teams that move through the loop quickly learn what’s working, align faster, and deliver more impactful product improvements.
</Note>

***

## Why Continuous Innovation Matters

Building great products isn’t just about speed—–it’s about learning continuously.

Markets shift, user expectations evolve, and what worked last quarter might not work tomorrow. The teams that win are the ones that turn data into a *habit of improvement* by observing what users do, analyzing why it happens, deciding what to do next, and acting with confidence.

Teams that move through the OADA loop quickly:

* Learn what’s working and what’s not
* Align on priorities faster
* Deliver more impactful product improvements with each iteration

<Note>
  **Pro tip**: Make closing the loop part of every sprint–—observe, analyze, decide, act.
</Note>

Digital innovation isn’t a one-time project. It’s a continuous cycle of learning and improvement.

***

## How Different Industries Use the Continuous Loop

Mixpanel powers the OADA loop across every industry--helping teams turn data into confident action.

Whether you’re optimizing user onboarding, increasing checkout conversions, or improving content engagement, the same continuous loop applies.

Below are examples of how teams in different industries use Mixpanel to measure, learn, and grow faster.

<AccordionGroup>
  <Accordion title="💼 SaaS: Improving Onboarding and Activation">
    A SaaS team observes where new users drop off during onboarding, analyzes key behaviors to uncover friction points, decides which improvements will reduce time-to-value, and acts by testing guided experiences that drive activation and retention.

    ***

    **Observe** <br /> The team monitors early-user activity using **Session Replay**, **Heatmaps**, and **Autocapture** to see how new users interact with the onboarding flow: *Account Created → Tutorial Completed → Key Action Taken*. They set up **Alerts** to track sudden drops in completion.

    ***

    **Analyze** <br /> Using **Funnels**, **Flows**, and **Cohorts**, the team identifies where users are stalling and compares completion across personas. Behavioral trends show that users who skip the advanced configuration step activate faster.

    | Tool                | Observation                                                     | Insight                                                        |
    | ------------------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
    | **Funnels & Flows** | 45% drop-off between “Account Created” and “Tutorial Completed” | Users struggle with early onboarding complexity.               |
    | **Cohorts**         | Different activation rates by persona                           | Simpler onboarding correlates with higher early success.       |
    | **Session Replay**  | Confusion at advanced setup screens                             | Users hesitate when asked to complete optional steps too soon. |

    ***

    **Decide** <br /> The team uses **Metric Trees** to understand which metrics--like “First Value Reached”--drive long-term retention. They decide to move optional setup later in the journey and emphasize the first “aha” moment sooner.

    ***

    **Act** <br /> They test this change through **Experiments**, rolling out a new guided flow to a subset of users. When the experiment shows faster activation and higher retention, they launch it to all users using **Feature Flags**.

    ***

    **✨ Result:** Activation improves 15%, and new users reach value faster with fewer drop-offs.
  </Accordion>

  <Accordion title="🛍️ eCommerce: Increasing Checkout Conversion">
    An eCommerce team observes shopper behavior throughout checkout, analyzes patterns to uncover mobile friction, decides which optimizations will improve conversion, and acts by testing streamlined checkout designs.

    ***

    **Observe** <br /> Using **Session Replay**, **Heatmaps**, and **Autocapture**, the team tracks the path from *Product Viewed → Added to Cart → Checkout Started → Purchase Completed* to see where users abandon the flow.

    ***

    **Analyze** <br /> Through **Funnels**, **Cohorts**, and **Retention**, the team identifies a 40% drop-off at payment on mobile devices.

    | Tool                          | Observation                               | Insight                                           |
    | ----------------------------- | ----------------------------------------- | ------------------------------------------------- |
    | **Funnels**                   | 40% mobile drop-off at payment            | Checkout fields are too dense for mobile screens. |
    | **Session Replay & Heatmaps** | Users zoom and misclick on payment fields | UI not optimized for mobile input.                |

    ***

    **Decide** <br /> The team leverages **Metric Trees** to link checkout completion to revenue impact. They decide to simplify payment forms and surface the most-used payment options first.

    ***

    **Act** <br /> They deploy a **Feature Flag** to release the redesigned checkout to 50% of traffic and use **Experiments** to confirm conversion improvements before rolling it out universally.

    ***

    **✨ Result:** Checkout completion rises 20%, and mobile shoppers complete purchases faster with fewer errors.
  </Accordion>

  <Accordion title="🎬 Media & Entertainment: Boosting Viewer Retention">
    A streaming platform observes viewer engagement across content, analyzes which experiences retain audiences, decides how to personalize recommendations, and acts by iterating on what drives continued watching.

    ***

    **Observe** <br /> The team uses **Session Replay**, **Autocapture**, and **Alerts** to track *Episode Started → Episode Completed → Next Episode Started* events, identifying drop-offs by series and genre.

    ***

    **Analyze** <br /> They turn to **Retention** and **Cohorts** to learn which viewers come back.  **Funnels & Flows** show most viewers stop after Episode 2, and qualitative data confirms weak recommendations at that point.

    | Tool                    | Observation                   | Insight                                       |
    | ----------------------- | ----------------------------- | --------------------------------------------- |
    | **Retention & Cohorts** | Only 30% return for Episode 3 | Low content continuity beyond early episodes. |
    | **Funnels & Flows**     | Drop-off after Episode 2      | Weak recommendations between episodes.        |

    ***

    **Decide** <br /> Using **Metric Trees**, the team connects “Episode Completion Rate” to “Viewer Retention.”  They decide to insert a personalized “Up Next” prompt and ratings flow to strengthen recommendations.

    ***

    **Act** <br /> They run an **Experiment** on the "Up Next" prompt. After positive results that indicate viewers who see the new recommendations have longer sessions and higher continuation rates, they expand rollout to all viewers using **Feature Flags**.

    ***

    **✨ Result:** Viewer retention improves 25%, with stronger engagement across new series launches.
  </Accordion>

  <Accordion title="💰 Fintech: Increasing Feature Adoption and Retention">
    A fintech product team observes user engagement with budgeting tools, analyzes setup friction, decides how to improve adoption, and acts by optimizing flows that drive retention.

    ***

    **Observe** <br /> They track customer actions with **Session Replay** and **Autocapture**, focusing on *Account Linked → Budget Created → Spending Reviewed → Budget Adjusted*. **Alerts** notify them of sudden drops in budget creation.

    ***

    **Analyze** <br /> Using **Funnels**, **Cohorts**, and **Retention**, they find that users linking smaller financial institutions often fail to complete setup.

    | Tool                  | Observation                                 | Insight                                     |
    | --------------------- | ------------------------------------------- | ------------------------------------------- |
    | **Funnels & Cohorts** | Users stop after linking a bank account     | Authentication errors block progress.       |
    | **Retention Reports** | Users who finish setup return 2× more often | Early success predicts long-term retention. |

    ***

    **Decide** <br /> The team uses **Metric Trees** to link budgeting feature adoption to retention KPIs. They decide to improve error handling and prompt users to set alerts immediately after creating a budget.

    ***

    **Act** <br /> They run an **Experiment** on a new “Set Alert” flow. After positive results, they expand rollout to all customers using **Feature Flags**.

    ***

    **✨ Result:** Budget feature adoption increases 30%, and retention rises 15% as users set up alerts sooner.
  </Accordion>

  <Accordion title="🎮 Gaming: Driving Player Engagement and In-App Purchases">
    A gaming studio observes player behavior across levels, analyzes progression data to uncover friction, decides what changes will improve engagement, and acts by launching prompts that drive completion and purchases.

    ***

    **Observe** <br /> The team uses **Session Replay**, **Heatmaps**, and **Autocapture** to track *Level Started → Level Completed → In-App Purchase Made*, identifying the points where players churn.

    ***

    **Analyze** <br /> They turn to **Funnels** and **Cohorts** on player feedback to understand why drop-offs occur.  Players who use “Power-Ups” progress faster, and replays show many ignore in-game hint icons.

    | Tool                          | Observation                        | Insight                                             |
    | ----------------------------- | ---------------------------------- | --------------------------------------------------- |
    | **Funnels & Cohorts**         | High player drop-off after Level 3 | Repeated failures at one level lead to early churn. |
    | **Session Replay & Heatmaps** | Players miss hint icons            | Poor visual placement of key gameplay aids.         |

    ***

    **Decide** <br /> Using **Metric Trees**, the team links early-level completions to retention and in-app purchases. They decide to introduce Power-Up tutorials earlier to help players progress.

    ***

    **Act** <br /> They run an **Experiment** on a new “Use Power-Up” tutorial and measure results. When they see improved completion and monetization metrics, they expand it to all players using **Feature Flags**.

    ***

    **✨ Result:** Level completion improves 35%, and in-app purchases increase 20%, driving sustained engagement.
  </Accordion>
</AccordionGroup>

No matter your industry, the OADA loop helps you turn insights into action-—and Mixpanel gives you the tools to complete that loop faster with every iteration.

***

## Learn More

Want to understand the strategy behind continuous innovation? Check out our blog on [How Digital Continuous Innovation Drives Sustainable Enterprise Growth](https://mixpanel.com/blog/digital-continuous-innovation/) to see how leading enterprises use the OADA framework to connect data, decisions, and action—–and build a culture of sustainable growth.


# Core Reports
Source: https://docs.mixpanel.com/guides/guides-by-topic/core-reports



The Fundamentals learning path teaches you about Mixpanel's core reports and how to use them. Whether you're new to Mixpanel or building on what you already know, you'll come away able to analyze user behavior with confidence.

The [learning path](https://university.mixpanel.com/student/path/3411736-mixpanel-fundamentals) is hosted on Mixpanel University. By the end, you'll be able to:

* Use Mixpanel's core reports: Insights, Funnels, Flows, and Retention
* Analyze user behavior
* Measure what matters for your product


# Features
Source: https://docs.mixpanel.com/guides/guides-by-topic/features



## AI

<CardGroup>
  <Card title="Use Mixpanel Agent" href="/guides/guides-by-use-case/empower-your-team/mixpanel-agent" />

  <Card title="Use Mixpanel MCP" href="/guides/guides-by-use-case/empower-your-team/mcp" />

  <Card title="Use Mixpanel Headless" href="/guides/guides-by-use-case/empower-your-team/headless" />

  <Card title="Write Business Context" href="/guides/guides-by-workflow/write-business-context" />
</CardGroup>

## Experiments and Feature Flags

<CardGroup>
  <Card title="Drive Product Innovation" href="/guides/guides-by-use-case/engage-your-users/drive-product-innovation" />

  <Card title="Ship Features" href="/guides/guides-by-use-case/engage-your-users/ship-features" />
</CardGroup>

## Metric Trees

<CardGroup>
  <Card title="Close Strategy-Execution Gap" href="/guides/guides-by-use-case/empower-your-team/close-strategy-execution-gap" />
</CardGroup>

## Revenue Analytics

<CardGroup>
  <Card title="Grow Revenue" href="/guides/guides-by-use-case/grow-your-usership/grow-revenue" />
</CardGroup>

## Session Replay

<CardGroup>
  <Card title="See Replays" href="/guides/guides-by-use-case/empower-your-team/see-replays" />
</CardGroup>


# Govern Your Mixpanel Data for Long-Term Success
Source: https://docs.mixpanel.com/guides/guides-by-topic/govern-data



Keep your Mixpanel data clean, trusted, and discoverable—no matter how your team changes. This Guide outlines the essential practices to prevent data drift, manage change, and keep reports accurate over time.

## Why Governance Matters

Strong governance delivers business value far beyond tidy data. When teams trust their metrics, they can make decisions faster, align more easily, and confidently scale their analytics without second-guessing results.

Governance increases the return on your data investments by ensuring that all analysis draws from a consistent, reliable foundation. The result is greater speed to insight and higher confidence in every product decision.

## What “Good” Governance Looks Like in Mixpanel

A trusted data environment features:

* A unified taxonomy for all events and properties.
* Clear ownership defining accountability for data quality.
* A structured QA workflow before new tracking goes live.
* Continuous data hygiene to prune obsolete events.
* Active documentation to keep teams aligned on definitions.

Good governance isn’t about rigid control—it’s about creating clarity and trust that scale with your team. The steps below walk through how to put these principles into practice, starting with defining ownership and standardizing your data language.

## Before You Begin: A Quick Tour of Lexicon

It’s helpful to know where most of the data governance features in this Guide live. Many of the steps you’ll take—like defining event names, managing visibility, and reviewing descriptions—happen directly in Mixpanel’s Lexicon.

Take a quick interactive tour below to see how to navigate Lexicon before you begin implementing governance best practices.

<Frame>
  <iframe title="Navattic walkthrough" />
</Frame>

> Note: The interactive demo above isn’t supported on smaller screens, but you can [click here](https://mixpanel.navattic.com/3sk0ug6) to open the experience in a new window.

With these basics in mind, you’ll be ready to apply governance best practices confidently.

## The Data Governance Framework

To make the workflow clear, this section introduces the core components of Mixpanel’s data governance framework and explains why each matters. These steps form a continuous cycle that keeps your data accurate, trusted, and useful over time.

The Mixpanel Data Governance Framework includes:

<Steps>
  <Step title="Establish and Document Data Governance Ownership.">
    Assign clear accountability for maintaining standards, reviewing new tracking, and ensuring data quality.
  </Step>

  <Step title="Standardize Your Taxonomy.">
    Define a shared vocabulary for events and properties to ensure teams interpret data consistently.
  </Step>

  <Step title="Manage Naming Changes Effectively.">
    Maintain continuity and understanding when renaming events and properties.
  </Step>

  <Step title="Maintain and Evolve Your Data Governance.">
    Create feedback loops and continuous improvement processes as your business grows.
  </Step>

  <Step title="Keep Training and Documentation Alive.">
    Maintain shared understanding through consistent documentation and training so governance practices stay effective as teams and data evolve.
  </Step>
</Steps>

Together, these components create a sustainable governance cycle that helps organizations evolve their analytics with confidence while minimizing data drift and confusion.

### Establish and Document Data Governance Ownership

Assign clear accountability for maintaining standards, reviewing new tracking, and ensuring data quality. These responsibilities are typically handled through ongoing processes.

**Steps to take**

* Designate a data governance owner or committee—often the analytics lead or data team—and at least one backup to ensure continuity when roles shift.
* Define who reviews new events and manages Lexicon ownership inside Mixpanel.
* Require sign-off for any schema or tracking changes before implementation.
* Maintain your governance workflow, meeting notes, and approval records in an internal wiki or shared doc.

<Note>
  **Pro tip**: If you already have a governance or tracking plan, update it to reflect current ownership and review processes. If you don’t, use the [Mixpanel Tracking Plan template](https://docs.google.com/spreadsheets/d/1ZdOZ6TMtRPxy7qRxiLsvH9HWcHJM6nZydWKoThRxFKc/edit?gid=1641519238#gid=1641519238) as a starting point to create one.
</Note>

**Governance Roles and Responsibilities** It can be helpful to clearly outline governance roles and responsibilities so teams understand who does what. Here’s a typical setup you can use as a reference or adapt to fit your organization:

| Role          | Responsibilities                              |
| ------------- | --------------------------------------------- |
| Data Owner    | Approves new events and ensures correctness.  |
| Analyst / PM  | Documents use cases and verifies metrics.     |
| Engineer      | Implements approved tracking.                 |
| Data Governor | Oversees Lexicon and enforces data standards. |

<Warning>
  **Pitfall:** Without a defined owner and clear process for how reviews happen, cleanup efforts stall and standards erode over time.
</Warning>

Once ownership is clear, the next step is to formalize your shared data language so that everyone in Mixpanel speaks the same analytical vocabulary.

### Standardize Your Taxonomy

Create a unified taxonomy that everyone in your organization can understand and use consistently. In Mixpanel, this shared vocabulary lives in Lexicon—your central reference for how events and properties are defined.

Teams typically begin by auditing what they already have, clarifying event names and ownership, and setting rules for how new tracking is proposed and approved.

Once your governance structure is in place, you can use Mixpanel’s built-in tools to make adherence automatic. This ensures that consistency doesn’t depend on individuals and new data entering your workspace meets your established standards before it’s visible to everyone.

With this foundation set, Lexicon becomes the trusted single source of truth for how data is used across teams.

**Steps to take**

* **Audit Data**: Audit all events and properties in [Lexicon](/docs/data-governance/lexicon). Add clear descriptions, categories, and owners for every event and property.
* **Select Naming Convention**: Choose one naming format—`snake_case` is recommended—and enforce it.
* **Enforce Data Standards**: Enable naming and description requirements in [Data Standards](/docs/data-governance/data-standards) to enforce your formatting and documentation rules.
* **Tag Events**: [Tag events](/docs/data-governance/lexicon#lexicon-event-details) by domain or team to make ownership and accountability clear.
* **Approve Events**: Turn on [Event Approval](/docs/data-governance/event-approval) to review unexpected tracking before it’s added to your Mixpanel project.
* **Hide Data**: [Hide](/docs/data-governance/lexicon#hiding-data) deprecated or unused events to prevent less-frequently used items from cluttering your events and properties menu, or from being considered in your reports.
* **Block Events**: To prevent an event from being ingested entirely, [block it](/docs/data-governance/lexicon#blocking-data) in Lexicon.

Prefer a guided walkthrough of these features? Check out our self-guided tours on how to [Govern & Maintain Data Quality](/guides/self-guided-tours#govern--maintain-data-quality).

👉 **Do this next**: Document your standards, and then schedule quarterly Lexicon reviews by data owners to keep definitions fresh and consistent.

Together, these steps help prevent data drift and ensure that your taxonomy remains consistent—leading to data that’s both trusted by and easy to navigate for all team members.

### Manage Naming Changes Effectively

When you change the raw name of an event or property (not just the display name), careful change management is essential to preserve data continuity and trust.

While updating a display name in Mixpanel doesn’t alter the raw event or property name, changing raw names impacts how data is collected and connected in reports, so coordination and communication are key.

**Steps to take**

When renaming raw events or properties:

* **Communicate and document the change** before implementation so that all impacted teams (analysts, PMs, engineers) are aware of what’s changing and why.
* **Use Mixpanel tools** like [Lexicon to merge events](/docs/data-governance/lexicon#merging-data) or [custom events to logically combine historical and new data](/docs/features/custom-events). The merge function in Lexicon can consolidate events or properties that represent the same underlying data, while custom events can group distinct raw events into a single analytical concept.
* **Update related dashboards and reports** to reference the new names, verifying that historical trends remain intact.
* **Record the update** in your governance log or internal documentation, including details on what was changed, the rationale, and which reports were reviewed.

<Warning>
  **Pitfall:** Changing event or property names without coordination leads to confusion, broken reports, and loss of trust in data.
</Warning>

A well-managed rename process—supported by documentation, communication, and Mixpanel’s tools—ensures data continuity and clarity as your taxonomy evolves.

### Maintain and Evolve Your Data Governance

Governance isn’t just about cleaning up—it’s about maintaining a strong feedback loop as your business and data evolve.

When a team launches a new feature or identifies a new use case to track, they should have a clear process for getting that data implemented in a way that aligns with your existing taxonomy and governance standards. This ensures consistency, prevents duplication, and keeps data relevant and trustworthy.

Cleanup is ongoing. Start where trust matters most, then expand gradually. This process is as much about building habits as it is about deleting old data—regular reviews help maintain confidence in your analytics and prevent noise from creeping back in.

**Steps to take**

* Begin with high-impact areas—your key metrics and dashboards.
* Use the [Mixpanel Monitoring Dashboard](https://mixpanel.com/project/3018488/view/3536632/app/boards/#id=6350211) to identify unused or duplicate events and see how your data is being used across the project. This dashboard gives you a clear view of event volume and identity trends, helping you pinpoint cleanup priorities and validate improvements over time.
* To review properties, use Lexicon to audit property usage, spot redundancy, and assess whether property definitions still align with your taxonomy.
* Review and clean one domain or product area at a time, ensuring each team validates their changes.
* Establish recurring cleanup checkpoints—quarterly or per release cycle—to keep data quality consistent and prevent drift.

These ongoing, focused reviews make cleanup part of your regular analytics rhythm rather than a disruptive, large-scale project. The result is a Mixpanel implementation that stays clean and trustworthy over time.

#### Property Maintenance

To support ongoing governance, regularly review both event and user properties as part of your data evolution workflows. Keeping properties organized ensures data remains accurate, relevant, and easier to analyze across teams.

**Steps to take**

* Periodically review [user profile properties](/docs/data-structure/user-profiles) and [event properties](/docs/data-structure/events-and-properties) in Mixpanel to identify fields that are outdated, redundant, or unused.
* Remove properties that are no longer relevant to your analysis, and keep active ones clearly defined. Ensure that commonly used properties—like plan type, device, or lifecycle stage—are standardized across your product and data sources.
* Document property standards in your governance wiki to make onboarding and troubleshooting easier.

<Warning>
  **Pitfall:** Letting properties accumulate unchecked leads to noisy data and makes analysis more difficult.
</Warning>

Routine property maintenance ensures your data stays clean, queries remain efficient, and every event and profile tells an accurate story of how people engage with your product.

### Keep Training and Documentation Alive

Sustainable governance relies on shared understanding. Governance processes, naming conventions, and tracking standards only work when everyone knows how and why to follow them.

Training and accessible documentation, using resources like the [Mixpanel Tracking Plan templates](/docs/tracking-best-practices/tracking-plan#translate-flows-into-events--properties), keep your entire organization aligned—especially as new people join and product tracking evolves.

**Steps to take**

* Document your standards and review process in a central wiki that all data contributors can access.
* Include governance and Lexicon usage in onboarding for new PMs, analysts, and engineers.
* Refresh training materials and documentation annually to reflect changes in your data model, team structure, or Mixpanel features.
* Link learning resources directly from your Mixpanel Boards for quick reference.

Well-documented and regularly reinforced governance practices ensure that data quality remains strong, institutional knowledge doesn’t fade, and every team member can confidently use Mixpanel to drive decisions.

## Common Governance Pitfalls

Even teams with strong data practices can run into issues that erode trust or slow decisions. Use the table below to self-diagnose common governance challenges and take quick action to fix them.

| Pitfall                      | Impact                                                                                           | Quick Fix                                                                                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unclear ownership            | Confusion over who approves or maintains tracking, leading to delays and inconsistent standards. | Establish clear governance roles and document responsibilities.                                                                                          |
| Inconsistent naming          | Harder to find and interpret data across teams.                                                  | Enforce naming standards using [Data Standards](/docs/data-governance/data-standards) and [Lexicon](/docs/data-governance/lexicon) descriptions.         |
| Lack of cleanup process      | Outdated or duplicate events clutter reports and reduce trust.                                   | Schedule periodic reviews and [hide](/docs/data-governance/lexicon#hiding-data) or [block](/docs/data-governance/lexicon#blocking-data) deprecated data. |
| No documentation or training | New team members repeat mistakes or create data drift.                                           | Centralize governance docs and include data standards in onboarding.                                                                                     |

## Key Takeaways

* Strong data governance creates trust, consistency, and clarity across your analytics so teams can make confident decisions as the business evolves.
* Establish clear ownership to ensure accountability for maintaining standards, reviewing new tracking, and managing data quality.
* Standardize your taxonomy so teams use a shared vocabulary for events and properties and interpret data consistently.
* Manage naming changes effectively by communicating updates and using Mixpanel tools to preserve continuity and historical context.
* Maintain and evolve governance processes through feedback loops and continuous improvement as your business grows.
* Keep training and documentation alive to ensure teams stay aligned on how data is defined, tracked, and used.

👉 **Next step**: Explore Mixpanel’s [Data Governance documentation](/docs/data-governance) to learn more about the tools and workflows that help you manage data quality, consistency, and trust across your workspace.

📖 **Want to go deeper on governance strategy?** If you're building or formalizing a data governance program—not just configuring Mixpanel, but aligning your organization around data quality—check out the [Data Governance for the Modern Enterprise](https://thesignalprod.wpenginepowered.com/wp-content/uploads/2025/10/Data-Governance-for-Modern-Enterprise.pdf) eBook. It covers how modern data teams establish ownership, define standards, and create accountability at scale.


# Set up Mixpanel AI for accurate answers
Source: https://docs.mixpanel.com/guides/guides-by-topic/trust-ai-answers



Any answer AI gives you is only as good as the data behind it. So how do you know you can trust what Mixpanel’s AI tells you? This guide walks through what actually shapes an accurate answer and the process to validate AI insights before you act on them.

Mixpanel's AI shows up in a few different ways — [Agent](/guides/guides-by-use-case/empower-your-team/mixpanel-agent), [MCP](/guides/guides-by-use-case/empower-your-team/mcp), and [Headless](/guides/guides-by-use-case/empower-your-team/headless) — ranging from a chat-style assistant inside the product to a connection an outside AI tool can query directly. This guide applies across all of them and assumes the reader is familiar with [Mixpanel reports](/docs/reports) and [event tracking concepts](/docs/what-is-mixpanel#concepts).

## What determines answer accuracy

Good data begets good answers. Two admin-controlled settings shape how accurate an AI response is, putting your team in the driver’s seat.

#### Business Context

Ask Mixpanel Agent how activation is trending, and it needs to know what activation means at your company before it can answer well. That's what [**Business Context**](/docs/business-context) is for. It covers things like:

* Company background
* Customer segments
* Key dashboards
* Team norms

Every Mixpanel AI tool reads your Business Context automatically, so filling it in helps every answer that follows.

<Info>
  If your organization has both org-level and project-level Business Context, Mixpanel AI will use both of them together. Should there be a conflict between the two, project context takes higher priority.
</Info>

#### Verified Mode

A team with five different event names for the same signup flow has a decision to make before letting AI loose on it: which one actually matters. [**Verified Mode**](/docs/mixpanel-agent#verified-mode) makes that decision explicit, guiding AI toward events, metrics, behaviors, and cohorts your team has reviewed in [**Lexicon**](/docs/data-governance/lexicon).

When you query with Verified Mode enabled, Mixpanel prioritizes verified equivalents when they exist. When Business Context and a verified event point in different directions, the Agent weighs both rather than following a fixed order, and will often tell you there were two options and why it chose the one it did.

[**AI-Powered Data Governance**](/docs/data-governance/ai-powered-data-governance) can help speed up Lexicon cleanup. It finds near-duplicate events and properties automatically, and lets you merge them in bulk once approved.

<Tip>
  Before turning on Verified Mode, check whether the events in your most-used queries are already verified in Lexicon. If your highest-traffic events aren't verified yet, verify those first so that turning on Verified Mode will immediately prioritize the data your team relies on most.
</Tip>

## Scope what the AI tool can do

It’s one thing to trust an AI’s answer. It’s another to trust its authority to act.

#### Control your own read-write access

Most MCP-compatible AI tools, such as Claude, let you set permissions per connector. Tools are typically grouped as read-only or write and delete, and each group can be set to:

* Always allow
* Require approval
* Block

Your AI tool's connector permissions control whether the connection is scoped to read-only, so it can only answer questions and never change anything in Mixpanel. That's separate from your existing Mixpanel role: You'll only ever see the projects and data you already have permission to view in Mixpanel, regardless of how the connector is scoped.

#### If you allow write access

When you allow write access, MCP may be able to do things like:

* Create boards
* Edit metrics
* Set up experiments

That means a change can happen without a person clicking through the UI themselves. For a full list of available tools, see [what's possible through MCP](/docs/mcp).

<Tip>
  If Lexicon cleanup has been sitting on someone's backlog, MCP can help clear it fast. Ask the Mixpanel MCP to generate descriptions for events that don't have any, or to surface likely duplicate event names for review. Preview the proposed changes before committing them at scale.
</Tip>

## Check the answer in front of you

Business Context and Verified Mode lower the odds of a wrong answer. They don't guarantee the specific one in front of you is right. Always do a quick check on any specific answer before acting on it.

#### Spot-check the mapping

Always open a report or investigate a finding that an AI tool returned, and confirm that the finding matches the data.

For example, when building manually in Mixpanel, you'd easily notice a cohort that comes back incorrectly with zero users because of a stale or renamed property. An AI-generated answer deserves the same scrutiny, not automatic trust just because AI produced it.

<Warning>
  Artificial intelligence can behave in ways that are inaccurate, incomplete, or unreliable despite guardrails. AI-generated insights in Mixpanel are designed to inform human decision-making, not replace it. Users remain in control of how insights are interpreted and acted upon.
</Warning>

#### Use RCA Agent's confidence and rating

[RCA Agent](/guides/guides-by-use-case/empower-your-team/mixpanel-agent#rca-agent) surfaces a confidence level for each finding, signaling how much to trust a given finding. You can also rate the RCA board's accuracy yourself after reviewing it, which improves future results.

#### Look for rendered charts in MCP

Look for MCP responses that render an actual interactive Mixpanel report, rather than the AI describing or redrawing the data itself. The interactive Mixpanel report is the same report you'd see inside Mixpanel directly, not the AI's interpretation of it.

## Common questions

A few questions come up often enough to answer directly, outside of configuration or spot-checking.

* **Does Mixpanel train on customer data?** No. For that, along with [GDPR](https://mixpanel.com/legal/mixpanel-gdpr/), [CCPA](https://mixpanel.com/legal/mixpanel-ccpa/), and similar compliance questions, see the [AI compliance page](https://mixpanel.com/legal/ai-compliance/).
* **What if an Agent answer is consistently off?** The feedback buttons inside the Agent experience enable you to provide feedback to Mixpanel's AI team. That's a way to improve the product over time, not a fix for the answer in front of you right now — for that, spot-check it using the section above.
* **Which AI model powers this?** See the [Mixpanel Agent FAQ](/docs/mixpanel-agent#faq) for information on the current model that powers the Mixpanel Agent. [Mixpanel MCP](/docs/mcp) doesn't run on a set model; it connects to whichever AI tool you're already using, including Claude, ChatGPT, Gemini, Cursor, or Notion.

## Key takeaways

* Business Context and Verified Mode are the settings you control that shape answer accuracy most directly.
* Your AI tool's connector permissions control whether the connection exposes write operations, while your existing Mixpanel roles and project permissions continue to determine which operations are allowed.
* Spot-checking a specific answer, using RCA Agent's confidence and rating, or looking for a rendered chart in MCP catches what configuration alone won't.

## Next step

Before utilizing Mixpanel’s AI tools, write [Business Context](/guides/guides-by-workflow/write-business-context). Mixpanel’s AI tools read it automatically, so it improves every answer that follows, not just the one in front of you.


# Guides by Use Case
Source: https://docs.mixpanel.com/guides/guides-by-use-case



## Engage Your Users

<CardGroup>
  <Card title="Drive Product Innovation" href="/guides/guides-by-use-case/engage-your-users/drive-product-innovation" />

  <Card title="Ship Features" href="/guides/guides-by-use-case/engage-your-users/ship-features" />
</CardGroup>

## Grow Your Usership

<CardGroup>
  <Card title="Grow Revenue" href="/guides/guides-by-use-case/grow-your-usership/grow-revenue" />
</CardGroup>

## Empower Your Team

<CardGroup>
  <Card title="Use Mixpanel Agent" href="/guides/guides-by-use-case/empower-your-team/mixpanel-agent" />

  <Card title="Use Mixpanel MCP" href="/guides/guides-by-use-case/empower-your-team/mcp" />

  <Card title="Use Mixpanel Headless" href="/guides/guides-by-use-case/empower-your-team/headless" />

  <Card title="Close Strategy-Execution Gap" href="/guides/guides-by-use-case/empower-your-team/close-strategy-execution-gap" />

  <Card title="See Replays" href="/guides/guides-by-use-case/empower-your-team/see-replays" />
</CardGroup>


# Operationalizing Metric Trees to Close the Strategy-Execution Gap
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/close-strategy-execution-gap



Most enterprise organizations don’t stumble because they lack strategy — they falter because strategy never reaches execution. The result: a 40% loss in potential value as teams operate in silos, measure the wrong outcomes, and optimize for activity over impact.

This Guide shows how to close that gap using Metric Trees — a data-driven system that links your North Star Metric (NSM) through every level of the organization, so execution becomes traceable, aligned, and adaptive.

## 💡 TLDR: Key Takeaways

* **The Problem:** The strategy-execution gap is an execution failure costing 40% of potential value due to unaligned, activity-focused effort.
* **Metric Trees as a Causal Map:** The Metric Tree is a quantified map that explicitly links the **North Star Metric (NSM)** down to the lowest-level, measurable team actions.
* **Focus Shifts:** The tree provides an unambiguous language, aligning teams and forcing a shift **from measuring activity** (features shipped) to **measuring outcomes** (value delivered).
* **Strategy Becomes a Flywheel:** Strategy is operationalized via the **Model → Execute → Learn** cadence, moving teams from guessing what to do, to measuring impact, to codifying lessons learned.

## The Messy Middle and the High Cost of Disconnected Strategy

The process of moving from corporate vision to tangible results often devolves into a **"messy middle.”** Visionary intent (e.g. "achieve market leadership") evaporates into fragmented, uncoordinated action at the execution level. This disconnect is a business pathology with quantifiable costs, eroding project spend and incurring massive opportunity costs. The gap persists because organizations fail to bridge four key challenges:

* **Lack of a Shared Language:** Abstract concepts like "synergy" and "transformation" are not actionable for a product team. Without a common, quantifiable vocabulary, efforts fragment.
* **Misaligned Resources and Priorities:** Strategic planning and financial budgeting often conflict, meaning resources (people, time, capital) are rarely allocated to the highest-leverage strategic initiatives.
* **Absence of Clear Accountability:** When the connection between a team's work and a top-line outcome is vague, performance reviews default to subjective activity reports, shielding low-impact projects from scrutiny.
* **Failure to Measure Outcomes Over Activities:** Teams naturally measure what’s easy (features shipped, tickets closed), creating a **"culture of activity"** where being busy is mistaken for making progress.

The Metric Tree is the architectural solution designed to systematically address these root causes by forcing leadership to move from **ambiguity to precision**. You can learn more about [Metric Trees in Mixpanel here](/docs/metric_tree).

## 1. Design Your Value Architecture

Before your organization can operationalize Metric Trees, you need to design the *value architecture* that defines how your business creates and measures impact. This step turns strategy into a quantifiable model every team can trace back to the North Star.

### Define Your North Star Metric

Building a Metric Tree is not a data visualization exercise; it is the process of **codifying your organization's hypothesis for value creation**. These design choices are foundational strategic decisions. The apex of any Metric Tree is the [**North Star Metric (NSM)**](https://mixpanel.com/blog/north-star-metric/). This is the single metric that best captures the **core value** the product or service delivers to its customers. All efforts must orient toward its movement.

**A strong NSM must:**

* **Lead to Revenue:** It must have a clear, causal link to the financial success of the business.
* **Reflect Customer Value:** It must measure successful usage or adoption of the core product utility.
* **Be Measurable and Actionable:** It must be something teams can directly influence.

**Examples of Strong Anchors:**

* **Usage-based:** Daily Active Users (DAU), Weekly Watch Time, Monthly Course Completions (Ideal for engagement/network effects).
* **Efficiency-based:** Time Saved Per User Per Week, Task Completion Rate (Ideal for B2B tools, internal platforms).
* **Revenue-based:** Net Dollar Retention (NRR), Customer Lifetime Value (CLTV) (Suitable for mature, subscription-based businesses).

✅ **Do:** Select an NSM that reflects long-term enterprise value, such as Net Dollar Retention or Enterprise Seats Active.<br />❌ **Do not:** Choose vanity metrics, such as Total Licenses Sold, that don’t reflect ongoing value creation.

### Choose Your Architectural Model

The Metric Tree is built on an underlying logic that defines the relationship between nodes.

* **Deterministic Trees:** Built on unbreakable mathematical formulas (e.g. *Revenue = Users x ARPU*). Powerful for precise root cause analysis and forecasting.
* **Hypothesis Trees:** Built on influential but not mathematically precise relationships (e.g. *Improved Onboarding Completion Rate will lead to Week 1 Retention*). Essential for innovation, making strategic assumptions explicit and testable.
* **Organizational Trees:** Defines relationships based on team ownership and accountability (e.g. *New Users decomposed into Organic Traffic (SEO Team) and Sign-up Conversion Rate (Product Team)*). Highly effective for clear resource allocation.

<Note>
  **Pro tip:** Treat your tree as *evolutionary* — a living model. New initiatives start as Hypothesis branches; as experiments are run and validated, the link is hardened into a Deterministic branch. The rate at which hypotheses are validated is the organization’s learning velocity.
</Note>

### Decompose Into Actionable Inputs

The goal is to break the NSM down into successive layers until the components are granular enough to be directly owned and influenced by a single team.

* **Level 1: Value Drivers:** The 2-4 primary components that are **Mutually Exclusive and Collectively Exhaustive (MECE)** of the NSM (e.g. *MAU = New Users + Retained Users + Resurrected Users*).
* **Level 2+: Input Metrics (The Leaves):** Decomposition continues until the metric is a lever a specific team can directly control through daily work (e.g. *Sign-up Conversion Rate*).

✅ **Do:** Keep decomposing until you reach metrics that a single team can influence directly. Anything broader is too abstract to drive accountability or improvement.

<Frame>
  <img alt="Metric Trees" />
</Frame>

Once you’ve defined your value architecture, plan a cross-functional workshop to map your first Metric Tree collaboratively — [Section 4](#4-run-metric-tree-workshops-for-model-creation) outlines how to run it.

## 2. Connect Data & Validate Relationships

Once your Metric Tree is designed, bring it to life by connecting it to trusted, real-time data. This step ensures every relationship in the tree is measurable, evidence-based, and ready to guide enterprise-scale decision-making.

### Instrument the Tree

Each node in your tree must map to a definable event or property in Mixpanel. For rollout:

* Use saved metrics for consistency.
* Maintain strict definitions and data governance.
* Generate your “data-to-do list” from gaps you surface.

Prioritize instrumentation of metrics that directly ladder to your NSM — not everything at once.

### Validate Relationships

Once your data is live in Mixpanel, validate that your assumed relationships actually hold true by:

* Running correlation or regression checks: Does input X affect metric Y as expected?
* Tagging each link with a confidence level (High / Medium / Low).
* Turning low-confidence links into experiment candidates.

👉 **Action:** Focus your next 90-day sprint on low-confidence links — they’re your most powerful learning opportunities.

## 3. Activate Your Value Architecture: The Model → Execute → Learn Operating Cadence

A well-designed and data-connected Metric Tree is a necessary precondition, but it is not sufficient to close the strategy-execution gap. To "make it real," the tree must be woven into the very fabric of how the organization operates.

This is achieved through a disciplined, cyclical operating cadence: the Model → Execute → Learn flywheel. This rhythm transforms the tree from a passive reporting tool into the central nervous system for strategic management.

### Model

**Model is your planning phase** where leadership identifies the metrics that matter most and teams propose the bets that will move them. It turns strategic intent into a testable, data-driven plan for the next operating cycle.

At the start of each cycle (quarter, half-year):

* **Target Inputs:** Leadership identifies the 1-3 input metrics on the tree that will be the primary focus for the cycle, preventing resources from being spread too thinly.
* **Generate Bets:** Teams brainstorm specific projects or experiments aimed at moving those target metrics.
* **Estimate Impact & Form Hypotheses:** Every bet requires a clear, falsifiable hypothesis: "We believe that \[Action X] will cause \[Metric Y] to change by \[Amount Z]."
* **Prioritize (Impact x Confidence vs. Effort):** The portfolio is prioritized using Impact vs. Effort, but the Impact score is weighted by the Confidence of the tree link being tested. This enforces rigor.
* **Forecast and Align:** Estimated impacts are aggregated to create a data-driven forecast for the NSM, representing a clear, quantifiable commitment and aligning all stakeholders.

✅ **Do:** Fund only initiatives tied to tree metrics — if it doesn’t align, it doesn’t run.<br />❌ **Do not:** Approve projects just because they sound strategic or have executive sponsorship — if they’re not tied to measurable impact in the Metric Tree, they dilute focus and waste resources.

### Execute

The Execute phase spans the duration of the cycle (e.g. the quarter). **During this time, the Metric Tree transitions from a planning tool to a real-time command center** for performance management. Its primary function is to provide clear, continuous visibility into progress against the plan, enabling rapid adaptation.

As your teams act, your live Metric Tree in Mixpanel becomes your strategic cockpit, allowing for:

* **Real-Time Visibility:** The live tree replaces static weekly slide decks and conflicting spreadsheets as the single source of truth.
* **Spotting of Early Warnings:** Leaders monitor the tree to see if targeted inputs are lagging. If a key input is behind halfway through the cycle, it is an **early warning** that triggers an immediate root cause analysis.
* **Agile Resource Allocation:** If a bet is dramatically **over-performing**, resources can be doubled down. If a bet is **failing** to move the metric despite successful delivery (a hypothesis failure), it can be **stopped early**, freeing up capacity for more promising initiatives.
* **Root Cause Analysis:** When a metric slumps, the tree enables rapid "5 Whys" diagnosis by tracing the decline down through the hierarchy to the exact granular metric that triggered the higher-level failure.
* **Gap Management:** By comparing live actuals to the quarterly forecast, the **forecast gap** is instantly calculated. Teams are immediately tasked with generating new, high-impact **gap-closing bets** rather than waiting for an inevitable miss.

<Note>
  **Pro tip:** When a top-level metric stalls, trace down the tree — you’ll find the actionable surface quicker than in traditional BI tools.
</Note>

### Learn

**Learn is the reflection and evolution phase** where you analyze outcomes, validate assumptions, and update your Metric Tree based on what actually drove impact. It’s how your organization compounds insight and gets smarter every cycle.

* **Compare Forecast vs. Actual:** The review begins with an objective comparison of the results. Teams present their initial impact estimates from the "Model" phase alongside the actual, measured results. The central questions are: What moved as expected? What didn't? And most importantly, Why?
* **Identify True Leverage:** This analysis is where deep strategic insights are unearthed. The comparison of forecast to actual reveals the true leverage points in the business model. Some metrics may be surprisingly easy to move, indicating an untapped growth opportunity. Others may prove stubbornly resistant to change, suggesting that they are less influential than previously believed or that the organization lacks the right capabilities to affect them.
* **Codify Learnings:** The "why" behind both successes and failures is rigorously investigated and documented. A successful bet that exceeded its forecast is analyzed to understand the underlying reasons for its success so they can be replicated. A failed bet is examined to distinguish between an execution problem (the team failed to deliver the initiative as planned) and a hypothesis failure (the team delivered the initiative perfectly, but it simply didn't have the desired effect). This distinction is critical for intelligent adaptation.
* **Update the Tree:** The cycle culminates in updating the value architecture itself. A hypothesis that was validated with strong data may have its confidence score increased or even be converted to a deterministic link. A failed bet may be pruned from the tree or annotated with the learnings from the experiment. A new, unexpected driver that was discovered during the cycle might be added.

Treat your Metric Tree as a *living source of truth*, not a static artifact. Over time, the tree becomes your organization’s collective intelligence on what truly drives value.

## 4. Run Metric Tree Workshops for Model Creation

Building your first Metric Tree is a cross-functional exercise, not a data project. Use structured workshops to align leaders, validate logic, and accelerate adoption across the organization.

**Workshop checklist:**

* Focus on one business domain (e.g. enterprise onboarding) to start.
* Invite a Decider (executive sponsor), an Owner (product/growth lead) and a Data Expert (analytics lead).
* Use a “bottom-up” mapping: Ask teams what inputs they control, then ladder up to NSM.
* Keep tree levels focused with 2-4 drivers per level to maintain clarity.

<Note>
  **Pro tip:** Emphasize causality — each link should reflect something you can measure, not just wishful thinking.
</Note>

📖 **Read more:** Check out [How we designed Metric Trees for Mixpanel](https://mixpanel.com/blog/designing-metric-trees/) for a behind-the-scenes look at how we applied this same framework to align our teams and accelerate growth.

## Ownership and the Change Management Imperative

Implementing a Metric Tree is proposing a new way to work, requiring deliberate change management. Success relies on a hybrid stewardship model that distributes accountability while ensuring central governance.

The initial Model Creation is a shared responsibility, developed in collaborative workshops involving a cross-functional team (Product, Data, Leadership) to ensure buy-in and contextual accuracy.

However, execution requires Distributed Ownership: Every single metric or sub-section within the tree must have a designated owner who is accountable for its performance, definition, and data accuracy.

Overarching the entire system is Centralized Governance, handled by the Metric Tree Steward (e.g. Product Ops or Strategy Analyst). The Steward's core focus is managing the system itself — ensuring Tree Integrity, governing the Bet Ledger, and running the Learn rituals — to guarantee the tree remains a reliable, single source of truth and a dynamic engine for strategic execution.

**Tips for Success:**

* **Pilot with Enthusiasts:** Do not launch organization-wide. Pilot the tree with a single, high-performing product area or team whose NSM is well-instrumented. Use their quick success to generate internal case studies.
* **Make it the Single Source of Truth:** Force adoption by explicitly replacing a legacy ritual. For example, ban all PowerPoint-based quarterly planning and make the Bet Ledger the only required input for resource allocation meetings. Leaders must publicly reference the tree and the ledger, not traditional roadmaps.
* **Reward the Right Behavior:** Publicly celebrate and reward teams whose bets fail — but whose hypotheses were clear, their learning was fast, and their tree update was rigorous. The goal is to celebrate learning and velocity, not just success.
* **Leaders Must Live the Tree:** The C-level executive who owns the top-level NSM must champion the process. They must use the tree and the Bet Ledger as the starting point for every operational and budgeting discussion.

## Closing Thoughts and Key Takeaways

The strategy-execution gap is not an unsolvable problem. It is a systems problem that requires a systems solution. The framework presented in this guide creates a direct, visible, and quantifiable link from the highest-level corporate vision to the daily work of every team.

Adopting this framework is not merely a new process to be implemented; it represents a fundamental shift in organizational culture. It requires, and in turn fosters, a new set of behaviors:

* **Intellectual Honesty:** A commitment to making assumptions explicit and a willingness to be proven wrong by data.
* **Radical Transparency:** The practice of making the strategy, the plan, and the real-time progress against it visible to everyone in the organization.
* **Outcome-Orientation:** A decisive shift in focus from celebrating the completion of tasks to celebrating the movement of metrics that create value.
* **Aligned Autonomy:** The empowerment of teams with the clarity, context, and data they need to make better, faster decisions autonomously, confident that they are aligned with the broader strategy.

For the senior leader, the call to action is clear. The role of leadership is not simply to approve the strategy, but to champion the system that brings it to life.

By embracing this framework, leaders are not just implementing a new tool or process. They are building the foundations of a more resilient, adaptive, and high-performing organization — one that is capable of learning faster than the market changes and consistently, predictably turning vision into value.


# Mixpanel Headless
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/headless

Programmatic access to your analytics

Mixpanel has always been built for builders. But until now, the only way to drive it was through a UI.

Headless changes that. It's a Python SDK that gives you direct, code-level access to the full Mixpanel product surface. If you're an engineer or data analyst who wants to automate analysis, build agents, or integrate Mixpanel into a pipeline, this is where you start.

## Multiple interfaces, one data layer

Headless doesn't replace the Mixpanel you already use. It extends it. Think of Mixpanel as a single data layer, now accessible through multiple interfaces depending on what you're building and where you're working:

* **Mixpanel Agent** is for exploration inside the product. Ask a question in plain language, get an answer from your data. No code required.
* **Mixpanel MCP** is for AI tools. Connect Claude, ChatGPT, Gemini, Cursor, and [other supported tools](/docs/mcp) to your Mixpanel project and query it from your existing AI workflow.
* **Mixpanel Headless** is for builders. Write Python that reads and acts on your Mixpanel data.

The same retention curve, the same funnel, the same cohort: available through whichever interface fits the job. What's new isn't the data. It's the surface area.

## What Headless is

At its core, Headless is a typed Python SDK. You authenticate once, instantiate a `Workspace` object, and every Mixpanel capability is available as a method call. Query results come back as structured Python objects with a `.df` property for DataFrame access.

Here's what makes it different from querying the REST API directly:

* **Typed results.** You get structured objects back, not raw JSON. Funnel results have `.overall_conversion_rate`. Retention results have a cohort-shaped DataFrame. You don't parse. You use.
* **Built-in discovery.** Before writing a query, you can inspect the project: list events, enumerate properties and their values, browse cohorts and boards. This matters especially when building agents that need to understand a project's shape before querying it.
* **Full product surface.** MCP exposes around 30 curated tools designed for natural-language sessions. Headless exposes everything: every report type, every configuration, every asset. If Mixpanel can do it, Headless can express it in code.

See the [Headless documentation](https://mixpanel.github.io/mixpanel-headless/) for the full picture.

## When to use Headless

Headless is the right tool when you're writing Python and need programmatic access to Mixpanel data. Below are a few patterns where it fits well.

### Automating repetitive analysis.

If you're building the same report week over week, a script can do it for you. Query the data, format the output, send it to Slack or email. No board required.

### Feeding AI agents.

Agents need a surface they can query without human mediation. Headless gives them typed access to the full Mixpanel product. An agent can discover what events exist, run the right query, interpret the result, and take action, all in code.

### Keeping Lexicon in sync.

Every Mixpanel project has a [Lexicon](/docs/data-governance/lexicon): a dictionary of events and properties with descriptions, ownership, status, and type metadata.

In the UI, keeping it current is a manual task. With Headless, it's automatable. You can read the current state, diff it against a tracking plan or warehouse schema, and write updates back from a script.

Tracking plan changes propagate automatically. New events get described on deploy. Stale events get flagged on a schedule.

For teams where Lexicon maintenance has slipped, Headless gives you the tools to automate it. See the [Data Governance docs](https://mixpanel.github.io/mixpanel-headless/guide/data-governance/) for implementation details.

### Cross-project tooling.

Query multiple projects in the same script. Useful for organizations managing several products, regions, or environments from a single codebase.

<Info>
  If you want to query Mixpanel from a chat interface rather than code, [Mixpanel MCP](/guides/guides-by-use-case/empower-your-team/mcp) is the better fit. For AI-assisted analysis inside Mixpanel itself, see [Mixpanel Agent](/guides/guides-by-use-case/empower-your-team/mixpanel-agent).
</Info>

## What's next

The direction is toward a fully agentic analytics layer: a Mixpanel that doesn't just answer questions when asked, but actively surfaces what matters, integrates into the tools teams already use, and runs without anyone having to open a browser. Headless is the foundation.

<Warning>
  **Early access:** Headless is in early access. The current rate limit is 60 requests per 60 minutes. Keep this in mind when designing workflows that run at scale or on a tight schedule. The API is under active development; expect changes before 1.0.
</Warning>

👉 **Ready to build?** [Request access](https://mixpanel.com/ai/headless), then start with the [installation](https://mixpanel.github.io/mixpanel-headless/getting-started/installation/) and [quick start](https://mixpanel.github.io/mixpanel-headless/getting-started/quickstart/) guides to get credentials and your first query running.


# Use Mixpanel MCP to Go From "What Happened?" to "What Should We Do?"
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mcp



**Mixpanel Model Context Protocol (MCP)** connects your Mixpanel project to the AI tools your team already uses — such as Claude, ChatGPT, Cursor, and Gemini — so you can ask real questions about product behavior in plain language and get answers without touching the Mixpanel UI.

But the bigger unlock isn't speed. It's context. MCP lets you layer in information that doesn't live in Mixpanel at all — campaign calendars, competitor signals, industry benchmarks, internal docs — and synthesize it with your product data in a single workflow. That's work that used to take days of manual exports and reconciliation.

<Frame>
  <img alt="image" />
</Frame>

This guide covers how to use MCP well: how to orient yourself in a new project, run analysis without building reports, and go from “What happened?” to “What should we do about it?”

## What Good Looks Like

Before diving into steps, it’s worth being clear about what “good” looks like in practice. Teams that use MCP effectively look materially different from teams that don’t:

* New team members can explore product data on day one, without learning your event schema first.
* Product Managers and Data Analysts explore questions and sanity-check assumptions quickly before formalizing anything in Mixpanel.
* Product questions are routinely answered with business context (not just metrics) attached.
* Strategic decisions are informed by synthesis across data sources, not stitched-together exports
* Teams use MCP to surface events and properties from their Mixpanel schema that lead to better metrics.

If you’re using MCP only as a faster way to build reports, most of this value never materializes.

## See MCP in Action

Before reading further, watch this walkthrough. It shows MCP end to end — from asking intent-based questions, to running live analysis against Mixpanel, and synthesizing product data with external context like calendars and benchmarks.

<FrameColumn title="Mixpanel MCP Overview" description="If you’re new to MCP, watch this first to ground the concepts below in a concrete example. If you’re evaluating MCP for your team, this video illustrates the difference between simply querying Mixpanel and using MCP as a data synthesis layer." />

## Before You Begin

You’ll need:

* MCP set up in your AI interface of choice. Review [Mixpanel MCP Integration](/docs/features/mcp) for setup instructions.
* Access to a Mixpanel project with reasonably stable event definitions.
* Any external context you want to analyze (CSVs, calendars, internal docs, benchmarks).
* The [MCP Prompt Library](https://mixpanel.com/wp-content/uploads/2026/04/Mixpanel_MCP_Prompt_Library.pdf) on hand as a reference — ready-to-use prompts for analysis, investigation, dashboards, and governance. If you use Claude Projects, Cursor, or another persistent AI environment, load the [agent version](https://storage.googleapis.com/cdn-mxpnl-com/libs/mcp-prompt/Mixpanel_MCP_Prompt_Library_agent.md) instead: It detects your connected tools automatically and composes multi-step workflows without you having to prompt each step separately.

Once MCP is connected, select it as a data source inside your AI tool before asking questions.

<Note>
  **How ready is your data?** MCP works best when your events are consistently named, key properties are populated, and your schema is documented in [Lexicon](/docs/data-governance/lexicon). If you're not there yet, that's OK — MCP can actually help you audit your data. Try asking: "Show me all events with their 30-day volume" or "What data quality issues exist in my project?"
</Note>

## Where You're Starting From

Most teams start with single questions about one metric. With practice, MCP becomes something more — a workflow embedded in how your team makes decisions every week.

| Level | Name                  | Description                                                                        | Example                                                                           |
| ----- | --------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| 1     | Single Query          | Ask basic questions about one metric in Mixpanel.                                  | "What's our 7-day retention?"                                                     |
| 2     | Multi-Query Analysis  | Chain multiple Mixpanel queries to build a complete picture.                       | "Show me retention by channel, then break down the top channel by feature usage." |
| 3     | Cross-Source Joins    | Connect Mixpanel with one additional data source for combined analysis.            | "Which users with high feature adoption also have open Salesforce opportunities?" |
| 4     | Automated Delivery    | Set up recurring MCP-powered reports delivered to Slack or other channels.         | Weekly metrics digest posted to your team's Slack every Monday.                   |
| 5     | Embedded in Decisions | MCP analysis is part of standing rituals (sprint planning, QBRs, board reporting). | Every product review starts with an MCP-generated impact summary.                 |

This guide covers the core workflow. [MCP Integration Pairings](/guides/guides-by-use-case/empower-your-team/mcp/integrations) goes deeper on tool-specific combinations — including automated delivery via Slack — and [MCP by Industry](/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry) gives you use cases and prompts tailored to your context.

## Step 1: Use MCP to Eliminate the Context Gap

Most teams don’t struggle with analysis first — they struggle with orientation. For instance, before you can answer “What's our activation rate?”, you need to know how activation is actually instrumented in your project.

### Start with intent, not event names

Begin with discovery questions that reflect how people actually think about the product, not how the data happens to be instrumented.

<Frame>
  <img alt="image" />
</Frame>

Examples:

* Which events and properties best represent checkout intent in our product?
* How do we currently define activation for new users?
* What signals represent meaningful engagement for a paid account?

### Let MCP reason about your schema

MCP reads your Mixpanel schema and reasons about how intent maps to your data — even when that intent doesn’t map cleanly to a single event.

It doesn’t just answer the question you asked. MCP proactively suggests *other relevant events and properties* you may not have considered.

This mirrors the value of [Lexicon](/docs/data-governance/lexicon) at its best: Instead of needing to know exactly what to look for, the AI helps surface adjacent signals that are often just as important.

<Warning>
  **Pitfall:** MCP helps interpret data — it doesn’t fix structural issues. When structural issues are found, pause and invest in [data governance](/guides/guides-by-topic/govern-data) first.
</Warning>

### Example: clarifying ambiguous intent

For example, based on how your project is actually implemented, MCP can help determine whether “purchase intent” is better represented by:

* Checkout Started
* Payment Method Added
* A specific property on Purchase Completed

This is especially valuable when you're working in an unfamiliar project, or when your schema has evolved over time and no single person holds all the context.

<Note>
  **Pro tip:** When MCP surfaces events you didn't expect, that's not a detour — that's often where the real insight lives. Follow those threads before formalizing anything.
</Note>

## Step 2: Use MCP to Run Analysis Without Touching the UI

Once MCP understands which events and properties represent your intent, you can ask it to analyze them directly.

<Frame>
  <img alt="image" />
</Frame>

Be explicit about:

* The behavior you care about
* The population (all users, first-time buyers, paid accounts, etc.)
* The timeframe
* The shape of the answer (trend, funnel, breakdown)

The more specific your question, the more useful the answer. Vague prompts return vague results.

| Prompt Specificity | Sample Prompt                                                                                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Vague              | Show me checkout conversion.                                                                                                                                      |
| Specific           | What's the conversion rate from Checkout Started to Purchase Completed for first-time buyers over the last 60 days? Show me how that rate changes week over week. |

MCP queries real Mixpanel data (funnels, trends, insights) and the AI analyzes those results to produce charts and written insights — directly in the AI interface.

This is especially effective for exploratory analysis, sense-checking assumptions, and helping non-analysts answer real questions without report-builder fluency.

<Note>
  **Pro tip:** Analysis you run via MCP isn't automatically saved to Mixpanel — but you don't have to recreate it manually either. You can ask MCP to create boards and reports directly from your AI tool so they're persistent and shareable in the Mixpanel UI.
</Note>

Think of MCP as a fast exploration layer — use it to discover and validate insights, then formalize the ones that matter in Mixpanel.

## Step 3: Add Context Mixpanel Was Never Meant to Store

Digital analytics tells you what users did. It rarely explains why.

That’s where MCP becomes especially powerful. It lets you layer in context that lives outside your analytics tool, so behavior can be interpreted, not just measured.

<Frame>
  <img alt="image" />
</Frame>

That context might include:

* Promotional or campaign calendars
* Competitor announcements or pricing changes
* Internal rollout notes or experiment timelines

Attach these external files or documents directly to your AI chat and ask questions that connect behavior to context.

| Context                     | Prompt                                                                                                                                                                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Promotional Calendar**    | Do changes in checkout conversion align with our promotional calendar? I've attached our Q1 campaign schedule.                                                                                                                  |
| **Competitor Announcement** | We saw a 15% drop in feature adoption last month. Here's a competitor announcement from that period — could this be related?                                                                                                    |
| **Rollout Timelines**       | Here are our experiment rollout dates. Which feature launches correlate with changes in retention?                                                                                                                              |
| **Campaign Schedule**       | Activation rate for new signups dropped from 42% to 31% over the last three weeks. Here's our campaign schedule — does the drop align with any traffic source or campaign change? Are there differences by acquisition channel? |

This is synthesis that previously required a data analyst, a spreadsheet, and a few days of manual work. Now, MCP synthesizes this context with your product data in a single line of questioning — without manual exports or reconciliation.

## Step 4: Combine Product Data with Unstructured Knowledge

Some of the most important inputs into product decisions live in documents, not databases. If your AI tool is connected to sources like Notion or Google Drive, MCP can analyze those alongside Mixpanel data.

<Frame>
  <img alt="image" />
</Frame>

Examples:

| Unstructured Knowledge     | Prompt                                                                                                                                                                                                           |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Industry Benchmarks**    | Compare our 30-day retention to the benchmarks in our Q4 industry report.                                                                                                                                        |
| **Historical Performance** | Based on our historical performance and the SaaS benchmarks in this doc, where are we most underperforming?                                                                                                      |
| **Customer Interviews**    | I've attached notes from our last three customer interviews. Based on what users said, where does the onboarding experience seem to be breaking down, and does that match what you're seeing in the funnel data? |

This is where MCP moves beyond analytics and into strategic reasoning — connecting quantitative signals to qualitative context in a single workflow.

## Step 5: Use MCP for Synthesis, Not Just Answers

The highest-value MCP prompts don’t ask for charts — they ask for judgment.

Once MCP has analyzed behavior, campaign context, benchmarks, and qualitative signals, ask MCP to synthesize across all of it: "Given everything we’ve analyzed, what would you change about our strategy going into the next quarter?"

<Frame>
  <img alt="image" />
</Frame>

This compresses work that previously took days or weeks into a single, iterative workflow.

### Keep a human in the loop

<Note>
  MCP can help summarize signals, highlight tradeoffs, and suggest areas to investigate — but it doesn’t make decisions for you.

  Treat AI-generated recommendations as inputs, not answers. The final judgment should always come from your team, informed by domain knowledge, business constraints, and risk tolerance.

  Used this way, MCP accelerates strategic thinking without replacing human accountability.
</Note>

## Common Pitfalls to Avoid

These issues come up most often when teams treat MCP as a shortcut instead of a complement to strong analytics fundamentals.

* **Treating MCP as only a report builder**: Its biggest value is as an exploration and synthesis layer. But it can also create boards, manage Lexicon metadata, and triage data quality at scale — so don't limit it to analysis alone.
* **Asking under-specified questions**: MCP is powerful, but clarity of intent still matters. Specify the behavior, the population, the timeframe, and the shape of the answer you need.
* **Using MCP to paper over unclear instrumentation**: MCP helps interpret data — it doesn’t fix structural issues. When this comes up, pause and invest in [data governance](/guides/guides-by-topic/govern-data) first (clear event definitions, ownership, and approval workflows) before relying on MCP for analysis.
* **Using MCP without clear data-use guardrails**: Only connect MCP to Mixpanel projects and external sources that comply with your organization’s security, privacy, and data-sharing policies, and be intentional about which data is exposed to AI tools. For detailed guidance, see [Mixpanel’s MCP security and compliance considerations](/docs/features/mcp#security--compliance-considerations).

## Key Takeaways

* MCP can both query Mixpanel and write back to it. Create boards, update Lexicon, and triage data quality issues, all from your AI tool.
* MCP's biggest impact is reducing context friction, not clicks. The real unlock is joining product behavior with external context.
* Use MCP to explore and validate. Use Mixpanel to formalize and share.
* The best teams use MCP to move faster from "What happened?" to "What should we do about it?"

👉 **Next step**: Ready to go deeper? See [MCP by Industry](/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry) for use cases and sample prompts tailored to your context, or [MCP Integration Pairings](/guides/guides-by-use-case/empower-your-team/mcp/integrations) to explore what each external data source unlocks.


# MCP Integration Pairings
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mcp/integrations



Each pairing below shows the questions that become answerable when you connect Mixpanel's MCP server alongside another data source. These work across all industries — for vertical-specific use cases, see [MCP by Industry](/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry).

## Mixpanel + Salesforce

Product signals meet pipeline context. When you join Mixpanel's behavioral data with Salesforce opportunity and lead data, you can move from "this account is engaged" to "this account is engaged, has an open opportunity above \$X, and hasn't been contacted in two weeks."

| # | Question                                                                                          |
| - | ------------------------------------------------------------------------------------------------- |
| 1 | Which trial accounts with the highest product engagement also have an open opportunity above \$X? |
| 2 | Do accounts where the champion is a heavy user convert at a higher win rate?                      |
| 3 | What's the product usage pattern in the 14 days before a deal closes vs. deals that go dark?      |
| 4 | Which product features are most adopted by accounts that expand their contract?                   |
| 5 | Are there churned accounts that re-engaged in the product but don't have a re-open opportunity?   |

## Mixpanel + Stripe

Product behavior meets revenue. Joining Mixpanel with Stripe lets you move from measuring feature adoption to measuring what that adoption is worth — in MRR, expansion, and conversion.

| # | Question                                                                            |
| - | ----------------------------------------------------------------------------------- |
| 1 | Do users who adopt \[feature] generate higher monthly recurring revenue?            |
| 2 | What's the activation-to-paid conversion rate by feature adoption depth?            |
| 3 | Which user behaviors in the 7 days before upgrade are most predictive of expansion? |
| 4 | What's the revenue impact of a 10% improvement in onboarding completion?            |
| 5 | How does usage-based billing align with actual feature usage patterns?              |

## Mixpanel + Sentry

User experience meets reliability. This pairing answers the question that engineering and product teams often can't align on: when something breaks, how much does it actually affect user behavior?

| # | Question                                                                            |
| - | ----------------------------------------------------------------------------------- |
| 1 | When error rates spike, how quickly does it show up in user engagement metrics?     |
| 2 | Which errors have the highest impact on session abandonment?                        |
| 3 | Are there features with high adoption but disproportionately high error rates?      |
| 4 | After a bug fix deployment, did user engagement recover — and how long did it take? |
| 5 | Which user segments experience the most errors, and does it correlate with churn?   |

<Note>
  **Pro tip**: Look at engagement recovery in the 7 days after a fix ships, not just the day of. User behavior often lags reliability improvements by several days.
</Note>

## Mixpanel + Slack

Analytics meet action. This pairing is less about answering questions and more about getting answers to the right people at the right time — automatically.

| # | Question                                                                               |
| - | -------------------------------------------------------------------------------------- |
| 1 | Can I get a weekly summary of key metrics posted to our team channel every Monday?     |
| 2 | When a key account's usage drops below a threshold, can an alert go to the CS channel? |
| 3 | Can I generate a launch performance summary and post it after each release?            |
| 4 | When a trial account hits activation milestones, can the sales channel get notified?   |
| 5 | Can my team ask data questions in Slack and get Mixpanel-powered answers?              |

## Mixpanel + Notion

Analytics meet documentation. If your team's strategy lives in Notion, this pairing closes the loop between what you're planning and what the data shows.

| # | Question                                                                                    |
| - | ------------------------------------------------------------------------------------------- |
| 1 | Can I generate a product performance summary and save it to our team wiki?                  |
| 2 | When reviewing a spec in Notion, can I pull usage data for the feature being discussed?     |
| 3 | Can I create a data-informed QBR template that pulls live metrics into Notion?              |
| 4 | When planning a new feature, can I reference engagement data for similar existing features? |
| 5 | Can I maintain a living "key metrics" page in Notion that reflects current Mixpanel data?   |

<Warning>
  **Pitfall**: Notion pages that pull live Mixpanel data via MCP reflect a point-in-time snapshot, not a persistent live connection. Treat them as up-to-date when generated, not as dashboards that auto-refresh.
</Warning>

👉 **Next step**: See [MCP by Industry](/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry) for vertical-specific use cases and role-based prompts, or return to [Explore Data with AI](/guides/guides-by-use-case/empower-your-team/mcp) for the full MCP workflow guide.


# MCP by Industry
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry



MCP's cross-source analysis is most useful when you know which questions to ask for your context. Select a guide below to see what's possible by industry — the use cases, the data joins, and the prompts that tend to matter most for your team.

<CardGroup>
  <Card title="AI" href="/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/ai" />

  <Card title="B2B SaaS" href="/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/b2bsaas" />

  <Card title="Ecommerce" href="/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/ecommerce" />

  <Card title="Finance" href="/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/finance" />

  <Card title="Healthcare" href="/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/healthcare" />

  <Card title="Media & Entertainment" href="/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/media" />
</CardGroup>


# MCP for AI Products
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/ai

Use Cases and Sample Prompts

AI products have a layer of complexity that most product analytics setups weren't built for: quality isn't just about UX, it's about model performance. The Mixpanel MCP server lets you connect behavioral data with model evaluation scores, error tracking, infrastructure costs, and billing data — so you can understand how what's happening under the hood translates into what users actually do.

## Use Cases

<Note>
  **New to MCP?** Start with [Explore Data with AI](/guides/guides-by-use-case/empower-your-team/mcp) for setup instructions and foundational concepts before diving into industry-specific use cases.
</Note>

Each use case below shows a cross-system question your team can ask, the data sources it draws from, and what you can do with the answer.

### User Engagement × Model Quality

**The question**: Do users who interact with higher-scoring model outputs have better retention?

| Data source   | What you're pulling                       |
| ------------- | ----------------------------------------- |
| Mixpanel      | Engagement events, thumbs up/down signals |
| Eval platform | Model scores, quality metrics             |

Thumbs up/down signals tell you something, but they're noisy and self-selected. Combining them with eval scores gives your ML team a more grounded optimization target — one that's anchored in what actually keeps users coming back, not just what they rate in the moment.

### Feature Usage × Infrastructure Cost

**The question**: Which AI features have the highest per-user compute cost relative to their retention impact?

| Data source    | What you're pulling             |
| -------------- | ------------------------------- |
| Mixpanel       | Feature usage events            |
| Cloud provider | Compute costs, API call volumes |

Not every high-engagement feature is worth what it costs to serve. This join helps you find the features where cost and retention impact are misaligned — either expensive features that aren't driving retention, or under-invested features that are.

<Note>
  **Pro tip**: Run this analysis before roadmap planning, not after. Knowing your cost-to-retain ratio per feature is one of the more defensible inputs into prioritization conversations.
</Note>

### Error Rates × User Drop-off

**The question**: When error rates spike, how quickly does it show up in session frequency?

| Data source | What you're pulling               |
| ----------- | --------------------------------- |
| Mixpanel    | Session frequency, feature events |
| Sentry      | Error rates, latency data         |

Infrastructure teams often work from SLOs that don't account for user behavior. This join gives you the user-side view of a reliability incident — how fast it ripples into engagement, which segments feel it most, and whether recovery shows up in the data after a fix ships.

<Warning>
  **Pitfall**: A spike in errors doesn't always produce an immediate drop in sessions — some users retry, some don't notice. Look at lagged engagement (Day 3, Day 7) rather than same-day metrics to get a more accurate picture of impact.
</Warning>

### Prompt Patterns × Conversion

**The question**: Which prompt types lead to the highest satisfaction and paid conversion?

| Data source    | What you're pulling                 |
| -------------- | ----------------------------------- |
| Mixpanel       | Prompt events, satisfaction signals |
| Billing system | Conversion and plan data            |

Different users come to AI products with different jobs to be done — writing, coding, analysis, research. This join shows you which use cases your product serves best and which ones convert, which is useful both for positioning and for deciding where to invest in fine-tuning.

## Sample Prompts by Role

These are starting points. Adjust the time ranges, segments, and metrics to match your product and data.

<Tabs>
  <Tab title="Product Manager">
    * Retention curve for users who used AI feature 5+ times in their first week
    * Funnel from free signup to first AI interaction to 10th interaction to upgrade to paid
    * Daily trend of AI outputs per user, segmented by plan tier
    * User segments with highest thumbs-down ratio on AI outputs
    * Engagement pattern for users who hit rate limits vs. those who don't
    * Average time from signup to first "power use" session (10+ prompts)
    * Output exported rate difference between free and paid users
    * Adoption curve for newest model version — are users switching?
    * Conversion rate for users who hit "wow moment" in session 1 vs. later
    * Which use case categories (writing, coding, analysis) have highest retention correlation?
  </Tab>

  <Tab title="ML Engineering Lead">
    * Negative feedback trend (thumbs down, regenerations) over 30 days by `model_version`
    * When error rate spiked last week, what was the impact on session frequency for 7 days after?
    * Which prompt categories generate the most "regenerate" or "edit" events (quality gaps)?
    * Satisfaction signals between model v2.3 and v2.4
    * Latency threshold where we lose users (response time vs. engagement)
    * Token count per prompt trend over time — are prompts getting longer?
    * Which `error_types` correlate most with session abandonment?
    * Sessions with model switch event — do those users show higher or lower satisfaction?
    * Output quality distribution across `use_case_categories`
    * After deploying model v2.4, Day 1 and Day 7 impact on output acceptance rate
  </Tab>

  <Tab title="Data Analyst">
    * Monthly cohort retention table for 12 months (M0 through M6)
    * Distribution of active days per month
    * Segment by `plan_type`: prompts per session, satisfaction rate, retention.
    * Frequency distribution of prompts per week for active users?
    * All events with 30-day volume sorted by frequency
    * Data quality: events missing `model_version` or `output_quality_score`
    * Behavioral paths of users who convert vs. churn during trial
    * Median prompts per session by platform and plan type
    * Properties most predictive of 90-day retention
    * Daily trend of total prompts, unique users, avg prompts per user for 6 months
  </Tab>

  <Tab title="Growth / Marketing Lead">
    * Signup-to-activation conversion by channel (activation = 3+ prompts)
    * Channels bringing users with highest 30-day retention, not just signups
    * Free-to-paid conversion by `use_case_category` — which drives most upgrades?
    * Behavior of users from "AI for \[use case]" landing pages vs. generic signups
    * Viral coefficient: share/export action rate and downstream signup
    * Conversion funnel for content marketing vs. product-led referral acquisitions
    * Segments with highest quota-warning-to-upgrade ratio (pricing optimization targets)
    * Reactivation rate for re-engagement campaign recipients last month
    * Behavior difference: work email vs. personal email signups
    * Trial usage patterns that predict conversion with highest accuracy
  </Tab>

  <Tab title="Executive">
    * AI dashboard: DAU, prompts per user, satisfaction %, free-to-paid conversion, cost per active user (week-over-week and month-over-month)
    * Unit economics: how does usage-based cost scale with engagement?
    * Which AI capability is driving the most engagement growth?
    * Model quality vs. business metrics: does better AI equal better retention?
    * Biggest risk in our user base: any segment with declining engagement
  </Tab>
</Tabs>

## Recommended Data Connections

| Source               | What it adds                       |
| -------------------- | ---------------------------------- |
| Weights & Biases     | Model eval and experiment tracking |
| Sentry               | Error and latency monitoring       |
| Stripe               | Billing and usage-based pricing    |
| GitHub               | Deployment and release tracking    |
| Slack                | ML and product team alerts         |
| Snowflake / BigQuery | Model logs and cost data           |

## Key Takeaways

* Model quality and user retention are measurable together — connecting eval scores with engagement data gives ML teams a product-centric target to optimize toward.
* Cost-to-serve analysis only means something when it's paired with retention impact; high compute cost on a high-retention feature is a different problem than high compute cost on a feature users abandon.
* Reliability incidents have a lagged user impact — look at engagement trends in the days after an incident, not just the day of.
* Prompt patterns and use case categories are underused signals for both product positioning and fine-tuning decisions.
* The teams getting the most from this setup are the ones sharing data across ML, product, and growth — not keeping it siloed by function.

👉 **Next step**: See the [MCP by Industry](/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry) page for other industry guides, or visit [MCP Integration Pairings](/guides/guides-by-use-case/empower-your-team/mcp/integrations) to explore what each data connection unlocks.


# MCP for B2B SaaS
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/b2bsaas

Use Cases and Sample Prompts

B2B SaaS companies sit at the intersection of product usage and commercial outcomes — but those two worlds usually live in separate systems. The Mixpanel MCP server lets you combine digital analytics with CRM data, support tickets, billing records, and engineering tools, so you can answer the questions that matter most: who's ready to buy, who's at risk of churning, and what's actually driving expansion.

## Use Cases

<Note>
  **New to MCP?** Start with [Explore Data with AI](/guides/guides-by-use-case/empower-your-team/mcp) for setup instructions and foundational concepts before diving into industry-specific use cases.
</Note>

Each use case below shows a cross-system question your team can ask, the data sources it draws from, and what you can do with the answer.

### Product Usage × Sales Pipeline (PQL Scoring)

**The question**: Which trial users have the highest feature adoption, and what stage are they at in the Salesforce pipeline?

| Data source | What you're pulling              |
| ----------- | -------------------------------- |
| Mixpanel    | Feature usage, activation events |
| Salesforce  | Opportunity stage, lead score    |

Demographic fit tells you who a prospect is. Product engagement tells you whether they're actually getting value. Combining both gives your sales team a prioritization signal that's grounded in behavior — not just firmographics.

<Note>
  **Pro tip**: The most useful PQL threshold isn't always the one based on the most events — it's the one that correlates most strongly with conversion. Run this analysis before setting your PQL definition, not after.
</Note>

### Feature Adoption × Support Tickets (Churn Prediction)

**The question**: Are accounts with declining usage also generating more support tickets?

| Data source        | What you're pulling      |
| ------------------ | ------------------------ |
| Mixpanel           | Usage trends, retention  |
| Zendesk / Intercom | Ticket volume, sentiment |

Either signal alone is noisy. A support ticket might mean a frustrated user or a curious one. Declining usage might be a seasonal slowdown or a real disengagement. When both signals move together, you have a meaningful early warning — and time to intervene before the renewal conversation starts.

### Activation Funnel × Revenue Expansion

**The question**: Do accounts that complete all onboarding steps in week 1 have higher expansion revenue at 12 months?

| Data source      | What you're pulling   |
| ---------------- | --------------------- |
| Mixpanel         | Onboarding funnel     |
| Stripe / billing | MRR, expansion events |

Onboarding investment is often justified by intuition rather than data. This join gives you a number: accounts that hit activation milestone X in week 1 expand at Y% higher rates at 12 months. That's a number worth knowing before your next onboarding redesign.

### User Engagement × Account Health

**The question**: Which enterprise accounts have users who've gone inactive in the last 14 days?

| Data source | What you're pulling          |
| ----------- | ---------------------------- |
| Mixpanel    | User-level engagement        |
| CRM         | Account tier, CSM assignment |

Account health scores built on aggregate usage miss the user-level signal that matters most: when a champion goes quiet. This join surfaces individual user inactivity inside your highest-value accounts, routed to the right CSM before the account flags at renewal.

<Warning>
  **Pitfall**: Accounts where one user does all the activity look healthy in aggregate but carry significant key-person risk. Filter for accounts where a single user accounts for 80%+ of events — those are worth a proactive check-in regardless of overall engagement levels.
</Warning>

### Release Impact × Bug Reports

**The question**: After v3.2, which new features are driving the most support tickets relative to usage volume?

| Data source   | What you're pulling        |
| ------------- | -------------------------- |
| Mixpanel      | Feature usage post-release |
| Sentry / Jira | Error reports, bug tickets |

Usage volume and support ticket volume tell different stories about a release. A feature with high usage and high tickets is a quality problem. A feature with low usage and low tickets might be a discoverability problem. Knowing which is which shapes where you invest in the next sprint.

## Sample Prompts by Role

These are starting points. Adjust the time ranges, segments, and metrics to match your product and data.

<Tabs>
  <Tab title="Product Manager">
    * Show me a funnel from signup to workspace created to first invite to first report built, by plan type.
    * What's the weekly retention for users who completed 3+ key actions in their first session?
    * Which features have the highest usage on Enterprise vs. Pro plan?
    * What's the average time-to-value (how long to reach our "aha moment" event)?
    * Compare feature adoption between invited users vs. workspace creators.
    * What's the funnel from trial to activation milestone to upgrade conversation to paid conversion?
    * Show me the impact of our last release: new feature adoption and retention change.
    * Which features are most correlated with 30-day retention? Rank them.
    * What's the engagement pattern in the 2 weeks before upgrade?
    * How does onboarding completion differ for users who watch the tutorial vs. skip?
  </Tab>

  <Tab title="Data Analyst">
    * Pull the monthly cohort retention table for the past 12 months (M0 through M6).
    * What's the frequency distribution of our core action per week?
    * Segment all users by `company_size` and show engagement metrics for each.
    * Which user properties correlate strongest with long-term retention?
    * Show me the event taxonomy: all events with 30-day volume, sorted by frequency.
    * What data quality issues exist? Events with low property fill rates or inconsistent naming?
    * DAU trend for 6 months segmented by platform (web, iOS, Android, API)
    * What's the distribution of active days per month?
    * List all properties on "Feature Used" and top 20 values for `feature_name`.
    * Week-over-week trends for our top 10 events — any significant decline?
  </Tab>

  <Tab title="RevOps / Sales Lead">
    * Which trial accounts completed 3+ activation milestones this week?
    * Trial-to-paid conversion rate by acquisition channel for the past quarter?
    * Usage pattern difference between trials that convert vs. don't — what predicts conversion?
    * Which enterprise trials invited 5+ team members? Those are strong signals.
    * Average time from trial start to paid conversion, by `company_size`?
    * Accounts where usage increased 50%+ month-over-month (expansion candidates)
    * Which features are most used by accounts that expand within 12 months?
    * Trial accounts that hit PQL threshold this month but haven't been contacted?
    * Win rate for deals where the champion is a heavy user vs. outbound-sourced deals?
    * Engagement of pipeline accounts vs. churned accounts — what's the early warning signal?
  </Tab>

  <Tab title="Customer Success Manager">
    * Health check for \[Account Name]: WAU, feature adoption breadth, trend vs. baseline
    * Which accounts have seen a 20%+ usage decline over the past 30 days?
    * Feature adoption gap between my healthiest and at-risk accounts?
    * Accounts with users who haven't logged in for 14+ days but were previously active weekly?
    * Onboarding completion status for accounts started in the past 60 days?
    * Accounts only using 1–2 features — these are shallow adoption and at risk
    * Engagement summary for all accounts in my book, sorted by declining usage
    * Accounts where one user does all the activity — that's key-person risk
    * Support event pattern for my top 5 largest accounts?
    * This quarter's usage for \[Account Name] vs. last quarter — what changed?
  </Tab>

  <Tab title="Engineering Lead">
    * After our last deploy, did error event volume or rate change?
    * Which features have the highest latency-related events?
    * Adoption curve for the feature shipped 2 weeks ago (daily active users since launch)?
    * Trend in "Error Encountered" events over 90 days, by `error_type`?
    * Which platform has the highest crash or error events per session?
  </Tab>

  <Tab title="Executive">
    * Company dashboard: WAU, DAU/MAU ratio, activation rate, trial conversion, net retention (week-over-week and quarter-over-quarter)
    * Overall product health: engagement trends, feature adoption breadth, leading churn indicator
    * Which customer segment is growing fastest in product adoption?
    * Free-tier engagement vs. paid — are we converting our most engaged free users?
    * Leading indicator that an account will expand: what behavior shows up 30 days before?
  </Tab>
</Tabs>

## Recommended Data Connections

| Source               | What it adds                     |
| -------------------- | -------------------------------- |
| Salesforce / HubSpot | Pipeline and account context     |
| Stripe               | Billing, MRR, and expansion data |
| Zendesk / Intercom   | Support ticket correlation       |
| Slack                | Surface signals to GTM teams     |
| Sentry               | Error and stability monitoring   |
| Jira / Linear        | Product issue tracking           |
| Notion               | Product documentation and wikis  |

## Key Takeaways

* PQL models built on behavioral data outperform demographic scoring alone — product engagement is a more direct signal of value realized than firmographic fit.
* Declining usage and rising support tickets are each weak signals individually; when they move together in the same account, treat it as an early churn warning.
* Onboarding completion in week 1 has measurable long-term revenue impact — the data to prove it is already in your systems, it just requires the join.
* Key-person risk is one of the most common account health blind spots; aggregate usage scores hide it, user-level data surfaces it.
* Engineering leads rarely have a direct line to product usage data — release impact analysis usually requires a separate data pull or a handoff to an analyst. MCP makes it practical to answer those questions directly.

👉 **Next step**: See the [MCP by Industry](/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry) page for other industry guides, or visit [MCP Integration Pairings](/guides/guides-by-use-case/empower-your-team/mcp/integrations) to explore what each data connection unlocks.


# MCP for Ecommerce
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/ecommerce

Use Cases and Sample Prompts

Ecommerce teams often have behavioral data on one side and ad spend, inventory, and order data on the other — with no easy way to connect them. The Mixpanel MCP server lets you query across both, so you can calculate true acquisition costs, prioritize restocking decisions, and understand what actually drives repeat purchases.

## Use Cases

<Note>
  **New to MCP?** Start with [Explore Data with AI](/guides/guides-by-use-case/empower-your-team/mcp) for setup instructions and foundational concepts before diving into industry-specific use cases.
</Note>

Each use case below shows a cross-system question your team can ask, the data sources it draws from, and what you can do with the answer.

### Conversion Funnel × Ad Spend

**The question**: What's my real cost-per-acquisition by channel when I combine Mixpanel conversion data with Google Ads spend?

| Data source       | What you're pulling               |
| ----------------- | --------------------------------- |
| Mixpanel          | Conversion funnel, UTM properties |
| Google / Meta Ads | Spend, impressions, clicks        |

Click-through attribution overstates the contribution of channels that benefit from late-funnel assists. Combining Mixpanel's on-site conversion data with ad spend gives you a CAC that reflects what users actually did after they clicked — not just that they clicked.

### Product Page Engagement × Inventory

**The question**: Which products have high engagement but are running low on inventory?

| Data source      | What you're pulling          |
| ---------------- | ---------------------------- |
| Mixpanel         | Product view and cart events |
| Inventory system | Stock levels                 |

High-demand products that go out of stock mid-consideration don't just lose a sale — they break momentum for users who were close to converting. This join surfaces restocking priorities before they become lost revenue.

<Note>
  **Pro tip**: Run this analysis at the category level, not just the SKU level. A category trending up in views is a better signal for merchandising decisions than a single product spike.
</Note>

### Cart Abandonment × Customer Segment

**The question**: What's the cart abandonment rate for first-time vs. returning buyers, and at which step?

| Data source | What you're pulling          |
| ----------- | ---------------------------- |
| Mixpanel    | Checkout funnel              |
| CDP         | Segment membership, LTV tier |

First-time and returning buyers drop off for different reasons. First-timers often hesitate at trust signals — shipping costs, return policies, payment options. Returning buyers who abandon are a different problem: something interrupted or changed. Knowing which segment is abandoning where lets you design recovery campaigns that actually match the reason.

### Post-Purchase Behavior × Lifetime Value

**The question**: Which post-purchase actions predict the highest 12-month LTV?

| Data source      | What you're pulling  |
| ---------------- | -------------------- |
| Mixpanel         | Post-purchase events |
| Order management | Repeat purchase, LTV |

Not all first purchases are equal. Some customers browse once and never return; others become high-frequency buyers within 30 days. This join shows you which behaviors in the first session or two after purchase predict which outcome — so you can build onboarding flows and retention campaigns around the signals that actually matter.

<Warning>
  **Pitfall**: LTV calculations that only use purchase data miss the behavioral signals that precede churn. A customer who stops browsing before they stop buying is already at risk — the engagement data shows it earlier than the order data does.
</Warning>

## Sample Prompts by Role

These are starting points. Adjust the time ranges, segments, and metrics to match your product and data.

<Tabs>
  <Tab title="Product Manager">
    * Add-to-cart to purchase conversion rate by product category over 30 days
    * Checkout funnel by device type — where's the biggest mobile vs. desktop gap?
    * Which site search terms lead to the highest conversion rate?
    * Impact of "saved for later" feature: adoption rate and does it increase eventual purchase?
    * PDP to add to cart to purchase funnel for our top 5 categories
    * Average sessions before a first-time buyer purchases?
    * Product recommendation CTR compared to organic browse-to-cart?
    * Return initiation funnel — at which step do customers abandon?
    * Wishlist creation engagement pattern: does it predict higher LTV?
    * Which PDP elements (reviews viewed, size guide, image zoom) correlate most with conversion?
  </Tab>

  <Tab title="Data Analyst">
    * Monthly buyer cohort retention (repeat purchase rate at M1 through M12)
    * Purchase frequency distribution: orders per quarter for active customers?
    * Segment all users by `acquisition_source`: conversion rate, AOV, repeat purchase rate.
    * Which properties predict high LTV? Compare top 10% by order value vs. the rest.
    * All checkout events with daily volume for the past 90 days
    * Data quality issues: inconsistent product category values or missing properties?
    * Cart size distribution (items, value) for completed vs. abandoned carts
    * Session-to-purchase conversion by day of week and hour of day?
    * Behavior paths comparing mobile app vs. mobile web vs. desktop
    * Full event flow from landing page through purchase — most common happy path?
  </Tab>

  <Tab title="Growth / Marketing Lead">
    * Conversion rate by UTM campaign for 30 days (actual purchases, not just clicks)
    * Which channels have the highest repeat purchase rate (long-term value, not just first orders)?
    * Retention curve for Black Friday customers vs. organic?
    * Email win-back performance: open to click to visit to purchase conversion
    * Coupon users vs. full-price buyers — do discounts attract high or low LTV?
    * Landing pages with highest bounce-to-browse-to-buy conversion path?
    * True CAC factoring in on-site conversion rate per channel?
    * Top 10 organic entry pages and their revenue contribution this month
    * Referral program funnel: link click to signup to first purchase to referral sent?
    * Which segments are most responsive to promotions based on behavioral engagement?
  </Tab>

  <Tab title="Merchandising / Buyer">
    * Categories with highest view-to-cart and cart-to-purchase ratios?
    * Products with high page views but low add-to-cart — need better presentation or pricing?
    * Cross-sell patterns: which products are most commonly purchased together?
    * Seasonal demand by category compared to last year based on engagement trends
    * New arrivals from past 30 days trending highest in engagement
    * Price sensitivity: conversion rate across `price_range` for each category
    * Which collections or curated pages drive the most downstream purchases?
    * Relationship between scarcity signals ("only X left") and conversion rate
    * Top 20 most-viewed products with below-average conversion (optimization opportunities)
    * Product engagement difference by customer segment (first-time vs. VIP vs. lapsed)
  </Tab>

  <Tab title="Executive">
    * Commerce dashboard: revenue, conversion rate, AOV, new vs. returning mix, top category (week-over-week and year-over-year)
    * Funnel health: visit to PDP to add to cart to purchase with week-over-week trend
    * Which category is driving the most revenue growth this quarter?
    * Mobile vs. desktop conversion gap — is it improving?
    * Leading indicator for customer churn: which signal predicts they won't return?
  </Tab>
</Tabs>

## Recommended Data Connections

| Source                | What it adds                        |
| --------------------- | ----------------------------------- |
| Shopify / BigCommerce | Order and catalog data              |
| Stripe                | Payment and subscription data       |
| Google Ads / Meta Ads | Ad spend and attribution            |
| Klaviyo / Braze       | Email and SMS campaign data         |
| Google Sheets         | Inventory and promotional calendars |

## Key Takeaways

* True CAC only makes sense when you pair ad spend with on-site conversion data — click-through attribution alone misattributes credit across the funnel.
* Inventory and engagement data belong together; knowing which products are trending in views before they go out of stock is a more actionable signal than reacting after the fact.
* Cart abandonment analysis works best when it's segmented — first-time and returning buyers drop off for different reasons and need different recovery approaches.
* Post-purchase behavioral signals predict long-term LTV earlier than order data alone; customers who stop browsing often stop buying shortly after.
* The Merchandising / Buyer role is underserved by most analytics setups — MCP makes product-level behavioral data accessible without requiring a data request.

👉 **Next step**: See the [MCP by Industry](/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry) page for other industry guides, or visit [MCP Integration Pairings](/guides/guides-by-use-case/empower-your-team/mcp/integrations) to explore what each data connection unlocks.


# MCP for Finance
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/finance

Use Cases and Sample Prompts

Financial services teams often have behavioral and business data — but they live in separate systems. The Mixpanel MCP server lets you query across both at once, so you can connect what users did in your product to what that means for revenue, risk, and compliance.

## Use Cases

<Note>
  **New to MCP?** Start with [Explore Data with AI](/guides/guides-by-use-case/empower-your-team/mcp) for setup instructions and foundational concepts before diving into industry-specific use cases.
</Note>

Each use case below shows a cross-system question your team can ask, the data sources it draws from, and what you can do with the answer.

### Account Opening Funnel × CRM Pipeline

**The question**: Which high-value prospects are dropping off during account opening, and what's their Salesforce lead score?

| Data source | What you're pulling       |
| ----------- | ------------------------- |
| Mixpanel    | Funnel events             |
| Salesforce  | Lead and opportunity data |

When drop-off concentrates among high-AUM prospects, the problem isn't just a UX issue — it's a revenue problem. Combining funnel data with lead scores tells you where to focus first.

### Feature Adoption × Transaction Revenue

**The question**: Do users who adopt mobile check deposit generate more monthly transaction volume than those who don't?

| Data source                      | What you're pulling  |
| -------------------------------- | -------------------- |
| Mixpanel                         | Feature usage events |
| Payment processor / core banking | Transaction data     |

This is how you move from "people use this feature" to "this feature drives revenue." Use the answer to prioritize your roadmap around features with measurable financial impact — not just high engagement.

<Note>
  **Pro tip**: Run this analysis across several features at once to build a clearer picture of which behaviors actually correlate with transaction volume. One feature rarely tells the whole story.
</Note>

### Session Behavior × Fraud Signals

**The question**: Are there behavioral patterns in Mixpanel session data that correlate with flagged fraud cases?

| Data source            | What you're pulling             |
| ---------------------- | ------------------------------- |
| Mixpanel               | Session replay, event sequences |
| Fraud detection system | Flagged accounts                |

Traditional fraud detection flags transactions after the fact. Behavioral patterns — unusual navigation sequences, rapid form completion, atypical device switching — can show up earlier. This join gives your risk team a behavioral layer to work with alongside transaction signals.

<Warning>
  **Pitfall**: Behavioral patterns are correlational, not causal. Use them to triage and investigate, not to automatically flag or restrict accounts.
</Warning>

### Onboarding Completion × KYC Status

**The question**: What's the completion rate for users stuck in KYC verification, and how does it vary by document type?

| Data source             | What you're pulling |
| ----------------------- | ------------------- |
| Mixpanel                | Onboarding funnel   |
| KYC / compliance system | Verification status |

KYC is one of the most common places onboarding falls apart in regulated products — and it's one of the hardest to instrument well. This join shows you exactly which document types or verification steps are driving abandonment, so you can address friction without compromising compliance requirements.

## Sample Prompts by Role

These are starting points. Adjust the time ranges, segments, and metrics to match your product and data.

<Tabs>
  <Tab title="Product Manager">
    * Show me the account opening funnel with conversion rates at each step, broken down by account type.
    * What's the 30-day retention for users who completed their first trade in week 1 vs. those who didn't?
    * Which features have the highest adoption rate among users who signed up in the past 60 days?
    * Compare onboarding completion for users acquired through paid ads vs. organic referral.
    * What's the average time from signup to first deposit, and how has that trended over 6 months?
    * Show me the top 5 events performed by users who are still active at Day 90.
    * Which onboarding step has the highest drop-off, and has it changed since our last release?
    * What's the funnel from app download to account created to KYC completed to first funded, by platform?
    * How does feature usage differ between users in the \$0–1K balance tier vs. \$10K+ tier?
    * What percentage of users who activated push notifications are retained at Day 30?
  </Tab>

  <Tab title="Data Analyst">
    * Pull the weekly trend of daily active users segmented by account type for the past 12 months.
    * What's the frequency distribution for login events — how many times per week do active users log in?
    * Run a retention analysis for the January 2026 signup cohort, broken down by acquisition channel.
    * Which user properties are most predictive of 90-day retention? Compare top decile vs. churned.
    * Show me event counts for all transaction-related events over the past quarter, grouped by week.
    * What are the top data quality issues in our project right now?
    * Compare segmentation of users by region and account type — where are our highest-engagement cohorts?
    * What's the correlation between number of features adopted in the first 14 days and 6-month retention?
    * Pull property values for `acquisition_channel` and show distribution of signups across channels for Q1.
    * List all events containing "transfer" and show their 30-day usage trends.
  </Tab>

  <Tab title="Growth / Marketing">
    * What's our signup-to-funded-account conversion rate by UTM campaign over the past 90 days?
    * Which acquisition channels have the highest Day 7 retention (not just signups, but users who came back)?
    * Show me the weekly new user trend overlaid with our activation rate.
    * How does the referral program funnel perform compared to paid acquisition?
    * What's the reactivation rate for users who received the win-back campaign last month?
    * Which landing page leads to the highest rate of account funding?
    * Compare behavior of users who signed up during our holiday promotion vs. non-promotional periods.
    * What's the cost-per-funded-account factoring in drop-off between signup and first deposit?
    * Show me top 3 acquisition channels by volume and their 30/60/90 day retention curves.
    * Which user segments have the highest cross-sell potential into investment products?
  </Tab>

  <Tab title="Customer Success / Ops">
    * Which enterprise accounts have seen a decline in weekly active users over the past 30 days?
    * What's the health score breakdown for accounts in the \$50K+ ACV tier?
    * Show me the top support-related events (password resets, failed transactions) and their weekly trend.
    * Which accounts have users who haven't logged in for 14+ days?
    * What's the feature adoption gap between our most engaged and least engaged accounts?
    * Pull the usage summary for \[Account Name], including features used and activity trend this quarter.
    * Are there accounts where usage dropped below historical average by more than 25%?
    * Which newly onboarded accounts from the past 60 days haven't hit activation milestones?
    * Show me the retention curve for accounts managed by each CSM — are there patterns?
    * What's the satisfaction signal trend for our top-tier accounts?
  </Tab>

  <Tab title="Executive">
    * Snapshot: total active users, 7-day retention, signup-to-activation rate (this week vs. last week vs. last month)
    * What's our overall funnel health — end-to-end from first visit to funded account with week-over-week trend?
    * Which product area is driving the most engagement growth this quarter?
    * How does mobile vs. desktop compare in terms of activation and retention?
    * What's the leading indicator for churn — which behavioral signal shows up first?
  </Tab>
</Tabs>

## Recommended Data Connections

| Source               | What it adds                      |
| -------------------- | --------------------------------- |
| Salesforce           | CRM and pipeline context          |
| Stripe               | Payment and transaction data      |
| Slack                | Alert teams on key signals        |
| Google Sheets        | Compliance tracking and reporting |
| Snowflake / BigQuery | Data warehouse joins              |

## Key Takeaways

* Connect Mixpanel funnel data with CRM records to identify where high-value prospects drop off — not just where drop-off is highest.
* Feature adoption means more when you can tie it to transaction volume or revenue outcomes, not just engagement metrics.
* Behavioral session data can complement fraud detection systems, giving risk teams earlier signals to investigate.
* KYC and compliance steps are often the highest-friction points in onboarding — instrument them carefully and join with verification status to find what's actually causing abandonment.
* The MCP server handles the cross-system query; the value comes from knowing which question to ask.

👉 **Next step**: See the [MCP by Industry](/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry) page for other industry guides, or visit [MCP Integration Pairings](/guides/guides-by-use-case/empower-your-team/mcp/integrations) to explore what each data connection unlocks.


# MCP for Healthcare
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/healthcare

Use Cases and Sample Prompts

Healthcare organizations track patient engagement across portals, telehealth apps, and wellness platforms — but behavioral data rarely lives next to scheduling, outcomes, or operational data. The Mixpanel MCP server lets you combine digital analytics with those systems to understand what drives appointment adherence, care plan compliance, and long-term patient retention.

<Warning>
  **Compliance note**: All data accessed through the Mixpanel MCP server respects your existing project permissions and data governance settings. For HIPAA-covered entities, ensure PHI is handled according to your BAA with Mixpanel and that any joined data sources maintain equivalent protections.
</Warning>

## Use Cases

<Note>
  **New to MCP?** Start with [Explore Data with AI](/guides/guides-by-use-case/empower-your-team/mcp) for setup instructions and foundational concepts before diving into industry-specific use cases.
</Note>

Each use case below shows a cross-system question your team can ask, the data sources it draws from, and what you can do with the answer.

### Portal Engagement × Appointment Adherence

**The question**: Do patients who actively use the patient portal have higher appointment completion rates?

| Data source       | What you're pulling |
| ----------------- | ------------------- |
| Mixpanel          | Portal usage events |
| Scheduling system | Appointment data    |

Portal investment is often justified by engagement metrics alone. This join gives you a more meaningful number: whether portal-engaged patients actually show up to their appointments at higher rates. That's the metric that justifies continued investment and shapes outreach strategy for low-engagement patients.

### Telehealth UX × Patient Satisfaction

**The question**: Which parts of the telehealth flow have the highest drop-off, and how do those correlate with post-visit satisfaction scores?

| Data source     | What you're pulling      |
| --------------- | ------------------------ |
| Mixpanel        | Telehealth funnel events |
| Survey platform | NPS / CSAT data          |

Drop-off in a telehealth flow could mean a technical problem, a UX problem, or a patient who changed their mind. Satisfaction scores help you distinguish between them. When a funnel step with high drop-off also correlates with low CSAT, you have a clear case for prioritization.

<Note>
  **Pro tip**: Segment this analysis by device type. Mobile and desktop patients often experience telehealth flows differently, and the friction points are rarely the same across platforms.
</Note>

### Feature Adoption × Care Plan Compliance

**The question**: Are patients who use the medication reminder feature more likely to complete their care plan milestones?

| Data source           | What you're pulling  |
| --------------------- | -------------------- |
| Mixpanel              | Feature usage        |
| EHR / care management | Plan completion data |

Clinical value is difficult to demonstrate from product data alone. This join connects a specific feature — medication reminders, secure messaging, educational content — to downstream care outcomes. That's the evidence your clinical and executive stakeholders need to support continued investment in digital health features.

### Onboarding Flow × Patient Demographics

**The question**: How does onboarding completion vary by age group and device type, and where are older patients dropping off?

| Data source          | What you're pulling                  |
| -------------------- | ------------------------------------ |
| Mixpanel             | Onboarding funnel, device properties |
| Patient demographics | Age, location                        |

Digital health tools are only valuable if patients can actually use them. Onboarding completion data segmented by age and device reveals where specific populations are struggling — and whether the experience is creating barriers for the patients who often need the most support.

<Warning>
  **Pitfall**: Aggregate onboarding completion rates can look healthy while masking significant drop-off in specific age groups or device types. Always segment before drawing conclusions about onboarding performance.
</Warning>

## Sample Prompts by Role

These are starting points. Adjust the time ranges, segments, and metrics to match your product and data.

<Tabs>
  <Tab title="Product Manager">
    * Show me the telehealth visit completion funnel broken down by device type over the last 90 days.
    * What's the 30-day retention for patients who completed onboarding in one session vs. multiple?
    * Which features have the highest weekly active usage among patients aged 65+?
    * Compare the appointment booking funnel for new patients vs. returning patients.
    * What's the average time from account creation to first appointment booked?
    * Which onboarding step has the highest abandonment, and does it vary by insurance type?
    * Show me the adoption curve for our medication reminder feature since launch.
    * What's the funnel from portal login to message sent to response viewed, by device type?
    * How does feature adoption differ between provider-referred vs. self-signup patients?
    * What percentage of patients who use secure messaging are retained at 90 days?
  </Tab>

  <Tab title="Data Analyst">
    * Run a retention analysis for the Q4 2025 patient cohort, segmented by primary care type.
    * What are the top 10 most frequent events and their week-over-week trends for 6 months?
    * Show me the frequency distribution for portal logins — how often do active patients log in per month?
    * Which user properties are most different between patients retained at Day 60 vs. churned?
    * Pull all events containing "telehealth" and show their daily trend for the past quarter.
    * What data quality issues exist? Events with inconsistent property values or missing fields?
    * Compare engagement metrics across our three patient segments.
    * What's the median session duration by platform, and has it changed since our last app update?
    * List all properties on "Appointment Booked" and show distribution of values.
    * Run a segmentation of patients by `age_group` and show the top 5 events for each.
  </Tab>

  <Tab title="Clinical / Operations Lead">
    * What percentage of patients are completing full care plan milestones each month? Show the trend.
    * Which departments have the lowest appointment completion rates based on portal engagement?
    * Are patients who engage with educational content more likely to complete follow-up visits?
    * Show me the weekly trend of prescription refill requests through the portal vs. phone calls.
    * What's the no-show rate for telehealth vs. in-person, correlated with portal engagement?
    * Which patient populations are underutilizing the patient portal?
    * What's the average time between symptom checker usage and appointment booking?
    * Show me care plan compliance rates for patients using the medication reminder vs. those not.
    * How many patients actively use secure messaging, and what's the provider response time trend?
    * Which wellness program features have the highest engagement?
  </Tab>

  <Tab title="Executive">
    * Patient engagement dashboard: monthly active patients, portal adoption, telehealth completion, 30-day retention (month-over-month and year-over-year)
    * What's the overall digital health ROI story — engagement vs. care adherence metrics?
    * Which patient segments are growing fastest in digital adoption?
    * How does mobile app engagement compare to the web portal?
    * What are the leading indicators that a patient will disengage from our platform?
  </Tab>
</Tabs>

## Recommended Data Connections

| Source               | What it adds                       |
| -------------------- | ---------------------------------- |
| Google Sheets        | Operational and outcomes tracking  |
| Slack                | Care team alerts and escalations   |
| Notion               | Clinical workflow documentation    |
| Jira                 | Product issue tracking             |
| Snowflake / BigQuery | De-identified data warehouse joins |

## Key Takeaways

* Portal engagement and appointment adherence are measurable together — that connection is the clearest ROI argument for digital health investment.
* Telehealth drop-off analysis only becomes actionable when paired with satisfaction data; without it, you can't distinguish technical friction from patient behavior.
* Feature adoption tied to care plan compliance is the metric that earns clinical buy-in — product engagement alone rarely moves that conversation.
* Onboarding completion rates must be segmented by age and device to be meaningful; aggregate numbers hide the access gaps that matter most in healthcare contexts.
* The Clinical / Operations Lead is often the decision-maker for portal and telehealth investment, but rarely has direct access to behavioral data — MCP makes that accessible without a data engineering request.

👉 **Next step**: See the [MCP by Industry](/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry) page for other industry guides, or visit [MCP Integration Pairings](/guides/guides-by-use-case/empower-your-team/mcp/integrations) to explore what each data connection unlocks.


# MCP for Media & Entertainment
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry/media

Use Cases and Sample Prompts

Media and entertainment companies track content consumption well — but consumption data alone doesn't tell you what drives a subscriber to renew or cancel. The Mixpanel MCP server lets you combine behavioral analytics with billing data, content metadata, and ad performance, so you can connect what users watch or read to what actually keeps them subscribed.

## Use Cases

<Note>
  **New to MCP?** Start with [Explore Data with AI](/guides/guides-by-use-case/empower-your-team/mcp) for setup instructions and foundational concepts before diving into industry-specific use cases.
</Note>

Each use case below shows a cross-system question your team can ask, the data sources it draws from, and what you can do with the answer.

### Content Consumption × Subscriber Retention

**The question**: Which content genres have the strongest correlation with 90-day subscriber retention?

| Data source    | What you're pulling                        |
| -------------- | ------------------------------------------ |
| Mixpanel       | Content play/read events, genre properties |
| Billing system | Subscription status, churn date            |

High engagement with a piece of content doesn't mean it drives retention. Some genres spike in short-term plays but don't bring subscribers back. This join shows you which content categories are actually worth investing in for long-term retention — not just what gets clicks.

<Note>
  **Pro tip**: Run this analysis by subscriber cohort, not just overall. What retains a subscriber who joined during a major release may be different from what retains an organic signup.
</Note>

### Engagement Depth × Ad Revenue

**The question**: Do users consuming 3+ pieces per session generate more ad revenue?

| Data source | What you're pulling           |
| ----------- | ----------------------------- |
| Mixpanel    | Session depth, content events |
| Ad server   | Impression revenue, CPM data  |

Ad-supported tiers live or die on session depth. Knowing which content types and discovery paths lead to multi-piece sessions — and how that translates to impression revenue — tells you where to invest in the recommendation experience and where deeper sessions are being left on the table.

### Onboarding × Content Discovery

**The question**: Users who engage with recommendations in their first session — how much higher is Day 7 retention?

| Data source | What you're pulling                      |
| ----------- | ---------------------------------------- |
| Mixpanel    | Onboarding events, recommendation clicks |
| Content CMS | Recommendation algorithm metadata        |

Recommendation engines are expensive to build and hard to evaluate. This join gives you a direct measure of their impact on early retention — so you can justify continued investment with data rather than assumptions, and identify which recommendation surfaces are actually working.

<Warning>
  **Pitfall**: First-session content engagement is strongly influenced by what's surfaced on the home screen, not just the recommendation engine. Make sure you're distinguishing between recommendation clicks and browse-initiated plays before drawing conclusions about algorithm performance.
</Warning>

### Platform Usage × Churn Prediction

**The question**: What usage patterns in the 30 days before churn distinguish churners from retained subscribers?

| Data source | What you're pulling                 |
| ----------- | ----------------------------------- |
| Mixpanel    | Usage frequency, feature engagement |
| Billing     | Churn events, plan downgrades       |

Churn prediction models built on billing data alone catch cancellations too late. Behavioral signals — declining session frequency, shorter session duration, fewer content completions — show up earlier. This join gives you the leading indicators you need to intervene before a subscriber decides to leave.

## Sample Prompts by Role

These are starting points. Adjust the time ranges, segments, and metrics to match your product and data.

<Tabs>
  <Tab title="Product Manager">
    * D1/D7/D30 retention for free trial vs. direct subscription signups?
    * Which onboarding steps have the highest drop-off for new subscribers?
    * Content completion rate by type (video, article, podcast) over 90 days
    * Average session depth and its trend this quarter?
    * Engagement of users who set preferences during onboarding vs. skipped?
    * Funnel from signup to first content to 5th content to paid subscription?
    * Engagement by discovery method: search vs. recommendations vs. browse?
    * Adoption rate for new playlist/collection feature since launch?
    * Notification-enabled users retained at Day 30 vs. not?
    * Average time between subscribing and first content interaction?
  </Tab>

  <Tab title="Data Analyst">
    * Monthly cohort subscriber retention table (M0 through M6 for 12 months)
    * Content consumption frequency distribution per week for active users?
    * Segment users by `subscription_tier`: sessions, content consumed, duration for each.
    * Genres ranked by completion rate?
    * Daily content play/read volume for 6 months by `content_type`
    * Data quality: content events missing genre or `content_id`?
    * Distribution of active days per month?
    * Median session duration by platform and day of week?
    * Top 50 content items this month: genre, completion rate, engagement time
    * Consumption patterns of subscribers who churned in 60 days vs. renewed?
  </Tab>

  <Tab title="Content Strategy / Editorial">
    * Which genres drive highest 90-day subscriber retention? Rank them.
    * Top 20 most-consumed content this month with audience demographics
    * Content discovery pattern: how do users find content they complete?
    * Highest "binge signal" (3+ episodes/articles consumed in one session)?
    * New release performance in first 7 days vs. catalog content?
    * Underserved genres: high search volume but low content completion?
    * Editorial picks vs. algorithmic recommendations: completion rate comparison?
    * Long-form vs. short-form: which is growing fastest in engagement?
    * Cross-genre pattern: after consuming genre A, what do they consume next?
    * Content performance difference between free-tier and paid subscribers?
  </Tab>

  <Tab title="Executive">
    * Platform dashboard: subscribers, DAU/MAU, content volume, churn rate, top genre (month-over-month and year-over-year)
    * Subscriber lifecycle: trial to paid to 3-month retained to 12-month retained funnel?
    * Which content investment is driving the most subscriber growth this quarter?
    * Multi-platform engagement: are smart TV users more retained than mobile?
    * Leading indicator of churn: which engagement drop predicts cancellation 30 days out?
  </Tab>
</Tabs>

## Recommended Data Connections

| Source                | What it adds                      |
| --------------------- | --------------------------------- |
| Stripe / App Store    | Subscription and billing data     |
| CMS / Content DB      | Content metadata and catalog      |
| Google Ads / Meta Ads | Audience and ad performance       |
| Slack                 | Editorial and product team alerts |
| Notion                | Content strategy documentation    |

## Key Takeaways

* Short-term content engagement and long-term subscriber retention don't always correlate — the join between play events and billing data shows which genres actually earn renewals.
* Session depth is the key lever for ad revenue on free tiers; knowing which content and discovery paths drive multi-piece sessions is more actionable than average session length alone.
* Recommendation engine impact is measurable: first-session recommendation engagement vs. Day 7 retention is a direct test of whether the algorithm is doing its job.
* Churn prediction built on behavioral signals gives you a 30-day window to intervene; billing-based detection gives you none.
* The Content Strategy / Editorial role is often data-poor despite being responsible for the product's most expensive decisions — this is where MCP adds the most immediate value.

👉 **Next step**: See the [MCP by Industry](/guides/guides-by-use-case/empower-your-team/mcp/mcp-by-industry) page for other industry guides, or visit [MCP Integration Pairings](/guides/guides-by-use-case/empower-your-team/mcp/integrations) to explore what each data connection unlocks.


# Use Mixpanel Agent to Go From Question to Decision, Faster
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mixpanel-agent



**Mixpanel Agent** is an AI analyst built directly into Mixpanel. Ask it a question or give it a task and it interprets your intent, selects the right tools, and returns an answer without you specifying each step.

You use it in two ways. The first is conversational: ask it a question, describe what you want to see, and it responds in the moment. The second is through agents you configure: set one up once and it runs on your behalf — monitoring, explaining, interpreting — without you having to ask each time. You'll find Mixpanel Agent in the side navigation for a full-page experience, or as a contextual panel you can open alongside any report or board.

<Frame>
  <img alt="image" />
</Frame>

This guide covers how to get the most out of each capability and how to migrate workflows you're already running today. If you're looking to query Mixpanel from an external AI tool like Claude or ChatGPT, see [Use Mixpanel MCP](/guides/guides-by-use-case/empower-your-team/mcp) instead.

## See it in action

New to Mixpanel Agent? Take a quick interactive walkthrough before diving into the details.

<Frame>
  <iframe title="Navattic walkthrough" />
</Frame>

> Note: The interactive demo above isn’t supported on smaller screens, but you can [click here](https://mixpanel.navattic.com/smr0zaw) to open the experience in a new window.

## Before you get started

Two project-level settings shape how all four capabilities behave.

### Business Context

Business Context is a shared layer where your team defines what Mixpanel can't infer from raw events: key metric definitions, fiscal calendar, launch history, team structure. Every AI surface reads it automatically.

Without it, AI answers are generic. With it, Mixpanel Agent knows your context — that "activation" means a user completed a key value moment, or that a drop on November 1 isn't anomalous because it's the day after a promo ended. For setup instructions, see the [Business Context documentation](/docs/business-context).

<Note>
  **Pro tip:** Start with your primary metric definitions and your fiscal calendar. Those two entries eliminate many of the common sources of AI misinterpretation.
</Note>

### Verified Mode

If your project has inconsistent event naming, duplicate metrics, or unverified events, the AI will work with what it finds — and two people asking the same question may get different answers. Verified Mode is how admins control that.

When it's on, all AI features are restricted to [verified data](/docs/data-governance/lexicon#verify-data): events, metrics, behaviors, and cohorts your team has explicitly reviewed in Lexicon. Unverified data stays in your project; it's just off-limits to AI. Users querying AI features will see a notice that results are limited to verified data — this is intentional, so they know it's a setting, not a Mixpanel limitation.

This is primarily an enterprise concern. It's most valuable when you're rolling out AI access broadly — to PMs, engineers, and stakeholders who may not know the difference between `checkout_complete` and `checkout_complete_v2`.

The tradeoff: Verified Mode puts the burden of verification on admins. If your team ships events faster than they get verified, the agents will feel incomplete. Before enabling it, make sure your verification workflow can keep pace. If it can't, the default experience, where AI prioritizes verified and high-usage data without being restricted to it, is probably the better call.

<Note>
  **Pro tip:** Before enabling Verified Mode, audit your verified events against the queries your team runs most often. Get your high-traffic events verified first, then enable the mode.
</Note>

***

## What you can do with Mixpanel Agent

Mixpanel Agent gives you four capabilities. They're designed to work together, but each one stands on its own.

| Capability             | What it replaces                                | Best for                                                                    |
| :--------------------- | :---------------------------------------------- | :-------------------------------------------------------------------------- |
| **Ask Mixpanel Agent** | Hours of query-building and context-switching   | Anyone who needs a quick answer or a new view without starting from scratch |
| **RCA Agent**          | 2–3 hours of manual segment slicing             | PMs and analysts investigating a metric shift                               |
| **KPI Agent**          | Weekly manual metric reporting                  | Anyone accountable for a specific number                                    |
| **Experiments Agent**  | Hours of manual setup and result interpretation | PMs and engineers running A/B tests                                         |

They map to four distinct moments in how you work with data: getting an answer, explaining a change, staying close to a metric, and running experiments with confidence.

**The full loop in practice:** A stakeholder asks for a view of onboarding performance after a recent flow change. Someone asks Mixpanel Agent to build it — it's ready in minutes. The PM notices activation dropped 8% and triggers RCA, which traces it to a new onboarding variant. The team pauses the variant and uses the Experiments Agent to interpret the results and roll back. The PM then sets up the KPI Agent on activation rate to watch the recovery.

<Note>
  **Pro tip:** Your judgment is still in the middle of that loop. What the four capabilities remove is the mechanical work surrounding the decisions.
</Note>

***

## Ask Mixpanel Agent

Open Mixpanel Agent from anywhere and ask in plain language. A single prompt can run an analysis, build a report, create a cohort, or walk you through session replays without you specifying each step. The Agent automatically picks up your current page as context, so you don't need to describe your setup first.

<Frame>
  <img alt="image" />
</Frame>

### When to use it

* You need a quick answer without opening a report
* A stakeholder asked a question you don't have a board for yet
* You want to explore an area quickly before deciding whether it's worth deeper instrumentation

### How to use it

A few things you can ask:

* **Data questions:** "Which acquisition channel has the best 30-day retention?" or "How did retention change after the onboarding update?"
* **Build requests:** "Build me a dashboard for our referral program — invites sent, signups from referrals, conversion rate, breakdown by channel." The Agent generates a full multi-chart board. Treat it as a first draft and review the events before saving.
* **Analysis:** "Compare mobile vs. desktop checkout conversion" or "What's the drop-off in our signup funnel?"

<Note>
  **Pro tip:** The more your Business Context is configured, the better the answers. If the Agent knows what "activation" means at your company, it uses the right events — not its best guess.
</Note>

### In practice

Marcus leads growth at a consumer app. His VP asks for a view of referral program performance — something that would normally take an hour to build. He asks Mixpanel Agent: "Show me referral program performance — invites sent, signups from referrals, conversion rate, and breakdown by referral channel." A six-chart board comes back in under a minute. He fixes one event mapping and sends the link before end of day.

***

## RCA Agent

When a metric moves, the RCA Agent tells you why. Trigger it from an Insights report, an alert, or directly through Mixpanel Agent, and it generates a board with contribution factor analysis, ranked dimensions, an AI interpretation, confidence levels, and suggested next steps.

This is reactive by design — it runs when you ask it to.

<Frame>
  <img alt="image" />
</Frame>

### When to use it

* A chart moved and you want an explanation without 30 minutes of manual segment slicing
* An alert fired and you need to know whether it's signal or noise before escalating
* You want a structured, shareable artifact, not just a hypothesis

### How to use it

Trigger the RCA Agent from three entry points:

* **From an Insights report:** Trigger RCA directly when you see a metric shift. The Agent analyzes the visible change in context.
* **From an alert:** Launch RCA from the notification. Detection and diagnosis in one step.
* **From Mixpanel Agent:** Ask "why did this metric drop?" and the Agent routes it to RCA and returns a structured explanation.

<Note>
  **Pro tip:** You can tell RCA which properties to always consider. Go to **Project Settings → AI Settings** to prioritize the dimensions most relevant to your team's analysis.
</Note>

### What you get back

* **Contribution factor analysis** — which dimensions explain the most variance in the shift
* **Ranked dimensions** — segments or properties most likely driving the change, ordered by significance
* **AI interpretation** — a plain-language explanation of what the analysis shows
* **Confidence levels** — how strongly the data supports each finding
* **Suggested next steps** — where to look or what to test next

After reviewing an RCA board, you can rate its accuracy. That feedback improves future results for your project.

<Note>
  **Pro tip:** The RCA Agent uses your Business Context when it's configured — pulling from both your Organization and Project settings. Cyclical patterns, seasonality, and known launches are all factored into its reasoning, so a traffic spike on Black Friday gets interpreted differently than an unexplained one.
</Note>

### In practice

Priya is a PM at a SaaS company. Checkout completion dropped 9% week-over-week. She triggers RCA from the Insights report. Top contribution factor: users on iOS 17.4, 61% of the variance, starting Friday — the same day a payment SDK update shipped. She sends the board to engineering: "SDK-related, iOS 17.4, started Friday, confidence is high." They're investigating within the hour.

***

## KPI Agent

The KPI Agent monitors a metric you care about and delivers a digest to you on a schedule you set. Instead of opening a dashboard to check whether something moved, it comes to you — with context, not just a number.

### When to use it

* You own a KPI and need to stay informed without opening a dashboard every day
* You send a weekly metric update to stakeholders and want to stop building it manually
* You want a digest that reflects what matters to you, not just raw numbers
* You track a KPI across many segments — regions, facilities, accounts — and want one digest that ranks them instead of one alert per value

### How to use it

1. Set it up from the Automation creation flow, or just ask Mixpanel Agent — either way it starts as a Draft you activate when you're ready
2. Choose the metric you want to monitor, and optionally a property to break it down by — the digest surfaces the top and bottom performing segments alongside the overall number
3. Set your cadence — daily, weekly, or monthly
4. Choose your delivery destination — Slack or email
5. Use "run now" to preview the digest before committing to a cadence

<Warning>
  The KPI Agent supports [Insights](/docs/reports/insights)-based queries on a daily, weekly, or monthly cadence. Funnel and Retention report support is coming soon.
</Warning>

### In practice

Lena owns weekly active users at a fintech company. Every Thursday she pulled the number manually, wrote context, and posted a Slack update. She sets up the KPI Agent on her WAU query with a Wednesday evening delivery. The Thursday update now takes 90 seconds instead of 20 minutes.

***

## Experiments Agent

Running an experiment has always required statistical knowledge most PMs don't have — choosing the right confidence level, understanding what a health check failure means, knowing whether a 4% lift is significant enough to ship.

The Experiments Agent works alongside you inside the [experiments](/docs/experiments) and [feature flags](/docs/featureflags) pages. Ask it to help configure an experiment, explain results in plain language, or roll out a winner. It's a conversation, not a form.

### When to use it

* You're setting up a new experiment and want to make sure it's configured correctly before launch
* Your experiment has results and you need to know what they mean and what to do next
* You want to ship a winning variant without navigating the decision modal yourself

### How to use it

Open Mixpanel Agent on any experiment or feature flag page.

**Setting up an experiment:** The Agent walks you through three questions — your hypothesis, your primary success metric, and how long it should run. Everything else (experiment name, variant split, confidence threshold, statistical defaults) the Agent handles. It presents the full configuration for your approval before creating anything.

**Interpreting results:** Ask the Agent to summarize your results and it reads the full experiment — your hypothesis, every metric, the statistical output — and returns a plain-language verdict: what happened, whether it's significant, and a clear recommendation to ship, iterate, or kill.

**Rolling out a winner:** After the Agent gives you a results summary, tell it to ship the winner. It concludes the experiment and updates the feature flag. You don't have to touch the decision modal.

<Note>
  **Pro tip:** The more specific your hypothesis, the better the Agent's defaults and interpretation. "If we simplify checkout to one page, purchase conversion will increase because fewer steps reduce drop-off" gives the Agent more to work with than "test the checkout flow."
</Note>

<Warning>
  The Agent reads the data in your experiment. If your experiment was misconfigured before launch — wrong metric, insufficient sample size — the Agent will flag what it sees, but it can't fix what already happened. Use it during setup, not just at results time.
</Warning>

### In practice

Dev is an engineer at a fintech company. His team's experiment on the savings goal flow has results — p-values, confidence intervals, a table of metrics — but nobody knows whether to ship the treatment or not.

He opens Mixpanel Agent on the results page and asks it to summarize. The Agent comes back: the treatment increased savings goal completion by 3.1%, both guardrail metrics passed, recommendation is to ship. It flags that session length trended down slightly and suggests a follow-up test.

The PM sends the summary to the VP instead of the raw stats table. The decision gets made in the same meeting.

***

## Migrating your existing workflows

Mixpanel Agent doesn't replace how you think about your data. It replaces the mechanical work between the question and the answer — and it makes some workflows practical that historically weren't.

| If you currently...                                                    | Migrate to...      | What changes                                                                                                     |
| :--------------------------------------------------------------------- | :----------------- | :--------------------------------------------------------------------------------------------------------------- |
| Send Board Subscriptions to stakeholders on a schedule                 | KPI Agent          | The digest includes interpretation, not just numbers.                                                            |
| Manually pull a metric each week and write a summary                   | KPI Agent          | The pull and the summary are automated. Your job is to review and act.                                           |
| Open Mixpanel every morning to check if anything moved                 | KPI Agent          | It comes to you — daily, weekly, or monthly, via Slack or email. You know where to dig in.                       |
| Investigate an alert by manually building breakdowns                   | RCA Agent          | The investigation runs automatically. You get a ranked explanation instead of a starting point.                  |
| Build boards from scratch or browse templates to find a starting point | Ask Mixpanel Agent | Describe your question. The board is your first draft.                                                           |
| Copy a teammate's board and customize it for your team                 | Ask Mixpanel Agent | Describe your team's specific question and get a board built for it directly.                                    |
| Manually interpret experiment results and write up a recommendation    | Experiments Agent  | Ask the Agent to summarize. It returns a verdict, key numbers, and a ship/kill recommendation in plain language. |

Those are direct replacements — workflows you're already running that an agent handles better. But there's a second category worth considering: things that weren't practical before because the effort was too high relative to the value, so teams either skipped them or did them infrequently. Agents change that calculus.

**On alerts:** Before, an [alert](/docs/features/alerts) was the beginning of an investigation. Now pair every meaningful alert with RCA — when it fires, the investigation runs automatically and you get a confidence-weighted explanation before you've opened Mixpanel.

**On questions that weren't worth asking:** A question like "what's driving retention in our power user cohort by acquisition channel" used to be a 2-hour task. Most of those questions didn't get answered because the people who could answer them were already underwater. That same question is now a 5-minute task.

**On metric ownership:** The mechanical parts of owning a KPI — the pull, the summary, the delivery — used to fall to whoever was accountable for the number. Now those are automated. What's left is interpreting movement, deciding what to investigate, and choosing what to do next.

***

## Key takeaways

* Configure Business Context before you do anything else — it's what turns generic AI responses into answers that reflect how your team actually works.
* Verified Mode is the right call for teams with broad AI access and a mature verification workflow. If your verification can't keep pace with instrumentation, the default experience is more reliable.
* Mixpanel Agent picks up your current page as context automatically — you don't need to describe your setup before asking a question.
* Pair every meaningful alert with RCA. The alert tells you something moved; RCA tells you why, before you've had to open a single breakdown.
* Set up the KPI Agent once on the metric you're accountable for and it delivers a digest on your schedule — daily, weekly, or monthly, via Slack or email.
* Use the Experiments Agent during setup, not just at results time — it can't fix a misconfigured experiment after the fact.
* The biggest shift these capabilities make isn't speed — it's what becomes worth doing. Questions that weren't practical before now take minutes.

**Next steps:** For access points, security, privacy details, and FAQs, see the [Mixpanel Agent documentation](/docs/mixpanel-agent).

***

## Quick reference

|                           | Ask Mixpanel Agent            | RCA Agent               | KPI Agent              | Experiments Agent                                 |
| :------------------------ | :---------------------------- | :---------------------- | :--------------------- | :------------------------------------------------ |
| **Trigger**               | On-demand                     | On-demand               | Scheduled              | On-demand                                         |
| **Scope**                 | Any question or build request | Single metric shift     | Single metric          | Experiment setup, results, rollout                |
| **Output**                | Answer or multi-chart board   | Generated RCA board     | Personalized digest    | Guided conversation + actions                     |
| **Delivery**              | In-product                    | In-product              | Slack or email         | In-product                                        |
| **Best for**              | Getting answers fast          | Explaining what changed | Staying close to a KPI | Running experiments without statistical expertise |
| **Uses Business Context** | Yes                           | Yes                     | Coming soon            | Yes                                               |


# 3 Ways Top Teams Put Mixpanel Agent to Work
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/mixpanel-agent/use-cases



[**Mixpanel Agent**](/docs/mixpanel-agent) is an AI analyst built into Mixpanel. Ask it a question or give it a task, and it works out which reports or actions to use, without you specifying each step.

If you're new to Mixpanel Agent, or you've tried it once and aren't sure what else it's good for, this guide is for you. It can do a lot, which makes "where do I start" the real question for most new users. Three patterns come up more than any others, across every industry and language:

* Build me something.
* Tell me why this moved.
* Tell me if this worked.

This guide walks through each one, so you can match your question to a starting point and act on it right away. No setup beyond what's already in your Mixpanel project is required, though results improve if your team has filled in [Business Context](/docs/business-context).

<Note>
  **Note**: You don't need the perfect prompt to get value with Mixpanel Agent. Describe what you want in plain language and see what comes back, knowing you can always refine from there.
</Note>

***

## Turn a rough idea into a board or report

Most people's first move with Mixpanel Agent isn't a question. It's a build request.

Some requests are bare: "make DAU over a week." Others come in fully specified, with filters and breakdowns already decided. Either way, describe what you want and Mixpanel Agent returns a working report or board.

<Frame>
  <img alt="Agent Use Cases Report" />
</Frame>

This is the easiest way to try Mixpanel Agent for the first time. If you'd normally open a blank report and click through metric and filter options, ask instead.

**In practice:** A growth lead needs a referral performance view for a stakeholder meeting: invites sent, signups, conversion rate, by channel. They describe it in one sentence. A multi-chart board comes back in about a minute. They fix one event mapping and share the link.

<Tip>
  **Pro tip**: Mixpanel Agent won't replace your own judgment. Treat what comes back as a first draft; and check the events and filters Mixpanel Agent chose before you share it with anyone else.
</Tip>

***

## Find out why a metric moved

Once a chart is in front of someone, the next question is "why."

Ask Mixpanel Agent directly, or trigger it from an Insights report or an alert. The [**RCA Agent**](/guides/guides-by-use-case/empower-your-team/mixpanel-agent/use-cases#rca-agent) (root cause analysis) returns which dimensions explain the shift, ranked by significance, plus a plain-language read and a confidence level.

<Frame>
  <img alt="Agent Use Cases Rca" />
</Frame>

The same instinct shows up in another form too: teams asking Mixpanel Agent to catch early signs a user is going quiet, before it shows up as a drop in a retention report. Asking Agent to look for these signals directly is often the fastest way to catch them.

**In practice:** A PM notices checkout completion dropped week-over-week and triggers RCA from the report. The top factor comes back in seconds: one iOS version, most of the variance, starting the same day a payment SDK update shipped. It’s specific enough to hand straight to engineering.

<Warning>
  **Pitfall**: RCA explains what's in your data, not what's true. If the underlying events weren't tracked correctly, RCA will confidently explain the wrong thing. Confirm your tracking before trusting a surprising result.
</Warning>

***

## Check whether a change worked

The third question shows up right after a launch: a pricing change, a policy update, a new onboarding flow. Teams come to Agent with a specific before-and-after comparison already in mind, often within hours of shipping.

The path depends on what kind of change you're measuring: an ongoing metric you're watching, or a formal test with a ship-or-kill decision at the end.

* **Watching a metric you own?** The [**KPI Agent**](/guides/guides-by-use-case/empower-your-team/mixpanel-agent#kpi-agent) delivers a scheduled digest, so you're not manually pulling the number and writing the summary yourself.
* **Ran a formal test?** The [**Experiments Agent**](/guides/guides-by-use-case/empower-your-team/mixpanel-agent/use-cases#experiments-agent) reads the full experiment or feature flag and returns a plain-language verdict: what happened, whether it's significant, what to do next.

**In practice:** An engineering team has results from a savings goal flow experiment, but no one's sure whether the lift is worth shipping. Asking the Experiments Agent for a summary returns a clear answer: Conversion increased a few percentage points, both guardrail metrics held, recommendation is to ship. That summary goes straight to the decision-maker.

***

## Key takeaways

* The fastest way to learn what Mixpanel Agent can do is to point it at a question you already have, not to read about its features first.
* If you'd normally build a report by hand, describe it instead and review what comes back before sharing it.
* Pair a metric shift with RCA before you dig into breakdowns yourself. You'll get a ranked explanation, not just a hunch to chase down.
* Route "did it work" questions to KPI Agent for metrics you own on an ongoing basis, and to Experiments Agent for formal tests with a ship or kill decision.
* All three use cases get sharper answers once your team's [Business Context](/docs/business-context) is filled in.

👉 **Next steps**: Make sure to set up [Business Context](/docs/business-context) if your team hasn't already. Then, pick whichever of the three matches your question right now and try it.


# Turn Clicks into Clarity: Best Practices for Heatmaps & Session Replay
Source: https://docs.mixpanel.com/guides/guides-by-use-case/empower-your-team/see-replays



Discover what users really experience—and turn those insights into action. This Guide shows you how to use [Heatmaps](/docs/session-replay/heatmaps) and [Session Replay](/docs/session-replay) together to quickly spot friction, understand behavior, and drive better product decisions.

***

## What Are Heatmaps and Session Replay?

Heatmaps and Session Replay combine the “what” and the “why” of user behavior.

* Heatmaps show where users click and focus attention.

<FrameColumn title="Mixpanel Heatmaps" description="In this 4-minute overview, learn how Mixpanel Heatmaps helps you visually pinpoint user friction and high engagement areas on your website, allowing you to instantly see where users are clicking and where they are getting stuck." />

* Session Replay shows how they move through your product in real time.

<FrameColumn title="Mixpanel Session Replay" description="In this 7-minute overview, discover how Mixpanel Session Replay unifies analytics and user behavior. Learn to seamlessly jump from your data to real user interactions to instantly diagnose friction and errors. The video also walks you through the incredibly easy, single-snippet implementation to accelerate your product's growth." />

Together, they help you understand not just *what* happened, but *why*.

***

## 1. Start with a Purpose

Begin with a clear goal instead of watching random replays. Ask:

* What behavior am I trying to understand?
* Which conversion, drop-off, or UX flow do I want to validate?

✅ **Do** define a specific question like:

* “Where are users dropping off in signup?”
* “Are people finding the new CTA?”
* “Do mobile users engage with the feature the same way as desktop users?”

❌ **Do not** assume watching any session will lead to insight. Without a clear question, you will end up chasing edge cases.

👉 **Do this next:** Define what “success” looks like before opening your first replay.

## 2. Use Heatmaps to Find the Pattern

Heatmaps are your first stop when you want to **see interaction trends at scale.**

**Steps to take:**

<Steps>
  <Step title="Choose a meaningful page or flow, like signup, pricing, or onboarding." />

  <Step title="Filter by device or cohort to compare how segments behave." />

  <Step title="Scan for anomalies, such as ignored CTAs or clicks on non-interactive elements." />
</Steps>

<Note>
  **Pro tip:** Use *Click Maps* for precision and *Traditional Heatmaps* for broader engagement patterns. Click Maps provide precise insights on dynamic pages with modals or dropdowns.
</Note>

Learn more about [Click Maps and Traditional Heatmaps](/docs/session-replay/heatmaps#overview).

***

## 3. Use Session Replay to Understand the “Why”

Once you have spotted a pattern, Session Replay lets you zoom in on the granular details of individual user sessions.

**Steps to take:**

<Steps>
  <Step title="Filter replays by key event or cohort.">
    For example, you can filter to “users who dropped after viewing pricing.”
  </Step>

  <Step title="Watch 6–8 replays.">
    This allows you to identify friction points and common paths your users take.
  </Step>

  <Step title="Look for behavioral feedback.">
    This includes excessive scrolling, hesitation, backtracking, or repeated form errors that highlights friction points.
  </Step>

  <Step title="Document your findings.">
    Take notes on where users struggle or deviate from expected behavior.
  </Step>
</Steps>

<Note>
  **Pro tip:** Start from within Mixpanel reports or user profiles to stay anchored to data—not anecdotes. You can click “View Replays” directly from an Event, Funnel, or User Profile to see related sessions immediately.
</Note>

<Warning>
  **Pitfall:** One replay ≠ one insight. Confirm patterns across multiple sessions before drawing conclusions.
</Warning>

***

## 4. Protect User Privacy and Data Integrity

Session Replay gives full visibility into user behavior—but it also introduces risk if sensitive data appears on-screen.

**Best practices for safe implementation:**

* Use Mixpanel's privacy controls to mask or block sensitive UI screens, like checkout or profile information.
* Test across devices, especially for mobile SDKs and embedded web views.
* Review your company's privacy notice and legal compliance before roll-out.

Learn more about [Session Replay Privacy Controls](/docs/session-replay/session-replay-privacy-controls).

***

## 5. Translate Insights into Product Decisions

Data becomes powerful only when shared. Once you identify friction, decide what change to make—and how you will measure its impact.

**Steps to take:**

<Steps>
  <Step title="Summarize your insight.">
    Turn observations into clear takeaways. For example, “Users abandon signup when validation errors are not visible.”
  </Step>

  <Step title="Share replay clips to align stakeholders on the problem.">
    Short, focused clips help everyone see the issue firsthand, creating a shared understanding and faster alignment on next steps.
  </Step>

  <Step title="Instrument or adjust tracking if needed.">
    Ensure what you are tracking capture key behaviors so you can validate results and spot new opportunities.
  </Step>
</Steps>

<Note>
  **Pro tip:** Create a recurring “Replay Review” with PMs and designers. It builds empathy and keeps teams aligned on real user behavior.
</Note>

**Strengthen your workflow with related features:**

* [Annotations](/docs/features/annotations): Add notes to your reports to document findings and experiments.
* [Alerts](/docs/features/alerts): Set notifications for spikes or drops in engagement or friction.
* [Experiments](/docs/experiments): Validate your hypotheses by testing product changes and measuring lift.

***

## Key Takeaways

* Start with a specific question or metric to guide your analysis.
* Use Heatmaps for **patterns** and Session Replay for **context**.
* Review **6–8** sessions per segment to find consistent trends.
* Safeguard user privacy during implementation and QA.
* Turn your findings into shared, actionable insights.

📚 **Go deeper:** Explore the Mixpanel Docs on [Heatmaps](/docs/session-replay/heatmaps) and [Session Replay](/docs/session-replay).


# Drive Product Innovation with Mixpanel Experiments
Source: https://docs.mixpanel.com/guides/guides-by-use-case/engage-your-users/drive-product-innovation



Experimentation is how modern product teams make decisions with confidence. Instead of guessing, you test changes with real users, measure the impact, and move forward knowing what works. Mixpanel makes it possible to plan, run, and analyze experiments in one place.

This guide shows you the best practices. Follow these steps to set up better experiments, avoid common mistakes, and scale experimentation across your team.

## Why Experiment?

Making product changes without data is risky. Experimentation helps you:

* **Reduce risk**: Test with a subset of users before rolling out broadly.
* **Learn faster**: Use data to validate ideas and iterate quickly.
* **Discover surprises**: Sometimes tests uncover unexpected insights.

Leading companies like [Step](https://mixpanel.com/customers/how-step-boosted-direct-deposits-by-14-with-mixpanels-experimentation/) use Mixpanel to build a culture of experimentation, moving quickly without losing customer trust.

👉 **Do this next:** Identify one upcoming product change you are unsure about and commit to testing it before launch.

### See Mixpanel Experiments in Action

Before you dive into best practices, take a quick look at how experimentation works inside Mixpanel.

<FrameColumn title="Mixpanel Experiments" description="In this 3-minute overview, learn how Mixpanel Experiments helps you reduce risk, learn faster, and discover surprises." />

## Setting Up Experiments the Right Way

Good experiments start with good planning. Skip this step, and your analysis will not tell you much.

### Write a strong hypothesis

Format: *If \[change], then \[impact], because \[reason].*

Example: *If we shorten the onboarding flow from 3 steps to 2, activation will increase by 15% because new users will encounter less friction.*

<Note>
  **Pro tip**: Keep hypotheses tied to a real user or business problem with measurable outcomes, not just a “gut feeling”.
</Note>

### Choose the right metrics

* **Primary metric**: The outcome that defines success (e.g. conversion rate).
* **Guardrails**: Protect against unintended damage (e.g. churn, CSAT).
* **Secondary metrics**: Add context but do not drive the decision.

Define metrics *before* launch. Adding them later biases results.

### Keep it simple

Do not test multiple changes at once. Focus on a single variable so you know what drove the outcome.

Testing too many things at once makes it impossible to know which change worked.

👉 **Do this next:** Draft your hypothesis and list your primary and guardrail metrics. Review with your team before launch.

## Choosing the Right Test Model

Mixpanel supports the following models. Pick the right one up front:

* **Frequentist**: Best for small lifts (\< 2%). Wait until your full sample size is reached before calling results.
* **Sequential**: Best for big, obvious changes (10%+). Let' you monitor results as data comes in and stop the experiment earlier.

<Note>
  **Pro tip**: If you expect only a tiny lift (like 1%), choose Frequentist as you will need maximum rigor.
</Note>

**Rule of thumb**

* Frequentist → accuracy matters most + expected lift is low
* Sequential → speed matters most + expected lift is high

Learn more about [Experiment Model Types](/docs/reports/experiments#experiment-model-types).

## Reading Results with Confidence

Mixpanel's [Experiment Report](/docs/reports/experiments) gives you three key signals:

* **Lift**: % change between control and variant.
* **P-value**: How confident you can be that the result is not random (≤0.05 is usually significant).
* **Confidence interval**: The likely range of the true impact.

How to interpret:

<Steps>
  <Step title="Start with the P-value.">
    This is your first and most important check.

    **If the P-value is > 0.05**: The result is *not statistically significant*. This means the difference you see is very likely due to random chance. You should *not implement the change*, even if the lift looks promising, because you can't be confident it's a real improvement.
  </Step>

  <Step title="Next, look at Lift and the Confidence Interval.">
    Only if the p-value is ≤ 0.05 do you move to these metrics. They tell you about the size and range of the true impact.
  </Step>
</Steps>

If your primary metric improves and the results are significant, you can trust it. If results are inconclusive, you still learned something. Revisit your hypothesis or run a follow-up. Use segmentation (new vs. returning users, geos, etc.) to understand nuances.

Do not treat inconclusive results as failures; they provide valuable clues, even if they are not yet a win.

👉 **Do this next:** Share experiment results in a [Mixpanel Board](https://mixpanel.com/blog/boards-collaborate-cards-mixpanel-feature-update/) and add notes on what the data means to provide additional context to your numbers.

## Acting on Experiment Insights

The most impactful teams do not stop at analysis; they act.

* **Decide**: Ship the winning variant, revert, or run a follow-up.
* **Document**: Capture the outcome in your Experiment Report.
* **Share**: Use Boards to communicate decisions and learnings with stakeholders.
* **Repeat**: Every experiment, win or lose, should inform your product strategy.

<Note>
  **Pro tip**:Always explain why you made your decision, not just what you decided. This builds institutional knowledge.
</Note>

👉 **Do this next:** Add a note in your Experiment Report explaining the reasoning behind your decision.

## Avoid Common Pitfalls

Stay alert to these common mistakes:

* **Ending too early**: Always run until your experiment criteria (e.g. sample size or statistical boundary) is met.
* **Overcomplicating**: Too many variants or changes muddy results.
* **Ignoring guardrails**: Success on one metric can hide damage elsewhere.
* **Underestimating sample size**: Small samples make results unreliable.

Avoid declaring a test a success at the first sign of movement; early spikes often disappear as more data arrives.

👉 **Do this next:** Review your last experiment—did you hit any of these pitfalls?

## Scaling Experimentation as a Habit

Experimentation works best when it is part of your culture.

* **Secure leadership buy-in**: Leaders should model data-driven decisions.
* **Create psychological safety**: Failed experiments = valuable learnings.
* **Share openly**: Publish results so others can benefit.
* **Use Mixpanel tools**: Boards and saved metrics keep experiments transparent and consistent.

<Note>
  **Pro tip**: Share at least one experiment outcome (good or bad) in every team meeting—it normalizes learning.
</Note>

👉 **Do this next:** Create a recurring agenda item in your weekly standup for experiment learnings. Keep it lightweight; 2–3 minutes max.

## Key Takeaways

Experimentation in Mixpanel lets you move faster, mitigate risk, and make more strategic decisions.

To get started:

1. **Begin testing your hypotheses with Mixpanel Experiments.** Use experiments to validate ideas with real user data before making broad product decisions.
2. **Share learnings widely.** Make results visible to other teams so everyone benefits.
3. **Treat experimentation as a repeatable process**, not a one-off.

👉 **Do this next:** AI is speeding up how fast you can ship. Make sure your testing keeps pace. [Get the ebook on experimentation in the age of AI](https://mixpanel.com/m/resource/ebook-experimentation-ai) to see how.


# How to Safely Ship New Features with Flags
Source: https://docs.mixpanel.com/guides/guides-by-use-case/engage-your-users/ship-features



Feature Flags give your team the power to launch confidently, roll back instantly, and measure success in real time. Mixpanel integrates feature flagging directly into your analytics—so every rollout is both controlled and measurable.

## What Are Feature Flags?

Feature Flags decouple deployment (when code ships) from release (when users see it). This means engineers can deploy at any time, while product teams control when—and to whom—new functionality appears.

Mixpanel's native feature flags integrate directly with your data, so you can track adoption, performance, and impact without additional setup.

***

## 1. Prepare for Rollout

Feature flagging starts with setup. Your engineering team must enable flag evaluation within your app before flags can be controlled in Mixpanel.

Steps to take:

<Steps>
  <Step title="Implement the Mixpanel SDK">
    Make sure to initialize the library with the config option `flags: true`.

    * [JavaScript SDK flags setup →](/docs/tracking-methods/sdks/javascript/javascript-flags)
    * [iOS / Swift SDK flags setup →](/docs/tracking-methods/sdks/swift/swift-flags)
    * [Android SDK flags setup →](/docs/tracking-methods/sdks/android/android-flags)
  </Step>

  <Step title="Define fallback variants in code to prevent errors if the flag fails to resolve." />

  <Step title="Verify flag evaluation using QA Testers before releasing to real users." />
</Steps>

* ✅ **Do** confirm the SDK setup and flag evaluation flow with Engineering before creating a feature flag in Mixpanel.
* ❌ **Do not** create flags in the UI before the SDK is integrated—the flag won't control behavior in your product until the SDK is configured.

<Warning>
  **Pitfall:** Skipping SDK setup causes flags to appear “inactive” even if configured correctly in Mixpanel.
</Warning>

***

## 2. Plan a Safe Rollout

With SDK setup complete, decide how to roll out the feature. Use data-driven rollout strategies to manage risk and learn quickly.

Common rollout types:

* **Phased Rollout**: Start with 5–10 % of users, expanding gradually.
* **Cohort-Based Targeting**: Show the feature to specific segments (e.g. power users or new signups).
* **Platform Segmentation**: Launch to a single platform (like iOS) before web.
* **Feature Gate**: Keep a kill switch ready for instant rollback.

<Note>
  **Pro tip:** Combine a phased rollout with [alerts](/docs/features/alerts) on key metrics—like conversion or retention—to catch regressions early.
</Note>

***

## 3. Configure Your Flag in Mixpanel

Once your SDK is live, create and manage feature flags directly in the Mixpanel UI.

Steps to take:

<Steps>
  <Step title="Create a new flag.">
    e.g. `onboarding_v2`
  </Step>

  <Step title="Add a variant and define rollout percentages." />

  <Step title="Target users by cohort or run-time properties.">
    e.g. `platform = android`
  </Step>

  <Step title="Use QA Testers to assign test variants and confirm logic." />

  <Step title="Monitor exposure and adoption in real time, adjusting rollout weights as you scale." />
</Steps>

<Note>
  **Pro tip:** Use consistent flag and variant names across systems to keep your analytics clean.
</Note>

### How it Works

When your app loads, the Mixpanel SDK automatically fetches active flags and evaluates which variant each user should see. Once a variant is displayed, Mixpanel logs an exposure event (`$experiment_started`), allowing you to track adoption and impact immediately in your reports—no manual tagging needed.

<Frame>
  <img alt="Experiments_and_FF.png" />
</Frame>

[📖 Full Feature Flags documentation →](/docs/featureflags)

***

## 4. Monitor and Learn

After launch, use Mixpanel analytics to determine whether to expand, iterate, or revert.

**Tools to Help**

* [Insights](/docs/reports/insights): Measure adoption and engagement by variant.
* [Funnels](/docs/reports/funnels/funnels-overview): Track conversion rates between control and variant users.
* [Boards](/docs/boards): Create a shared rollout dashboard with annotations and alerts.
* [Session Replay](/docs/session-replay): Watch user interactions to diagnose UX issues.

<Note>
  **Pro tip:** Use [borrowed properties](/docs/features/custom-properties#borrowed-properties) or [cohorts](/docs/users/cohorts) to track downstream behavior for users exposed to each variant.
</Note>

👉 **Do this next:** Validate exposure counts and cohort membership before scaling.

***

## 5. Govern and Clean Up

Feature flags are powerful, but unmanaged flags become “flag debt.” Maintain hygiene by:

* Assigning an **owner** for each flag.
* **Auditing** monthly or quarterly.
* Keeping flags scoped to one use case.
* **Documenting** rollout intent and success criteria.
* **Sunsetting** flags once a feature reaches 100 % rollout.

<Note>
  **Pro tip:** Add flag cleanup reviews to your sprint rituals to stay organized and efficient.
</Note>

***

## Key Takeaways

* Prepare your setup by enabling flag support in your SDK so Mixpanel can control feature visibility.
* Plan safe roll outs using phased or cohort-based release strategies to manage risk.
* Configure and control flags directly in Mixpanel—no redeploy required.
* Monitor adoption and performance with built-in analytics to decide when to expand or revert.
* Govern and clean up flags regularly to prevent confusion and keep your implementation scalable.

📚 **Go deeper:** [Feature Flags overview in Mixpanel Docs](/docs/featureflags)


# Understand and Grow Revenue with Mixpanel
Source: https://docs.mixpanel.com/guides/guides-by-use-case/grow-your-usership/grow-revenue



[Revenue analytics](/guides/strategic-playbooks/onboarding-playbook/launch/revenue-analytics) connects product usage to business results—helping you see which actions drive paying customers, where money comes from, and how to increase it.

***

## Before You Begin

Revenue analytics in Mixpanel requires Warehouse Connectors. To analyze revenue, you will need to sync your billing or transactional data (for example, from your payment platform or internal finance systems) into Mixpanel using [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors).

After your warehouse is connected, set up the data structure that fits your business model:

* **Transactional revenue** (e.g. one-time purchases, orders): Use [Mirror](/docs/tracking-methods/warehouse-connectors#mirror) to bring purchase events from your warehouse into Mixpanel. Mirror automatically syncs new transactions on a scheduled cadence.
* **Subscription-based revenue** (e.g. recurring plans, renewals): Use [Profile History](/docs/tracking-methods/warehouse-connectors#user-profiles) to track subscription changes, upgrades, and cancellations over time.

Once your data source is connected, you can link behavioral data (from Mixpanel events) with business data (from Mirror, Profile History, and Warehouse Connectors) to understand how user actions drive revenue outcomes.

📖 [Set up Warehouse Connectors →](/docs/tracking-methods/warehouse-connectors#step-1-connect-a-warehouse)

<Note>
  **Pro tip:** Make sure your revenue tables include shared identifiers such as `user_id` or `account_id` so Mixpanel can link purchases back to user actions.
</Note>

***

## What Is Revenue Analytics?

Revenue analytics lets you connect product behavior to business impact. In Mixpanel, this means tracking events that represent value exchange (signups, upgrades, purchases, renewals) and tying them to monetary outcomes.

When set up correctly, you can:

* See which actions or features correlate with higher spend
* Determine which in-trial actions lead to higher customer lifetime value after conversion
* Understand retention patterns among paying customers
* Align product and finance teams on shared metrics

By following the steps in this guide, you will learn how to track, verify, and act on your revenue data to fuel growth.

***

### 1. Capture the Right Revenue Events

Once your warehouse connection is live, focus on the key moments that represent a value exchange—either when money is transferred or when a commitment to future revenue is established.

* ✅ **Do** focus on meaningful milestones like `subscription_created`, `upgrade_completed`, or `payment_success`.
* ❌ **Do not** log every possible interaction as a revenue event.

Each event should include:

* `amount` (numeric)
* `currency` (ISO code)
* `plan_type` (or equivalent)
* `user_id` or `account_id`

<Note>
  **Pro tip:** For multi-currency transactions, include `base_currency` and `base_ccy_amount` so Mixpanel can convert all revenue to a single base currency for consistent reporting.
</Note>

<Warning>
  **Pitfall:** Missing any of these properties will prevent Mixpanel from rolling up revenue totals accurately.
</Warning>

***

### 2. Verify and Define Your Revenue Data

Before you begin analysis, confirm that Mixpanel is reading your data correctly.

Steps to take:

<Steps>
  <Step title="Tag your revenue events in Lexicon.">
    Tagging your revenue events make them discoverable and easy to reference across reports.
  </Step>

  <Step title="Check event integrity.">
    Look for duplicate event names, missing properties, or inconsistent casing.
  </Step>

  <Step title="Compare totals against your source-of-truth.">
    Compare your totals against your finance system warehouse to confirm that imported revenue matches what you expect.
  </Step>
</Steps>

Note: Warehouse Connector data updates on a scheduled sync (not in real time), so totals will reflect the most recent completed sync rather than live revenue changes.

<Note>
  **Pro tip:** Ask a finance or data engineer to confirm that your daily imports are up to date and correctly formatted.
</Note>

📖 [Learn more about data validation →](/docs/tracking-best-practices/debugging)

***

### 3. Analyze What Drives Revenue

Once your data is verified, you can start exploring what behaviors drive your business outcomes. There are many ways to analyze revenue in Mixpanel—each highlighting a different aspect of user value, conversion, or retention.

One simple but powerful example is **Average Revenue Per User (ARPU).**

**How it is calculated:**

   $Average \ Revenue \ Per \ User \ (ARPU) = \frac{Sum \ of \ Revenue \ Over \ Time}{Number \ of \ Unique \ Users}$

Tracking ARPU helps you understand how much revenue each active user generates during a given period. It is a great starting point for comparing user segments, evaluating pricing changes, or measuring growth trends over time.

**Tools to Help**

* [Insights](/docs/reports/insights): Visualize ARPU trends and spot spikes or dips after product or pricing changes.
* [Funnels](/docs/reports/funnels/funnels-overview): See how user behaviors along the purchase path affect downstream revenue.
* [Cohorts](/docs/users/cohorts): Compare high-value cohorts (e.g. annual plan users) with lower-value ones to identify drivers of growth.

**Example:** Explore how ARPU looks in practice in our [E-commerce demo project](https://mixpanel.com/s/300OIR). This sample dashboard uses an **Insights** report to calculate revenue per user over time, helping teams visualize revenue trends in real Mixpanel data.

ARPU is just one approach to revenue analysis.

* For transactional revenue, you can explore metrics like **Revenue per Purchase Event** or **Revenue by Feature Usage** to uncover which actions or products generate the most value.
* For subscription-based revenue, try tracking **Recurring Revenue Change** or **Churned Revenue** to understand how upgrades, downgrades, and cancellations impact your overall recurring revenue growth.

***

### 4. Connect Insights to Action

Revenue analytics is only valuable if it drives decisions. Once you have identified what moves the needle, turn insights into action across teams.

* Share [Boards](/docs/boards) with product and growth teams to align on revenue drivers.
* Set up [Alerts](/docs/features/alerts) to notify you of significant revenue drops or spikes.
* Add [Annotations](/docs/features/annotations) to track launches, pricing changes, or campaigns that may explain revenue shifts.

<Note>
  **Pro tip:** When you notice a revenue dip or spike, dig into which user actions changed around the same time—and share those findings with product or marketing so they can act on them quickly.  Set up a quarterly review to ensure data stays current and your insights remain actionable.
</Note>

***

## Key Takeaways

* Revenue analytics in Mixpanel requires Warehouse Connectors to import financial data.
* Track only the key events that represent real value exchange.
* Always verify totals and event integrity before drawing conclusions.
* Use Funnels, Insights, and Cohorts to discover what behaviors drive conversions.
* Refresh and share dashboards regularly to align business and product teams.

📚 **Go deeper:** [Mixpanel Docs on Revenue Analytics](/guides/strategic-playbooks/onboarding-playbook/launch/revenue-analytics)


# How To Build a Tracking Strategy
Source: https://docs.mixpanel.com/guides/guides-by-workflow/build-tracking-strategy



A well-defined tracking strategy ensures your product data stays consistent and reliable, enabling teams to make data-informed decisions without wasting time on data cleanup.

This guide details how to create a tracking strategy that enables your team to capture the right events and properties, keep them consistent, and set them up for meaningful analysis.

## What is a Tracking Strategy?

A tracking strategy is a plan for deciding **which events and properties to capture, how to name them, and how to manage them over time**.

In Mixpanel, this means using the [data model](/docs/data-structure/concepts) (events, users, and properties) intentionally, so your data is structured for the KPIs that matter most to your business.

A tracking strategy is not just about what you log; it is about creating a shared framework so product, engineering, and analytics teams can trust the data and use it to answer business questions.

## Building a Tracking Strategy

A good strategy is built step by step, not all at once. The practices below will help you move from a vague idea of “we should track more” to a clear, scalable framework your whole team can rely on.

### Define the Events that Matter

Events are the backbone of Mixpanel. Start by mapping out the key user actions tied to your KPIs (e.g. sign-up started, checkout completed, feature used).

* ✅ **Do** choose events that represent meaningful behaviors connected to business goals.
* ❌ **Do not** track every click or interaction simply because it is possible, since doing so can clutter your analysis.

Learn more about [Events](/docs/data-structure/events-and-properties).

### Use Event Properties to Add Context

Events tell you *what* happened, properties tell you *how* it happened. Properties give you the flexibility to keep your event list small while still allowing rich analysis.

<Steps>
  <Step title="Utilize properties to avoid creating separate events for each variation.">
    Properties like `plan_type`, `payment_method`, or `device` can help keep your event list targeted and make analysis easier. Instead of hunting across multiple events, you can filter one event by property values.
  </Step>

  <Step title="Use consistent data types for predictable analysis.">
    Consistency in [data types](/docs/data-structure/property-reference/data-type) (e.g. string, numeric, or Boolean) ensures your metrics are accurate and comparable over time. For example, if a property is sometimes a string and sometimes a number, queries can break and charts can become unreliable.
  </Step>

  <Step title="Attach session-level context as super properties.">
    Promoting context like app version, device type, or campaign source to a [super property](/docs/tracking-methods/sdks/javascript#setting-super-properties) auto-attaches it to every event, which saves engineering effort and guarantees important context is always available in your analysis.
  </Step>
</Steps>

<Note>
  **Pro tip**: Teams typically see the best results when they limit their schema to a manageable set of core events, enriched with properties for detail.
</Note>

### Capture User Profiles and Properties

Events capture behavior, while user profiles capture who the user is today (e.g. their email, location, and subscription level). When you pair event properties with user properties, you can compare past behavior with the current state.

For example, a user property for `current_country = Singapore` can be compared with an event geolocation property showing where they logged in previously. A user who travels often may track events in different locations despite their current location being somewhere else.

Learn more about [User Profiles](/docs/data-structure/user-profiles).

### Tips for Choosing Properties

Properties, whether attached to events or stored on user profiles, add the context that makes your analysis meaningful. The right ones make it easy to answer business questions; the wrong ones add noise and confusion.

Use these guidelines to decide which properties to include.

<Steps>
  <Step title="Prioritize analysis needs.">
    Capture properties that directly support the questions your team needs to answer. For example, if “Which payment methods drive the most revenue?” is a key question for your team, you should prioritize including properties like `payment_processor` and `payment_method`.
  </Step>

  <Step title="Favor stability.">
    Pick properties that are unlikely to change meaning or format frequently. This keeps your reporting consistent over time.
  </Step>

  <Step title="Balance detail with simplicity.">
    More properties mean more flexibility, but too many can overwhelm dashboards and confuse stakeholders.
  </Step>

  <Step title="Reuse across events.">
    Standardize common properties like `plan_type`, `device`, or `region` so you can compare data across events instead of reinventing them each time.
  </Step>
</Steps>

Following these guidelines keeps your schema focused, while still giving you the flexibility to answer the questions that matter most.

### Standardize Naming Conventions

Clear, consistent names make your data easier to use and trust. A naming convention prevents confusion, reduces duplicate events, and keeps your queries simple.

* ✅ **Do** pick one convention and use it everywhere.
* ❌ **Do not** mix formats like `SignUp`, `signup_started`, and `Signup Started`.

As a best practice, use `snake_case` for all event names, properties, and property values (for example: `checkout_completed`, `payment_method = credit_card`). Snake case works well with APIs and avoids ambiguity.

<Note>
  **Pro tip**: Write down your naming rules in your tracking plan so engineers and analysts always know what to follow.
</Note>

### Document and Govern Your Tracking Plan

Your strategy only works if it is shared and enforced. Keep a **living tracking plan** and lean on Mixpanel's governance features.

1. Store your tracking plan in a shared location, such as a Google Sheet or Notion page.
2. Keep your tracking plan updated as your product evolves.
3. Share your tracking plan widely across product, engineering, and analytics teams.

**Tools to Help with Data Governance**

* [Tracking Plan Template](/docs/tracking-best-practices/tracking-plan): Organize event names, properties, and owners in one place.
* [Lexicon](/docs/data-governance/lexicon): Add descriptions, assign owners, and hide deprecated events right in Mixpanel.

Learn more about [Data Governance](/docs/data-governance).

## Key Takeaways

* Only track events that tie directly to KPIs.
* Use properties to keep your schema flexible.
* Capture user profiles to combine “who” with “what.”
* Standardize names using snake\_case.
* Document your plan and use governance features to keep data clean.

<Note>
  Check out our Onboarding Playbook on [Building Your Tracking Strategy](/guides/plan/tracking-strategy).
</Note>


# Mixpanel Guide to Data Privacy & PII Best Practices
Source: https://docs.mixpanel.com/guides/guides-by-workflow/data-privacy



Mixpanel’s recommended approach for managing sensitive data is built on a simple goal: help you collect only what you need, reduce risk, and maintain high-quality analytics.

Privacy in analytics isn't solved by a single setting—it's a continuous practice. At Mixpanel, we aim to make responsible data behaviors the default, ensuring you can maintain a safe environment without compromising your team's velocity.

To achieve this balance, we recommend adhering to **four core principles** that act as practical habits for your team:

* **Data Minimization**: Track only what supports your KPIs and product decision-making. If a specific data point or property doesn't drive insight, do not collect it.
* **Pseudonymization by Default**: Use stable internal identifiers (like `user_id`) rather than emails or phone numbers. If internal IDs are identifying, hash or encrypt them before sending.
* **Purpose Alignment**: Design tracking around meaningful "value moments" rather than exhaustive behavioral capture. Data collected without a specific purpose is almost always a liability.
* **Shared Responsibility**: While Mixpanel provides governance tools like [Data Views](/docs/data-governance/data-views-and-classification#data-views-overview), [Data Classification](/docs/data-governance/data-views-and-classification#data-classification), [Data Deletion](/docs/data-governance/data-clean-up), and [privacy features](/docs/privacy), you determine what enters the system to align with your regulatory requirements.

Below is a simple three-step framework for deciding what data to collect, identifying any sensitive data involved, and ensuring it’s handled safely.

## Phase 1: Design & Collection

This phase focuses on the decision-making process before data is collected: defining what data creates value versus what creates risk.

### What is PII?

PII (Personally Identifiable Information) refers to **any data point that can directly identify a person or can be combined with other data to do so**. While often associated with obvious fields like names or emails, PII in Mixpanel also includes technical identifiers—such as IP addresses or device IDs—that require governance.

Understanding how these identifiers surface in events and profiles helps you design tracking that protects users while still giving product teams the insight they need.

PII can appear in several forms:

* **Direct identifiers**: Names, emails, phone numbers.
* **Account identifiers**: Internal user IDs, workspace IDs.
* **Device/network identifiers**: IP address, device ID, ad IDs.
* **Highly sensitive data**: Government IDs, payment card details, authentication secrets.

### Classifying Data Risk

While Mixpanel captures data through [events](/docs/data-structure/events-and-properties), [user profiles](/docs/data-structure/user-profiles), and (optionally) [group profiles](/docs/data-structure/group-analytics), the privacy risk lies almost entirely in the properties you attach to them. Use this matrix to classify your data before adding it to your tracking plan.

| Risk Level        | Common Examples                                                     | Best Practice                                                                                                             |
| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Low Risk**      | Plan tier, device type, experiment variation, feature metadata.     | **Safe to Track.** These properties drive product insights without identifying specific individuals.                      |
| **Moderate Risk** | Email, phone number, IP address, Device ID.                         | **Govern Carefully.** Only track if needed for a legitimate business purpose. Must be marked as "Classified" immediately. |
| **High Risk**     | Government IDs (SSN), payment card details, authentication secrets. | **Do Not Track.** Avoid sending this data entirely.                                                                       |

### Tracking Do's

* **DO use internal IDs**: Use non-personally identifiable internal IDs (like `user_id` or `account_id`) whenever possible. If an internal ID reveals identity, hash or encrypt it before sending.
* **DO maintain a [tracking plan](/docs/tracking-best-practices/tracking-plan#translate-flows-into-events-/-properties)**: Document definitions, data types, business purposes, and PII flags for every event and property you intend to collect.
* **DO track value moments**: Map events directly to KPIs—such as activation, engagement, monetization, or retention—rather than tracking every possible click.

### Tracking Don'ts

* **DON'T send high-sensitivity data**: Never send government ID numbers, payment data, or credentials.
* **DON'T rely on email/phone as IDs**: Treat emails and phone numbers as optional properties for communication, not as your primary stable user identifier.
* **DON'T send unreviewed free-text**: Avoid free-text fields (like form inputs) that may contain unintentional PII.
* **DON'T send raw identifiers in Session Replay**: [Mask](/docs/session-replay/session-replay-privacy-controls#how-does-masking-and-blocking-work-what-are-the-high-level-technical-details) or redact input fields where appropriate.

### Handling "Must-Have" PII

Mixpanel’s stance is that you should avoid sending highly sensitive data entirely. If you must send PII (like an email for targeting), ensure it has a legitimate business purpose approved by your compliance team, and mark it as "Classified" immediately.

## Phase 2: Governance & Access

Once you have defined what data to collect, you must ensure it is accessed safely. Rather than gating analytics behind complex configurations, Mixpanel uses a "governance layer" to control visibility without blocking data ingestion.

<Steps>
  <Step title="Classify Sensitive Properties">
    [Data Classification](/docs/data-governance/data-views-and-classification#data-classification) is your first line of defense. It is a simple toggle that marks a property as "Classified."

    * **Action**: Review your tracking plan and mark any property containing identifiers (e.g. `$email`, `$ip`) or sensitive business data as classified.
    * **Effect**: This does not stop data collection, but it tags the data so you can enforce policies on who views it.
  </Step>

  <Step title="Curate Data Views">
    Instead of giving every user access to raw data, use [Data Views](/docs/data-governance/data-views-and-classification#data-views-overview) to create governed subsets of data relevant to their specific role. This allows you to "curate" a safe environment rather than just restricting access.

    * **Create a "Broad-Access" View**: Exclude classified PII (like email or Device ID) from the default view used by Product Managers and Analysts. This prevents accidental exposure while maintaining full analytical power.
    * **Create Regional Views**: Filter events by geography (e.g. `city` or `region`) to create specific views (like "EU Data Only") that align with local data residency and compliance requirements.
  </Step>

  <Step title="Define Access & Roles">
    Privacy and strong governance depend on how you plan your organizational settings around who has access, how projects are structured, and how often those permissions are reviewed.

    * **Least-Privilege Access**: Grant teams access only to the Data Views they need. For example, Customer Support may need a "User History" view (with PII), while the Strategy team only needs "Anonymized Trends." Start with minimal permissions and add them only when necessary.
    * **Routine Access Reviews**: Conduct regular audits to confirm that only the right people can still see classified data.
    * **Training**: Train your teams on what PII is and how to interpret "Classified" badges inside Mixpanel so they understand the boundaries.
    * **Separate Environments**: Use separate Mixpanel projects for Production and QA. Never populate non-production projects with real user identifiers.
  </Step>

  <Step title="Operationalize Compliance">
    Mixpanel includes specific [features to support compliance](/docs/privacy) with GDPR, CCPA, and other similar frameworks, helping you operationalize privacy requirements without manual workarounds.

    * [**Data Retention**](/docs/privacy/gdpr-compliance#data-retention-policy): Set up policies to automatically purge older data that is no longer needed for analysis.
    * [**User Deletion API**](/docs/privacy/gdpr-compliance#right-to-erasure): Integrate the Deletion API to delete all user-related data programmatically upon request (e.g. "Right to be Forgotten").
    * [**Opt-out Settings**](/docs/privacy/protecting-user-data#opting-users-out-of-tracking): Ensure your SDK implementation respects user consent flags and local requirements.
  </Step>

  <Step title="Document in Lexicon">
    Use [Lexicon](/docs/data-governance/lexicon) as your single source of truth. Document the privacy posture of each field—explicitly stating its business purpose and which Data Views it belongs to—so new team members understand how to handle it safely.
  </Step>
</Steps>

## Phase 3: Monitoring & Maintenance

Even well-governed data drifts over time. This phase ensures your privacy posture remains healthy as your product evolves.

<Steps>
  <Step title="Routine Reviews">
    Schedule quarterly or semi-annual reviews to catch issues early. Your review checklist should cover:

    * **New Tracking**: Audit recently added events and properties to ensure no accidental PII was introduced.
    * **Drift**: Check existing properties to ensure they haven't started capturing PII (e.g. a "Search Query" field where users have started typing names).
    * **Clean-up**: Identify and deprecate redundant or unused fields to minimize your data footprint.
  </Step>

  <Step title="Remediation Workflow">
    If you discover unexpected PII, follow a structured remediation flow immediately:

    * **Stop Ingestion**: [Drop](/docs/data-governance/data-clean-up#3-drop-filters) the event or property at ingestion to stop the leak.
    * **Restrict Access**: Immediately reclassify the property and restrict access using [Data Views](/docs/data-governance/data-views-and-classification#data-views-overview) and [Data Classification](/docs/data-governance/data-views-and-classification#data-classification).
    * **Notify & Update**: Inform relevant stakeholders (including Legal/Compliance) and update your [tracking documentation](/docs/tracking-best-practices/tracking-plan#translate-flows-into-events--properties) to prevent recurrence.
  </Step>

  <Step title="Governance Toolkit">
    Leverage Mixpanel’s tools to automate maintenance and cleanup:

    * **Visibility Control**: [Hide](/docs/data-governance/lexicon#hiding-data) data in Lexicon that is no longer needed to keep the project clean without permanently deleting it.
    * **Configuration Updates**: Update [Data Classification](/docs/data-governance/data-views-and-classification#data-classification) and [Data Views](/docs/data-governance/data-views-and-classification#data-views-overview) as your data evolves to ensure new properties are governed correctly.
    * **Project Data Deletion**: Use Mixpanel's [Data Deletion](/docs/data-governance/data-clean-up#2-deleting-problematic-data) feature to permanently remove specific events or properties that contain accidental PII or are no longer valid.
    * **Lexicon Updates**: Keep [Lexicon](/docs/data-governance/lexicon) descriptions up to date so the "safe" status of every metric is clear to all users.
  </Step>
</Steps>

## Summary

Privacy-aware analytics requires intentional data collection, strong governance, and continuous review.

* **Design intentionally**: Send only the data you truly need to drive decisions, and keep high-risk data out of your tracking plan from the start.
* **Govern proactively**: Use Data Classification and Data Views to curate safe environments, ensuring teams access only the insights they need without unnecessary exposure to PII.
* **Maintain habits**: Treat privacy as an organizational practice—using regular access reviews, documentation in Lexicon, and cleanup routines to reinforce safety over time.

**Get the Checklist**: To ensure your implementation meets all these standards—including naming hygiene, security controls, and QA workflows—download the [PII & Data Privacy Best Practice Checklist](https://docs.google.com/document/d/1tDp_NIuGtWakyHGmvvMqJMt075ww0i007g35xLUHdNo/template/preview).

When teams operate within these guardrails, Mixpanel becomes a secure, reliable foundation for confident decision-making.


# Embed Analytics into Your Product Development Cycle
Source: https://docs.mixpanel.com/guides/guides-by-workflow/embed-data



When a feature ships without verified tracking in place, the cost shows up later — empty dashboards, re-opened tickets, roadmap decisions made without reliable numbers. This guide walks you through how to treat instrumentation as part of the feature cycle itself: planned before the first line of code is written, verified before you call a feature done.

The principle behind this approach is borrowed from quality engineering: The earlier you catch a problem, the cheaper it is to fix. The same applies to analytics. When tracking is planned at the start of a feature rather than added after it ships, your data is more accurate, your metrics are more reliable, and your team can make decisions from day one instead of playing catch-up.

## Phase 1: Define what you're measuring before you build

The most common instrumentation problem isn't technical — it's that no one decided what to measure before the sprint started. Before any feature moves to development, answer three questions in the design phase:

* What user actions prove adoption?
* What does success look like at 30, 60, and 90 days?
* What signal would tell you to double down or cut the feature?

Writing down the answers forces a useful conversation early, while changing course is still cheap.

**Steps to take**

* Write your success metrics in the feature spec itself, not in a separate doc. If they're not in your spec, they'll be skipped.
* Check whether events you need already exist in your schema before creating new ones. Reusing existing events keeps your data consistent and reduces clutter.
* Review your team's naming conventions before adding anything new. A consistent format — like `Object Action` (e.g. `Button Clicked`, `Checkout Completed`) — makes your schema readable and queryable across teams.

<Note>
  **Pro tip**: If you can't name your success metric before you build, that's often a signal to tighten the feature scope first, not a reason to defer tracking.
</Note>

## Phase 2: Write a tracking plan as part of your spec

A [tracking plan](/docs/tracking-best-practices/tracking-plan) is a structured list of the events and properties you intend to fire for a feature: what triggers them, what properties they carry, and what naming conventions apply. It's the contract between PM, engineering, and data — and it belongs in your spec, not in a separate document that gets out of sync.

If your team is new to tracking plans, Mixpanel provides [templates for common verticals](/docs/tracking-best-practices/tracking-plan#translate-flows-into-events--properties) — including e-commerce, financial services, media, and SaaS — as well as a blank template you can copy and adapt. The format matters less than the habit.

**Steps to take**

* Add a tracking plan section to your feature spec or ticket template. At minimum: event name, trigger condition, required properties, and any naming conventions that apply.
* Share the tracking plan with engineers before they write implementation code. Tracking planned after the fact means re-opening shipped code.
* Use [Lexicon](/docs/data-governance/lexicon) to check whether the events you need already exist and whether their property schemas match what you're planning. Lexicon is Mixpanel's central schema registry — every event and property your project sends lives there.
* Enable [Event Approval](/docs/data-governance/event-approval) so new, unplanned events require review before they're ingested. This is your primary tool for preventing schema drift when engineers ship new tracking without a plan.
* If your team sends data across multiple product areas, consider setting up [Data Views](/docs/data-governance/data-views-and-classification) to segment your Mixpanel project by team or feature area. This reduces noise and keeps each team focused on the data relevant to their work.

<Warning>
  **Pitfall**: Skipping the tracking plan when a feature feels "small" is how schemas accumulate inconsistent events over time. Every unplanned event is technical debt in your data.
</Warning>

## Phase 3: Verify tracking before you ship

A feature isn't done until its events are firing correctly. Verification belongs in your QA pass, not as a post-launch clean-up task.

**Steps to take**

* Verify events fire in staging using Mixpanel's [Events View](/docs/tracking-best-practices/debugging#debugging-with-events) before pushing to production. Spot-check that required properties are populated and not null, missing, or malformed.
* Review any new events for [PII](/guides/guides-by-workflow/data-privacy). No personally identifiable information should be sent as an event property without explicit governance approval.
* Update [Lexicon](/docs/data-governance/lexicon) with descriptions for any new events and properties. If another team member can't tell what an event means from its Lexicon entry, they'll either ignore it or create a duplicate.
* Use the [Lexicon Schemas API](/reference/lexicon-schemas-api) to load your pre-release tracking plan into Mixpanel programmatically. This lets you compare planned vs. actual events after launch and catch gaps early.

<Note>
  **Pro tip**: Add event verification to your pull request template so it's a required step. The conversation about whether tracking is verified shouldn't happen in a retrospective.
</Note>

## Phase 4: Launch with measurement ready

Shipping with measurement in place means you can assess impact from day one, not three sprints later when someone finally builds the board.

**Steps to take**

* Have at least one Mixpanel report or board live before or alongside the feature announcement. Link it from the announcement so your team knows where to look.
* Document the pre-launch state of your key metrics. Without a baseline, you can't measure impact — you can only observe activity.
* Set up a [Mixpanel alert](/docs/features/alerts) or a scheduled check-in cadence to catch unexpected data drops after launch. A spike or gap in event volume post-launch is worth catching early.
* If you're using [Feature Flags](/docs/featureflags) to control rollout, connect them to your Mixpanel reports so measurement is tied directly to the release.
* Define [Data Standards](/docs/data-governance/data-standards) at the project level if you haven't already — naming conventions, required properties, and approved values enforced across every team that sends data.

<Warning>
  **Pitfall**: Capturing baseline metrics after launch makes it nearly impossible to attribute changes to the feature you shipped. Document the baseline before you turn the feature on.
</Warning>

## Roles and responsibilities

Proactive data governance is a team effort. Here's who owns what across a typical product team:

| Role                    | Responsibilities                                                                                                                    |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Product Manager         | Defines success metrics. Writes the tracking plan. Ensures tracking is a line item in every feature spec. Reviews data post-launch. |
| Engineer / Developer    | Implements tracking per the plan. Flags ambiguities before building. Verifies events fire correctly in staging.                     |
| Data Governor / Analyst | Maintains naming conventions and Data Standards. Reviews new events via Event Approval. Keeps Lexicon descriptions current.         |
| QA / Test Engineer      | Validates tracking as part of the QA pass. Includes event verification in acceptance criteria.                                      |
| Engineering Manager     | Makes tracking plan completion a gate in the definition of done. Holds the standard across sprints.                                 |

## Getting started: A 30-day plan

Changing team habits takes time. Here's a realistic approach to introducing these practices without disrupting your current velocity.

### Weeks 1–2: Establish the standard

* Agree on a [tracking plan template](/docs/tracking-best-practices/tracking-plan#translate-flows-into-events--properties) your team will use for all new features. A simple spreadsheet is fine to start.
* Add "tracking plan complete" to your definition of done in your project management tool.
* Enable [Event Approval](/docs/data-governance/event-approval) in Mixpanel to start catching unplanned events.
* Audit your 10 most-used events in [Lexicon](/docs/data-governance/lexicon) and add descriptions for any that are undocumented.

### Weeks 3–4: Build the habit

* Walk through the tracking plan for one upcoming feature in your next sprint planning session.
* Identify one person to serve as your data governor — the person who reviews new events and maintains your naming standards.
* Set up one [Mixpanel board](/docs/boards) for a recently shipped feature. Even retroactively, this builds the habit.

### Day 30 and beyond: Make it repeatable

* Review your first full feature cycle with the new process. What worked? What didn't?
* Document your naming conventions in [Data Standards](/docs/data-governance/data-standards) within Mixpanel.
* Schedule a monthly 30-minute data review across your product and analytics teams.
* Expand the practice to more features and more teams.

The goal isn't perfect tracking from day one. It's a team that thinks about measurement before shipping — so your data gets more accurate with every feature, not less.

## Key takeaways

* Define success metrics in the design phase, before any code is written.
* Write a tracking plan as part of your spec or ticket, not as a separate artifact that gets out of sync.
* Share the tracking plan with engineers before implementation begins, not after.
* Verify events in staging before every production release.
* Document your baseline metrics before launch so you can measure actual impact.
* Shipping a feature means shipping its measurement — Mixpanel board included.

👉 **Next step**: To build out the governance infrastructure that supports this process, see [Govern Your Mixpanel Data for Long-Term Success](/guides/guides-by-topic/govern-data). For a deeper look at tracking strategy, start with the [Building a Tracking Strategy](https://university.mixpanel.com/training/01971248-cfad-7259-9c42-b9c246278b9d/register) module in Mixpanel University.


# Ensuring Data Quality in Mixpanel
Source: https://docs.mixpanel.com/guides/guides-by-workflow/ensure-data-quality



Poor data quality leads to misleading insights and wasted effort. The fastest way to prevent this is to treat QA and auditing as a required step in your Mixpanel implementation, not an optional one.

The steps below are the must-do practices for every team to keep insights accurate and trustworthy.

## Always Use Separate Projects

From day one, set up **two projects** in Mixpanel:

* **Development Project** → used for testing event tracking, identity management, and property values
* **Production Project** → where only clean, validated data is ingested

This separation ensures:

1. Developers can experiment safely without polluting your production dataset
2. Data teams have confidence that every event in production has been tested

* ✅ **Do** enforce a rule: *“Nothing hits production until it passes QA.”*
* ❌ **Do not** shortcut by sending test events to production.

## QA Before You Launch

QA is not optional. Every implementation should pass through **two levels of QA** before production:

* Code-Level QA (developer focus)
* User Flows QA (product & data team focus)

### Code-Level QA (developer focus)

This QA allow developers to verify that individual events are firing correctly.

Steps to take:

1. Trigger events in the development app/site.
2. Inspect the network calls or SDK logs.
3. Confirm the following:

   * Event names match your tracking plan
   * Properties have expected values
   * No API errors are returned

#### Enable Debug Mode

Developers should [enable debug mode](/docs/tracking-best-practices/debugging#enable-debug-mode) to review requests and confirm the payloads sent to Mixpanel.

* Web: view logs in the browser console
* Mobile: view logs in Xcode (iOS) or Android Studio (Android)

Debug Mode surfaces:

* Client-side errors
* API ingestion errors
* Successful ingestion
* Payloads in the ingestion requests

### User Flows QA (product and data team focus)

This QA ensures that end-to-end journeys are tracked correctly.

Steps to take:

1. Walk through real flows in your app (sign up, purchase, upgrade, etc.)
2. Confirm events fire as expected at each step.
3. Check Mixpanel UI:

   * [Events](/docs/tracking-best-practices/debugging#debugging-with-events) appear in reports
   * [User profiles](/docs/tracking-best-practices/debugging#debugging-with-user-profiles) are created or updated correctly
   * [Identity stitching](/docs/tracking-methods/id-management/identifying-users-simplified) works when a user moves from anonymous to known

<Note>
  **Pro tip**: Involve non-developers in your User Flows QA. Product managers and data analysts often catch issues developers miss because they think in terms of *business flows* rather than code.
</Note>

Learn more about [QA workflows](/docs/tracking-best-practices/debugging).

## Audit Regularly

Even if you QA perfectly before launch, things break. Code changes, new features, and third-party integrations can all introduce silent data errors.

**Make Auditing Recurring**

Schedule audits quarterly or alongside product releases to check for:

* Missing or duplicate events
* Unexpected property values
* Identity stitching anomalies (e.g. multiple profiles for the same user)

**Tools to Help**

* [Lexicon](/docs/data-governance/lexicon): to validate event/property naming
* [Events report](/docs/tracking-best-practices/debugging#debugging-with-events): to spot-test events in real time

<Note>
  **Pro tip**: Treat auditing like regression testing; it is not about fixing what is broken now, but preventing broken data from piling up unnoticed.
</Note>

## Key Takeaways

* **Two projects, always**: Development + Production
* **QA before production**: Run both code-level and user flow QA
* **Use Debug Mode**: Catch ingestion issues instantly
* **Audit often**: Data quality is not set-and-forget

Learn more about [best practices for debugging](/docs/tracking-best-practices/debugging).


# Eliminate Data Drift Between Your Warehouse and Mixpanel Using Mirror
Source: https://docs.mixpanel.com/guides/guides-by-workflow/sync-with-mirror



When your warehouse is the source of truth, you need Mixpanel to stay in sync with it — not just ingest a snapshot and drift. [Mirror sync mode](/docs/tracking-methods/warehouse-connectors#mirror) does that by tracking every change in your warehouse (new rows, updates, and deletions) and reflecting them in Mixpanel automatically. The result is a Mixpanel project that always matches your warehouse, without manual reconciliation.

Getting there takes more than pointing a connector at a table. How you model your data, which sync mode you choose, and how you map identifiers all determine whether your analytics hold up under real-world conditions.

## Before You Start

Mirror is one of several sync modes in [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors). It uses Change Data Capture (CDC) to detect and replicate changes, which means every row update or deletion in your source counts as a billable event in Mixpanel. That makes data modeling decisions consequential — not just for accuracy, but for cost.

You'll need:

* Access to a [supported warehouse](/docs/tracking-methods/warehouse-connectors#step-1-connect-a-warehouse), such as Snowflake, BigQuery, Databricks, or Redshift
* Read-only credentials (SELECT access) scoped to the tables you intend to sync
* A clear picture of what each warehouse table represents — event log, current profile state, or historical state changes

## Phase 1: Choose the Right Sync Mode for Each Table

Not every table belongs on Mirror. The sync mode you choose determines how Mixpanel processes incoming data and what it costs. Use the table below to match each source table to the right mode based on **how that data changes over time** — whether it's ever corrected, deleted, or only appended to.

| Sync Mode | What it does                                      | Best for                                           |
| --------- | ------------------------------------------------- | -------------------------------------------------- |
| Mirror    | Reflects new rows, updates, and deletions via CDC | Transactional events, profile history (SCD Type 2) |
| Append    | Loads new rows only; ignores changes and deletes  | Immutable event logs (e.g. raw page views)         |
| Full Sync | Overwrites with a fresh snapshot each run         | Lookup tables, current-state profiles              |
| One-Time  | Single load, no recurring updates                 | Historical backfills from a static source          |

Mirror is the right choice when your source data changes after the fact — refunds, subscription updates, compliance deletions. For high-volume event data that will never be corrected, Append is more efficient and cheaper.

<Note>
  **Pro tip**: Start your connector configuration in a staging project. This lets you validate permissions, test sync behavior, and catch mapping issues before they affect production data or existing reports.
</Note>

## Phase 2: Model Your Event Tables for Mirror

Mirror works by detecting row-level changes, so your event tables need to be structured to support both initial ingestion and downstream updates.

### Naming conventions

Use `snake_case` for event and property names (e.g. `purchase_completed`). Follow an object-action pattern — `order_shipped`, `user_signed_up` — so event names are self-explanatory across teams and in downstream exports.

There's a soft limit of 5,000 distinct event names in Mixpanel. Exceeding it makes data discovery and autocomplete harder to work with.

### Core column mapping

| Mixpanel field    | Required | Type              | Notes                                        |
| ----------------- | -------- | ----------------- | -------------------------------------------- |
| Event Name        | Yes      | String            | The action performed                         |
| Time              | Yes      | Timestamp         | When the event occurred                      |
| User ID           | No\*     | String or Integer | Maps to `distinct_id` for identified users   |
| Device ID         | No\*     | String or Integer | Maps to `distinct_id` for anonymous tracking |
| JSON Properties   | No       | JSON or Object    | Flattened automatically by Mixpanel          |
| Group Key(s)      | No       | String or Integer | Required for group-level analysis            |
| All other columns | No       | Any               | Auto-detected as event properties            |

\* *User ID or Device ID is technically optional in connector setup, but without one, events can't be linked to a user profile or attributed to a consistent identity.*

Each event supports a maximum of 255 properties. Property names longer than 255 characters are truncated. For [data type](/docs/data-structure/property-reference/data-type) details and a full list of [events and properties limits](/docs/data-structure/events-and-properties#what-are-the-limits-of-events-and-properties), refer to the Mixpanel docs.

<Warning>
  **Pitfall**: Adding a new column to a source table triggers a full resync of every row in that table. For large datasets, that's a significant spike in billable event volume. Plan schema changes intentionally and time them to avoid unexpected cost.
</Warning>

## Phase 3: Set Up Profiles and Profile History

[User Profiles](/docs/data-structure/user-profiles) and [Group Profiles](/docs/data-structure/group-analytics#group-profiles) capture the current state of a person or group. They're mutable by design — you can update them any time, and they join retroactively with all past events sharing the same identifier. That means you don't need to track events and profiles in lockstep; Mixpanel applies the current state at query time.

For most current-state profile tables, Full Sync is the right mode. Use Mirror when you need to track how profile properties changed over time.

### Modeling Profile History (SCD Type 2)

[Profile History](https://mixpanel.com/blog/slowly-changing-dimension-tables-in-product-analytics/) lets you analyze how attributes like subscription status or MRR evolved, and associate each event with the user's state at the moment it occurred — not their current state. This is critical for accurate revenue reporting and churn analysis.

Your source table needs to follow SCD Type 2 structure: each state change is a new row, not an overwrite. Mixpanel infers the end time of each record from the start time of the next one.

**Required columns:**

| Mixpanel field            | Required | Type                      | Notes                                            |
| ------------------------- | -------- | ------------------------- | ------------------------------------------------ |
| Distinct ID or Group ID   | Yes      | String or Integer         | Unique user or group identifier                  |
| Start Time                | Yes      | Timestamp or Date         | When this version of the attribute became active |
| At least one other column | Yes      | Any (no Lists or Objects) | The attribute(s) whose history you're tracking   |

<Warning>
  **Pitfall**: Profile History columns don't support List/Array or Object (JSON) types. Flatten those fields in your warehouse before syncing, or they won't ingest correctly.
</Warning>

<Note>
  **Pro tip**: When modeling churn, you need to explicitly sync a row where `subscription_status` is `inactive` or `mrr_value` is `0`. Mixpanel assumes a user stays in their last known state until a new row arrives — so without that explicit record, historical reports will overstate active users and revenue.
</Note>

Only track properties that change at a manageable frequency and matter for analysis. Tracking high-velocity fields like `last_active_at` in a history table creates row volume that can hurt query performance and inflate costs. Focus on core business drivers: `status`, `tier`, `plan`, `geography`.

## Phase 4: Map Identities Consistently

The [`distinct_id`](/docs/tracking-methods/id-management) is the primary join key in Mixpanel. It connects events to user profiles and drives all core analyses — Funnels, Retention, and unique user counts.

In a warehouse-native setup, you define this mapping. The column you map to `distinct_id` in your Events table must contain the exact same values as the primary key in your User Profiles table. If they don't match, events and profiles won't join, and your analyses will fragment.

For group-level analysis using [Group Analytics](/docs/data-structure/group-analytics), the Group Key (e.g. `account_id`) plays the same role — make sure it's consistent across event and group profile tables.

<Note>
  **Pro tip**: Unlike client-side SDK tracking, Mirror doesn't handle ID bridging automatically. [Validate your identity mapping](/docs/tracking-methods/id-management) before your first sync, not after. A mismatch across millions of rows is expensive to fix.
</Note>

## Phase 5: Configure Sync Frequency and Monitor Health

Sync frequency is a tradeoff between data freshness and warehouse compute cost. Options are Manual (Sync Now), Daily, or Hourly (on select plans).

For slower-changing data like profiles, daily is usually sufficient. For transactional events where corrections happen quickly, hourly or API-triggered syncs give you tighter parity.

If your data pipeline runs on a schedule, the Advanced Sync API lets you trigger a sync programmatically after a transformation job completes — so Mixpanel always reflects your most recent warehouse run.

Once live, monitor regularly:

* **Sync status**: Check for failures, delays, or mapping errors. Sync success is your primary signal for data parity.
* **Event volume alerts**: Set automated alerts in [Data Volume Monitoring](/docs/data-governance/data-volume-monitoring) to catch unexpected spikes. These often signal an upstream warehouse issue or an unplanned schema change triggering a resync.

## Key Takeaways

* Mirror uses CDC to reflect every warehouse change — new rows, updates, and deletions — but every change counts as a billable event, so modeling decisions directly affect cost.
* Match sync mode to how your data changes: Mirror for transactional events and profile history, Full Sync for current-state profiles and lookup tables, Append for immutable high-volume logs.
* Profile History (SCD Type 2) enables as-of analysis — associating each event with the user's state at the moment it occurred — but requires flat column structures and explicit churn rows to work correctly.
* `distinct_id` must match exactly between your event and profile tables; mismatches fragment the user view and can't be easily fixed after the fact.
* Schema changes to source tables trigger full resyncs. Plan them intentionally.
* Daily sync frequency is sufficient for most profile data; use hourly or API-triggered syncs for transactional data where corrections are time-sensitive.

👉 **Next step**: For guidance on naming conventions, metadata, and access controls once your sync is live, see [Govern Your Mixpanel Data for Long-Term Success](/guides/guides-by-topic/govern-data).


# Write business context that grounds AI answers
Source: https://docs.mixpanel.com/guides/guides-by-workflow/write-business-context



### Overview

Mixpanel Agent, MCP, and Headless can all draw on your project's business context to ground their answers. Without it, they guess at what "activation" means or which report is the source of truth.

This guide is for anyone with project owner or admin access who already has one of these tools turned on and is staring at a blank business context field, unsure what to put in it.

If you’re looking for details on how to use one of those surfaces or define your event schema, check out the guides on [Mixpanel Agent](/guides/guides-by-use-case/empower-your-team/mixpanel-agent), [MCP](/guides/guides-by-use-case/empower-your-team/mcp), [Headless](/guides/guides-by-use-case/empower-your-team/headless), or [event schema](/docs/data-structure/events-and-properties).

### What makes context useful, not just present

[Business context](/docs/business-context) has a structure: markdown text at the organization level and the project level, read by AI assistants across Mixpanel Agent, MCP, and Headless.

Filling in the structure correctly isn't the same as filling it in well. A field labeled "North Star Metric" with a metric name in it tells an AI assistant nothing it can compute. A field with the actual formula does.

The difference comes down to a handful of things:

* **Keep it tight.** Each point should read like something you'd tell a new hire in one sentence, not a page of documentation.
* **Formulas, not names.** "North Star Metric: Weekly Active Analyzers" is a label. "Weekly Active Analyzers = users who create, edit, or share a report at least once in a seven-day window, excluding internal seats" is something an assistant can act on.
* **Event semantics, stated.** If an event name could mean two different things, say which one. For example, `completed_project` could mean saved a draft or published. Write down which.
* **Scope and boundaries.** Say whom an analysis applies to and where it stops. "This metric applies to self-serve accounts, not enterprise" prevents an answer that's technically correct for the wrong segment.
* **Restraint on anything that goes stale.** Live usage numbers, like query volume and dashboard counts, feel like context but age out fast. Include a number only if it's genuinely load-bearing for how an answer gets built, not because it makes the context feel more complete.
* **Description, not direction.** Business context works best as facts about your business, not instructions for how the AI should behave. Something like "our north star metric is X" is reliable. Something like "always respond in three bullet points" isn't guaranteed to be followed, and isn't what this field is for. If you want to shape how an assistant responds, that's a prompting or settings question, not a context question.

Context has a generous size limit, but it's headroom, not a target. Well-written context for most projects uses a fraction of it. If you're approaching the limit, that's usually a sign some of what you've written belongs in Lexicon descriptions instead, not that you need more room.

<Info>
  It's tempting to pull live stats straight from your project into context because they're easy to grab and look thorough. Resist it. A metric formula stays true indefinitely. A count of active users, team members, or accounts is wrong by next quarter.
</Info>

### How to structure context

Business context works at two levels, and they're not interchangeable.

#### Organization context

**Organization context** applies to all of your projects and is shared across your whole team. [Only organization admins can edit it](/docs/business-context#edit-organization-context); everyone with access can read it.

Think of it as what any AI assistant should know about your business no matter which one of your Mixpanel projects it's working in: the big picture that doesn't change from one project to the next. It ideally covers:

* **Company background**: What the business does
* **Business model**: How the business generates value, whether that's revenue, subscriptions, usage, or another growth driver
* **North star metrics**: With the formula, not just the name
* **Customer segments**: The groupings that matter for analysis, whether that's individual users, accounts, or organizations
* **Internal acronyms**: Anything your team abbreviates that an outsider would have to guess at

<Danger>
  Never put credentials, passwords, or customer PII in business context. It's sent to your connected AI provider as part of the conversation, so treat it the same as anything else leaving your systems.
</Danger>

#### Project context

**Project context** describes the domain a specific project covers and how it's used. [Project owners and admins, along with anyone assigned a Custom Role that includes the ability to edit project settings, can edit business context](/docs/business-context#edit-project-context); anyone with project access can read it.

This matters most if you run more than one project — for example, separate projects for different business lines, or per-region deployments, since each project's event taxonomy and dashboards can differ.

If you run a single project, some of this may already be obvious from the org context, but it's still worth stating anything project-specific that Mixpanel Agent, MCP, or Headless wouldn't otherwise know.

Project context covers:

* **Product overview**: What the project tracks and the main user actions
* **Event taxonomy**: Naming conventions and what each major event represents
* **Property conventions**: Units, formats, and what specific properties mean
* **Key dashboards**: Where the canonical reports live, and why they're canonical
* **Team norms**: How your team defines active users, churned users, or qualified leads
* **Operating procedures**: The kind of thing you'd tell a new hire on day one, like which cohort to use for marketing analyses

### How to add context

You can write business context two ways:

1. **Mixpanel UI**: Go to either of the following locations and use the textbox to edit it directly.
   1. Settings → Org → AI Settings → Company Context
   2. Settings → Project → AI Settings → Project Context
2. **Mixpanel MCP**: If you're already connected through MCP, ask your AI assistant to update it for you, in the same conversation you're already having.

Either way, the same permissions apply as above: for org context, only organization admins; for project context, anyone who has access to edit project settings, such as project owners or admins.

MCP doesn't grant any additional access. If your account can't edit context in Settings, asking your AI assistant to do it through MCP will fail.

The MCP path is often faster once you're mid-conversation and realize the assistant is missing something. No need to switch to Settings to fix it.

<Warning>
  The `Update-Business-Context` MCP tool always performs a full replace — there's no append or merge mode. To add something without losing what's already there, ask your assistant to fetch the current context first, then write the updated version with both the old content and your addition included, before saving.
</Warning>

### Worked examples

Here's what dense context looks like in practice. These are composite examples, not real customers' actual context, but each is built to the same level of specificity you should aim for.

Pick the tab closest to your business as a reference point, not something to copy in directly. The specific metrics, event names, and terminology are illustrative, and only your own context will actually match your data.

<Tabs>
  <Tab title="E-commerce / Subscription">
    **Organization context**

    ```text wrap theme={"system"}
    ## Business Overview
    B2C e-commerce retailer selling pet supplies.

    ## Business Model
    Revenue from direct purchases plus a recurring subscription program for replenishment purchases.

    ## North Star Metric
    Subscription Conversion Rate = % of first-time purchasers who place a second order via subscription within 30 days of their first purchase.

    ## Customer Segments
    - New vs. returning customers
    - Subscribers vs. one-time purchasers
    - High-value: loyalty program members with 5+ lifetime orders

    ## Internal Acronyms
    - "KM" = Key Milestone: the framework for tracking user milestones  (first order, first subscription signup, first category expansion)
    - "OMS" = Order Management System, the server-side order source of truth
    ```

    **Project context**

    ```text wrap theme={"system"}
    ## Product Overview
    This project tracks the pet supplies shopping funnel, account registration, and the subscription program lifecycle. Order data comes from both storefront clickstream and the order management system (OMS).

    ## Event Taxonomy
    - Order data arrives from two sources, storefront clickstream and OMS, with each source using a different event name for the same action. A custom event, "Order Placed", combines them so you can analyze orders from both sources together under one name instead of running separate queries for each raw event.
    - Naming convention: Title Case for events (e.g. "Product Added to Cart"), not snake_case.
    - Noun-Verb pattern is standard ("Registration Succeeded", not "Registration").

    ## Property Conventions
    - Subscription status lives on the user profile, not the event (property: current_subscription_status).
    - "New to [Category]" properties flag first-time category purchases, used for cross-sell targeting, not just reporting.

    ## Key Dashboards
    - "Subscription Health" is the source of truth for subscription metrics: conversion, churn, reactivation. Don't rebuild from raw events; the board is built on the "Order Placed" custom event and already excludes test accounts.
    - "Revenue Attribution" is the canonical view for channel performance. It's built on the "Order Placed" custom event, so orders are counted consistently regardless of which system originally recorded them.

    ## Team Norms
    - "Active user" = placed an order or logged in within the last 30 days.

    ## Operating Procedures
    - Use the "Order Placed" custom event, not the individual raw OMS or clickstream events, so orders from both sources are analyzed together under one name.
    - Legacy notification events (email/SMS delivery telemetry) are in the schema but not used in current reporting. Their presence doesn't mean they're relevant. Ignore them unless someone specifically asks about email or SMS delivery.
    ```
  </Tab>

  <Tab title="B2B SaaS">
    **Organization context**

    ```text wrap theme={"system"}
    ## Business Overview
    B2B SaaS platform serving individual users through enterprise organizations.

    ## Business Model
    Usage-based and tiered subscription revenue, spanning free-tier individual use through paid enterprise contracts.

    ## North Star Metric
    Org Activation Rate = % of newly registered organizations that reach paid-tier usage within 30 days of signup.

    ## Customer Segments
    - Individual users (free tier) vs. paid organizations
    - Segmented by firmographic data (company size, industry) enriched from CRM systems, not just in-product behavior

    ## Internal Acronyms
    - "Org" = the top-level account entity in the product, encompassing multiple users or teams, distinct from an individual user
    ```

    **Project context**

    ```text wrap theme={"system"}
    ## Product Overview
    This project tracks the organization lifecycle, from registration through initial product setup and ongoing usage across web and integrated third-party tools.

    ## Event Taxonomy
    - Event data comes from two sources: client-side web tracking and a periodic data warehouse sync. If a question needs near-real-time data, check whether the relevant event is warehouse-sourced first, since batch syncs run on a delay. Warehouse-sourced events carry a data_source: warehouse property.
    - Naming convention: Title Case is standard for events (e.g. "Account Created"), with a strong Noun-Verb pattern.
    - Group Analytics is enabled and used for organization-level reporting, since most business questions are about org-level behavior, not individual user behavior.

    ## Property Conventions
    - Customer properties are enriched with CRM and firmographic data (company size, industry), not just tracked in-product behavior, since org segmentation depends heavily on company-level context.
    - An event property named bot_traffic marks non-human traffic, separate from any user-agent or behavior-based heuristic. Exclude events where bot_traffic is true from any analysis of real user behavior, unless the question is specifically about bots.
    - Marketing and channel attribution relies on UTM properties.

    ## Key Dashboards
    The "Org Activation Funnel" dashboard is the source of truth for how organizations move from registration to their first paid action.

    ## Team Norms
    - "Active organization" = at least one user at the organization took a core product action (e.g. created an item, invited a teammate, completed a workflow step) in at least 3 of the past 4 weeks. Recurring engagement is what distinguishes an active org from a dormant one.

    ## Operating Procedures
    - Use Group Analytics for any question about organization behavior; individual user-level analysis undercounts activity for accounts with multiple team members.
    - Prefer verified events and metrics over raw equivalents when both exist, since raw versions haven't been vetted for accuracy.
    ```
  </Tab>

  <Tab title="QSR / Multi-channel Ordering">
    **Organization context**

    ```text wrap theme={"system"}
    ## Business Overview
    Quick-service restaurant (QSR) chain with ordering available across mobile app, web, and in-store kiosk.

    ## Business Model
    Revenue from food and beverage purchases made across multiple ordering channels rather than one primary channel.

    ## North Star Metric
    Cross-Channel Order Conversion Rate = % of sessions across app, web, or kiosk that result in a completed purchase within that same session.

    ## Customer Segments
    - Channel used to order: app vs. web vs. in-store kiosk
    - Repeat purchasers vs. first-time or occasional purchasers

    ## Internal Acronyms
    - "AOV" = Average Order Value, used alongside standard revenue-per-user metrics as a core financial measure
    ```

    **Project context**

    ```text wrap theme={"system"}
    ## Product Overview
    This project tracks the ordering funnel across three channels: app (iOS and Android), web, and in-store kiosk. Data is a mix of user-driven ordering actions and system-level telemetry, such as errors and login issues.

    ## Event Taxonomy
    - Checkout funnel events use short, snake_case step names (e.g. cart_viewed, checkout_started), unlike the curated Metrics and Formulas layer, which uses Title Case.
    - A small number of saved metrics and formulas are treated as the source of truth for core funnel reporting, rather than raw event queries.

    ## Property Conventions
    - A property named order_source (values: app, web, or kiosk) identifies which ordering channel a purchase event originated from. Break down by this property when comparing channel performance, since a single event name can represent purchases from more than one channel.
    - Marketing-driven sessions are flagged separately from organic ones, so campaign performance isn't conflated with unpaid engagement when reporting on channel performance.

    ## Key Dashboards
    - The "Order Funnel Overview" dashboard is the source of truth for overall conversion, covering app, web, and kiosk together, not one platform in isolation.
    - A dedicated "In-Store Ordering" dashboard tracks the in-store flow specifically, since kiosk behavior (queue time, order errors) differs enough from app and web to need its own view.

    ## Team Norms
    - "Repeat purchaser" = 4 or more completed orders within a 90-day window, evaluated per customer across all channels, not per channel.
    - Login errors and failed checkout attempts are tracked as a standing reliability signal. Check these first when conversion drops, not just when someone reports an outage.

    ## Operating Procedures
    - Use the "Order Funnel Conversion" metric for any conversion reporting; rebuilding from raw events risks missing the cross-channel unification these metrics already handle.
    - Always exclude marketing-attributed sessions before assessing organic engagement, since campaign-driven traffic is tracked separately for this reason.
    ```
  </Tab>
</Tabs>

Notice what's absent from the finished examples: no counts of active users or team members, no query volumes, no dashboard counts. Everything here is something an AI assistant would otherwise have to guess at, and nothing here goes stale on its own.

### Common mistakes

Most of what goes wrong with business context isn't a formatting mistake. It's writing context as if it's a one-time setup task instead of something that needs upkeep, or mistaking a copy of your schema for something an AI assistant actually needed to be told.

* **Writing context once and never touching it again.** Context should change when your taxonomy or strategy change, not just when someone remembers it exists.
* **Copying schema instead of explaining it.** An AI tool connected through MCP can already see your schema in Lexicon. Context is the part it can't infer, such as how your team defines the terms it uses internally, and who or what those terms actually apply to.
* **Trying to document every event in business context.** As your event and property list grows, documenting each one individually will burn through the character limit fast, and that level of detail belongs in Lexicon event descriptions instead, which Mixpanel AI surfaces also read.
* **Trying to control behavior through context.** Writing instructions like "always summarize in three bullet points" isn't what this field is for and isn't guaranteed to work.
* **Skipping the org level entirely.** Project context without org context tells an AI assistant how your data is shaped but not what business it's shaped for.

### Beyond business context

Business context isn't the only thing that shapes what an AI assistant knows about your data. A few other things are worth investing in alongside it:

* [**Lexicon**](/docs/data-governance/lexicon) descriptions, sample values, and tags document individual events and properties. If business context is the big picture, Lexicon is the detail underneath it.
* [**Verified Mode**](/docs/mixpanel-agent#verified-mode) flags which events, metrics, behaviors, and cohorts your team has vetted as trustworthy, so an AI assistant (and your teammates) can tell the difference between something reviewed and something not.
* [**Annotations**](/docs/features/annotations) mark specific moments on your data, like a launch or an incident, that explain why a metric moved on a given day.

This guide covers business context specifically. These are separate, complementary practices, not something business context replaces.

### Key takeaways

* Write formulas and specifics into context, like metric definitions, event semantics, scope, and boundaries, not just labels.
* Skip anything that goes stale fast (live usage stats) and anything that reads as an instruction rather than a fact.
* Never include credentials, passwords, or PII. Context leaves Mixpanel and goes to your connected AI tool.
* Keep organization context about the business and project context about how that specific project is used; don't blend them.
* Updates through Settings or MCP always fully replace what was there. Fetch the current context before making a change.
* Revisit context whenever something it describes changes, whether that's your event taxonomy, your customer segments, or how the business measures success. Stale context can be worse than none.

Not sure which tool fits your team? Compare [Mixpanel Agent](/docs/mixpanel-agent), [MCP](/docs/mcp), and [Headless](/docs/mixpanel-headless) to see which one matches how you work, and then start to use it with your updated context.


# Mixpanel Introduction
Source: https://docs.mixpanel.com/guides/mixpanel-introduction



Mixpanel is a **digital analytics platform** that helps teams continuously improve their products by turning data into action. At its core, Mixpanel supports a **continuous innovation loop**—helping you observe what users do, analyze why it happens, decide what to do next, and act on those insights.

<Note>
  **Why it matters:** Teams use Mixpanel to learn faster, align decisions across functions, and measure the impact of every product change.
</Note>

***

## See Mixpanel in Action

<FrameColumn title="Mixpanel Overview" description="In this 5-minute overview, learn how Mixpanel powers the continuous innovation loop––from observation to impact." />

***

## Mixpanel Features That Power Continuous Innovation

<Columns>
  <div>
    Mixpanel is built around a simple but powerful framework for continuous improvement: **Observe → Analyze → Decide → Act (OADA)**.

    Each stage in the OADA framework connects directly to Mixpanel’s tools, helping you move from data to observation to action–—all in one platform.
  </div>

  <div>
    <Frame>
      <img alt="OADA Loop diagram" />
    </Frame>
  </div>
</Columns>

| 👀 **Observe**                                                                                                                                                                                                       | 📊 **Analyze**                                                                                                                                                                                                        | 💡 **Decide**                                                                                                                                                | 🚀 **Act**                                                                                                           |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| See what’s happening in your product with [Session Replay](/docs/session-replay), [Heatmaps](/docs/session-replay/heatmaps), [Autocapture](/docs/tracking-methods/autocapture), and [Alerts](/docs/features/alerts). | Explore [Insights](/docs/reports/insights), [Funnels](/docs/reports/funnels), [Flows](/docs/reports/flows), [Retention](/docs/reports/retention), and [Cohorts](/docs/users/cohorts) to find what moves your metrics. | Align on what to change next with [Metric Trees](/docs/metric_tree), [Boards](/docs/boards), [Annotations](/docs/features/annotations), and shared insights. | Measure impact with [Experiments](/docs/experiments) and ship improvements with [Feature Flags](/docs/featureflags). |

All of this is powered by Mixpanel’s modern data foundation—–bringing together AI-assisted analysis through features like [MCP Server](/docs/features/mcp), robust [data governance](/docs/data-governance) for accuracy and trust, and built-in collaboration tools that help teams move from insight to action faster.

**Learn more:** [Go deeper on the OADA Loop →](/guides/guides-by-topic/continuous-innovation)

***

## Mixpanel Data Model

Everything in Mixpanel starts with **events**––the building blocks of your data model.

An event represents something a **user** does (like *Signed Up*, *Viewed a Product*, or *Completed Purchase*). Each event can include **event properties** that add context, such as the user’s plan type, location, or device.

Alongside events, Mixpanel also tracks **user profiles**––records that represent individual people. These profiles store demographic attributes known as **user properties** (like name, email, or signup date), which help you understand who your users are and analyze behavior at the individual level.

Optionally, you can analyze data at the group level using [Group Analytics](/docs/data-structure/group-analytics).

<Frame>
  <img alt="Data Model" />
</Frame>

Together, these events and properties form a flexible data model that mirrors how people actually use your product. Once instrumented, you can analyze this data instantly—–without writing SQL or waiting on an analyst.

**Learn more:** [Dive deeper into how Mixpanel structures data →](/docs/data-structure/concepts)

***

## Keep Learning

Keep building your Mixpanel expertise with these resources designed to help you learn, connect, and put insights into action.

| Resource           | Purpose                                                                                              | Link                                      |
| ------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| **Community**      | Connect with other Mixpanel users, share ideas, and learn how peers are tackling similar challenges. | [Open →](https://community.mixpanel.com/) |
| **Developer Docs** | Build and extend Mixpanel with SDKs, APIs, and advanced implementation guides.                       | [Open →](/reference/overview)             |
| **Docs**           | Explore product capabilities, setup guides, and detailed feature references.                         | [Open →](/)                               |
| **Events**         | Join live sessions and webinars to explore new features, use cases, and expert-led best practices.   | [Open →](https://mixpanel.com/events)     |
| **Guides**         | Apply Mixpanel best practices to real-world workflows and use cases.                                 | 📍 You are here                           |

Wherever you are in your Mixpanel journey, these resources will help you keep learning, stay connected, and keep improving.


# Self-Guided Tours
Source: https://docs.mixpanel.com/guides/self-guided-tours



Discover Mixpanel’s core features through quick, self-guided tours. Click any card below to explore interactive walkthroughs of key workflows.

<div>
  <a href="https://mixpanel.com/contact-us/sales/">
    Want a guided demo instead?
    <span>→</span>
  </a>
</div>

### Overview

Understand what Mixpanel is, how it works, and how to navigate it.

<SelfGuidedTours />

### Get Set Up

Connect data, configure your workspace, and validate that events flow correctly.

<SelfGuidedTours />

### Find Insights

Explore and analyze user behavior to understand what’s happening in your product.

<SelfGuidedTours />

### Experiment & Optimize

Run tests, manage feature rollouts, and improve product experiences.

<SelfGuidedTours />

### Govern & Maintain Data Quality

Ensure your data is consistent, trustworthy, and well-documented.

<SelfGuidedTours />


# Strategic Playbooks
Source: https://docs.mixpanel.com/guides/strategic-playbooks



## Guide to Product Analytics

<CardGroup>
  <Card title="Introduction" href="/guides/strategic-playbooks/guide-to-product-analytics/intro" />

  <Card title="Chapter 1: Measure Values" href="/guides/strategic-playbooks/guide-to-product-analytics/measure-value" />

  <Card title="Chapter 2: Get to Know Your Users" href="/guides/strategic-playbooks/guide-to-product-analytics/get-to-know-your-users" />

  <Card title="Chapter 3: Analyze User Engagement" href="/guides/strategic-playbooks/guide-to-product-analytics/analyze-user-engagement" />

  <Card title="Chatper 4: Retain Your Users" href="/guides/strategic-playbooks/guide-to-product-analytics/retain-your-users" />

  <Card title="Chapter 5: Grow and Scale" href="/guides/strategic-playbooks/guide-to-product-analytics/grow-and-scale" />

  <Card title="Conclusion" href="/guides/strategic-playbooks/guide-to-product-analytics/conclusion" />
</CardGroup>

## Product Analytics Strategy

<CardGroup>
  <Card title="Introduction" href="/guides/strategic-playbooks/product-analytics-strategy/get-started" />

  <Card title="Stage 0: Non-Existent" href="/guides/strategic-playbooks/product-analytics-strategy/non-existent" />

  <Card title="Stage 1: Novice" href="/guides/strategic-playbooks/product-analytics-strategy/novice" />

  <Card title="Stage 2: Intermediate" href="/guides/strategic-playbooks/product-analytics-strategy/intermediate" />

  <Card title="Stage 3: Advanced" href="/guides/strategic-playbooks/product-analytics-strategy/advanced" />

  <Card title="Stage 4: Expert" href="/guides/strategic-playbooks/product-analytics-strategy/expert" />

  <Card title="Conclusion" href="/guides/strategic-playbooks/product-analytics-strategy/finale" />
</CardGroup>

## Onboarding Playbook

<CardGroup>
  <Card title="Onboarding Playbook" href="/guides/strategic-playbooks/onboarding-playbook" />
</CardGroup>

## Project Migration

<CardGroup>
  <Card title="Project Migration Playbook" href="/guides/strategic-playbooks/project-migration" />
</CardGroup>

## Feature Flag and Experiments Migration

<CardGroup>
  <Card title="Feature Flag & Experiments Migration Playbook" href="/guides/strategic-playbooks/feature-flag-migration-playbook" />
</CardGroup>


# Migrating Your Feature Flags and Experiments to Mixpanel  
Source: https://docs.mixpanel.com/guides/strategic-playbooks/feature-flag-migration-playbook



This guide walks through migrating your feature flags and experiments hosted in another platform into Mixpanel. It's for teams currently running flags and experiments on a third-party vendor who want to consolidate that work in Mixpanel instead.

By following this guide, your flags and experiments will be set up in Mixpanel, your historical results will carry over, and your application code will be evaluating flags through Mixpanel rather than your old provider.

<Note>
  This guide is a reusable template. The steps below are vendor-agnostic. To migrate from a provider (Statsig, LaunchDarkly, Optimizely, GrowthBook, OpenFeature, or any setup), substitute that vendor's export API in each "Export" step — the Mixpanel side stays the same.
</Note>

## Migration overview

A complete migration has five parts:

1. **Migrate past experiment exposure events** so your historical results carry over.
2. **Migrate feature gate, experiment, and dynamic config configurations** (both the setup and the reporting).
3. **Complete setup of Feature Flags and Experiments** in the Mixpanel UI.
4. **Recreate critical flags and experiments** in your application code.
5. **Verify migration status**, including number of feature flags migrated and exposure count.

Here's how to work through each step.

## Step 1. Migrate past experiment exposure events

An exposure event records that a user was enrolled in a feature gate, an experiment, or a dynamic config, and was exposed to a specific variant. To keep your historical data, export your existing exposure events from your current vendor and ingest them to Mixpanel as `$experiment_started` events.

<Warning>
  Running migrations for experiments mid-flight is a high risk task. As the Mixpanel SDK will randomly assign variant assignments in your app, it is impossible to maintain the same variant assignment in your current set up.
</Warning>

### Export exposure events from your vendor

Most vendors have a dedicated exposure event you can export. You can usually export them directly from the UI or by using the vendor's API. You will need the following fields at minimum:

* The enrollment ID: user ID, device ID, or group ID exposed to the experiment or feature flag
* Timestamp of the exposure
* The experiment or feature flag name
* The assigned variant

Details about Mixpanel's `$experiment_started` event can be found [here](/docs/experiments#implementation-for-experimentation).

#### **Equivalent events**

Each vendor has its own definition of exposure event and they can be mapped to Mixpanel's exposure event depending on the Mixpanel Feature Flag type (feature gate, an experiment, or a dynamic config). Use this table to find the equivalent for your setup:

| Mixpanel Feature Flag Type | [Statsig Equivalent](https://docs.statsig.com/integrations/event_webhook#event-format) | LaunchDarkly Equivalent                                                                                                                                                                                                                                                                                                                                        | [Optimizely Equivalent](https://docs.developers.optimizely.com/experimentation-data/docs/event-api-getting-started#activate-users) | [GrowthBook Equivalent](https://docs.growthbook.io/app/event-forwarder#experiment-view-events) |
| :------------------------- | :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- |
| Experiment                 | `statsig::experiment_exposure`                                                         | [*Streaming*](https://launchdarkly.com/docs/integrations/data-export/schema-reference#feature-events) <br />`Feature` event where `reason.inExperiment` = true<br /><br />[*Warehouse*](https://launchdarkly.com/docs/integrations/data-export/warehouse-schema-reference#evaluation-events) <br />`evaluation_events` where `experiment_iteration_id` != NULL | `campaign_activated`                                                                                                               | `Experiment Viewed`                                                                            |
| Feature Gate               | `statsig::gate_exposure`                                                               | *Streaming* <br />`Feature` event where `reason.inExperiment` is absent/false<br /><br />*Warehouse* <br />`evaluation_events` where `experiment_iteration_id` is absent                                                                                                                                                                                       | Feature Rollout                                                                                                                    | (no gate exposure concept)                                                                     |
| Dynamic Configuration      | `statsig::config_exposure`                                                             | *Streaming* <br />`Feature` event where `reason.inExperiment` is absent/false<br /><br />*Warehouse* <br />`evaluation_events` where `experiment_iteration_id` is absent                                                                                                                                                                                       | Flag with Variables                                                                                                                | (no config exposure concept)                                                                   |

### Import events into Mixpanel as `$experiment_started`

Transform each exported exposure row into a Mixpanel `$experiment_started` event and send it through the **Mixpanel Import API**.

Ensure **Experiment name** and **Variant name** are correctly translated. Keep the original exposure timestamp so historical analysis is accurate, and include a unique `$insert_id` so re-runs don't create duplicates.

```javascript theme={"system"}
{
	"event": "$experiment_started",
	"properties": {
		"distinct_id": "alice@example.com", // enrollment ID
		"time": 1709275888, // Timestamp of exposure
		"$insert_id": "exp_4821_alice_1709275888", // for re-run deduplication
		"Experiment name": "checkout_flow_test", // The experiment or feature flag name
		"Variant name": "treatment" // The assigned variant
	}
}
```

## Step 2. Migrate feature gate, experiment, and dynamic config configurations

Now that you've brought over your historical exposure data, it's time to bring over the configurations themselves. This section guides you in moving configurations for experiment and feature flag **setup**, as well as, experiment **reporting**.

### Export configurations from your vendor

Your vendor may have a UI export, API export, or warehouse export options. Ensure you list and fetch definitions for feature gates, experiments, and dynamic configurations by consulting your vendor's documentation.

### Import the setup via Mixpanel API

Recreate each configuration in Mixpanel using Mixpanel APIs. Create experiments first, then the feature flags that reference them. You can refer to the [Mixpanel Feature Flags](/reference/feature-flags-api) API for more details.

<Tip>
  **Tip**: Test by migrating a few low-risk flags to validate the process first.
</Tip>

#### Experiment

You will need to make two API calls:

* **Create Experiment**: POST [`/api/app/workspaces/{workspace_id}/experiments`](/reference/create-experiment).
  * This creates the experiment entity.
* **Create Feature Flag**: POST [`/api/app/projects/{project_id}/workspaces/{workspace_id}/feature-flags`](/reference/create-feature-flag-1).
  * This creates the **feature flag** that references the experiment.
  * For an Experiment, the key is to provide values for`experiment_id`,`is_experiment_active`, and ensure the control and treatment values in the `ruleset.variants.value` are sent as strings.

#### Feature Gate

* **Create Feature Flag**: POST [`/api/app/projects/{project_id}/workspaces/{workspace_id}/feature-flags`](/reference/create-feature-flag-1).
  * For a Feature Gate, ensure you specify the control and treatment values in the `ruleset.variants.value` as a boolean value.

#### Dynamic Config

* **Create Feature Flag**: POST [`/api/app/projects/{project_id}/workspaces/{workspace_id}/feature-flags`](/reference/create-feature-flag-1).
  * For a Dynamic Config, the key is to specify the control and treatment values in the `ruleset.variants.value` as an object.

## Step 3. Complete setup of Feature Flags and Experiments in the Mixpanel UI

Now that you've recreated your flags and experiments base configurations through the Mixpanel API, complete the rest of the detailed setup via Mixpanel UI.

### Feature Flag setup

There are custom configurations that require additional effort to set up in Mixpanel, such as user targeting, rollout conditions, and runtime evaluation. Set these up in Mixpanel directly under the [Feature Flags](/docs/featureflags) menu by searching for the name of the feature flag that you have created via the Mixpanel API.

<Frame>
  <img alt="Feature Flag Setup" />
</Frame>

### Experiment setup

This step is only relevant if you have imported experiments into Mixpanel. A corresponding [Mixpanel Experiment](/docs/experiments#monitor-your-experiment) report will be created for every experiment you've imported. You will need to continue populating this experiment with the right configuration and metrics. Go to [Experiments](/docs/experiments) menu, and search for your experiment by name.

<Frame>
  <img alt="Screenshot 2026 07 21 At 4 36 21 PM" />
</Frame>

Map each of your vendor's experiment metrics to a Mixpanel metric so the same success criteria are measured.

<Frame>
  <img alt="Experiment Setup Metrics" />
</Frame>

## Step 4. Recreate critical flags and experiments in your code

With your feature flag configurations now migrated to Mixpanel, update your application code to use Mixpanel methods for flag evaluation and exposure. How much code changes depends on how your code calls your flags today.

In the case of live experiments, migration will result in users getting reassigned to a different variant mid-experiment. We recommend completing any existing experiments and importing the historical exposure events into Mixpanel, then launching the equivalent experiment fresh in Mixpanel post-cutover.

1. **If your code uses OpenFeature**: Swap the provider — replace your current provider with the Mixpanel provider and leave your existing evaluation calls unchanged, as long as your flag keys are carried over identically.
2. **If your code uses your vendor's SDK directly**: Replace those evaluation calls with the equivalent Mixpanel SDK calls for your language (for example, a boolean gate check becomes a Mixpanel boolean flag evaluation; a dynamic config read becomes a Mixpanel variant/JSON lookup).

If you are currently using LLMs, we also recommend exploring this migration approach with the [Mixpanel MCP server](/docs/mcp). The MCP server can read all the flags and experiments in your project, and will be a good assistant in making code changes.

```javascript theme={"system"}
// The following is for client side JS SDK experiments implementation

// Step 1: Initialize the JS SDK
mixpanel.init("YOUR_PROJECT_TOKEN", {
  flags: {
    persistence: {
      // Configure a variantLookupPolicy in the flags init options
      variantLookupPolicy: "networkFirst",
    },
  },
});

// Step 2: Check the variant value when you want to trigger the experiment
// The async get_variant_value waits for the call to succeed and
// falls back to the persisted value if it exists.
const variant_value = await mixpanel.flags.get_variant_value("my-feature-flag", "control");
```

```javascript theme={"system"}
// The following is for server side Node.js SDK experiments implementation

const Mixpanel = require('mixpanel');

const mixpanel = Mixpanel.init('YOUR_PROJECT_TOKEN', {
    // This experiment setup is with local evaluation, suited for low latency.
    // The SDK will poll Mixpanel servers for feature flag configurations.
    // Assignment of user contexts to variants will be done locally within the SDK.
    local_flags_config: {
        api_host: 'api.mixpanel.com',
        enable_polling: true,
        polling_interval_in_seconds: 60
    }
});

// If enable_polling is set to false, this will fetch definitions only once for the lifetime of the SDK.
await mixpanel.local_flags.startPollingForDefinitions();

// This should be the 'key' of the feature flag from Mixpanel's UI.
const flagKey = 'sample-flag';

// This is the fallback variant to return if the user context is not in a rollout group for the flag.
const fallbackValue = 'control';

// Current user context for evaluation.
// At minimum, this needs to include the user's distinct_id.
// If any of your feature flags use a Variant Assignment Key other than 'distinct_id', this should also include those keys for evaluation. For example, 'company_id' below.
// If any of your feature flags use runtime targeting, this should also include 'custom_properties' for evaluation.
const userContext = {
    distinct_id: '1234',
    custom_properties: {
        platform: 'node'
    }
};

// Gets the assigned variant for the flag for the given user context.
// This will return the fallback_variant if the user context is not in an assignment group for the flag.
const variantValue = mixpanel.local_flags.getVariantValue(flagKey, fallbackValue, userContext);

// Call trackExposureEvent when the user actually sees the feature.
mixpanel.flags.trackExposureEvent('test', variant);
```

3. **Add a fallback during cutover (recommended)**: Wrap your Mixpanel flag calls so that if a value can't be retrieved, the code falls back to the same value as configured in your previous provider. This lets you run both systems side-by-side and confirm parity with no risk.
4. **Switch over and clean up**: Once you've verified the Mixpanel flags behave correctly in production, route fully to Mixpanel, then remove the fallback and the old provider's code. Keep a thin wrapper around flag evaluation as a facade so future changes happen in one place.

## Step 5. Verify migration status

Ensure you run a parity check. Things to verify include:

1. Number of feature flags migrated.
2. Feature flag exposure count — for number of users that were included in feature flag, as well as total number of exposure events.
3. Variant splits in feature flag setup — number of variants and rollout ratio match.
4. User variant match — QA on individual user levels for variant assignment.

### The result

The result is a clean, reviewed migration of your feature flags and experiments into Mixpanel: configurations recreated, historical results preserved, and your release workflow intact. Your Mixpanel team will partner with you through each step.

For the full reference on how flags and experiments work in Mixpanel — including targeting, rollout groups, and variant management — see [Feature Flags](/docs/featureflags) and [Experiments](/docs/experiments).


# Analyze User Engagement
Source: https://docs.mixpanel.com/guides/strategic-playbooks/guide-to-product-analytics/analyze-user-engagement

Understand product usage intervals, identify power/core/casual users, and track user lifecycle patterns for better engagement insights.

## Questions answered

* [What is my product usage interval?](#what-is-my-product-usage-interval)
* [Who are my power/core/casual users?](#who-are-my-powercorecasual-users)
* [What is the right definition of power/core/casual users for my product?](#what-is-the-right-definition-of-powercorecasual-users-for-my-product)
* [Besides segmenting by level of engagement, how else can you analyze different groups of users with product analytics?](#besides-segmenting-by-level-of-engagement-how-else-can-you-analyze-different-groups-of-users-with-product-analytics)
* [How can I track new users, resurrected users, retained users, and dormant users?](#how-can-i-track-new-users-resurrected-users-retained-users-and-dormant-users)

In the previous chapters on value and active usage, you learned what to measure, and how to decide whether your users are active or not based on true value moments.

But knowing whether your users are getting value isn't the end game. The natural next step is to find the dimensions or the texture of the engagement. **Why are some users active and others disengaged? Why are some users more active than others? And what can you do about it?**

## What is my product usage interval?

To group your users based on how engaged they are, we need to know how frequently they typically use your product. Daily? Weekly? Monthly? Every couple of months?

The answer, inevitably, is: **"It depends."** Take the now-popular "concierge medicine" category and apps like One Medical, Forward, or Parsley Health. The key value proposition of these apps is the convenience of booking medical appointments, so somebody who books an appointment once every six months on One Medical may well be "very active." And somebody who books an appointment every year is still "quite active."

Now let's flip it and look at the other extreme — a video-hosting social media app like TikTok. The value moment here might be watching a video and "hearting" it. Every night, a typical "active" user can "heart" 10, 20, even 30 videos. That's a far cry from once a year!

**In short, there's no standard "good" product usage interval, and you will need a combination of your product intuition and data to figure out the right one for your product.**

[Reforge](https://www.reforge.com/) pioneered this way of thinking about product usage intervals with their "habit zone" framework.

<Frame>
  <img alt="image" />
</Frame>

> "Fundamentally, the 'right frequency' of activity needs to be defined based on a candid assessment of how the product's target user personas can get optimal value out of the product. Highly frequent usage is expected for certain product categories (e.g., messaging, music, fitness trackers) whereas less frequent usage is better for users' success or fulfillment in other product categories (e.g., personal finance, shopping).
>
> Great PMs understand how their product should fit into their target users' lives and accordingly decide the right activity metric. As a tactic, great PMs also separate out proactive usage (where the user made the decision to engage with the product) from reactive usage (where a notification or other prompt from your product brought the user to it)."
>
> <div>**Shreyas Doshi**</div> *Lead PM at Stripe; Former Lead PM at Twitter, Google, Yahoo*

## Who are my power/core/casual users?

To find your power/core/casual users, start by defining what it means to be "a power/core/casual" user in your product:

1. In the Insights report, select an event that you define as your value moment (e.g., "watch video")
2. Highlight "total" to bring up all the different ways you can group your users. Select "total per user"
3. Select your level of aggregation. **Median (50th percentile) will be your core users. 90th percentile will be your power users. 25th percentile will be your casual users**
4. By highlighting the line graph, you can view how many videos each group typically watches hourly, daily, weekly, or monthly
5. Customize the date range. Mixpanel will default your line graph over time to a lookback of the last 30 days (from the active day) and a day-by-day count

### Take it one step further: Build and save your new cohorts

1. Click over to "Users" and "Cohorts"
2. Define what it means to be a power/core/casual user. For example, "Users that watched videos 2 or more times in the last 7 days"
3. Save the cohort

<Frame>
  <img alt="image" />
</Frame>

Using the median value as a baseline for your analysis, you can create cohorts to track how different groups of users are changing over time.

## What is the right definition of power/core/casual users for my product?

The tutorial above suggests that the more videos people watch (daily, weekly, monthly), the more active they are. This is helpful information to figure out which users are the most valuable, and which ones are likely to churn, but there are more dimensions of user behavior you can take into account:

### Frequency

How many days (a week, a month, a year) did people use your product?

For a product where you expect your users to come back weekly, perhaps a power user uses the product 6 out of 7 days, a core user uses the product 3 out of 7 days, and a casual user uses the product 1 out of 7 days.

### Breadth

How many different product features or offerings did people use?

For a ride-sharing company, a power user might have used their economy ride-sharing option, deluxe ride-sharing option, and their vanpool option, whereas a core user might have used only their economy and van pool option, and a casual user may have used just their economy ride-sharing option.

When a company extends its products beyond the core use case (e.g., a ride-sharing company adds food delivery), you can measure breadth of usage based on the number of unique product offerings users have tried.

### Depth

How deeply have users engaged with your product?

For a video platform company, a depth metric might be the number of videos watched, number of minutes spent watching videos, etc. For a marketplace platform company, it might be the total dollars spent on the platform.

**The dimension you end up picking depends on how people get the most value out of your product and what's correlated with engagement and long-term retention of your users.**

### Industry Examples

<div>
  <RakutenViberLogo />

  <div>
    "Active users are people who are using Viber seven out of seven days a week. From a product perspective, if we're doing something good, active users are supposed to grow and if we're doing something bad, then eventually they're going to drop. We monitor this metric daily."<div>**Idan Dadon**</div> *Product Manager, Viber*
  </div>
</div>

<div>
  <RoLogo />

  <div>
    "To us, an active member is someone who has an active plan—they haven't canceled or their plan hasn't expired. To make sure our members are getting value, we also look at how many of them have continued treatment in the past four months."<div>**Ira Patnaik**</div> *Director of Product, Ro*
  </div>
</div>

<div>
  <VrboLogo />

  <div>
    "An active user takes a trip 1-2 times per year. For us, it's a bit tricky because the shopping funnel has distinct phases—dreaming, planning, deciding, and booking. We haven't necessarily cracked the code of how to recognize what part of the funnel a person is in based on the activity that they're doing on the site and what the common actions are that can help us decide that a shopper has officially moved past one phase to the next one."<div>**Jamie Kapilivsky**</div> *Data Insights, Vrbo, part of Expedia Group*
  </div>
</div>

## How can I tie active usage to my value exchange (monetization) model?

Earlier, we covered various approaches to product monetization. If you're a PM early in the development process deciding how to monetize, how often (plus, how broadly and deeply) people engage with your product can be a valuable signal.

For example, on social media entertainment apps like TikTok, where users engage and get value daily, showing ads might be a natural fit. On the other hand, for a medical service where once a year engagement is expected, an annual subscription is a more reliable way to monetize.

## Besides segmenting by level of engagement, how else can you analyze different groups of users with product analytics?

### Regional and Behavioral Cohorts

<div>
  <RakutenViberLogo />

  <div>
    "We create cohorts based on percentiles of activity (to identify power users), region-based cohorts/breakdowns by countries (there's a lot of cultural difference in how people use the app as well as their data usage). We break it down as much as we can and try to understand users based on their behavior, not the average behavior."<div>**Idan Dadon**</div> *Product Manager, Viber*
  </div>
</div>

<div>
  <AviraLogo />

  <div>
    "We use a lot of cohorts, including: free/paid users, new/existing users, operating systems (Windows 10 versus Windows 7), region, and frequency of use.

    * **Free/paid users**: We look at how free users behave versus how paid users behave. Do paid users use the Smart Scan more often than free users, for example, or less often? What features do they use? We can then find behavioural twins in the free segment and push them to become paid.
    * **New/existing users**: We define a 'new' user as someone using our product for 30 days or less. We've noted that people tend to go from free to paid within the first 30 days. We look at this cohort specifically to see what the free to paid rate is, and how they behave.
    * **Operating systems (Windows 10 versus Windows 7)**: We've learned that our system speed up cleaning product is more interesting for people who still are on Windows 7, because they are on old hardware, and perhaps don’t want to invest in new hardware.
    * **Region**: Our marketing is based on different regions: Germany/Austria/Switzerland; U.S./English-speaking countries; and the rest of the world. We use these segments to see how regional users behave differently, and how business KPIs differ in these different countries.
    * **Frequency**: On how many days out of the last 28, 48 or 91 days has a user used our product?”
      <div>**Manuel Eugster**</div> *Vice President Data Intelligence, Avira*
  </div>
</div>

## How can I track new users, resurrected users, retained users, and dormant users?

To explore user behavior with lifecycle analysis, create cohorts for each group of users.

**In Mixpanel, you can define these groups in two simple steps:**

1. Select a meaningful event (your value moment, such as "watch video")
2. Check if a user has performed the event within your typical product usage interval (such as 7 days)

**For example, to create a cohort for resurrected users, you can select users who:**

* Performed "watch video" in the last 7 days
* Did NOT perform "watch video" between 14 and 7 days ago
* Performed "watch video" between 21 to 14 days ago

**Now let's apply similar logic to other cohorts:**

* **New active users**: Performed "sign up" in the last 7 days AND "watch video" at least once within the same time window
* **Retained users**: Performed "watch video" at least once in two consecutive intervals
* **Dormant users**: Performed "watch video" in previous usage interval, but did not in the current one

<Frame>
  <img alt="image" />
</Frame>

Once you create the cohorts you'd like to track, head over to the Insights report in Mixpanel to visualize their growth over time.

## Next Steps

### Retain your users

Now that you understand user engagement patterns, the next chapter focuses on identifying drop-off points and improving user retention.

[Read Chapter 4 →](/guides/strategic-playbooks/guide-to-product-analytics/retain-your-users)


# Conclusion
Source: https://docs.mixpanel.com/guides/strategic-playbooks/guide-to-product-analytics/conclusion



Imagine that every digital product has a value button. Every time a user gets value from your product, they hit that button and pay you a dollar. If they don't get value from your product, you don't get paid.

## So what are you going to build?

In this book, we've covered the foundations of product analytics. You now have the knowledge and tools to understand your users, measure engagement and retention, and optimize user acquisition for your north star metric. We've shared tips from PMs, data scientists, marketers, technology VPs and CEOs who rely on product analytics to make decisions. **They also rely on their product intuition, which can be just as valuable as their data.**

**The truth is, you need both.** The reason product analytics is so often mystified is that, unlike other forms of analytics, what we attempt to measure is, at its core, something very elusive: a person's behavior and their emotional state. Are they feeling entertained? Motivated? Happy? Does the product fill the need they have?

So when we see Video Views and Friends Added on Mixpanel dashboards, what each of those events represent is a moment when a person got a sense of satisfaction or happiness from a product. Unlike a set of data grounded in physical reality, like the number of items sold in a store, **product analytics is an attempt to capture these behavioral signals and turn them into something tangible, a number that can guide you as you iterate and improve your product to serve the user.**

Given this approach, when you analyze product usage as a PM, it is key that you bring not only the hard knowledge and skills and data to problem-solve but also your intuition and empathy to ask: **How would I feel if I were a parent signing up my kid for this online education app? Or a newly divorced person joining this dating app for the first time?**

**Only when you layer intuition and empathy on top of product analytics data will you be able to build truly useful features and product improvements that bring value, over and over again.**

## Worksheet

Ready to apply these concepts to your own product? Download our comprehensive worksheet to guide you through the process.

[Download Worksheet](https://mixpanel.com/wp-content/uploads/2020/09/Guide-to-Product-Analytics-Worksheet.pdf)

## Credits

### Written by

* **Anya Pratskevich** - Product Marketing Manager, Mixpanel
* **Marco Sanchez Junco** - Former Head of Customer Education, Mixpanel

### Editor

* **Lorraine Valestuk** - Editor

### Design

* **Alex Shepherd** - Associate Creative Director, Mixpanel
* **Mike Casebolt** - Brand Design Lead, Mixpanel
* **Goksu Kocakcigil** - Brand Designer, Mixpanel

### Contributors

**Industry Experts:**

* Drew Ashlock - Lead Product Manager, DocuSign
* Brian Balfour - CEO, Reforge
* Akio Bandle - Sr. Product Manager, ZipRecruiter
* Stephan Brenner - VP - Product, Avira
* Andrew Chen - General Partner, Andreessen Horowitz, Board Member, Reforge
* Idan Dadon - Product Manager, Viber
* Shreyas Doshi - PM Lead at Stripe, Former PM Lead at Twitter, Google and Yahoo
* Josh Elman - VC & Advisor; Former Product Leader at Robinhood, LinkedIn, Twitter
* Manuel Eugster - VP - Data Intelligence, Avira
* Shannon Ferguson - Director of Measurement, The Weather Company
* Carlos Gonzalez de Villaumbrosia - CEO Product School
* Dan Hockenmaier - Founder, Basis One; Growth Mentor and Contributor at Reforge
* Jamie Kapilivsky - Data Insights, Vrbo, part of Expedia Group
* Vinati Malik - Sr. VP of New Product Development, Tata Play
* John Meakin - Lead Statistician, Vrbo, part of Expedia Group
* Karim Mouahbi - Head of Marketing, Mad Paws
* Jordan Ng - Sr. Product Manager, Deliveroo
* Ira Patnaik - Director of Product, Ro, Former Product Lead at Airbnb

### Mixpanel Contributors

* Moinak Bandyopadhyay - Sr. Product Manager, Mixpanel
* Jeff Beckham - Director of Product and Content Marketing, Mixpanel
* Sam Graham - Brand Marketing Manager, Mixpanel
* Pranav Kashyap - Group Product Manager, Mixpanel
* Michael LaRosa - Product Manager, Mixpanel
* Hannah Maslar - Sr. Product Marketing Manager, Mixpanel
* Kiley Sheehy - Customer Success Manager, Mixpanel
* Alana Tees - Content & Communications Lead, Mixpanel

***

## Key Takeaways

Throughout this guide, we've explored:

1. [**Measuring Value**](/guides/strategic-playbooks/guide-to-product-analytics/measure-value): Understanding what value your product brings and how to quantify it
2. [**Getting to Know Your Users**](/guides/strategic-playbooks/guide-to-product-analytics/get-to-know-your-users): Segmenting users and understanding DAU/WAU/MAU
3. [**Analyzing User Engagement**](/guides/strategic-playbooks/guide-to-product-analytics/analyze-user-engagement): Identifying power, core, and casual users and their behavior patterns
4. [**Retaining Your Users**](/guides/strategic-playbooks/guide-to-product-analytics/retain-your-users): Finding drop-off points and improving retention
5. [**Growing and Scaling**](/guides/strategic-playbooks/guide-to-product-analytics/grow-and-scale): Building sustainable growth strategies

Remember: **The goal isn't just to collect data, but to use it thoughtfully, combined with empathy and intuition, to build products that truly serve your users' needs.**


# Get to Know Your Users
Source: https://docs.mixpanel.com/guides/strategic-playbooks/guide-to-product-analytics/get-to-know-your-users



## Questions answered

* [What's user segmentation in product analytics?](#whats-user-segmentation-in-product-analytics)
* [What's DAU/WAU/MAU?](#what’s-dau%2Fwau%2Fmau)
* [When should I measure DAU/WAU/MAU?](#when-should-i-measure-dau%2Fwau%2Fmau)
* [How can I measure my DAU/WAU/MAU count?](#how-can-i-measure-my-dau%2Fwau%2Fmau-count)
* [When it comes to measuring active usage, what's the difference between a good PM and a great PM?](#when-it-comes-to-measuring-active-usage-what’s-the-difference-between-a-good-pm-and-a-great-pm)

## What's user segmentation in product analytics?

If there's one thing that product managers, regardless of their industry and location, 100% agree on, it is that **to build great products, you need to understand your users**.

One of the first things that product managers do when they get into product analytics is to look at different user actions and then segment them by country, hoping to find some magical distinction. Are users in South Korea more active than in Mongolia? Such data is curious and potentially useful for marketing. But when it comes to making product decisions, **data on what users actually do in your product (behavioral data) speaks volumes more about who people actually are than their demographics**.

Such insights are more actionable, because in-product behavior can be "nudged"—and changed—more easily than demographics.

<Frame>
  <img alt="" />
</Frame>

User segmentation in product analytics is grouping users based on their demographics or behavior in order to establish a baseline for analysis.

**Mixpanel was built to help product managers understand user behavior. However, it lets you easily organize and analyze any user segment — behavioral (event-based) or demographic (profile-based).**

## How does it work?

<Frame>
  <img alt="" />
</Frame>

In Mixpanel, each data point is connected to a single user through a unique ID. **Events** are interactions between a user and your product. These are things users do, like signing up, adding items to cart, liking and following. **Profiles** store information about who your users are, like where they live (geo), and what email they use to log in.

## What's DAU/WAU/MAU?

Not all behavioral insights are equally actionable. Take DAU (daily active users), WAU (weekly active users), and MAU (monthly active users), the industry's most popular product metrics. These metrics are used to draw a simple distinction: **are my users active or not?**

If you know what "active" means for your business, getting this data is easy with product analytics. Below, we explain:

* How to define and measure DAU/WAU/MAU
* The pitfalls of measuring active usage
* When to use DAU/WAU/MAU (and when not to)

### Defining "active usage"

#### When calculating your DAU, WAU, or MAU, remember that A stands for "Active"

Some companies consider an active user to be someone who simply accesses the site or app. This approach is simple but flawed, because it creates a distorted perspective of user engagement. Obviously, not every user who logs into your app ends up engaging with your product in a meaningful way. **A better way to calculate active usage is to look only at users who find value in your product** (daily, weekly, or monthly).

#### Examples of DAU/WAU/MAU

**Facebook**, for example, defines an active user as someone who has interacted with the site by "liking, sharing, commenting, or clicking through another link."<sup>2</sup> At **Mixpanel**, we consider customers to be "active" when they use our product analytics platform to analyze user behavior. The primary way to do that in Mixpanel is through what we call "segmentation" (i.e., our active users are those who "filter by" or "breakdown by" in their queries).

#### Monetizable "active usage"

Even though "active usage" should ideally be tied to "value moments" in your product, they are not the same metrics. As with any metric, the definition of "active users" is ultimately what a company internally decides "active users" should be in their business's specific context. That means sometimes "active usage" is based on "value exchange moments" instead of "value moments."

An example is the **mDAU metric**, which stands for monetizable daily active usage. Twitter defines monetizable active users as "users who logged in or were otherwise authenticated and accessed Twitter on any given day through twitter.com or Twitter applications that are able to show ads."<sup>3</sup> This metric doesn't reflect the product's value moments for Twitter users (which could be when a user learns "what's happening" — through retweets, replies "@", or follows) and shouldn't be top of mind when building a value-first product. However, it's an important KPI for tracking the value of Twitter for advertisers.

> "As a builder turned investor and advisor, I've learned that it's easy to get lost in numbers that can fake you out—things like clicks, downloads, DAU. But at the end of the day, your job is to focus on what these numbers tell you about users who are most likely to stick. The core of any product strategy is the answer to the question:
>
> 'How many times did users perform a core action on the expected cycle?'
>
> It’s nice to be able to say that you once had a 28% conversion rate, and you increased it to 32%. Progress! But really, 72 out of 100 people used to not convert to the desired action, and now, 68 people still don’t. Ask yourself: What’s the most impactful thing you can do to make those people feel compelled to stick around?”
>
> <div>**Josh Elman**</div> *VC & Advisor; Former Product Leader at Robinhood, LinkedIn, Twitter*

## When should I measure DAU/WAU/MAU?

Because active usage is such a popular KPI, it often becomes the default metric for all types of product analyses, including industry benchmarking, product growth, marketing campaign performance, and the like. Let's look at some of the ways DAU/WAU/MAU are used, so you can assess when these metrics serve you well (and when they don't).

### DAU/WAU/MAU as one of the ways to assess overall business health

Alongside other metrics like LTV (lifetime value), churn, and ARR (annual recurring revenue), DAU/WAU/MAU can be useful for reporting. Venture capitalists will often see these metrics in startup pitch decks, and established companies add them to their quarterly investor earnings reports.

However, because DAU/WAU/MAU numbers are volatile and don't paint the full picture, some companies are dropping them in favor of more meaningful metrics. For example, Microsoft made the call to stop sharing monthly active counts for Xbox Live. This year, Electronic Arts followed suit.

> "We're going to stop talking about monthly or weekly or daily active users because I'm not sure what anyone can do with that information."
>
> <div>**Blake Jorgensen**</div> *EA's COO and CFO*

If you clearly define what "active" means for your business, DAU/WAU/MAU can be helpful for assessing overall business health. But without a well-defined "active" part of the picture, it becomes a vanity metric. Our advice: DAU/MAU/WAU might be a great opening statement, but it’s never a full story.

### DAU/WAU/MAU to track seasonal changes for your business

When it comes to internal benchmarking, DAU/WAU/MAU can be useful. Some businesses see spikes in active usage caused by seasonality. Tracking active usage can help forecast such changes and prepare you to optimize online inventory or efficiently distribute incoming network traffic.

### DAU/WAU/MAU to measure marketing funnel effectiveness

Measuring the number of active users coming from different user acquisition campaigns helps optimize your ad spend for deeper-funnel performance.

For example, your TikTok mobile app install campaign might be generating thousands of installs at a low cost that poorly convert into active users. At the same time, your Apple Search Ads bids might yield expensive installs that convert into users who are active. Because of higher intent (or better targeting, or a more effective channel for this campaign type, or other reasons), these users find more value in your product, show higher engagement, and as a result, might become your most valuable users. C **Cheap doesn't necessarily equal effective**, and looking at how active your new users are by each acquisition channel can help you better measure and improve marketing ROI.

## How can I measure my DAU/WAU/MAU count?

To get your daily, weekly or monthly user count in Mixpanel and monitor it over time, follow these three simple steps:

1. In the Insights report, select an event that your active users should be doing (e.g., "watch video")
2. Highlight "Total" to bring up all the different ways you can group your users, including Total per User, Unique, and DAU/WAU/MAU. Select "WAU" for weekly active users
3. Customize the date range. Mixpanel will default your line graph over time to a lookback of the last 30 days (from the active day) and a day-by-day count

### DAU/WAU/MAU for product benchmarking

Some companies use DAU/WAU/MAU to benchmark their performance against other companies. Here's why it seldom works:

"Active" is a loaded term because it has a different meaning for each product. Defining "active users" without tying that definition to value (the ultimate goal), such as through relying on a generic metric like logins or app opens, is meaningless. Because the average product usage interval and the user actions that companies choose to define "active" vary widely, **product benchmarking by DAU/WAU/MAU alone is problematic**.

This is true even for products in similar categories. For example, for a fitness app like Mindbody, the value moment could be when a person books a fitness class through the app, which on average happens, say, twice a week. For another fitness app, such as Sweat with Kayla, the value moment could be workout completed, because it's an online workout app. And for Kayla’s app, the optimal frequency for “active” users might be three, not two times a week. Very simply, active users behave differently depending on the product. Even identical products can have varying active usage definitions depending on their business and monetization strategies.

### DAU/WAU/MAU for building better products

If you see growth or decline in active users, there's not much you can do except wonder: why is that? DAU/WAU/MAU might point you in the right direction to explore what's happening but, by themselves, **they are not actionable**.

## When it comes to measuring active usage, what's the difference between a good PM and a great PM?

**A good PM** knows what constitutes active behavior in their DAU/WAU/MAU definition to ensure they are tracking the right thing.

**A great PM** finds what user actions correlate with the "A" in their DAU, and makes product adjustments to encourage those actions early on and in more users.

<Note>
  2. Tardi, Carla. Monthly active users (MAU) (2015, April 6). Investopedia. [https://www.investopedia.com/terms/m/monthly-active-user-mau.asp](https://www.investopedia.com/terms/m/monthly-active-user-mau.asp)
  3. Twitter Q1 2019 Earnings Report. [https://s22.q4cdn.com/826641620/files/doc\_financials/2019/q1/Q1-2019-Slide-Presentation.pdf](https://s22.q4cdn.com/826641620/files/doc_financials/2019/q1/Q1-2019-Slide-Presentation.pdf)
</Note>

## Next Steps

### Analyze user engagement

Now that you understand user segmentation and active usage metrics, the next chapter dives deeper into analyzing different levels of user engagement.

[Read Chapter 3 →](/guides/strategic-playbooks/guide-to-product-analytics/analyze-user-engagement)


# Grow and Scale
Source: https://docs.mixpanel.com/guides/strategic-playbooks/guide-to-product-analytics/grow-and-scale



## Questions answered

* [How do you measure growth?](#how-do-you-measure-growth)
* [How should your growth strategy change as your company matures?](#how-should-your-growth-strategy-change-as-your-company-matures)
* [How can a product manager drive growth?](#how-can-a-product-manager-drive-growth)
* [Where are my most valuable users coming from?](#where-are-my-most-valuable-users-coming-from)

No analytics guide would be complete without talking about growth. And perhaps you're on the Growth team at your company and skipped ahead to this chapter without reading the part for PMs. You want the details on how to hack growth. **We've got news for you: growth for the sake of growth doesn't work.**

When you talk about Growth, you are obviously referring to the growth of your company. This concept shows you just how easy it is to pull focus from user value toward your own self-interests. **If the Product team is focused on bringing value, then the Growth team should align with that as closely as possible.**

## How do you measure growth?

<div>
  <AndreessenHorowitzLogo />

  <div>
    "More often than not, the right combination of metrics for understanding your business' growth won't be the things that are easiest to measure, or even the most favorable. Take user growth month over month. A company can potentially artificially inflate these numbers by investing heavily in acquisition with things like ad buys, excessive marketing outreach, and other awareness plays that might not be sustainable in the long run, or can oversaturate the market. If these are the only channels for acquisition, growth will eventually stagnate or decline—especially if churn grows.

    **The best metrics for understanding growth will be aligned with your company's north star metric**, and therefore, will vary widely depending on the specific context. In a luxury jewelry company, for example, a key metric might be the number of items sold over \$10k where the buyer is x."<div>**Andrew Chen**</div> *General Partner, Andreessen Horowitz; Board Member, Reforge*
  </div>
</div>

<div>
  <ProductSchoolLogo />

  <div>
    "User acquisition matters as a growth metric but you also need to focus on retention. **If you're churning users, you're not really growing.** And while companies like Amazon can afford to stay unprofitable for years, your company probably can't. Outrageous success stories are outliers. Don't get dazzled by what works for them. Focus on what works for you. What's 'table stakes' will vary by industry and market, but these days, it's all about UX—especially at the onboarding stage. Make the user jump through hoops to use your app/software, and they will simply hop away."<div>**Carlos González de Villaumbrosia**</div> *CEO, Product School*
  </div>
</div>

## How should your growth strategy change as your company matures?

**If the goal of Product is to create value, the goal of Growth is to identify all the people out there who can benefit from the value that your product brings.** At an early startup stage, it will likely be a very small, niche audience. When you reframe growth in this way, demand generation becomes less about convincing an unwilling crowd to buy your product and more about showing people that your product can bring value to them or alleviate some friction in their lives.

When you find your product-market fit, measuring growth and value becomes even more important. Given the costs of ads and the fracture of channels and media, a core challenge will be to scale your reach beyond the niche market you've already captured. At this point, you've hopefully collected enough data that will guide your acquisition in terms of who those users are, where to find them, and how to educate them about your product's value. **Product analytics will help you stay the course and spend your budget efficiently.**

### Growth Strategy Evolution

<div>
  <ProductSchoolLogo />

  <div>
    "When you're a startup, you need to throw a lot of things against the wall and see what sticks. Your approach is often broad—like a shotgun. And then when you start noticing what works, you can become more focused—like a sniper rifle. This is product-market fit. Through trial, error, and experimentation you've found what works and now you can focus on this almost exclusively. When you reach maturity, you can consider expanding again, using your established clout, resources, and expertise to open new avenues and opportunities for growth."<div>**Carlos González de Villaumbrosia**</div> *CEO, Product School*
  </div>
</div>

## How can a product manager drive growth?

Beyond acquiring users, **the key to growth is retention**. Similarly to how in its early days Facebook found that adding 7 friends in 10 days was their shortcut to value, you can use product data to identify your product's unique ancillary action that increases the likelihood of retention.

This only comes with having a clear idea of the foundations laid out in this Guide (e.g., value moment, user journey, product usage interval) and then regularly asking questions in terms of what else users are doing (frequency, depth, breadth) that are the behavioral markers for long-term loyalty. **If you do find that shortcut, you can nurture new users in their critical early stages to reach value quickly and maybe even spread word of your product's value organically, thus creating a self-feeding loop.**

### Industry Examples

<div>
  <RakutenViberLogo />

  <div>
    "The strategy is to try and understand, as soon as possible, what a retained user regularly does and then try to get users who are not retained to form the same habits. Eventually, we want to provide users with the content that will increase retention and encourage them to stay in for a long enough time for others to join. **This is really the network effect.** Because as more people join, eventually the more active or more retained they'll be."<div>**Idan Dadon**</div> *Product Manager, Viber*
  </div>
</div>

<div>
  <VrboLogo />

  <div>
    "Let's say five people take a trip but only one goes through the whole planning and booking process. There are four other adults attached to the trip that we (Vrbo) never communicated with. We don't yet have their information. **We aim for organic growth**, by trying to get the other people on the trip—the guests of guests—involved. It's a free/inexpensive acquisition channel instead of having to reach out to a completely unknown person."<div>**Jamie Kapilivsky**</div> *Data Insights, Vrbo, part of Expedia Group*
  </div>
</div>

<div>
  <DocusignLogo />

  <div>
    "We have more than 661,000 customers and hundreds of millions of users around the world—we want them all to love the DocuSign experience. **The 'wow…that was easy' reaction cements the positive impression and helps to drive viral growth.** After all, once they see the value of going digital, they rarely go back to paper."<div>**Drew Ashlock**</div> *Lead Product Manager, DocuSign*
  </div>
</div>

In this section on growth, we've repeated the importance of educating potential users about the value that your product can bring. The tricky part is that, out in the wild, it is hard to distinguish a potential user from a person who has no use for your product. The previous chapters focused on how to break down users based on behavior since, as a PM, you have the ability to influence user actions (and ultimately find that magic shortcut to value).

## Where are my most valuable users coming from?

With Mixpanel, you can segment users based on their source and find or confirm whether you are targeting the right group. In the Funnels report, you can compare conversion rates and see where your engaged users are coming from. Organic traffic? Google Ads? LinkedIn?

**Best case**: you find that your targeting criteria on Twitter ads are spot on and you double down.

**Worst case**: you find that the bought users find less value (because they don't retain) than the organic users or users from other sources, so you modify the targeting criteria for your ad audience.

**Growth is about finding people who need your product and showing them that your product can bring value to them.** Product analytics can help you see the impact beyond vanity metrics (like email open rates or pipeline) so you can focus on what really matters: serving the user.

## Next Steps

### Conclusion

You've now learned the foundations of product analytics from measuring value to understanding users, analyzing engagement, improving retention, and driving growth. The final chapter brings it all together.

[Read Conclusion →](/guides/strategic-playbooks/guide-to-product-analytics/conclusion)


# The Guide to Product Analytics
Source: https://docs.mixpanel.com/guides/strategic-playbooks/guide-to-product-analytics/intro



## Introduction

Product management is riddled with buzzwords—growth loops, power user curves, big data, AI—and the sheer number of metrics, retention types, charts, and frameworks can overwhelm attempts to understand users and make better products for them.

But strip away the jargon, and the problem that product managers are solving today suddenly becomes very clear. The specifics will vary by product and market context, but essentially, every product manager wants the same thing: **to build products that customers find valuable**.

Makes sense. If COVID-19 can teach us anything about product management, it's this: there's no room for products that don't bring value to the customer. The pandemic has put every single product and service to a value test. It has also put every single business to an agility test: How quickly can you adapt and pivot when the lives of your users change dramatically?

That, of course, depends on how well you understand your users—which depends, in turn, on your ability to ask the right questions and use data to get the answers you need. From defining product value, to measuring it and prioritizing what's next, this book is about using product analytics to build a sustainable path for growth.

## About This Guide

We wrote this book in collaboration with dozens of product leaders, people who earned their stripes at companies like Google, Twitter, LinkedIn, and ZipRecruiter. We wrote it for product managers, but it's really for anyone who wants to deeply understand how people use products—without coding or asking a data analytics team. Because when more people can ask product questions and get answers quickly, companies move faster, build better products, and create more value for everyone.

## What You'll Learn

The questions in this book are grouped into broad but practical categories that will help you learn such important things as:

* **What exactly do I need to measure in my product?**
* **How do I account for different types of users in my analysis?**
* **How do I narrow my focus around a single conversion flow to iterate faster?**
* **Where are my best users coming from?**

Lastly, we are a product analytics company, so throughout the book, we'll show you some hands-on examples of how you can answer these questions with Mixpanel. And just like with any digital product today, this book will be continuously updated.

## Next Steps

### Measure value: The foundation of product analytics

Ready to dive deeper into product analytics? The next chapter focuses on the fundamental concept of measuring value in your product.

[Read Chapter 1 →](/guides/strategic-playbooks/guide-to-product-analytics/measure-value)


# Measure Value
Source: https://docs.mixpanel.com/guides/strategic-playbooks/guide-to-product-analytics/measure-value

The Foundation of Product Analytics

## Questions answered

* [How does my product bring value?](#how-does-my-product-bring-value)
* [How can I monetize my product?](#how-can-i-monetize-my-product)
* [Can product value always be measured and analyzed?](#can-product-value-always-be-measured-and-analyzed)
* [What is a value moment?](#what-is-a-value-moment)
* [Which metrics should I pick to measure product success?](#which-metrics-should-i-pick-to-measure-product-success)
* [Where do product leaders typically go wrong when defining their value metric?](#where-do-product-leaders-typically-go-wrong-when-defining-their-value-metric)
* [When it comes to choosing product metrics, what's the difference between a good PM and a great PM?](#when-it-comes-to-choosing-product-metrics-whats-the-difference-between-a-good-pm-and-a-great-pm)

## How does my product bring value?

The idea of value (as opposed to physical or digital features) is at the core of every product. If customers find value in your product, they use it. If they don't, they stop using it. This simple truth explains why defining your product's value comes first.

Later in this guide, we'll cover many questions that you can answer with product analytics. But this question—"Why are people using my product?"—is not one of them, because no product analytics tools can define that for you.

But you probably already know why. Depending on your product, your customers usually have very clear and obvious reasons for using it. Fitbit users, for example, buy the watch and download the Fitbit app because they are looking for motivation. Netflix users keep coming back for entertainment. For over four and a half million Weight Watchers users, the app fills the need for community and support.

To understand your product's value, you need to step back and ask: *"What are my users hoping to do with my product? And what is my product really about?"*

<Frame>
  <img alt="" />
</Frame>

If you look at the most successful digital products today, they have one thing in common: **they make it easier, cheaper, or more convenient for people to live their lives and get what they want**.

Identifying the specific behaviors that indicate that people are getting value is key to building a lasting product. Further, knowing when your users get value from your product can help you clear the path to that critical value moment for more users, which means more people get value and are willing to keep coming back, and perhaps even pay.

## How can I monetize my product?

A classic value exchange is money in return for a product or service. Depending on your profit model, the most common types of value exchange are:

### Transactional

Users pay a fixed price per unit of the product, such as \$3.99 for a mobile app.

### Subscription

Users pay a fixed price per unit of time, and then receive a fixed number of units (such as 3 audio books monthly) or unlimited use over the subscription period (such as unlimited number of movies and shows monthly on a video streaming app).

### Licensing

Users pay a license fee to use, sell, or copy a product. For example, a ride sharing app pays a fixed fee to the provider of mapping software.

### Freemium

Some users get a version of the product for free, while others pay for a premium version (with more/better features). For example, an audio streaming service sells a subscription that allows uninterrupted listening.

The moment of value exchange between a user and a business isn't always tied (directly) to money. User attention (monetized, for example, through advertising) and data (used for training machine learning models) can be just as valuable. For product managers, these new types of value exchange require new ways of thinking about user experience and clear communication around data-sharing practices to earn people's trust.

These profit models, or different ways of getting money in exchange for value in the digital world, are now so sophisticated and complex that understanding how your users derive value from your product becomes even more important. If you’re not using product analytics, you’re going to have a hard time grappling with this complexity. Without easy access to the data you need to make decisions quickly, it’s challenging to grow and successfully monetize your business.

### On monetization post-COVID-19

<div>
  <B1Logo />

  <div>
    "While the fundamentals of monetization are unlikely to change, Covid-19 has two significant implications for how companies think about pricing and monetization in the near and medium term:<br /><br />At the heart of monetization strategy is always a deep understanding of customer willingness to pay, and how it differs for different customer segments and use cases. Covid-19 changed customer behavior and their option set so dramatically that, in many cases, willingness to pay is fundamentally different. It is worth assessing whether this is the case and whether monetization strategy needs to change as a result.<br /><br />A surprisingly high percentage of companies designed their monetization early in the company lifecycle with limited rationale. However, they are often reluctant to enact change, because big changes to monetization take a lot of work, and the risk of getting it wrong or suffering customer backlash is scary. A major event like Covid-19 brings so much change that it can give companies air cover to make the big changes they've been considering, and we're seeing many companies take advantage of this."<div>**Dan Hockenmaier**</div> *Founder, Basis One; Growth Mentor and Contributor at Reforge*
  </div>
</div>

## Can product value always be measured and analyzed?

**Yes.** No matter how "fuzzy" or intangible the value may appear, you can apply quantitative measurements to any product. For example, While it's tough to gauge precisely how much **fun and entertainment** users are getting from a video streaming service, you can measure how many videos they watch weekly, or how much time is spent on each.

Similarly, While finding a 100% precise way of measuring **anxiety reduction** in users of a meditation app might seem difficult without a qualitative study, you can measure completion rates for meditation sessions, and the percentage of people coming back each week to use the app again and again. In addition, you can observe in what ways people who do come back behave differently from those who don’t.

In short, **fuzzy measurement is still a useful measurement if it tells you more than you knew before**<sup>1</sup>.

A helpful tool in measuring value for your product is defining the so-called **"value moments"**—user events or actions that indicate that a person is getting value out of your product.

## What is a value moment?

Your product's **value moment** is an event, an action, or a series of events and actions that represent the moment that a user found value in your product. Here are a few examples of value moments:

<Frame>
  <img alt="image" />
</Frame>

Depending on your product, a user journey might look very different. To get to the value moment for the first time, some user flows require registration, verification, adding friends, or entering credit card information before a user can "activate" and experience the product's value for the first time. This initial journey to value is critical: **the more quickly you can get your users to value, and the more you can signal during that journey what value is to come, the better the chances they'll stick around for more value moments**.

### Industry Examples

<div>
  <VrboLogo />

  <div>
    "From the traveler side, **booking** is our number one objective—any test we run from the homepage all the way to the end of checkouts is going to have that as a primary goal. That said, we're a two-sided marketplace—we also want partners to accept those booking requests."<div>**Jamie Kapilivsky**</div> *Data Insights, Vrbo, part of Expedia Group*
  </div>
</div>

<div>
  <AviraLogo />

  <div>
    "We want users to **complete a Smart Scan flow** because it's important in activating them, and then getting them engaged. Smart Scan checks your system for all kinds of problems: privacy issues, performance issues, network and wifi security, out-of-date software. In this flow, we show what we have to offer. For the new users, this is the moment where they get impressed."<div>**Stephan Brenner**</div> *Vice President - Product, Avira*
  </div>
</div>

<div>
  <RakutenViberLogo />

  <div>
    "To grow in new markets, or maintain our current market presence in countries where we have strong presence, it's super critical for new users to start a conversation. But if they don't have anyone to communicate with, then eventually they'll probably just drop. For existing users, a referral is what we're hoping for."<div>**Idan Dadon**</div> *Product Manager, Viber*
  </div>
</div>

## Which metrics should I pick to measure product success?

Think of your value moment as a building block for successful product adoption. More value moments means a user has more opportunities to build a habit around your product and remain a customer in the long term. Turning value into a single key metric (known as the **"north star metric"** or **"focus metric"**) can help your teams set tangible goals and measure what really matters.

To learn more about defining your focus metric, check out [Mixpanel’s Guide to Product Metrics](https://mixpanel.com/wp-content/uploads/2023/11/eBook_Guide-to-Product-Metrics.pdf).

<Frame>
  <img alt="image" />
</Frame>

<div>
  <MadpawsLogo />

  <div>
    "Our key focus metric is the number of bookings per customer. This is how we track how well we're doing, as well as our year-on-year growth rate."<div>**Karim Mouahbi**</div> *Head of Marketing, Mad Paws*
  </div>
</div>

<div>
  <ZipRecruiterLogo />

  <div>
    "One of our most important metrics is the conversion rate, which helps us determine what percentage of job seekers come into our platform, find a job that's relevant to them, and then complete the Apply flow."<div>**Akio Bandle**</div> *Senior Product Manager, ZipRecruiter*
  </div>
</div>

<div>
  <TheWeatherCompanyLogo />

  <div>
    "My team uses AI technology and conversational units to create engaging and effective ads. We track active user sessions (when a user clicks on the front screen and activates the ad) as well as conversation rate (when users click a button and/or type something in). The final metric we look at is engagement: if a user performs any action at all. We watch how users engage with our various ad units according to those three metrics, and optimize toward the better performing ad units, whether they be for desktop or mobile."<div>**Shannon Ferguson**</div> *Director of Measurement, The Weather Company*
  </div>
</div>

<div>
  <DocusignLogo />

  <div>
    "Given that the DocuSign Agreement Cloud simplifies and accelerates the way people prepare, sign, act on and manage agreements, one of our key metrics relates to speed. We've seen that 82% of DocuSign agreements are completed in less than 24 hours, and 50% in less than 15 minutes—that means the average turnaround time for a signature is reduced by >80% compared to paper . . . and that in turn means significant ROI!"<div>**Drew Ashlock**</div> *Lead Product Manager, DocuSign*
  </div>
</div>

Often, a rookie PM will attempt to track every single user event, come up with an array of metrics, and consider them all equally. This is risky because it can give you a false sense of how many active users you have and how often they get value from your product. Is everyone who logs into a messaging app, clicks into a profile, changes status, and goes to settings truly active and getting value? Maybe it’s only those who send messages? **Prioritizing a single value moment is hard, but it's a more straightforward way of gauging the value that your product brings to market**.

Though initially your retention numbers might dribble down if you are no longer considering every single user action as a valuable moment, in the long term, retention and value are intrinsically the same. So, for a PM, focusing on value at all times is a surefire way to set up for long-term retention.

## Where do product leaders typically go wrong when defining their value metric?

> "Great PMs understand that their specific product's context is a more important factor for defining metrics than any industry best practices. Creating a north star metric has its benefits–chiefly, simplicity in measuring progress and communicating it within and outside the team responsible for the product.<br /><br />When picking a north star metric, Great PMs look for a metric that: (a) is responsive to product changes (b) is an aggregate measure of the product's value for its users (c) can be readily tied to value for the business or to broader company goals (d) is expected to remain relevant for a reasonable duration of time (e.g., at least 2-3 years)<br /><br />Great PMs typically also complement a north star metric with balancing metrics that can help measure any major negative user impact or business impact from moving that north star metric in the desired direction."<div>**Shreyas Doshi**</div> *Lead PM at Stripe; Former Lead PM at Twitter, Google, Yahoo*

<div>
  <ReforgeLogo />

  <div>
    "The most common pitfall is relying either too much on intuition or too much on data. You have to start with a qualitative hypothesis of what the value moment is, based on first principles of your product's problem, target audience, differentiation, and other elements. You then need to validate that hypothesis with certain analyses. Teams that let the data drive the definition are letting the data dictate the strategy, when the data should be used to measure whether or not you are achieving the strategy. Those two things are fundamentally different.<br /><br />The best leaders understand that a [single metric](https://www.reforge.com/blog/north-star-metric-growth) can't capture the entire picture of their business, but that one metric at any given time can be the most important. It is a balance.<br /><br />
    Most products should have four high-level metrics: an acquisition metric, retention metric, engagement metric, and monetization metric. The four of these act as a system where one can influence the other. They each capture a different dimension of what is happening with a product. But trying to improve all metrics at once typically isn't possible until you get to a much later stage and are able to dedicate teams to each area. Instead, leaders need to understand which one is most important at any given moment and make sure the teams understand that and are properly resourced to make meaningful progress."<div>**Brian Balfour**</div> *CEO, Reforge*
  </div>
</div>

<div>
  <ZipRecruiterLogo />

  <div>
    "An effective north star metric is a product manager's best friend. It provides cross-functional alignment on goals and tasks, and an objective barometer for success when a product ships. Even products that generate direct revenue require an alternative product metric that tells a more holistic story of what's going on. When your north star metric is clear, product ideation becomes a lot easier. Instead of asking yourself, 'what should I build next?', you should be asking, 'what feature or product is most likely to move this metric the most?'"<div>**Akio Bandle**</div> *Senior Product Manager, ZipRecruiter*
  </div>
</div>

## When it comes to choosing product metrics, what's the difference between a good PM and a great PM?

> "Great PMs understand that metrics are not the mission. At the macro-level, metrics are useful markers for whether the product is achieving its mission and is doing so in a way that creates value for the company (i.e., that the execution is in alignment with the product strategy). At the micro-level, it's important to recognize that certain products lend themselves well to metrics-based product decisions whereas others don't.
>
> For example: there is little to gain (and a lot to lose) from largely metrics-based product decisions for an early-stage product whose current usage is infinitesimal compared to its potential usage. In these situations, exercising product judgment by using inputs such as qualitative user feedback and competitive analysis will lead to better product decisions than “reading too much” into the current usage metrics. Great PMs will still diligently define and track metrics for such a product, but they will use metrics as one of many inputs for their product decisions.”
>
> <div>**Shreyas Doshi**</div> *PM Lead at Stripe, Former PM Lead at Twitter, Google and Yahoo*

<br />

<br />

<br />

<TataPlayLogo />

> "A good PM understands and tracks user behavior in the product that correlates with users getting value. A great PM prioritizes each new product feature based on how it can move the key value metric.
>
> A great PM is one who can think about innovation and incredibly technologically forward features... but never loses sight of their customer. She continually puts herself in the place of her customer, evaluating themselves at every step, behaving and thinking like the average user."
>
> <div>**Vinati Malik**</div> *Senior Vice President of New Product Development, Tata Play*

<Note>
  1. Hubbard, Douglas W. How to Measure Anything: Finding the Value of ‘Intangibles’ in Business, 3rd ed. Wiley: 2014.
</Note>

## Next Steps

### Get to know your users

Now that you understand how to measure value, the next chapter focuses on understanding your users and their behavior patterns.

[Read Chapter 2 →](/guides/strategic-playbooks/guide-to-product-analytics/get-to-know-your-users)


# Retain Your Users
Source: https://docs.mixpanel.com/guides/strategic-playbooks/guide-to-product-analytics/retain-your-users



## Questions answered

* [Where are my users dropping off?](#where-are-my-users-dropping-off)
* [Should B2B and B2C companies measure drop off on their user's path to value differently?](#should-b2b-and-b2c-companies-measure-drop-off-on-their-users-path-to-value-differently)
* [How can I measure user drop off?](#how-can-i-measure-user-drop-off)
* [Why should I measure retention?](#why-should-i-measure-retention)
* [How do I measure retention?](#how-do-i-measure-retention)
* [When it comes to retention, what's the difference between a good PM and a great PM?](#when-it-comes-to-retention-whats-the-difference-between-a-good-pm-and-a-great-pm)
* [Who are my most retained users?](#who-are-my-most-retained-users)

In previous chapters, we've established that the most successful products are those that bring the most value to users. That's why measuring value is key to product analytics, whether it's defining activation, tracking the growth of DAU/WAU/MAU, or grouping users by their level of engagement.

Some products can deliver an incredible amount of value in a single value moment. For example, you download an AR measuring app, use it once when you buy a couch, and delete it for good. You open a dating app, swipe on the first person you see, fall in love at first sight, and never use the app again. **But for most digital products, the only way to bring a lot of value to users is to keep them coming back regularly and engaging with your product.**

## Where are my users dropping off?

Users are more likely to retain when they successfully experience value in your product early and often. But somewhere on their path to value, at least some users are going to drop off. So it's not surprising that one of the most popular questions in product analytics is (and something our support team at Mixpanel gets asked frequently) **"Where are my users dropping off?"**

To realize the value of your business, a user needs to survive two key drop offs in their product journey:

1. **The value moment**, which is key to activation, engagement, and retention (the moment when they get value)
2. **The value exchange** (or payment), which is essential to monetization and business health (the moment when you get value)

<Frame>
  <img alt="image" />
</Frame>

The value moments for the user and the business are sometimes the same. For example, the value moment in shopping apps (e.g., "complete checkout") is naturally tied to revenue. People get value when they buy an item they like; shops get value when people buy that item.

More often, however, the journey to value and the journey to value exchange in digital products are two different journeys. For a fitness app like ClassPass, for example, people get the value when they complete workouts, while ClassPass gets value when people buy workout credits.

Which one of the two drop offs should you focus on? Focusing on value is more helpful for building better products than focusing on revenue. If you optimize your product to get users to pay you but don’t optimize for the value they get, soon you will have a churn problem. In fact, it’s the perfect way to end up with a leaky bucket—many customers who pay once and never come back. This goes back to the point made earlier in the book: if people don’t get value from your product, they won’t use it, and of course they won’t pay for it.

**Key insights:**

* Drop-offs most often occur before the value exchange moment (e.g., before a person submits their credit card information, makes a purchase, etc.).
* The more important drop-off point to track, however, is the drop-off before the value moment. The more people reach value in your product, the more people will reach value exchange.
* The fewer steps to get to the value moment, the fewer points of drop-off you'll encounter.

## Should B2B and B2C companies measure drop off on their user's path to value differently?

**No.** B2B enterprise products are also no longer immune to this type of churn. For a while, CTOs, CIOs, and CEOs of Fortune 2000 companies were purchasing software based on what the analyst firms told them (regardless of whether end users liked or hated the software). But now, especially with freemium products, employees often trial different tools, or purchase paid plans with their credit card, and then expense it (until their IT department figures out that it makes more sense to get a company license). And in many cases, SaaS contracts don’t get renewed shortly after an email goes out to the team with the subject line: “Does anyone use this?”

**Enterprise buyers are not that different from consumers now.** So for any product, B2C or B2B, understanding and measuring value comes first.

## How can I measure user drop off?

We've established that the end goal—the moment where value is realized—should be crystal clear, as should the points leading up to that moment. **If users open your app or product for the first time, what is the shortest and most ideal path to the value moment?** That is the funnel to work with.

Each step, screen, page, or button in that journey is critical and the conversion from one to the next will point you to the areas you need to optimize.

The Mixpanel Funnels report helps you understand and measure drop off within a product.

To build a funnel, head over to the Funnels report in Mixpanel and add steps by selecting events from the drop-down list.

For example, when you select "sign up" and "watch video," you'll see how many people out of those who sign up go on to watch a video. Use filters and exclusion steps (e.g., "exclude users who did not do X") and modify conversion criteria (e.g., rearrange the order or select "any order funnels") to customize your question for Mixpanel.

If you’re thinking, “My product is too complex and unique to have a single path to value,” this is a sign of an insufficiently thought-out product. If you can’t express the path to value and build a funnel, go back to the “sign up” page of your product. As a user, go through all the steps to define the dominant canonical journey in your product.

### Key Questions to Ask

With this funnel in mind, as a PM you can expand the range of questions and ways to focus:

* **Where is the lowest conversion rate?**
* **Do converted users share certain characteristics of behavior?**
* **Are users performing certain steps more than once?**
* **Do users get hung up on certain steps longer than on others?**

And finally, "Where are my users dropping off?" is a good question to ask, but only if you get to the question behind it: **"Where should I direct my resources and creativity to increase the number of users that reach the value moment?"**

### Industry Example

<div>
  <DeliverooLogo />

  <div>
    "Deliveroo wants to ensure its restaurant partners are successful, that they get orders and high ROI from using the company's services. We look closely at the conversion funnel from sign up to the first order. For each market, we have targets we want partners to hit, so we know they are reducing churn and increasing conversion. We track how well our restaurant partners are doing on the platform. Are they engaged? Are they taking actions that are good indicators of whether they're going to be successful? How long has it taken them to onboard? We want our partners to be able to go from making the decision to be on Deliveroo to actually taking their first order in a matter of hours, and being able to look at these metrics is what's going to enable us to do that."<div>**Jordan Ng**</div> *Senior Product Manager, Deliveroo*
  </div>
</div>

## Why should I measure retention?

So: you've mastered conversion analysis, tracked your users' journey to their first value moment, and then streamlined your UX so as many users as possible reach the value exchange moment where you actually make some revenue. Congratulations!

However: **in a world where every user knows what is best for themselves and can delete your app or unsubscribe from your product at the click of a link, your product can survive only if it repeatedly brings value to users.** As with a reality show, you might win the challenge one week, but everything resets for next week’s challenge, and if you don’t show up and bring value, you might just get cut.

It's not enough to ask: "Does my product bring value to users?" Instead, you have to ask **"Does my product bring value to users—over and over and over again?"**

To put it another way: "Grey's Anatomy" remains on air after 16 years because, after all this time, it still brings an addictive emotional release. **Is your product the "Grey's Anatomy" of your industry? Or will it be cancelled after one season?**

### Common Retention Mistakes

With this in mind, as a PM, you don’t need convincing that measuring retention or churn is valuable. You’re probably already tracking it, with product analytics or in some other way. But the key is not to set out to “fix churn” through interdepartmental task forces and changes to your pricing model. You’ll need to fix your product itself. Low churn and high retention rate are two sides of the same coin—and reliable signals of lasting product success.

Retention data can show you which customers are more likely to stay, and how they compare to those who churn. Such insights are helpful by themselves, but even more so as a starting point for more qualitative digging. The paths and actions that retained users take in your product can inspire product optimizations that help more new users find value faster and stick around for longer.

Since retention is simply the percent of users who stay with your product and continue using it in a given period, calculating it is pretty straightforward. You just take the number of your active users during that period divided by the number of active users at the beginning of the period. And yet PMs often get this metric wrong.<sup>4</sup> Brian Balfour from Reforge says that there are three mistakes companies make when defining their retention metric:

#### Focus on revenue

SaaS companies often focus on monthly or annual revenue retention instead of measuring the frequency and depth of product usage.

#### Choosing the wrong frequency

Some products should focus on daily retention vs. weekly or monthly. This depends on your product's natural usage interval.

#### Failure to tie retention back to value

Your retention metric should reflect the number of retained users who experience value. Defining what "active" means for your product is a great place to start.

### Industry Example

<div>
  <DeliverooLogo />

  <div>
    "Deliveroo looks at one-week and three-week retention to see if restaurants are engaging with the platform. Are they finding value in using Hub? You don't necessarily need to use Hub to get orders. You could get set up and then completely go on autopilot and your orders can come in. You may not necessarily need to come back to that portal, but we want to help you grow and manage your business. It's an opportunity for us to educate you, give direction, and help you improve your business so we want to measure that engagement and retention."<div>**Jordan Ng**</div> *Senior Product Manager, Deliveroo*
  </div>
</div>

## How do I measure retention?

**N Day retention** calculates the percentage of users who come back on a specific day.

**Unbounded retention** calculates the percentage of users who come back on a specific day (or week, month, etc.) or any time unit afterwards.

To analyze retention in Mixpanel, select up to two events to see how many people come back to perform the same event.

## When it comes to retention, what's the difference between a good PM and a great PM?

Remember how you identified the user interaction that symbolizes the moment when your users get value back? That should be the metric that you build your retention reports around. **A good PM gets this far and, once a month, they look at the report to see if things went up or down, they nod, and then go back to not looking at it.**

**A great PM focuses on the users that are getting the most value**—they are likely the best fit for your product. A common misstep for new PMs is to focus on the users that churned and obsess about how to get them back. Instead, **obsess over the users that are getting value**. Look at the full breadth of behavior for those users; interview them; send them an email; offer them a gift card in exchange for 15 minutes of their time. Build the best, most valuable product for these users and you won't have a churn problem in the first place.

### Expert Perspectives

<div>
  <ZipRecruiterLogo />

  <div>
    "A good PM builds a value-moment retention report and analyses on a regular cadence. They can make conjectures about how feature releases or product updates impacted retention rate. A great PM breaks down retention data by cohorts to understand what causes churn. They obsess over the users that get the most value, connect with their use cases, and build features specifically for them.

    A great PM works with their data science team on a definition that makes sense for the business. They also account for 'happy churn.' Especially with transactional services, some users churn because your service works as intended, which is a good thing."<div>**Akio Bandle**</div> *Senior Product Manager, ZipRecruiter*
  </div>
</div>

<div>
  <VrboLogo />

  <div>
    "A great PM understands the difference between correlation and causation; they can figure out that a higher conversion rate among more intentful visitors is not a signal that they need to drive that particular user behavior, but that it's a function of the way they've built their analysis. They don't go after opportunities based on that information and then find themselves in a position where they have to defend their sizing of that opportunity and why they prioritized that work.

    A great product manager needs to see the difference between an actual trend that can be corrected or adjusted... and a data point."<div>**John Meakin**</div> *Lead Statistician, Vrbo, part of Expedia Group*
  </div>
</div>

## Who are my most retained users?

Mixpanel can help you understand which users are sticking around longer and continue to get value.

You can create cohorts for retained users directly from the Retention report. Simply click a segment of the Retention report, and click the "create cohort" button.

You can then investigate what causes your users to be retained by exploring the different properties of your "retained users" cohort in the Insights report.

<Frame>
  <img alt="image" />
</Frame>

<Note>
  4. Why Retention is the Silent Killer (2017). Reforge. [https://www.reforge.com/blog/retention-engagement-growth-silent-killer](https://www.reforge.com/blog/retention-engagement-growth-silent-killer)
</Note>

## Next Steps

### Grow and scale

Now that you understand retention and how to identify your most valuable users, the next chapter focuses on growth strategies and scaling your product.

[Read Chapter 5 →](/guides/strategic-playbooks/guide-to-product-analytics/grow-and-scale)


# Onboarding Playbook
Source: https://docs.mixpanel.com/guides/strategic-playbooks/onboarding-playbook



The Onboarding learning path walks you through implementing Mixpanel and getting the most from it. Whether you're new to digital analytics or switching from another platform, you'll learn to track user behavior, measure key metrics, and answer the questions behind your product decisions. The full [learning path](https://university.mixpanel.com/student/path/3411734-mixpanel-onboarding) is hosted on Mixpanel University. By the end, you'll be able to:

* Plan, implement, and launch a Mixpanel deployment
* Configure your organization, projects, and tracking
* Drive a production rollout your team adopts

The rest of this page outlines that process at a high level, and the full learning path covers each step in more depth.

## Methodology

We recommend an iterative 3-step sprint approach to implementing Mixpanel, with each sprint ranging between 1 to 3 weeks. Once you've completed the onboarding, this same process should be repeated in subsequent sprints where you refine and expand your Mixpanel tracking.

<Frame>
  <img alt="image" />
</Frame>

### Step 1: Plan

**Plan**: If you have not defined your metrics and KPIs (*what you should measure*) that align to your company or product objectives, and need guidance, this section of the tutorials should help you. We will go through how to map these metrics and what the best practices are for defining your events and properties in a [Tracking Plan](/guides/guides-by-workflow/build-tracking-strategy). We’ll also cover setting up your Mixpanel [Organization](/docs/orgs-and-projects/organizations) and [Projects](/docs/orgs-and-projects/managing-projects), especially if this is your first time [signing up](https://mixpanel.com/register).

### Step 2: Implement

**Implement**: We will guide you through [sending your first data](/docs/tracking-methods) into Mixpanel, and the best practices around [Quality Assurance Testing](/guides/guides-by-workflow/ensure-data-quality) and how to audit your data. We will also show you how to establish a [data governance](/guides/guides-by-topic/govern-data) framework to keep your Mixpanel implementation clean, concise, and consistent.

### Step 3: Launch

**Launch**: Once your data is in Mixpanel, we will guide you through rolling out Mixpanel to your wider team and training users on [Mixpanel Fundamentals](https://university.mixpanel.com/student/path/3411736-mixpanel-fundamentals) so they can leverage core reports ([Insights](/docs/reports/insights), [Funnels](/docs/reports/funnels/funnels-overview), [Flows](/docs/reports/flows), and [Retention](/docs/reports/retention)) to analyze user behavior and measure what matters for your product. Finally, we'll help you execute your adoption plan to set your organization up for long-term success after go-live.


# Advanced
Source: https://docs.mixpanel.com/guides/strategic-playbooks/product-analytics-strategy/advanced



## Stage 03

In this section:

* [Introduction to Advanced product analytics maturity](#introduction)
* [Common markers of Advanced stage](#common-markers-of-advanced-stage)
* [Example of Advanced product analytics maturity](#example-of-advanced-product-analytics-maturity)
* [How to move on from Advanced](#how-to-move-on-from-advanced)

## Introduction

In the Advanced stage of product analytics maturity, data is your compass for most decisions. This analysis is driving your product development because you're constantly considering what works, for who, and why.

You've gotten in shape with your dumbbells and bench press and mile-long runs. Now it's time to join a gym. Something that allows you to choose the equipment or exercise that will strengthen the muscle group of your choice and/or lead to greater endurance.

<Note>
  Most (or all) decisions are made with product analytics in mind, and are supported by real-time data. All teams have access to product data, and your Product, Engineering, and Design teams will rely on it heavily.
</Note>

<br />

<Frame>
  <img alt="" />
</Frame>

## Common markers of Advanced stage

In this stage, businesses use multiple user journey solutions. These include attribution, engagement, and experimentation tools that are mostly integrated, requiring very few manual workflows.

The automation means you can more easily pull product analytics into your decision workflow. At the same time, because most user experiences are tracked, you have access to a much deeper dataset. Careful planning is critical at this stage in order to leverage the data instead of getting overwhelmed by it.

<Note>
  **Explore Mixpanel**

  See how product and growth teams use Mixpanel's powerful reports to answer any question.

  [Try It With Sample Data](https://mixpanel.com/register/?next=%2Fget-started%2F%3Fexplore%3Dtrue\&link=aypas)
</Note>

## Example of Advanced product analytics maturity

### Questions you can answer

In the Advanced stage, you can assess what's happening to your product and identify factors contributing to these patterns:

* What combination of user attributes (like device or region) lead to the highest product retention rates?
* Who are my power users and how does their usage differ from that of casual users?
* What sequences of actions lead my users to upgrade their membership?
* Which in-product actions correlate most strongly with high retention, a plan upgrade, or any other goal?
* How do engagement and retention vary by company or account?

In this stage, businesses not only have a solid grasp on how to collect and utilize data, but analytics is woven into the fabric of their culture. Employees are curious, ask questions, and are encouraged to use tools to make iterative improvements.

### For Example

Eventually, the ridesharing app collects sophisticated data: type of ride requested (e.g., SUV vs. shared, length of ride, rider interactions vs. driver interactions) and finds a tool that supports advanced metrics and analysis.

This product analysis informs and guides future changes to the app. They regularly consult what data they have to make sure that what they're doing lines up with what they should be doing.

They implement the right tech stack for improving their user experience and for making decisions based on product analytics.

Because they're using data well, their development is more effective and they waste less time and money on features that might not be well received. There is still some manual upkeep (e.g., tracking new events as new features and functions are released) necessary to maintain their product analytics implementation, but it's kept to a minimum and well worth the effort.

## How to move on from Advanced

Advanced product analytics maturity means that your company knows the value of data and uses it to guide product decisions. However, there's still a good chance that your analytics process has a few gaps that require a manual workflow.

This may seem like a good place for many companies to stop with their adoption of product analytics. But moving to Expert product analytics capabilities means that you can dig deep into the impact of individual marketing campaigns and feature updates on product and company KPIs.

To achieve the Expert stage, all parts of the process need to be automated by a quality tool. More importantly, the product analytics and metrics should be guiding all, not just most, product decisions. At the Expert level, companies begin to implement machine learning and data science.

## Next Steps

### Achieve full automation and scale

Now that analytics is deeply integrated into your product decisions, the next stage focuses on automating all workflows and using advanced techniques like machine learning to unlock deeper insights.

[Read Stage 04: Expert →](/guides/strategic-playbooks/product-analytics-strategy/expert)


# Expert
Source: https://docs.mixpanel.com/guides/strategic-playbooks/product-analytics-strategy/expert



## Stage 04

In this section:

* [Introduction to Expert product analytics maturity](#introduction)
* [Common markers of Expert stage](#common-markers-of-expert-stage)
* [Example of Expert product analytics maturity](#example-of-expert-product-analytics-maturity)
* [How to move on from Expert](#what-follows-expert)

## Introduction

In the final stage of product analytics maturity, the entire product development team has access to a full set of accurate data and uses it in every part of product development. The company has unified goals — and everyone is in lock step trying to move the needle on them.

The available metrics and analysis aren't just occasionally consulted, but consistently used, sought out, and considered. Every team member knows how to use the tool and does so regularly.

In this stage, you go from a gym membership to also hiring a personal trainer to teach you new techniques and exercises you've never tried. You've even challenged yourself by signing up and training for your first half marathon.

No product development decision is made without the use of product analytics.

<br />

<Frame>
  <img alt="" />
</Frame>

<Note>
  **Explore Mixpanel**

  See how product and growth teams use Mixpanel's powerful reports to answer any question.

  [Try It With Sample Data](https://mixpanel.com/register/?next=%2Fget-started%2F%3Fexplore%3Dtrue\&link=aypas)
</Note>

## Common markers of Expert stage

At this stage, data can come from a multitude of sources, from cloud imports to customer data platforms. Your product analytics tool is part of your stack, not outside of it.

At its core, building out robust product analytics capabilities is about more than engagement and growth. Because expert product analytics maturity allows in-depth time-series and cohort analysis, teams can start to use the insights to align their product roadmaps with customer priorities, experiment with new features, and more.

## Example of Expert product analytics maturity

### Questions you can answer

Consider the questions that can be answered in the Expert stage:

* What's my product's equivalent of Facebook's "7 friends in 10 days"?
* How do various combinations of user behaviors and user attributes affect engagement and retention?
* How do marketing launches cause changes in specific user behaviors or my primary metrics?
* How quickly do users reach my activation metric? What actions are likely to convert activated users to power users?
* How do all my A/B tests affect key metrics over time, and which of them are worth continuing?
* How many times do users repeat a given step in a funnel before moving on to the next step, and how does that affect conversion rates?

At this level, the latest advancements in experimentation and impact reporting are implemented.

### For Example

Once the ridesharing app has become expert in product analytics, they've successfully learned that a decision isn't complete until it's been verified with data. Their product analysis tool is sophisticated and the answers they can get are nearly limitless.

They recognize the importance of continuing to scale their product analytics and want to use experiment and impact reporting well as they do.

## What follows Expert?

The work's not done once your company reaches the Expert stage of product analytics maturity. There's work to be done to maintain your spot in the final stage.

Employees must be kept up-to-date with changes in your product analytics platform so that they always know what new metrics are being tracked. New team members must be onboarded as soon as possible to live out the data-informed culture.

## Next Steps

### Maintaining excellence and implementation

Now that you've reached the Expert stage, learn how to maintain your analytics maturity, implement best practices, and leverage Mixpanel to its fullest potential.

[Read Conclusion →](/guides/strategic-playbooks/product-analytics-strategy/finale)


# Getting started with product analytics
Source: https://docs.mixpanel.com/guides/strategic-playbooks/product-analytics-strategy/finale



## Conclusion

Product analytics maturation doesn't look identical for every company, but there are factors that everyone should take into account before deciding what product analytics software is best for them.

Ask yourself (and/or your team) the following questions as you move through the stages of product analytics maturity:

**What's the endgame?** First, make sure that you really are looking for product analytics, not marketing analytics. Knowing what questions you're hoping to ask of your data will help you narrow down the analytics software you can choose from. Have a framework for the metrics you want to measure, if you need guidance getting started read our [Guide to Product Metrics](https://mixpanel.com/wp-content/uploads/2023/11/eBook_Guide-to-Product-Metrics.pdf).

**Who will be using the tool?** Anyone who wants product data should have access to it. Therefore should you prioritize accessibility and those who stand to gain the most value from robust product analytics? Be sure to address buy-in, training and anything that could stand in the way of ROI.

**Have you put significant thought into what stage of product analytics maturity you're in?** Go through our [product analytics strategy guide](/guides/strategic-playbooks/product-analytics-strategy/get-started) again and make sure you're being honest with yourself. If you don't know where you are, you probably don't know what you need.

**Where are you headed?** Movement is possible, but you need to know how realistic that movement is. Are you ready to take the next step now, or do you expect to take it in a year? When you do, how will your current software scale or adapt?

**Who's on board?** If you're the only one excited about product analytics and maturity, you have more work to do. Make sure that everyone involved in Product and Development understands the value of product analytics and related software.

<Note>
  **Explore Mixpanel**

  See how product and growth teams use Mixpanel's powerful reports to answer any question.

  [Try It With Sample Data](https://mixpanel.com/register/?next=%2Fget-started%2F%3Fexplore%3Dtrue\&link=aypas)
</Note>

## How to improve your product analytics capability with Mixpanel

Looking to level up your product analytics maturity? Keep a few things in mind as you take your first steps forward.

### You don't have to crawl before you run

We want to clarify something: if you're currently in a non-existent stage and want to achieve advanced product analytics maturity, you don't have to start with Novice. Instead, use the product analytics maturity matrix to determine where you want to end up and the steps you must take to get there.

### Identify new opportunities and changes.

The product analytics maturity model gives your business a framework for understanding the limits of your data right now and identifying areas for growth.

### Drive new value and increase efficiency

Analytics is the foundation for a robust understanding of what makes users convert, engage, and retain in your product; it's also the path towards business growth. Understanding the questions you want to answer will help you identify the nuances between the different stages—and help you identify where you must be in order to get value from your tools, teams, and processes.

### Choose the right analytics tools

Knowing your stage of product analytics maturity can guide your choice of a product analytics platform that's right for your current and future needs. "The value that you get out of any product analytics tool depends on the quality of your implementation," Personal Capital's VP of Product Management, Vince Maniago, told the Mixpanel team. If you don't know what you have, it's difficult to find the right platform to fit your needs.

### Verify your data

Not all data is created equal. Taking the time to understand where your product analytics capabilities stand — and how that affects data collection and interpretation — means understanding if you can trust your data.

As long as you have buy-in from both leadership and your dev team, you can quickly go from Absent to Expert product analytics maturity. We'll walk you through the rest.

### Determine the metrics, KPIs and events you want to track first

Implementing more advanced product analytics with Mixpanel takes between 10 and 40 days, depending on the number of events you need to track. As you get ready for implementation, be prepared to answer these three questions:

* Do we already have the data, or do we need Mixpanel to collect it?
* Do we want Mixpanel to track behaviors on the client side or server side?
* Do we want to use a Mixpanel SDK? Or do we want to use our own?

In short, make sure you're going after the right stats as you build out product analytics maturity.

Looking for a bit more guidance? Check out our [guide to implementation.](https://mixpanel.com/blog/how-long-does-it-take-to-implement-mixpanel-a-3-step-evaluation/)

## It's never too late to advance

There's no question when it comes to whether or not product analysis is useful. But there may be plenty of questions about the best time and way to choose product analytics software.

We hope that this guide has helped in determining where you are and where you want to be in the trajectory of product analytics maturity — and the tools and mindset you'll need to get there.

### Already a Mixpanel user?

By now, you've seen the power of Mixpanel.

Take the opportunity to take a deeper look at your data. Here are some ideas for how our customers double down with the Mixpanel platform:

* Look at the first event time — how are new users adopting your products?
* Use our Impact report to measure your KPIs after your recent product launch.
* Compare funnels to see how different groups convert in your product.
* Aggregate sessions to look at trends across user groups.

Check out these [help articles](https://developer.mixpanel.com/docs) or get in touch with your CSM if you have questions about going deeper with Mixpanel.

### Why Mixpanel?

There's no wrong time to improve your use of product analytics. Knowing where you stand in the progression of product analytics maturity guides and directs that use.

Mixpanel provides flexible and varied data that is accessible even to those who aren't data scientists. Our platform is also scalable — we're with you in the beginning when your reporting needs might be basic, and we will continue to support your growth well into the future.

Looking to level up your product analytics maturity? [Set up a demo today.](https://mixpanel.com/contact-us/demo/)

## About our partners

### About Product Collective

<div>
  <ProductCollectiveLogo />

  <div>
    Product Collective is a community serving 30,000+ technology product management professionals. Through its various resources, products and events, Product Collective aims to help product people answer the question, "Am I doing this right?"

    Members of Product Collective have access to a host of resources, including a weekly newsletter, a semi-monthly live video Q\&A chat series, and an active Slack community. Product Collective also co-hosts one of the top-rated product management podcasts, Rocketship.FM, and organizes one of the top product management conferences series in the world, [INDUSTRY](https://www.industryconference.com/): The Product Conference. Most recently, Product Collective launched INDUSTRY On Demand, a video subscription platform with over 100 hours of educational product management content.

    To help you improve your product analytics strategy, check out these handpicked resources from Product Collective:

    * [Talk from INDUSTRY Europe w/ Dan Olsen](https://youtu.be/_YDaNCGiH6k)
    * [Video Interview w/ Ross Walker](https://youtu.be/5q3CL_1lKoo)
    * [Podcast episode w/ Rahul Vohra of Superhuman](https://music.amazon.com/podcasts/cf646510-46b8-44ad-8865-15f086559f0f/episodes/dfbe1c51-996f-4ff7-826a-d9980667dda9/Rocketshipfm-The-Trick-That-Supercharged-Superhumans-Growth)
  </div>
</div>

### About OpenView

<div>
  <OpenViewLogo />

  <div>
    OpenView is the venture capital firm for expansion stage B2B software companies. Founded in 2006, OpenView invests globally with the mission to improve people's working lives.

    OpenView's focused investment approach across sector and stage enables the firm to identify and partner with category-leading business software companies. The firm's focus extends to operational excellence through its dedicated expansion team, who works with portfolio companies on go-to-market, sales and marketing, product led growth, talent, and corporate development projects.

    For more information, visit [openviewpartners.com](https://openviewpartners.com/).

    To help you benchmark your SaaS performance, check out our [newly released 2020 report](https://openviewpartners.com/expansion-saas-benchmarks#.X6161pNKiko).
  </div>
</div>

## Where do you stand?

Use this matrix as a guide to understand the characteristics of your product analytics strategy at each stage and what's needed to progress.

[Get PDF](https://mxpnlcmsstage.wpengine.com/wp-content/uploads/2023/10/eBook_Guide-to-Advanced-Product-Analytics.pdf)


# Advance Your Product Analytics Strategy
Source: https://docs.mixpanel.com/guides/strategic-playbooks/product-analytics-strategy/get-started



You already know that product analytics is critical to innovation and growth.

Maybe you're a disciple of the product-led growth school of thought, or you harbor a professional envy of Airbnb's data team, but the prospect of going from 0 to 60 seems daunting. In this guide, we break down the success requirements for product analytics—and how you can work your way up to an Expert level of maturity.

Product analytics maturity means:

* Collecting the right data
* Asking the right questions
* Using data for cross-functional product decision making

More than anything, it means directing your attention toward specific success metrics for your product. Product analytics will help you identify hidden trends in user behavior, uncover product flows that lead to churn, and get real-time insight into product usage.

But first, you have to assess your own capabilities and product analytics goals.

At Mixpanel, we've consulted thousands of companies—from bootstrapped startups to leaders in tech. We know what "good" looks like, and we've developed a formula to get companies to "great."

<div>
  <ProductCollectiveLogo />

  <div>
    "Every product person wants to make data-driven decisions. But to do so, you must have the right data, ask the right questions, and use the right tools. That's having true product analytics maturity"
    <div>**Mike Belsito**</div> *Co-Founder, Product Collective*
  </div>
</div>

## What will you learn here?

In order to improve their products, companies must know what questions to ask—and the tools that can answer them.

By assessing your product analytics maturity, you'll see the possibility (and benefit) of moving product data from the periphery to the center of product decisions.

This guide helps you determine:

* Your current product analytics maturity
* Where you want to land on the maturity scale
* What you need to do to get there
* Why it all matters to product and company growth

<div>
  <OpenViewLogo />

  <div>
    "Without data on how the user is moving through your product, you won't grasp where they're unlocking the most value. Without those insights, your team and product devolve into conjecture and building for the vocal minority. Once you've started that, it's impossible to scale."
    <div>**Sam Richard**</div> *Director of Growth, OpenView*
  </div>
</div>

<Note>
  **Explore Mixpanel**

  See how product and growth teams use Mixpanel's powerful reports to answer any question.

  [Try It With Sample Data](https://mixpanel.com/register/?next=%2Fget-started%2F%3Fexplore%3Dtrue\&link=aypas)
</Note>

## What is product analytics maturity?

Product analytics is not just about setting up a tool. It's a discipline that requires the right tool, along with limitless curiosity.

Product analytics maturity refers to where a company stands in the product analytics lifecycle.

### What makes a company more mature in product analytics?

At its core, product analytics is made up of four pillars: data collection, depth of analysis, collaboration, and product metrics.

<br />

<Frame>
  <img alt="" />
</Frame>

Your product analytics maturity determines your capability within each of these areas—and ultimately how you're relying on your data to make product decisions. Throughout the guide, we'll be using a fictional company (a ridesharing app) to help you understand what this looks like in practice.

Product maturity comes in stages—it's sequential, but not necessarily consecutive. Teams can jump from Novice to Advanced product analytics maturity, as long as they've collected the right data, focus on the right questions, and have the right tool.

## The tools you use matter more than you think

Ultimately, the depth of insights that you can ask of your tool—or that you're asking of your own product—is the primary driver of maturity.

To avoid hitting roadblocks with basic tools that track only default activities, take time to identify the events, properties, sessions, and all the user data you want to track.

<Note>
  Mixpanel supports product analytics at every stage, from foundational questions to sophisticated analysis for product and user growth.
</Note>

Select a product analytics tool that will make running analysis straightforward, and is easy to use regardless of your technical abilities. If you're already using an advanced product analytics tool but not to its full capabilities, this guide will help you get the most out of it.

## Why knowing your product analytics maturity matters

Product analytics lets you answer key questions about your product and users—but you can't answer the most essential questions if you're unsure of your product analytics capabilities.

There are five separate levels in our product maturity analytics model—ranging from non-existent to expert. Businesses that fall within the same stages have shared characteristics, limits to the questions they can or can't answer, and the ability to derive value out of their data.

Product analytics maturity matters because it can help you:

### Build the right things

Keep users engaged and happy by improving all aspects of your product experience. Use data to optimize onboarding flows, re-engage inactive user groups, and identify the behaviors that define power users. You can continue to track improvement as your user base and product experience change and grow.

### Empower teams to move faster

Keep up with customer expectations by constantly learning and improving your products. Use real-time user insights and experience testing to rapidly identify what works, and where you should invest further.

### Move the metrics that matter to your business

Identify KPIs at the leadership level, enable each team to impact key metrics, and measure how they change in real-time.

Integrating product analytics into your organization's workflows means everyone can use data to be more strategic.

### Learn about your product analytics maturity stage

Jump to the section that best represents your level of product analytics maturity:

* [Stage 00: Non-Existent](/guides/strategic-playbooks/product-analytics-strategy/non-existent)
* [Stage 01: Novice](/guides/strategic-playbooks/product-analytics-strategy/novice)
* [Stage 02: Intermediate](/guides/strategic-playbooks/product-analytics-strategy/intermediate)
* [Stage 03: Advanced](/guides/strategic-playbooks/product-analytics-strategy/advanced)
* [Stage 04: Expert](/guides/strategic-playbooks/product-analytics-strategy/expert)

## Where do you stand?

Use this matrix as a guide to understand the characteristics of your product analytics strategy at each stage, and what's needed to progress.

[Get PDF](https://mixpanel.com/wp-content/uploads/2021/11/Maturity-Matrix.png)

## Next Steps

### Start assessing your maturity

Begin your journey by understanding where your organization currently stands in the product analytics maturity model.

[Read Stage 00: Non-Existent →](/guides/strategic-playbooks/product-analytics-strategy/non-existent)


# Intermediate
Source: https://docs.mixpanel.com/guides/strategic-playbooks/product-analytics-strategy/intermediate



## Stage 02

In this section:

* [Introduction to Intermediate product analytics maturity](#introduction)
* [Common markers of Intermediate stage](#common-markers-of-intermediate-stage)
* [Example of Intermediate product analytics maturity](#example-of-intermediate-product-analytics-maturity)
* [How to move on from Intermediate](#how-to-move-on-from-intermediate)

## Introduction

In the next stage of product analytics maturity, your metrics and analysis aren't yet as focused as they could be — but you have more of a sense of what you want to track and are willing to invest in the tools and resources needed to answer questions.

At this point, you recognize that product analytics is important, but aren't quite sure how to prioritize metrics and use them to guide product development. You've moved on from "just curling dumbbells" to the bench press — and have added in a mile-long run for good measure.

<Note>
  You're using data to inform product decisions, but not yet to propel them forward in an iterative or systematic way.
</Note>

<br />

<Frame>
  <img alt="" />
</Frame>

You're beginning to use product analysis on a regular basis, but don't know how to use it as a driver for product development.

<div>
  <EmpowerLogo />

  <div>
    "Think about how you can include your product analytics tool in the day-to-day and week-to-week operating of your business. It will make your team's analytics and experimentation muscles that much stronger."
    <div>**Vince Maniago**</div> *VP of Product Management, Empower*
  </div>
</div>

Businesses have a lot of information on their hands — but to get the most out of it, they rely on analysts to uncover meaningful insights. Individuals and teams are empowered to look at data but not to run analysis; instead, they are trained to send questions to the queue. This can lead to bottlenecks in getting necessary information to Product, Design, and other departments.

Bringing your product analytics activity to the next level requires a fundamental shift in the organization toward data democratization and leveraging data focused on product usage. More than that, it means utilizing a tool that can easily and quickly tell you what users do in your product and what's working via detailed user tracking, metadata and more. Not every tool will stand up at this stage.

<Note>
  **Explore Mixpanel**

  See how product and growth teams use Mixpanel's powerful reports to answer any question.

  [Try It With Sample Data](https://mixpanel.com/register/?next=%2Fget-started%2F%3Fexplore%3Dtrue\&link=aypas)
</Note>

## Common markers of Intermediate stage

In this stage, some businesses will opt for codeless product analytics tools in addition to Business Intelligence (BI). This means they begin tracking all events up front, leaving the act of determining their product analytics strategy for later. The resulting implementations are easier at first, with minimal effort needed from developers resources.

However, codeless implementations can lead to serious issues down the line— [missing or inaccurate data, broken tracking, exporting difficulties, and heightened security risks.](https://mixpanel.com/blog/codeless-analytics-problems/) A codeless solution will also limit your depth of analysis by not capturing all the metadata associated with your events. You'll soon reach a limit on the insights you can uncover.

## Example of Intermediate product analytics maturity

### Questions you can answer

In this stage, you can assess what's happening to your product:

* How many daily/weekly/monthly active users does my product have?
* What is the average retention rate of all my users?
* Where in my funnel do users drop off?
* What are the most common user journeys?

In this stage, you can assess what's happening to your product:

### For Example

At some point, the ridesharing app decides to step up their product analytics game.

They begin to gather much more data. They're not agile enough at finding product insights due to bottlenecks with analytics teams or the limitations of a BI tool. Because they don't want to fully commit to product analytics, they seek out codeless tools to save some engineering resources and accept gathering only high-level insights.

They've got the right idea but lack the focus to turn it into productive action.

## How to move on from Intermediate

You achieve more mature product analytics by asking questions of your analysis. To advance even further, it's time to start tying product analytics to other teams and processes.

To move to the Advanced stage, you'll need to acquire buy-in for data democracy, and lay the groundwork for an analytics strategy and strategic implementation from the start. Buy-in means you'll be able to implement a custom solution needed for more robust product analytics capabilities.

## Next Steps

### Implement strategic data collection

Now that you're regularly using product analytics, the next stage focuses on creating a comprehensive data strategy and integrating analytics into your product development workflow.

[Read Stage 03: Advanced →](/guides/strategic-playbooks/product-analytics-strategy/advanced)


# Non-Existent
Source: https://docs.mixpanel.com/guides/strategic-playbooks/product-analytics-strategy/non-existent



## In this section:

* [Introduction to Non-Existent product analytics maturity](#introduction)
* [Example of Non-Existent product analytics maturity](#example-of-non-existent-product-analytics-maturity)
* [How to move on from Non-Existent](#how-to-move-on-from-non-existent)

## Introduction

The "first" stage of product analytic maturity covers businesses that have no existing product analytics capabilities.

<Note>
  Product analytics is non-existent, and development is guided by something other than product metrics: limited customer feedback, intuition, or assumptions about user behavior.
</Note>

It's not that these companies don't have product analytics tools available to them. It's just that the discipline isn't there. They want to work out — they just haven't purchased the dumbbells yet.

<br />

<Frame>
  <img alt="" />
</Frame>

Many startups or non-digitally native businesses believe they have to reach a certain threshold of data in order for it to be valuable or necessary to uncover insights.

However, businesses don't have to stay here long. No signal is too small, and low data volumes are often tracked for free on analytics tools, so there is no cost. These businesses can quickly move to any of the following stages as long as they have a commitment to using data to improve their products. The more buy-in a company has at all levels in data-driven decision making, the easier it will be to move to more advanced stages.

## Example of Non-Existent product analytics maturity

Imagine a new startup with a single product: a ridesharing app.

In Stage 0 of the product analytics maturity process, the product may still be in ideation or in a closed beta launch. Those involved have yet to track or analyze any real metrics. They're simply planning on providing a product to a customer base, or have a very limited audience for the purpose of product feedback.

<Note>
  **Explore Mixpanel**

  See how product and growth teams use Mixpanel's powerful reports to answer any question.

  [Try It With Sample Data](https://mixpanel.com/register/?next=%2Fget-started%2F%3Fexplore%3Dtrue\&link=aypas)
</Note>

## How to move on from Non-Existent

Start defining the questions you would want answered:

* How many rides does the average user take a week?
* On what days of the week are most users taking rides?
* What behaviors lead users to buy a package of rides or to refer a friend?
* How long is the average ride and how does it vary by city?

There's no way to use data well without first having data to use.

No company is too small to prepare to collect, organize, and analyze data — it's the foundation of building great products and accelerating your growth in product analytics maturity.

## Next Steps

### Begin tracking basic metrics

Now that you understand the importance of product analytics, the next stage focuses on starting to track high-level metrics and basic user behaviors.

[Read Stage 01: Novice →](/guides/strategic-playbooks/product-analytics-strategy/novice)


# Novice
Source: https://docs.mixpanel.com/guides/strategic-playbooks/product-analytics-strategy/novice



## Stage 01

In this section:

* [Introduction to Novice product analytics maturity](#introduction)
* [Common markers of Novice stage](#common-markers-of-novice-stage)
* [Example of Novice product analytics maturity](#example-of-novice-product-analytics-maturity)
* [How to move on from Novice](#how-to-move-on-from-novice)

## Introduction

In the Novice stage the product analytics maturity, you're likely measuring a few high-level metrics. You may be focused primarily on traffic, number of sign-ups, total downloads, etc.

The downside is that the questions you're answering are limited and provide an incomplete understanding of their product and users. To carry the exercise metaphor: you've purchased the dumbbells and started your first set of curls. You can only do so many.

<Note>
  If you're in this stage, the good news is that you're committed to using data to some extent to guide your product — if only in response to something breaking.
</Note>

<br />

<Frame>
  <img alt="" />
</Frame>

This is a starting point for companies that are new to data adoption.

Using data, even generic data, to influence product development will benefit your company. But there are limitations to being in this stage.

<Note>
  **Explore Mixpanel**

  See how product and growth teams use Mixpanel's powerful reports to answer any question.

  [Try It With Sample Data](https://mixpanel.com/register/?next=%2Fget-started%2F%3Fexplore%3Dtrue\&link=aypas)
</Note>

## Common markers of Novice Stage

Comfortable with Google Analytics or other marketing analytics tools, many businesses try to hack a product solution to understand product usage. They confuse product analytics with marketing analytics. Additionally, many companies may have a product analytics tool but aren't using it to its fullest potential. This often results in high-level tracking of only a few key default actions (events), primarily around main product lifecycle milestones, traffic, number of sign-ups, total logins, and so on — resulting in data that doesn't drive value.

## Example of Novice product analytics maturity

### Questions you can answer

[Marketing analytics](https://mixpanel.com/blog/the-difference-between-product-analytics-and-marketing-analytics-and-why-you-need-both/) tell only the first part of the story: the traffic to your product and where users come from. Other questions you might ask in the Novice stage include:

* What's my conversion rate to the product?
* What acquisition channels are driving traffic?
* What pages have the highest views?
* What's my overall traffic?

Marketing analytics help you understand how you attract and convert customers. Product analytics solutions help you understand how users engage with your product and what makes them retain.

### For Example

In the Novice stage, the ridesharing startup has launched its product and has decided to track certain metrics. They know they should be keeping track of various custom events, though they may not know which are most important.

Their software tells them that most people log into their app on weekends, and that most customers come from their referral network.

They know some numbers (total signups and new users as of this week), but the data they have isn't affecting product development. It's simply informing them after the fact.

## How to move on from Novice

It can be hard to break out of the Novice stage because you're not sure where you're going. You may be tracking only a few events and therefore you don't have what you need to make informed decisions moving forward.

<Note>
  Plenty of teams have data available. But they're not asking sophisticated questions of that data, they're not tracking the right things to move forward, or the data they're tracking is incomplete.
</Note>

This can lead to gradual but slow growth (best case scenario) or poor product decisions (worst case scenario).

To keep maturing, determine what [metrics](https://mixpanel.com/content/guide-to-product-metrics/full-report/) are most important to your growth. Ask follow-up questions of your analysis: Why are users dropping off? Who are my power users? What causes users to stick around?

If you found out that most users sign up on weekends, find out how this varies by city or what time of day has the highest spike. Being curious and asking more of your data will help you advance.

## Next Steps

### Expand your data collection

Now that you're tracking basic metrics, the next stage focuses on gathering more comprehensive data and beginning to use it more strategically in your product decisions.

[Read Stage 02: Intermediate →](/guides/strategic-playbooks/product-analytics-strategy/intermediate)


# Project Migration Playbook
Source: https://docs.mixpanel.com/guides/strategic-playbooks/project-migration



As companies grow and evolve, projects often become siloed, with data scattered across multiple systems or initiatives. Bringing siloed data into a unified project enhances decision-making and ensures consistency and clarity across teams. Migrating data across projects is a critical process that can significantly impact the efficiency and success of your organization’s operations.

The effort needed for a project migration can vary based on your organization’s specific use case. Generally, more time and resources are required if your data governance practices have not been standardized over time. Key factors, such as the volume of data, the number of projects being migrated, the complexity of events and properties being tracked, your approach to identity management, the standardization of naming conventions, and the severity of the issues can all impact the timeline. By understanding your organization’s objectives and ultimate goals, you can better identify and prioritize which data is essential to transfer and where to focus your efforts.

This project migration playbook is designed to guide you through the complexities of merging and/or migrating project data, providing you with the strategies, best practices, and actionable steps needed to ensure a smooth and successful migration.

We will cover the following key areas:

* **Understanding the Scope:** Assess your data sources and define the objectives of your project migration.
* **Planning and Preparation:** Establish a clear plan, and identify which data is critical to your business.
* **Execution:** Follow our step-by-step guidance on effectively migrating and validating data.
* **Post-Migration Review:** Validate our checklist of best practices for ensuring data integrity, migrating saved entities, and addressing any issues that arise.

This guide will help you navigate the process, minimize risks, and streamline your data consolidation efforts, leading to more informed decision-making and better alignment across your organization.

# When project migrations may be needed

There are various reasons why you may want to complete a project migration.

* Security and Data Access

  * You want to better govern data access in Mixpanel. Consolidating data into one Mixpanel project and leveraging our features such as data views and data classification can ensure that only users with the correct permissions can view certain data.
* Identity Management

  * Addressing identity management issues and resolving problems related to defining unique users across projects.
* Group Analytics

  * You have existing project data that does not contain the group key data that you need in order to run your analysis. You  need to backfill group key data on historical event data.
* Messy data

  * Your organization has been relying on a legacy project for quite some time, but the data has become increasingly difficult to use. You’re looking to create a streamlined, more efficient version of the project while ensuring you can retain the valuable data that is still actively utilized by your organization.
* Consolidating siloed data

  * You have data in multiple Mixpanel projects based on product, platform, or location, but would like to consolidate the data to ensure analysis can be done cross-product, cross-platform, or cross-location.

# Establish Scope & Key Stakeholders

To better understand the goals of investing in a project migration, it’s best to define the scope and objectives upfront with key stakeholders.

**1. Define the Project Scope**

* **Objectives and Goals:**

  * **Clearly state the objectives** of the migration. What are you aiming to achieve? This could include consolidating data in one place, improving data governance, etc.
  * **Identify what is in scope** for this migration. Do you want to bring all data from all projects into one or select a subset of data to retain?
* **Timeline and Milestones:**

  * **Create a high-level timeline** that outlines key phases of the migration, such as planning, execution, validation, and post-migration review. This will help keep the project on schedule.

    * **Best practice:** For larger migrations, the planning phase can become more complex. Using a phased approach to break down the data migration process, with multiple QA checkpoints along the way, helps identify and resolve issues early. This approach reduces the risk of discovering problems in later stages and minimizes the need to reimport quality improvements in subsequent phases.

**2. Identify Key Stakeholders and Define Owners**

* **Identify key points of contact upfront**:

  * **Project Manager**: Point of contact responsible for developing a detailed project plan that includes scope, objectives, timelines, and resources. Engage with stakeholders to understand their requirements and expectations. Regularly communicate progress, risks, and issues to ensure everyone is aligned and informed.
  * **Key *Product* Stakeholders**: Point of contact responsible for documenting established KPIs and the product-specific requirements for the data migration. Ensure that the data migration aligns with the overall business goals and objectives of the team. Provide input and feedback on the migration plan and give final approval on data mapping and transformation to ensure that the product team can clearly understand and utilize the ingested data.
  * **Key *Data* Stakeholders**: Serve as the primary contact for defining data migration requirements, including what data needs to be migrated, how it should be transformed, and any specific constraints or needs in order to report on product’s established metrics. Ensure that the migration team has the necessary data access for each required tool. Assist in assessing and validating data quality, including identifying and resolving issues such as duplicates, inconsistencies, or errors.
  * **Executive Buy in**: Gaining strategic alignment is imperative to the success of this project. This point of contact is responsible for ensuring the data migration initiative aligns with broader business goals. Without it, there’s a risk the project could be deprioritized, leading to delays or incomplete execution.

**3. Document the Project Plan**

* **Feedback mechanisms**, such as having Project Managers create a shared project plan where stakeholders can stay informed about progress, decisions, and issues, can help generate greater visibility throughout the project migration process.

  [Example Data Migration Project Plan](https://docs.google.com/spreadsheets/d/1zSh2OuFuIejieZ7BGTDM6ovdIQ9nuq7DYgpgEeePoU0/edit?gid=0#gid=0)

# Steps

## Step 1: Create New Project

Go to your Mixpanel UI, select the project down-drop at the top left-hand corner of your window, and select “Create Project.”

In your Organization settings navigate to the “Identity Merge” tab. There will be a “New projects in this organization will default to” drop-down, ensure this is set to “Simplified API”.

<Frame>
  <img alt="image" />
</Frame>

## Step 2: Data Audit

Conducting a thorough data audit is essential for a successful project migration. By systematically reviewing and assessing your data, you can ensure that only the most relevant and high-impact information is transferred. Follow these steps to audit your data effectively and streamline your migration process:

**Prioritize Current Uses Cases:**

* Your project Lexicon provides insight into the number of UI and API queries performed by end users over the past 30 days. Focus on consolidating a list of events and properties where the “30-day queries” count is greater than 0. Prioritize migrating only the data that is actively being queried or has a clear, measurable business impact.
* Build out a reverse spec that is inclusive of only the events/properties being utilized today. You can export your Lexicon data dictionary from the legacy projects as a starting point for the reverse spec. Be sure to note which events and properties will be retained for the new project as your metrics and business needs become formalized.

**Understand Your Analytic Strategy:**

* If you haven’t done so already, consider running an [analytics strategy session](/guides/plan/framework) to develop a framework of KPIs and identify the events and properties that are needed to unlock this analysis.
* Using the reverse spec built above, denote the events and properties that enable the analysis of each KPI deemed important during your analytic strategy discussion. If none of the events and properties in the reverse spec can be used to report on a KPI that was surfaced in the analytics strategy, scope out events and properties that would be needed in the next sprint to achieve this analysis.

  * Conversely, if events and properties are included in the reverse spec but are not being used to measure any KPIs from your strategic discuss, determine if these events and properties are crucial to your analysis or if they can be removed from tracking.

**Assess Data Quality:**

* When merging multiple projects, review the event and property taxonomy across all projects to identify opportunities for consolidation during the ETL process. This can help reduce the number of events and properties being transferred to the new project, streamlining the dataset and improving overall efficiency. This includes data type conflicts, inconsistent naming conventions, duplicate/missing values, and identity management strategies. When comparing the data schemas of the projects being migrated, ensure that key event and property names align and that there are no conflicts in data types, structures, or naming conventions.

The output of these steps should serve as the scope and implementation plan that defines your new project schema.

**Outline Scope:**

* Once these key steps are complete you should have a clear & explicit set of events & properties in scope for this migration. As well as established requirements around how far back you expect the data to go, which user identifier will define uniqueness, and an established naming convention to avoid type conflicts moving forward.

  💡 **Best practices for scoping data:**

  * Only migrate events and properties that are being actively utilized to avoid cluttering your project data.
  * Mixpanel only retains data for up to five years. It is worth surveying your team to understand time intervals of the metrics most important to them as to not bring over years of data that may go unused.

## Step 3: Export Existing Data

Once you have determined how far back your data requirement is you can export this data via our [Raw Export API](/reference/raw-event-export) or, if your organization has our Data Pipelines add-on, you can leverage the data you already have in your data warehouse. We recommend exporting a raw pipeline, as opposed to a schematized pipeline, this will export events as JSON to a cloud storage bucket.

With the [raw data export API](/reference/raw-event-export) you can export all event data as the 'event' parameter is optional. See example request below:

```bash theme={"system"}
curl --request GET \
     --url 'https://data.mixpanel.com/api/2.0/export?project_id=<YOUR_PROJECT_ID>&from_date=<FROM_DATE>&to_date=<TO_DATE>' \
     --header 'accept: text/plain' \
     --header 'authorization: Basic ' # set up service account auth
```

*Note:*

* The API will allow for a maximum of 100 concurrent queries, 60 queries per hour, and 3 queries per second.
* If your original project was created prior to March 2023, time should be converted to UTC.

If you choose to export a subset of events to bring over to your new project, you can leverage the `event` or `where` parameters to query for the specific event data you’re looking to migrate.

## Step 4: Transform Data

Upload the exported event data to your storage object, the process here may vary depending on the data warehouse you use. Our [warehouse connector](/docs/tracking-methods/warehouse-connectors) supports integrations with BigQuery, Snowflake, Databricks, and Redshift.

Checklist before running transformations:

* [ ] &#x20;Compare the timezones from your existing projects to the new project to determine any [**timezone offsets**](/docs/orgs-and-projects/managing-projects#manage-timezones-for-projects) that are necessary
* [ ] &#x20;Understand if any transformations are required to uniquely [**identify**](/docs/tracking-methods/id-management) your users
* [ ] &#x20;Determine a To/From **Date**

Optionally:

* [ ] &#x20;Add a [group identifier](/docs/data-structure/group-analytics#group-by-a-custom-identifier) if you’re looking to backfill analysis on a group analytics key.
* [ ] &#x20;Add a super property to utilize [data views](/docs/data-governance/data-views-and-classification) to leverage access to a subset of data for a group of users within a single Mixpanel project.

Begin here and add in transformations and filters to support the table or view that will be leveraged to pull in data from your data warehouse.

```sql theme={"system"}
CREATE VIEW `project.dataset.view` AS
SELECT
    event_name,
    event_time,
    distinct_id,
    properties,
    mp_processing_time_ms, -- insert time
    -- Add in your transformations here
FROM `project.dataset.table`
WHERE condition; -- filter your view here
```

## Step 5: Import Data

Once your event table/view is formatted as expected, navigate to the new project you created in Step 1 in your project settings and connect your warehouse source to Mixpanel. Find your table/view in the drop-down settings and map your fields accordingly.

**Setup**

Source: find your source

Dataset: find your dataset

Table/View: find your table/view

**Map Columns**: `Default Event`

Event Name: Select the ellipsis and choose `Map to Column` select `event_name`

Event Time: `event_time`

User ID: `user_id` (this will serve as your canonical ID)

Device ID: `anonymous_id` (this will serve as your pre-authenticated ID)

+Add Mapping Button: Select `JSON Properties` and select `properties`

**Sync Settings**

Sync Mode: `Append` (if you’re actively sending data to Mixpanel otherwise you can select `One Time`)

Insert Time: `mp_processing_time_ms`

If you are not leveraging our warehouse connectors offering, you can use our [import API](/reference/import-events) instead. Review the GCS batch import script below and modify it to suite your needs (i.e. If your project is stored in the EU adjust your API endpoints accordingly):

```python theme={"system"}
import gzip
import json
import random
import time

from google.cloud import storage
import requests

SECRET = "" # located in project settings
BUCKET_NAME = "" # located in gcs cloud storage
EVENTS_PER_BATCH = 2000
BYTES_PER_BATCH = 2 * 1024 * 1024

def transform_to_event(line):
    """Convert a line of the file to a json string in Mixpanel's format."""
    event = json.loads(line)
    if event["event"] == "$identify":
        return None

    if "$user_id" in event["properties"]:
        event["properties"]["distinct_id"] = event["properties"]["$user_id"]

    return json.dumps(event)

def flush(batch):
    payload = gzip.compress("\n".join(batch).encode("utf-8"))
    tries = 0
    while True:
        resp = requests.post(
            "https://api.mixpanel.com/import",
            params={"strict": "1"},
            headers={
                "Content-Type": "application/x-ndjson",
                "Content-Encoding": "gzip",
                "User-Agent": "mixpanel-gcs"
            },
            auth=(SECRET, ""),
            data=payload,
        )
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(min(2 ** tries, 60) + random.randint(1, 5))
            tries += 1
            continue
        return resp

def main():
    gcs = storage.Client()
    bucket = gcs.get_bucket(BUCKET_NAME)

    for blob in bucket.list_blobs():
        # Skip files that do not end with 'export.json.gz'
        if not blob.name.endswith('export.json.gz'):
            continue

        error = None
        batch, batch_bytes = [], 0

        f = blob.open("rb")
        if blob.name.endswith(".gz") and blob.content_encoding != "gzip":
            f = gzip.open(f)

        for line in f:
            transformed_line = transform_to_event(line)

            if transformed_line is None:
                continue

            batch.append(transformed_line)
            batch_bytes += len(transformed_line)

            if len(batch) == EVENTS_PER_BATCH or batch_bytes >= BYTES_PER_BATCH:
                resp = flush(batch)
                batch, batch_bytes = [], 0

                if resp.status_code != 200:
                    error = resp.json()
                    break

        # Flush final batch
        if batch and not error:
            resp = flush(batch)
            if resp.status_code != 200:
                error = resp.json()

        f.close()
        print(
            json.dumps(
                {
                    "message": "Import complete for blob: {blob.name}",
                    "success": error is None,
                    "first_error": error,
                    "severity": "INFO",
                }
            )
        )

if __name__ == "__main__":
    main()
```

## (Optional) Step 6: Export Users

This step is optional if you would like to migrate historical user properties into your new project.

If you have our [Data Pipelines add-on](/docs/data-pipelines) you can use the user table in your data warehouse.

If you do not have access to this user profile data outside of Mixpanel, you can utilize the python script below to export user profile data.

Run `pip install mixpanel-api` in your command line

```python theme={"system"}
from mixpanel_api import Mixpanel

if __name__ == '__main__':

 api_secret = 'YOURAPISECRET'
 project_token = 'YOURPROJECT'

 m = Mixpanel(api_secret,token=project_token, pool_size=4, debug=True)

 selector = ''
 behaviors = ''
 parameters = {'selector': selector, 'behaviors': behaviors}
 m.export_people('people_export.csv',parameters,timezone_offset=-8,format='csv')
```

Update the above script with your project inputs. The API secret and project token can be located in your project settings. To find the selector and behavior inputs you can look at the XHR request on the Users page that contains the profiles you want to export. This is done by pressing CMD+option+J on Chrome for macOS and then selecting the Network tab.

## (Optional) Step 7: Transform Users

Using the imported user data in your data warehouse, you can build out logic in SQL to create a view to pull specific data in or import your table as is.

Example SQL logic to build out transformations to import as user profiles in Mixpanel:

```sql theme={"system"}
CREATE VIEW `project.dataset.view` AS
SELECT
    distinct_id
    -- Add in your transformations here
FROM `project.dataset.table`
WHERE condition; -- filter your view here
```

It’s important to check that each project will be using the same values for distinct\_id across projects to ensure you’re not updating the wrong user profile or creating duplicates.

## (Optional) Step 8: Import Users

Once your user table/view is formatted as expected navigate to your new project, head over to your project settings and connect your warehouse source to Mixpanel. Find your table/view in the drop-down settings and map your fields accordingly.

If you have not purchased warehouse connectors, you can leverage our [Engage API](/reference/profile-set) instead. Here's some sample code to get you started, utilizing the `$set` operator to update user profiles:

```python theme={"system"}
# Fill this out. You can get it from https://mixpanel.com/settings/project
PROJECT_TOKEN = ""
 
import json
import requests
 
 
def get_users_from_database():
    # Replace this with code that reads users from your database or CRM.
    # Note: $name and $email are optional, but useful properties that automatically populate certain parts of our UI when Mixpanel detects them.
    return [
        {"user_id": "123", "$name": "Alice", "$email": "alice@linear.app", "department": "engineering"},
        {"user_id": "456", "$name": "Bob", "$email": "bob@notion.so", "department": "product"},
        {"user_id": "789", "$name": "Carol", "$email": "carol@figma.com", "department": "design"}
    ]
 
def transform_to_mp_format(user):
    """Transform the above into Mixpanel's format"""
    # It's important to set this to the same distinct_id that you use when tracking events.
    # We recommend using the primary key of your users' table for this.
    distinct_id = user.pop("user_id")
 
    # Note: we set `$ip` to 0 here to tell Mixpanel not to look up the IP of this user.
    return {"$distinct_id": distinct_id, "$token": PROJECT_TOKEN, "$ip": "0", "$set": user}
 
 
users = get_users_from_database()
profiles = [transform_to_mp_format(u) for u in users]
 
# We recommend calling this API with batches of 200 user profiles to do this at scale.
resp = requests.post(
    "https://api.mixpanel.com/engage",
    params={"verbose": "2"},
    headers={"Content-Type": "application/json"},
    data=json.dumps(profiles)
)
 
print(resp.json())
```

## Step 9: Redirect Project Data

Update the project token for platforms actively sending data to Mixpanel today. If any ETL work was completed during the migration to consolidate events and properties or change unique identifiers, make sure your implementation incorporates these changes. This will ensure that all new data streaming into your project aligns with the migrated data.

## Step 10: Data Validation

**1. Post-Migration Data Quality Checks**

* **Count Verification:** After the migration, verify that the number of events (totals & uniques) in the migrated dataset matches the expected total. This can be easily verified using our Insights report. Any discrepancies should be investigated and resolved.
* **Data Consistency Check:** Ensure that the data is consistent across all events. For example, verify that all related properties have been correctly migrated and that no data types, or naming convention conflicts exist.
* **Unique Identifier Validation:** Check that all unique identifiers remain unique after the migration and that no duplicates have been introduced.

💡 **Note:** For projects created before 1 Jan 2023, Mixpanel converts event timestamps to your project timezone before writing the event to your Mixpanel data stores, meaning that event timestamps are stored based on the project timezone setting at the time of ingestion.

**2. Stakeholder Review**

* **Collaborative Validation:** Involve key stakeholders, such as data owners, project managers, and end-users, in the validation process. Their insights can help identify potential issues that automated checks might miss. Ensure they can pull the KPIs they’ve identified as critical in the analytic strategy discussion. Document the KPI in a shared board and how you gained this insight for future reference.

  * Pro tip: Creating a reference guide at this step can serve as a helpful guide as you socialize the new project with end users getting up to speed at your organization.
* **Feedback Loop:** Create a feedback loop where stakeholders can report any issues or concerns after reviewing the migrated data. This feedback is essential for making final adjustments.
* **Obtain Sign-Off:** Before the migrated data is put into production, obtain formal sign-off from all relevant stakeholders to confirm that the data has been validated and meets the necessary standards.

## Step 11: Migrate Saved Entities

Saved entities, such as reports, boards, custom events, custom properties, cohorts, and lexicon metadata, are critical components that provide valuable insights and streamline workflows. During a project migration, it's essential to carefully migrate these entities to ensure continuity and maintain the integrity of your analyses.

**Steps for Migrating Saved Entities:**

1. **Inventory and Categorize Saved Entities:**

   * Begin by creating a comprehensive inventory of all saved entities in each project. Categorize them by type (i.e. boards, reports) and by their usage frequency and importance.
   * Identify any duplicate or obsolete entities that may not need to be migrated, streamlining the overall process.
2. **Map Saved Entities to the New Project Structure:**

   * Review how saved entities relate to the data model and taxonomy in the new project. Update or adjust entity configurations as needed to align with the new structure.

     * For example, if event names or properties have been consolidated during the ETL process, ensure that these changes are reflected in the saved entities.
3. **Migrate Entities in Phases:**

   * Consider migrating saved entities in phases, starting with the most critical and frequently used ones.
   * Engage key stakeholders to review and validate the migrated entities, as their input can help identify any issues that might have been missed.
4. **Update Documentation:**

   * Update any documentation related to the saved entities to reflect changes made during the migration. This includes updating success plans, reference guides, and any other resources that refer to these entities.
5. **Communicate with End Users:**

   * Notify end users of the migration and provide them with any necessary training or resources to understand changes in the saved entities.
   * Offer support channels for users who may encounter issues or have questions about the migrated entities.

💡 **Best Practices:**

* **Prioritize Key Entities:** Focus on migrating the most important and frequently used entities first to ensure critical business functions continue uninterrupted.
* **Collaborate with Stakeholders:** Involve key stakeholders throughout the migration process to ensure that their needs are met and that the migrated entities align with their expectations.
* **Boards & Reports**: Utilize [Move](/docs/boards/move-boards) to transfer saved boards and reports across the same region (i.e. US, EU data centers). Permissions are managed by group admins allowing Boards to be moved across Projects or Organizations, depending on your use case.

  * Move does not support the migration of custom events, custom properties, cohorts, and lexicon metadata. This would need to be done manually. Review these lists with stakeholders and decide if any of these saved entities would need to be recreated in the new project to set your end users up for success.
  * Lexicon metadata can be [retrieved](/reference/list-all-schemas-for-project) from existing projects and [recreated](/reference/upload-schemas-for-project) in the new project via our Lexicon Schemas API.

## Ongoing Optimization

As organizations grow and new use cases become available to become analyzed it presents an opportunity for data to drift from the governed processes we put in place throughout this playbook. Having a process in place for new teams to follow allows for your customer to scale cleanly.

Leveraging our in-product data governance tools can help support ongoing structure throughout your customers projects. Implementing the use of “verified” metrics, events, and formulas helps end users identify trusted content across the organization. Once your trusted governance owner(s) verify content, a blue checkmark badge will be displayed in the query builder as well as within a dedicated category within the query builder to help users quickly filter to see only trusted content.

Having pinned and favorite boards for new users to jump into as they familiarize themselves with the data is a great place to start. We see the most success when companies have a trusted metrics board for each team or product that leverages this. These boards not only guide users in exploring new use cases but also ensure they leverage the correct events and properties to get the answers they need.

Our in-product data standards tooling empowers your organization to scale your data operations by acting on your data at scale through the a rule based system.

Today, you can define the following standards:

* All my events must be \[X] case
* All my events must include a description
* All my events must include an owner

If Data Standards are violated, you can define actions to be automatically applied. As a result, you can ensure your data quality stays high, without needing to invest corresponding amounts of time enforcing manually.

By enforcing continuous governance practices and leveraging our in-product tooling, you can proactively address potential inconsistencies and maintain alignment across your new and existing data in Mixpanel, fostering reliability and long-term data quality.


# Customer.io
Source: https://docs.mixpanel.com/links/customerio





# Get Help
Source: https://docs.mixpanel.com/links/get-help





# Hire an Expert
Source: https://docs.mixpanel.com/links/hire-an-expert





# Intercom
Source: https://docs.mixpanel.com/links/intercom





# Additional Information
Source: https://docs.mixpanel.com/links/jql





# Legal Hub
Source: https://docs.mixpanel.com/links/legal-hub





# Mixpanel-utils
Source: https://docs.mixpanel.com/links/mixpanel-utils





# Join Slack
Source: https://docs.mixpanel.com/links/slack





# What's New?
Source: https://docs.mixpanel.com/links/whats-new





# Profile Event Activity
Source: https://docs.mixpanel.com/reference/activity-stream-query

openapi/query.openapi.yaml GET /stream/query
> ❗️stream/query is currently in maintenance mode.

This endpoint returns the activity feed for specified users.

**Note:** The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.




# Add Service Accounts To Projects
Source: https://docs.mixpanel.com/reference/add-service-accounts-to-projects

openapi/service-accounts.openapi.yaml POST /organizations/{organizationId}/service-accounts/add-to-project
Adds a list of service account ids to a list of project ids with the specified role



# Archive Experiment
Source: https://docs.mixpanel.com/reference/archive-experiment

openapi/experiments.openapi.yaml POST /workspaces/{workspace_id}/experiments/{experiment_id}/archive



# Authentication Methods
Source: https://docs.mixpanel.com/reference/authentication



Most of our APIs require authentication for which we recommend using [Service Accounts](/reference/service-accounts) to authenticate. However, most of our [Ingestion API](/reference/ingestion-api) calls such as [Import Events](/reference/import-events), [Track Events](/reference/track-event), [User Profiles](/reference/profile-set), and [Group Profiles](/reference/group-set-property) only require a [Project Token](/reference/project-token). Because these APIs are often called from our client-side SDKs, we do not want to expose credentials, but we do need to know which project to send data to so we use the Project Token for that purpose.

<Warning>
  **HTTPS Only**

  Our APIs will reject calls made over HTTP to protect request and response information.
</Warning>


# Authentication
Source: https://docs.mixpanel.com/reference/authentication-2



## Service Account

<Note>
  **Roles & Permissions**

  To use the Data Pipelines API, the Service Account must have the role of admin or owner.
</Note>

[Service Account Authentication Details](/reference/service-accounts)


# Delete Pipeline
Source: https://docs.mixpanel.com/reference/cancel-warehouse-pipeline

openapi/data-pipelines.openapi.yaml POST /nessie/pipeline/cancel
For a given pipeline name, this request deletes the pipeline and stops any future jobs to be scheduled for the pipeline.  Deleting the pipeline will result in the loss of all its historical data. If you wish to retain the history, it is recommended to pause the pipeline instead.



# List Saved Cohorts
Source: https://docs.mixpanel.com/reference/cohorts-list

openapi/query.openapi.yaml POST /cohorts/list
The list endpoint returns all of the cohorts in a given project. The JSON formatted return contains the cohort name, id, count, description, creation date, and visibility for every cohort in the project.

If you're trying to get a list of users in a cohort, you can use the [`/engage` endpoint with the `filter_by_cohort` parameter](/reference/engage-query).
The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.




# Create Annotations
Source: https://docs.mixpanel.com/reference/create-annotation

openapi/annotations.openapi.yaml POST /projects/{projectId}/annotations
Create an Annotation. Requires a role of at least Analyst.



# Create Annotation Tag
Source: https://docs.mixpanel.com/reference/create-annotation-tag-1

openapi/annotations.openapi.yaml POST /projects/{projectId}/annotations/tags
Creates a new tag using the provided name. Requires a role of at least Analyst



# Create a Deletion
Source: https://docs.mixpanel.com/reference/create-deletion

openapi/gdpr.openapi.yaml POST /data-deletions/v3.0
Creates a task that specifies a list of users in a project to delete



# Create Event Stream Import
Source: https://docs.mixpanel.com/reference/create-event-stream-import

openapi/warehouse-connectors.openapi.yaml POST /projects/{projectId}/warehouse-sources/imports/event-stream
Create a new warehouse import for event data.

Event stream imports sync event data from your warehouse table to Mixpanel.
Each row in your table becomes an event in Mixpanel.

### Sync Modes

- **time_based**: Incrementally syncs new rows based on an insert time column
- **mirror_mode**: Detects changes in the source table and mirrors them to Mixpanel
- **full_sync**: Re-syncs all data on each run
- **one_time**: Syncs data once and does not repeat

### Required Column Mappings

You must specify either:
- `event_name`: A static event name for all rows
- `event_column_name`: The column containing the event name

For B2B projects, `company_column_name` is also required.

### Scheduling

- **run_every** (integer): Sync frequency in nanoseconds. Allowed values:
  - Trigger via API: `0`
  - Hourly: `3600000000000` (60 * 60 * 10^9)
  - Daily: `86400000000000` (24 * 60 * 60 * 10^9)
  - Weekly: `604800000000000` (7 * 24 * 60 * 60 * 10^9)
- **databricks_params** (object): Databricks-specific cluster configuration (only for Databricks sources)




# Create Experiment
Source: https://docs.mixpanel.com/reference/create-experiment

openapi/experiments.openapi.yaml POST /workspaces/{workspace_id}/experiments



# Create Feature Flag
Source: https://docs.mixpanel.com/reference/create-feature-flag-1

openapi/feature-flags-management.openapi.yaml POST /projects/{project_id}/workspaces/{workspace_id}/feature-flags



# Create Groups Import
Source: https://docs.mixpanel.com/reference/create-groups-import

openapi/warehouse-connectors.openapi.yaml POST /projects/{projectId}/warehouse-sources/imports/groups
Create a new warehouse import for group profile data.
Groups imports sync group properties from your warehouse to Mixpanel group profiles. 



# Create Identity
Source: https://docs.mixpanel.com/reference/create-identity

openapi/identity.openapi.yaml POST /track#create-identity

<Note>
  The `$identify` event payload is only useful for projects using the Original ID Merge system; it has no functionality in other ID management systems. Please review [this section of our documentation](/docs/tracking-methods/id-management#identity-merge-apis) for more information.
</Note>

<Note>
  You can also use the import endpoint: [https://api.mixpanel.com/import/](https://api.mixpanel.com/import/)
</Note>

```sh theme={"system"}
curl --request POST \
     --url 'https://api.mixpanel.com/track#create-identity' \
     --header 'accept: text/plain' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data 'data={
      "event": "$identify",
      "properties": {
          "$identified_id": "YOUR_CHOSEN_USER_ID",
          "$anon_id": "ORIGINAL_ANON_ID",
          "token": "YOUR_PROJECT_TOKEN"
      }
}
'
```

**Identify Criteria:**

<Frame>
  <img alt="" />
</Frame>

**Required[Event Object](/docs/data-structure/concepts#anatomy-of-an-event) attributes**

| Event Object property           | Type                                           | Description                                                                                                                                                                                            |
| :------------------------------ | :--------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **event**                       | <span>String</span><br /><span>required</span> | value must be: `$identify`                                                                                                                                                                             |
| **properties**                  | <span>Object</span><br /><span>required</span> |                                                                                                                                                                                                        |
| **properties.distinct\_id**     | <span>String</span><br /><span>optional</span> | The distinct ID post-identification (same as \$identified\_id - it will be inferred from \$identified\_id if not included)                                                                             |
| **properties.\$identified\_id** | <span>String</span><br /><span>required</span> | A distinct\_id to merge with the \$anon\_id.                                                                                                                                                           |
| **properties.\$anon\_id**       | <span>String</span><br /><span>required</span> | A distinct\_id to merge with the \$identified\_id. The \$anon\_id must be [UUID v4](https://en.wikipedia.org/wiki/Universally_unique_identifier) format and not already merged to an \$identified\_id. |
| **properties.token**            | <span>String</span><br /><span>required</span> | The project token.                                                                                                                                                                                     |


# Create Lookup Table Import
Source: https://docs.mixpanel.com/reference/create-lookup-table-import

openapi/warehouse-connectors.openapi.yaml POST /projects/{projectId}/warehouse-sources/imports/lookup-table
Create a new warehouse import for lookup table data.

Lookup tables allow you to enrich event and user properties with additional
attributes from your warehouse.




# Create People Import
Source: https://docs.mixpanel.com/reference/create-people-import

openapi/warehouse-connectors.openapi.yaml POST /projects/{projectId}/warehouse-sources/imports/people
Create a new warehouse import for user profile data.

People imports sync user properties from your warehouse to Mixpanel user profiles.
Each row represents a user, identified by the `user_column_name`.




# Create a Retrieval
Source: https://docs.mixpanel.com/reference/create-retrieval-1

openapi/gdpr.openapi.yaml POST /data-retrievals/v3.0
Creates a data retrieval job.



# Create Service Account
Source: https://docs.mixpanel.com/reference/create-service-account

openapi/service-accounts.openapi.yaml POST /organizations/{organizationId}/service-accounts
Create a new service account for your organization and optionally add it to one or more projects in your organization



# Create Pipeline
Source: https://docs.mixpanel.com/reference/create-warehouse-pipeline

openapi/data-pipelines.openapi.yaml POST /nessie/pipeline/create

This request creates an export pipeline. The `type` parameter defines the kind of pipeline that is initiated. Note that only 2 recurring and 1 non-recurring events pipelines (**data\_source**: `events`) are allowed per project.

Create API returns the name of the pipeline created. Use the name of the pipeline to check the status of or cancel the pipeline.

> **Important:** For BigQuery pipelines, `gcp_project` and `bq_dataset_name` are **required** fields. Mixpanel-hosted BigQuery is not supported.

> **Important:** For Snowflake pipelines, customer-hosted credentials (`snowflake_account_name`, `snowflake_warehouse`, `snowflake_storage_integration`, `snowflake_user`, `snowflake_password`, `snowflake_role`, `snowflake_database`, `snowflake_schema`) are **required**. Only password-based authentication is supported. Mixpanel-hosted Snowflake is not supported.


# Decide Experiment
Source: https://docs.mixpanel.com/reference/decide-experiment

openapi/experiments.openapi.yaml PATCH /workspaces/{workspace_id}/experiments/{experiment_id}/decide



# Delete all Schemas
Source: https://docs.mixpanel.com/reference/delete-all-schemas-in-project

openapi/lexicon-schemas.openapi.yaml DELETE /projects/{projectId}/schemas
Delete all schemas in a project



# Delete Annotation
Source: https://docs.mixpanel.com/reference/delete-annotation-1

openapi/annotations.openapi.yaml DELETE /projects/{projectId}/annotations/{annotationId}
Delete an Annotation. Requires a role of at least Analyst.



# Cancel a Deletion
Source: https://docs.mixpanel.com/reference/delete-deletion

openapi/gdpr.openapi.yaml DELETE /data-deletions/v3.0/{tracking_id}
Cancel a deletion task that is still in progress



# Delete Experiment
Source: https://docs.mixpanel.com/reference/delete-experiment

openapi/experiments.openapi.yaml DELETE /workspaces/{workspace_id}/experiments/{experiment_id}



# Delete Feature Flag
Source: https://docs.mixpanel.com/reference/delete-feature-flag-1

openapi/feature-flags-management.openapi.yaml DELETE /projects/{project_id}/workspaces/{workspace_id}/feature-flags/{flag_id}



# Delete Group
Source: https://docs.mixpanel.com/reference/delete-group

openapi/ingestion.openapi.yaml POST /groups#group-delete
Deletes a group profile from Mixpanel.



# Delete User Profile
Source: https://docs.mixpanel.com/reference/delete-profile

openapi/ingestion.openapi.yaml POST /engage#profile-delete
Permanently delete the profile from Mixpanel, along with all of its properties. The \$delete object value is ignored - the profile is determined by the \$distinct_id from the request itself.

If you have duplicate profiles, use property \$ignore_alias set to true so that you don't delete the original profile when trying to delete the duplicate (as they pass in the alias as the \$distinct_id). 



# Delete for Entity and Name
Source: https://docs.mixpanel.com/reference/delete-schema-by-entity-and-name

openapi/lexicon-schemas.openapi.yaml DELETE /projects/{projectId}/schemas/{entityType}/{name}
Delete schema for an entity type and entity name



# Delete for Entity
Source: https://docs.mixpanel.com/reference/delete-schemas-for-entity

openapi/lexicon-schemas.openapi.yaml DELETE /projects/{projectId}/schemas/{entityType}
Delete all schemas of a specific entity type



# Delete Service Account
Source: https://docs.mixpanel.com/reference/delete-service-account

openapi/service-accounts.openapi.yaml DELETE /organizations/{organizationId}/service-accounts/{serviceAccountId}
Removes the service account from all associated projects and deletes it from the organization



# Delete Warehouse Import
Source: https://docs.mixpanel.com/reference/delete-warehouse-import

openapi/warehouse-connectors.openapi.yaml DELETE /projects/{projectId}/warehouse-sources/imports/{importId}
Deletes a warehouse import and optionally deletes the imported data.

When `delete_data: true` is specified, an event deletion request will be
created to remove the imported events from Mixpanel.




# Edit Pipeline
Source: https://docs.mixpanel.com/reference/edit-warehouse-pipeline

openapi/data-pipelines.openapi.yaml POST /nessie/pipeline/edit
This request edit the params for an export pipeline.




# Query Profiles
Source: https://docs.mixpanel.com/reference/engage-query

openapi/query.openapi.yaml POST /engage

Query user (or group) profile data and return list of users (or groups) that fit specified parameters.

API responses will return at most `page_size` records for each request. To request additional records, callers should repeat their call to the API using the same `where` param, but provide a `session_id` parameter with a value taken from the first response, and include a `page` parameter with a value one greater than the value of page in the response.

A caller trying to retrieve all of the records for a particular query might use an algorithm something like this:

```javascript theme={"system"}
// Get the first page of data associated with our selector expression
this_page = query_api(where=YOUR_SELECTOR_EXPRESSION)
do_something_with_response(this_page)

// If we get fewer records than the page_size returned with our results,
// then there are no more records to get. Otherwise, keep querying for additional pages.
while (length of this_page.results) >= this_page.page_size:
    next_page_number = this_page.page + 1
    this_page = query_api(where=YOUR_SELECTOR_EXPRESSION, session_id=this_page.session_id, page=next_page_number)
    do_something_with_response(this_page)
```

The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.


# Event Deduplication
Source: https://docs.mixpanel.com/reference/event-deduplication



Mixpanel provides an event deduplication mechanism to ensure that duplicate events do not skew your analytics. Deduplication is essential when events may be sent multiple times due to network retries, client-side batching, or integration with multiple data sources.

## How Deduplication Works

Mixpanel deduplicates events using a combination of four key event properties:

* Event Name (`event`)
* Distinct ID (`distinct_id`)
* Timestamp (`time`)
* Insert ID (`$insert_id`)

If all four of these properties are identical across two or more events, Mixpanel considers them duplicates and will only show the most recent version of that event in your reports. This applies regardless of whether the events are sent via SDKs, APIs, or other integrations.

The `$insert_id` should be a randomly generated, unique value for each event to ensure proper deduplication. If `$insert_id` are reused, events may be unintentionally deduplicated.

Only the four key event properties listed above are used for deduplication. Additional event properties are not considered for the deduplication mechanism. For example, if two events share the same Event Name, Distinct ID, Timestamp, and Insert ID, but have different \$city value, they are still considered duplicate events.

### Deduplication Example

Deduplication occurs when a subset of the event data (event name, distinct\_id, timestamp, \$insert\_id) is identical. Other event properties are not considered.

**Required [Event Object](/docs/data-model#anatomy-of-an-event) attributes**

<table>
  <thead>
    <tr>
      <th>Event Object property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**event**</td>

      <td>
        <span>String</span><br /><span>required</span>
      </td>

      <td>A name for the event. For example, "Signed up", or "Uploaded Photo".</td>
    </tr>

    <tr>
      <td>**properties**</td>

      <td>
        <span>Object</span><br /><span>required</span>
      </td>

      <td />
    </tr>

    <tr>
      <td>**properties.distinct\_id**</td>

      <td>
        <span>String</span><br /><span>required</span>
      </td>

      <td>The value of `distinct_id` will be treated as a string, and used to uniquely identify a user associated with your event. If you provide a distinct\_id property with your events, you can track a given user through funnels and distinguish unique users for retention analyses. You should always send the same distinct\_id when an event is triggered by the same user.</td>
    </tr>

    <tr>
      <td>**properties.token**</td>

      <td>
        <span>String</span><br /><span>required</span>
      </td>

      <td>The Mixpanel token associated with your project. You can find your Mixpanel token in the project settings dialog in the Mixpanel app. Events without a valid token will be ignored.</td>
    </tr>

    <tr>
      <td>**properties.time**</td>

      <td>
        <span>String</span><br /><span>required</span>
      </td>

      <td>The time an event occurred. If present, the value should be a unix timestamp (seconds since midnight, January 1st, 1970 - UTC). If this property is not included in your request, Mixpanel will use the time the event arrives at the server.</td>
    </tr>

    <tr>
      <td>**properties.\$insert\_id**</td>

      <td>
        <span>String</span><br /><span>required</span>
      </td>

      <td>A unique UUID tied to exactly one occurrence of an event.</td>
    </tr>
  </tbody>
</table>

In other words, each event containing an `$insert_id` is checked for duplication after being minimized to the following shape:

```json theme={"system"}
{
  "event": "Item Purchased",
  "properties": {
    "token": "my_project_token",
    "distinct_id": "user123xyz",
    "time": 1601412131000,
    "$insert_id": "88B7hahbaschhhB66cbsg"
  }
}
```

If this minimized event object is an exact match to any other minimized event object, it is marked as a duplicate. Ingested events that have been marked as duplicates will be deduplicated.

If an event is sent to the Ingestion API without an `$insert_id`, one will be generated for it. However, it will not qualify for the deduplication process.

## Deduplication Mechanisms

Mixpanel uses two main deduplication processes:

### Query-Time Deduplication

* When: Happens immediately when you query data in the Mixpanel UI.
* How: If multiple events share the same event\_name, distinct\_id, timestamp, and \$insert\_id, only the most recent version of the event is shown in reports (based on the API ingestion time). In most cases, only the more recent version of the event is shown in reports (based on the API ingestion time). It is important to note that Mixpanel does not guarantee upsert behavior.
* Scope: This deduplication is visible in the Mixpanel UI and reports, but not in raw data exports. Raw event export will contain all data as they were ingested, without any deduplication.

### Compaction-Time Deduplication

<Warning>
  Compaction-time deduplication does not run at a guaranteed or deterministic time. The process can take several hours to days to complete, and in some cases may not run at all. Do not rely on this mechanism to upsert existing data.
</Warning>

* When: Runs periodically in the backend, typically after a few hours and again after about 20 days, once data ingestion for a day is complete.
* How: During compaction, Mixpanel scans for events with the same event name, distinct\_id, and \$insert\_id (timestamp does not need to match exactly, just the same calendar day).
* Scope: This process helps reduce the storage of duplicate events and may affect event counts if duplicates were present with different timestamps

<br />

## Important Notes

**Raw Event Export** - Deduplication is not applied to raw data exports. If you export events via the API, you may see duplicates. It is recommended to apply the same deduplication logic (event name, distinct\_id, timestamp, \$insert\_id) to your exported data

**Insert ID Best Practice** - Always generate a unique \$insert\_id for each event. Reusing \$insert\_id (e.g., setting it to the user’s distinct\_id) can cause unintended deduplication and data loss

**Deduplication Timing** - Query-time deduplication is immediate. Compaction-time deduplication timing is not guaranteed and may take hours to days to complete.


# Overview
Source: https://docs.mixpanel.com/reference/feature-flags-api



Mixpanel's Feature Flagging API's provides an interface for assigning your users to variants for feature flags defined within Mixpanel projects.


# Overview
Source: https://docs.mixpanel.com/reference/feature-flags-management-api



Use the Feature Flags Management API to create, update, delete, and manage feature flags. Requires Service Account authentication.


# Force Conclude Experiment
Source: https://docs.mixpanel.com/reference/force-conclude-experiment

openapi/experiments.openapi.yaml PUT /workspaces/{workspace_id}/experiments/{experiment_id}/force_conclude



# List Saved Funnels
Source: https://docs.mixpanel.com/reference/funnels-list-saved

openapi/query.openapi.yaml GET /funnels/list
Get the names and funnel_ids of your funnels.

> ❗️The Funnels Query API is in maintenance mode. We recommend discontinuing new use of this endpoint. To get funnel data, build a [Funnels report](https://docs.mixpanel.com/docs/reports/funnels) in-app and query it programmatically with the [Insights Query API](https://developer.mixpanel.com/reference/insights-query). For raw event data, see [export methods](https://docs.mixpanel.com/docs/export-methods). If you need help choosing the best method, reach out to [support](https://mixpanel.com/get-support).


# Query Saved Report
Source: https://docs.mixpanel.com/reference/funnels-query

openapi/query.openapi.yaml GET /funnels
Get data for a funnel. The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.

> ❗️The Funnels Query API is in maintenance mode. We recommend discontinuing new use of this endpoint. To get funnel data, build a [Funnels report](https://docs.mixpanel.com/docs/reports/funnels) in-app and query it programmatically with the [Insights Query API](https://developer.mixpanel.com/reference/insights-query). For raw event data, see [export methods](https://docs.mixpanel.com/docs/export-methods). If you need help choosing the best method, reach out to [support](https://mixpanel.com/get-support).


# Overview
Source: https://docs.mixpanel.com/reference/gdpr-api



## GDPR and CCPA API (v3)

The following retrieval and deletion API calls are updated for version 3 and are made for GDPR and CCPA compliance.

#### Create Retrieval

Request Type: **POST**<br />Description: Creates a data retrieval job.<br />Endpoint: `https://mixpanel.com/api/app/data-retrievals/v3.0/?token=<your_project_token>`<br />Parameters:

| Parameter        | Parameter Type                    | Data Type              | Description                                                                                                                               |
| ---------------- | --------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Token            | URL. Passed in request URL.       | Query String Parameter | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).                                        |
| distinct\_ids    | Body. Passed in JSON blob format. | Array of strings       | A list of distinct IDs associated with the users whose data you would like to export. You can add up to 2000 distinct IDs.                |
| compliance\_type | Body. Passed in JSON blob format. | String                 | Select CCPA or GDPR. Default is GDPR.                                                                                                     |
| disclosure\_type | Body. Passed in JSON blob format. | String                 | Only required if compliance\_type = CCPA. Can be [Data, Categories, or Sources. Default is Data](/docs/privacy/end-user-data-management). |

Authorization:

| Authorization Type | Pass As                           | Description                                                                                    |
| ------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------- |
| Bearer             | Body. Passed in JSON blob format. | Your [OAuth token](/docs/privacy/end-user-data-management#generate-oauth-token) for GDPR APIs. |

Example Request:

```text theme={"system"}
curl "https://mixpanel.com/api/app/data-retrievals/v3.0/?token=591b3354bb2bdd96f72f23bf56911673"
-H "Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc"
```

##### Rate Limit

We place a rate limit in place to ensure the integrity of our system as well as prevent a single project from monopolizing the available resources for other projects. Getting a 429 response code from our GDPR API means that you have reached our rate limit. We currently have a rate limit of 1 request per second for GDPR APIs. We also limit the maximum number of outstanding scans for a single project to approximately 5 years.

GDPR data retrieval process works by dividing the job of extracting the events by the granularity of the day, getting the events belonging to each distinct\_id in the request for each day going back to the first day for which we have events in Mixpanel. Since user activity can go back several years, this means that even a single data retrieval request might require scans of many hundred days.

To maximize the throughput of data retrievals, we recommend sending the maximum number of distinct IDs per request, now at 2000, and then retrying with exponential backoff. Depending on the amount of data that needs to be scanned, retrying for several hours might sometimes be necessary.

Example Return:<br />`{"status":"ok","results":[{"status":"PENDING", "disclosure_type":"DATA", "date_requested":"2020-03-09T22:28:55.078315", "tracking_id":"1583792934719392965",  "project_id":1978118, "compliance_type":"ccpa", "destination_url":null, "requesting_user":"pat.davis@mixpanel.com", "distinct_id_count":1}]}`

#### Check Status of Retrieval

Request Type: GET

Description: Checks the status of a data retrieval job.

Endpoint: `https://mixpanel.com/api/app/data-retrievals/v3.0/<tracking_id>?token=<your_project_token>`

Return Format:<br />`200 OK {
    "results": {
         "status":  oneOf [
                         "PENDING",
                         "STAGING",
                         "STARTED",
                         "SUCCESS",
                         "FAILURE",
                         "REVOKED",
                         "NOT_FOUND",
                         "UNKNOWN",
          ],
     }
}`

Return Key:

| Name       | Type   | Description                                                                                           |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------- |
| PENDING    | String | Task ID returned from POST.                                                                           |
| STAGING    | String | The staging process of the retrieval task has started. The task can still be canceled during staging. |
| STARTED    | String | The retrieval task has started, and cannot be canceled.                                               |
| SUCCESS    | String | The retrieval task is complete.                                                                       |
| FAILURE    | String | The retrieval task has failed. Check the original task input parameters and create a new task.        |
| REVOKED    | String | The retrieval task has been canceled through a DELETE operation.                                      |
| NOT\_FOUND | String | The retrieval task cannot be found.                                                                   |
| UNKNOWN    | String | An error occurred while locating the retrieval task.                                                  |

Parameters:

| Parameter | Parameter Type              | Type                   | Description                                                                                        |
| --------- | --------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| Token     | URL. Passed in request URL. | Query String Parameter | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens). |
| Task ID   | URL. Passed in request URL. | Query String Parameter | The tracking ID shown in the response.                                                             |

Authorization:

| Authorization Type | Pass As                           | Description                                                                                    |
| ------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------- |
| Bearer             | Body. Passed in JSON blob format. | Your [OAuth token](/docs/privacy/end-user-data-management#generate-oauth-token) for GDPR APIs. |

Example Request:<br />`curl "https://mixpanel.com/api/app/data-retrievals/v3.0/1583958896131033662/?token=591b3354bb2bdd96f72f23bf56911673"
-H "Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc"`

Example Return:<br />`{"status": "ok", "results": {"status": "PENDING", "result": "", "distinct_ids": ["1"]}}`

#### Create a Deletion Task

Request Type: POST

Description: Creates a task that specifies a list of users in a particular project to delete. This will schedule a deletion job that will delete all data, including events and user profile data, for the users specified by distinct\_ids. This deletion job may be canceled until it reaches the STARTED stage. It may take up to 30 days to complete a deletion task in a customer’s Mixpanel database. Mixpanel may retain records of deletion tasks for legal compliance purposes or for a short time based on our legitimate interest in providing a service continuity.

Endpoint: `https://mixpanel.com/api/app/data-deletions/v3.0/?token=<your_project_token>`

Parameters:

| Parameter        | Parameter Type                    | Type                   | Description                                                                                                                |
| ---------------- | --------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Token            | URL. Passed in request URL.       | Query String Parameter | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).                         |
| distinct\_ids    | Body. Passed in JSON blob format. | Array of strings       | A list of distinct IDs associated with the users whose data you would like to export. You can add up to 1999 distinct IDs. |
| compliance\_type | Body. Passed in JSON blob format. | String                 | Select CCPA or GDPR. Default is GDPR.                                                                                      |

Authorization:

| Authorization Type | Pass As                           | Description                                                                                    |
| ------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------- |
| Bearer             | Body. Passed in JSON blob format. | Your [OAuth token](/docs/privacy/end-user-data-management#generate-oauth-token) for GDPR APIs. |

Example Request:<br />`curl "https://mixpanel.com/api/app/data-deletions/v3.0/?token=591b3354bb2bdd96f72f23bf56911673"
-H "Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc" -d '{"compliance_type":"CCPA", "distinct_ids":["1"]}'`

Example Return:<br />`{"status":"ok","results":[{"status":"PENDING", "disclosure_type":"DATA", "date_requested":"2020-03-09T22:28:55.078315", "tracking_id":"1583792934719392965",  "project_id":1978118, "compliance_type":"ccpa", "destination_url":null, "requesting_user":"pat.davis@mixpanel.com", "distinct_id_count":1}]}`

#### Check Status of a Deletion Task

Request Type: **GET**

Description: Checks the status of an existing deletion task.

Endpoint: `https://mixpanel.com/api/app/data-deletions/v3.0/<tracking_id>?token=<your_project_token>`

Return Format:<br />` "results": {
         "status":
//You will get one of the following returns
oneOf [
                         "PENDING",
                         "STAGING",
                         "STARTED",
                         "SUCCESS",
                         "FAILURE",
                         "REVOKED",
                         "NOT_FOUND",
                         "UNKNOWN",
          ],
     }
}`

Return Key:

| Name       | Type   | Description                                                                                          |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------- |
| PENDING    | String | Task ID returned from POST.                                                                          |
| STAGING    | String | The staging process of the deletion task has started. The task can still be canceled during staging. |
| STARTED    | String | The deletion task has started, and cannot be canceled.                                               |
| SUCCESS    | String | The deletion task is complete.                                                                       |
| FAILURE    | String | The deletion task has failed. Check the original task input parameters and create a new task.        |
| REVOKED    | String | The deletion task has been canceled through a DELETE operation.                                      |
| NOT\_FOUND | String | The deletion task cannot be found.                                                                   |
| UNKNOWN    | String | An error occurred while locating the deletion task.                                                  |

Parameters:

| Parameter | Parameter Type              | Type                   | Description                                                                                        |
| --------- | --------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| Token     | URL. Passed in request URL. | Query String Parameter | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens). |
| Task ID   | URL. Passed in request URL. | Query String Parameter | The tracking ID shown in the response.                                                             |

Authorization:

| Authorization Type | Pass As                           | Description                                                                                    |
| ------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------- |
| Bearer             | Body. Passed in JSON blob format. | Your [OAuth token](/docs/privacy/end-user-data-management#generate-oauth-token) for GDPR APIs. |

Example Request:<br />`curl "https://mixpanel.com/api/app/data-deletions/v3.0/35bd8477-f71f-4088-af55-c88a6fb4ad4b/?token=591b3354bb2bdd96f72f23bf56911674" -H "Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc"`

Example Return:<br />`{"status": "ok", "results": {"status": "PENDING", "result": "", "distinct_ids": ["1"]}}`

#### Cancel Deletion

Request Type: **DELETE**

Description: Cancels an existing deletion task. Deletion jobs can be canceled until the STARTED stage initiates.

Endpoint: `https://mixpanel.com/api/app/data-deletions/v3.0/?token=<your_project_token>`

Return Format: `204 NoContent` or `405 MethodNotAllowed`

Return Key:

| Name                 | Type                              | Description                                                                                        |
| -------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------- |
| 204 NoContent        | Query String Parameter `required` | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens). |
| 405 MethodNotAllowed | Query String Parameter `required` | Task ID returned from POST.                                                                        |

Parameters:

| Parameter     | Parameter Type                    | Type                   | Description                                                                                                                |
| ------------- | --------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Token         | URL. Passed in request URL.       | Query String Parameter | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).                         |
| distinct\_ids | Body. Passed in JSON blob format. | Array of strings       | A list of distinct IDs associated with the users whose data you would like to export. You can add up to 1999 distinct IDs. |

Authorization:

| Authorization Type | Pass As                           | Description                                                                                    |
| ------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------- |
| Bearer             | Body. Passed in JSON blob format. | Your [OAuth token](/docs/privacy/end-user-data-management#generate-oauth-token) for GDPR APIs. |

Example Request:<br />`curl "https://mixpanel.com/api/app/data-deletions/v3.0/?token=591b3354bb2bdd96f72f23bf56911673"
-H "Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc" -d '{"distinct_ids":["1"]}'`

Example Return:<br />`{"status": "ok", "results": {"task_id": "35bd8477-f71f-4088-af55-c88a6fb4ad4a"}}`


# Get Annotation
Source: https://docs.mixpanel.com/reference/get-annotation-1

openapi/annotations.openapi.yaml GET /projects/{projectId}/annotations/{annotationId}
Get an Annotation



# Get Annotation Tags
Source: https://docs.mixpanel.com/reference/get-annotation-tags-1

openapi/annotations.openapi.yaml GET /projects/{projectId}/annotations/tags
Get all tags that have been added to at least one annotation. Requires a role of at least Analyst



# Check Status of Deletion
Source: https://docs.mixpanel.com/reference/get-deletion

openapi/gdpr.openapi.yaml GET /data-deletions/v3.0/{tracking_id}
Checks the status of an existing deletion task



# Get Experiment
Source: https://docs.mixpanel.com/reference/get-experiment

openapi/experiments.openapi.yaml GET /workspaces/{workspace_id}/experiments/{experiment_id}



# Get Feature Flag
Source: https://docs.mixpanel.com/reference/get-feature-flag-1

openapi/feature-flags-management.openapi.yaml GET /projects/{project_id}/workspaces/{workspace_id}/feature-flags/{flag_id}



# Get Flag Definitions
Source: https://docs.mixpanel.com/reference/get-flag-definitions

openapi/feature-flags.openapi.yaml GET /flags/definitions
Retrieve all enabled feature flag definitions for the authenticated project. Returns complete flag metadata including rulesets, variants, and rollout configurations.

This endpoint returns the flag definitions for all enabled feature flags within a Mixpanel project.

This endpoint returns a set of the flag definitions that are currently provisioned within a Mixpanel project and are enabled. This is used in local evaluation by Mixpanel service side SDK's such as the Python SDK. Local evaluation polls for flag definitions according to provided configuration and assignment to a variant is implemented directly by the SDK without making a network request.


# Get Import History
Source: https://docs.mixpanel.com/reference/get-import-history

openapi/warehouse-connectors.openapi.yaml GET /projects/{projectId}/warehouse-sources/imports/{importId}/history
Returns the execution history for a warehouse import. Returns 30 most recent events.



# Check Status of Retrieval
Source: https://docs.mixpanel.com/reference/get-retrieval

openapi/gdpr.openapi.yaml GET /data-retrievals/v3.0/{tracking_id}
Checks the status of a data retrieval job



# Get Service Account
Source: https://docs.mixpanel.com/reference/get-service-account

openapi/service-accounts.openapi.yaml GET /organizations/{organizationId}/service-accounts/{serviceAccountId}
Return service account details by id



# Get Variant Assignments
Source: https://docs.mixpanel.com/reference/get-variant-assignments

openapi/feature-flags.openapi.yaml GET /flags
Evaluate all enabled feature flags for a user with the provided context. Returns selected variants for flags the user is eligible for.

This endpoint returns the variant assignments for enabled flags within a Mixpanel project.

This endpoint returns a map from all feature flags that are provisioned within a Mixpanel project to the variant that the current user context is assigned to.


# Get Warehouse Import
Source: https://docs.mixpanel.com/reference/get-warehouse-import

openapi/warehouse-connectors.openapi.yaml GET /projects/{projectId}/warehouse-sources/imports/{importId}
Retrieves detailed information about a specific warehouse import by ID.
Returns the full configuration of the import including table parameters,
column mappings, and sync settings.



# Get Pipeline
Source: https://docs.mixpanel.com/reference/get-warehouse-pipeline-status

openapi/data-pipelines.openapi.yaml GET /nessie/pipeline/status

Given the name of the pipeline this API returns the status of the pipeline. It returns the summary and status of all the recent run export jobs for the pipeline.

**Example Response:** Status with no Summary and a Filter

```sh theme={"system"}
curl https://data.mixpanel.com/api/2.0/nessie/pipeline/status \
  -u API_SECRET: \
  -d name="YOUR_PIPELINE_NAME" \
  -d status="running"
```

**Example Response:** Status with no Summary and a Filter

```json theme={"system"}
{
  "canceled": [
    {
      "name": "company-july-2016-backfill-hourly-monoschema",
      "state": "canceled",
      "last_finish": "0000-12-31T16:00:00-08:00",
      "run_at": "2016-07-26T00:00:00-07:00",
      "from_date": "2016-07-26T00:00:00-07:00",
      "to_date": "2016-07-26T00:00:00-07:00"
    },
  ]
}
```


# Batch Update Group Profiles
Source: https://docs.mixpanel.com/reference/group-batch-update

openapi/ingestion.openapi.yaml POST /groups#group-batch-update
Send a batch of group profile updates. Instead of sending a single JSON object as the data query parameter, send a JSON list of objects as the data parameter of an application/x-www-form-urlencoded POST or GET request body.

Refer to the respective group profile update commands (\$set, \$set_once, \$add, \$union, \$remove, \$unset, and \$delete) on syntax for their parameters.

Send a batch of group profile updates. Instead of sending a single JSON object as the data query parameter, send a JSON list of objects as the data parameter of an application/x-www-form-urlencoded POST or GET request body.

Refer to the respective group profile update commands (\$set, \$set\_once, \$add, \$union, \$remove, \$unset, and \$delete) on syntax for their parameters.


# Delete Group Profile Property
Source: https://docs.mixpanel.com/reference/group-delete-property

openapi/ingestion.openapi.yaml POST /groups#group-unset
Unsets specific properties on the group profile.



# Remove from Group Profile List Property
Source: https://docs.mixpanel.com/reference/group-remove-from-list-property

openapi/ingestion.openapi.yaml POST /groups#group-remove-from-list
Removes a specific value in a list property.



# Update Group Profile Property
Source: https://docs.mixpanel.com/reference/group-set-property

openapi/ingestion.openapi.yaml POST /groups#group-set
Updates or adds properties to a group profile. The profile is created if it does not exist.



# Set Group Profile Property Once
Source: https://docs.mixpanel.com/reference/group-set-property-once

openapi/ingestion.openapi.yaml POST /groups#group-set-once
Adds properties to a group only if the property is not already set. The profile is created if it does not exist.



# Union to Group Profile List Property
Source: https://docs.mixpanel.com/reference/group-union

openapi/ingestion.openapi.yaml POST /groups#group-union
Adds the specified values to a list property on a group profile and ensures that those values only appear once. The profile is created if it does not exist.



# Create Alias
Source: https://docs.mixpanel.com/reference/identity-create-alias

openapi/identity.openapi.yaml POST /track#identity-create-alias

<Note>
  The `$create_alias` event payload is only useful for projects using the Original ID Merge system and the Legacy ID Management System; it has no functionality in the Simplified ID Merge system. Please review [this section of our documentation](/docs/tracking-methods/id-management#identity-merge-apis) for more information.
</Note>

<Note>
  You can also use the import endpoint: [https://api.mixpanel.com/import/](https://api.mixpanel.com/import/)
</Note>

Mixpanel supports adding an alias to a distinct id. An alias is a new value that will be interpreted by Mixpanel as an existing value. That means that you can send messages to Mixpanel using the new value, and Mixpanel will continue to use the old value for calculating funnels and retention reports, or applying updates to user profiles.

**Alias Criteria:**

<Frame>
  <img alt="960" />
</Frame>

**Required [Event Object](/docs/data-structure/concepts#anatomy-of-an-event) attributes**

<table>
  <thead>
    <tr>
      <th>Event Object property</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**event**</td>

      <td>
        <span>String</span><br /><span>required</span>
      </td>

      <td>value must be: <br />`$create_alias`</td>
    </tr>

    <tr>
      <td>**properties**</td>

      <td>
        <span>Object</span><br /><span>required</span>
      </td>

      <td />
    </tr>

    <tr>
      <td>**properties.distinct\_id**</td>

      <td>
        <span>String</span><br /><span>required</span>
      </td>

      <td>A distinct\_id to be merged with the alias.</td>
    </tr>

    <tr>
      <td>**properties.alias**</td>

      <td>
        <span>String</span><br /><span>required</span>
      </td>

      <td>A new distinct\_id to be merged with the original distinct\_id. Each alias can only map to one distinct\_id.</td>
    </tr>

    <tr>
      <td>**properties.token**</td>

      <td>
        <span>String</span><br /><span>required</span>
      </td>

      <td>The project token.</td>
    </tr>
  </tbody>
</table>


# Merge Identities
Source: https://docs.mixpanel.com/reference/identity-merge

openapi/identity.openapi.yaml POST /import

<Note>
  The `$merge` event payload is only useful for projects using the Original ID Merge system; it has no functionality in other ID management systems. Please review [this section of our documentation](/docs/tracking-methods/id-management#identity-merge-apis) for more information.
</Note>

<Warning>
  **Merging identities is irreversible**

  `$merge` is a very powerful tool, so we will only accept `$merge` events that are sent via `https://api.mixpanel.com/import`, which is protected by the project api secret. You **cannot** unmerge `distinct_id`.
</Warning>

**Merge Criteria:**

<Frame>
  <img alt="960" />
</Frame>


# Import Events
Source: https://docs.mixpanel.com/reference/import-events

openapi/ingestion.openapi.yaml POST /import

Use this API to send batches of events from your servers to Mixpanel.

## Request Format

Each request ingests a batch of events into Mixpanel. We accept up to 2000 events and 10MB uncompressed per request. Events are part of the request body.

We support Content-Type `application/json` or `application/x-ndjson`:

<CodeGroup>
  ```json JSON theme={"system"}
  [
    {"event": "Signup", "properties": {"time": 1618716477000,"distinct_id": "91304156-cafc-4673-a237-623d1129c801","$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4","Referred by": "Friend","URL": "mixpanel.com/signup"}},
    {"event": "Purchase", "properties": {"time": 1618716477000,"distinct_id": "91304156-cafc-4673-a237-623d1129c801","$insert_id": "935d87b1-00cd-41b7-be34-b9d98dd08b42","Item": "Coffee", "Amount": 5.0}}
  ]
  ```

  ```json ndJSON theme={"system"}
  {"event": "Signup", "properties": {"time": 1618716477000,"distinct_id": "91304156-cafc-4673-a237-623d1129c801","$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4","Referred by": "Friend","URL": "mixpanel.com/signup"}}
  {"event": "Purchase", "properties": {"time": 1618716477000,"distinct_id": "91304156-cafc-4673-a237-623d1129c801","$insert_id": "935d87b1-00cd-41b7-be34-b9d98dd08b42","Item": "Coffee", "Amount": 5.0}}
  ```
</CodeGroup>

We also support `Content-Encoding: gzip` to reduce network egress.

## Authentication

`/import` requires an Owner or Admin [Service Account](/reference/service-accounts). project\_id, service account username, and service account password are required to authenticate a request.

`/import` also supports [Project Token](/reference/project-token) as an authentication method. You can provide your token as the basic auth username value with an empty password. If project\_id is not specified, the request will be authenticated using the provided token.

## Validation

If you provide the `strict=1` parameter (recommended), `/import` will validate the supplied events and return a 400 status code if **any** of the events fail validation with details of the error. If some events pass validation and others fail, Mixpanel will ingest the events that pass validation. When you encounter a 400 error in production, simply log the JSON response, as it will contain the `$insert_id`s of the invalid events, which can be used to debug.

### High-level requirements

* Each event must be properly formatted JSON.
* Each event must contain an event name, time, distinct\_id, and \$insert\_id. These are used to deduplicate events so that this endpoint can be safely retried.
* Each event must be smaller than 1MB of uncompressed JSON.
* Each event must have fewer than 255 properties.
* All nested object properties must have fewer than 255 keys and a max nesting depth is 3.
* All array properties must have fewer than 255 elements.

### Example of an event

```json JSON theme={"system"}
{
  "event": "Signed up",
  "properties": {
    "time": 1618716477000,
    "distinct_id": "91304156-cafc-4673-a237-623d1129c801",
    "$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4",
    "ip": "136.24.0.114",
    "Referred by": "Friend",
    "URL": "mixpanel.com/signup",
  }
}
```

#### event

This is the name of the event. If you're loading data from a data warehouse, we recommend using the name of the table as the name of the event.

We recommend keeping the number of unique event names relatively small and using properties for any variable context attached to the event. For example, instead of tracking events with names "Paid Signup" and "Free Signup", we would recommend tracking an event called "Signup" and having a property "Account Type" with the value "paid" or "free".

#### properties

This is a JSON object representing all the properties about the event. If you're loading data from a data warehouse, we recommend using column names as the names of properties.

##### properties.time

The time at which the event occurred, in seconds or milliseconds since epoch. We require a value for time. We will reject events with time values that are before 1971-01-01 or more than 1 hour in the future as measured on our servers.

If the time value is set in the future, it will be overwritten with the current present time at ingestion.

##### properties.distinct\_id

`distinct_id` identifies the user who performed the event. distinct\_id must be specified on every event, as it is crucial for Mixpanel to perform behavioral analysis (unique users, funnels, retention, cohorts) correctly and efficiently.

If the event is not associated with any user, set distinct\_id to the empty string. Events with an empty distinct\_id will be excluded from all behavioral analysis.

If no distinct\_id is provided, Mixpanel will use the ip address of the incoming request and compute a distinct\_id using a hash function.

To prevent accidental implementation mistakes, we disallow the following values for distinct\_id:

```text theme={"system"}
- 00000000-0000-0000-0000-000000000000
- anon
- anonymous
- nil
- none
- null
- n/a
- na
- undefined
- unknown
- <nil>
- 0
- -1
- true
- false
- []
- {}
```

##### properties.\$insert\_id

We require that \$insert\_id be specified on every event. \$insert\_id provides a unique identifier for the event, which we use for deduplication. Events with identical values for (event, time, distinct\_id, \$insert\_id) are considered duplicates and only one of them will be surfaced in queries.

\$insert\_ids must be ≤ 36 bytes and contain only alphanumeric characters or "-". We also disallow any value for \$insert\_id from the list of invalid IDs provided for distinct\_id above.

### Example of a validation error

```json JSON theme={"system"}
{
  "code": 400,
  "error": "some data points in the request failed validation",
  "failed_records": [
    {
      "index": 0,
      "$insert_id": "8a66058c-a56d-4ef6-8123-28b7c9f7e82f",
      "field": "properties.time",
      "message": "properties.time' is invalid: must be specified as seconds since epoch"
    },
    {
      "index": 3,
      "$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4",
      "field": "properties.utm_source",
      "message": "properties.utm_source is invalid: string should be valid utf8"
    },
  ],
  "num_records_imported": 23,
  "status": "Bad Request"
}
```

When any single event in the batch does not pass validation, we return a 400 status code and a response that looks like the above.

`failed_records` includes one row for each of the failed events, with details about the error we found. If some of the rows passed validation, we will ingest them and return their count in `num_records_imported`.

## GeoIP Enrichment

If you supply a property `ip` with an IP address, Mixpanel will automatically do a GeoIP lookup and replace the `ip` property with geographic properties (City, Country, Region). These properties can be used in our UI to segment events geographically.

If you do not supply an `ip` property in your event payload, the IP address of the request will be used to parse for geolocation. You can set manually set the value of `ip` to `0` and our API will skip the geolocation parsing for that event.

This is an example of an event before and after enrichment:

<CodeGroup>
  ```json Pre-Enrichment theme={"system"}
  {
    "event": "Signed up",
    "properties": {
      "time": 1618716477000,
      "distinct_id": "91304156-cafc-4673-a237-623d1129c801",
      "$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4",
      "ip": "136.24.0.114",
      "Referred by": "Friend",
      "URL": "mixpanel.com/signup",
    }
  }
  ```

  ```json Post-Enrichment theme={"system"}
  {
    "event": "Signed up",
    "properties": {
      "time": 1618716477000,
      "distinct_id": "91304156-cafc-4673-a237-623d1129c801",
      "$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4",
      "Referred by": "Friend",
      "URL": "mixpanel.com/signup",
      "$city": "San Francisco",
      "$region": "California",
      "mp_country_code": "US"
    }
  }
  ```
</CodeGroup>

## Rate Limit

To ensure real-time ingestion and quality-of-service, we have a rate limit of 2GB of uncompressed JSON/minute or \~30k events per second, measured on a rolling 1 minute basis.

We recommend the following when it comes to sending data to our API at scale:

* Send data as quickly as possible with concurrent clients until the server returns 429. We see the best results with 10-20 concurrent clients sending 2K events per batch.
* When you see 429s, employ an [exponential backoff with jitter](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) strategy. We recommend starting with a backoff of 2s and doubling backoff until 60s, with 1-5s of jitter.
* We recommend gzip compression and using `Content-Encoding: gzip` to reduce network egress and transfer time.
* In the rare event that our API returns a 502 or 503 status code, we recommend employing the same exponential backoff strategy as with 429s.
* Please do not retry validation errors (400 status code), as they will consistently fail and count toward the rate limit.

If you are an enterprise customer and require a higher limit for a 1-time backfill, please reach out to your sales representative with your project\_id and use-case.

## Common Issues

`$insert_id` is required on all events. This makes it safe to retry `/import` requests. If your events don't already have a unique ID (eg: a UUID/GUID), we recommend computing a hash of some set of properties that make the event semantically unique (eg: distinct\_id + timestamp + some other property) and using the first 36 characters of that hash as the \$insert\_id.

We truncate all strings down to 255 characters. Here's what we recommend for the various cases in which this typically happens:

* URLs: We recommend parsing the URL and tracking its individual components (host, path, url params) as properties. This is more useful in analysis, as you can segment events by hostname or a particular URL parameter.
* JSON encoded strings: Sometimes a long string may be a JSON object encoded as a string. We recommend parsing the JSON and flattening it into properties to send with the event. This is similarly much more useful in analysis, as you can filter or breakdown by any key within the JSON.
* Free text / user generated content: Some long fields may include full-text (eg: a search term or a comment). If this property isn't useful for analysis, we recommend excluding it from tracking to Mixpanel to avoid accidentally sending over any PII.

## Guides

See our Cloud Ingestion guides for example usage of this API to integrate with  [Google Pub/Sub](/docs/tracking-methods/integrations/google-pubsub), [Amazon S3](/docs/tracking-methods/integrations/amazon-s3), or [Google Cloud Storage](/docs/tracking-methods/integrations/google-cloud-storage).


# Overview
Source: https://docs.mixpanel.com/reference/ingestion-api



Mixpanel's Ingestion APIs allow you to send event or profile data to Mixpanel, which can be analyzed in our reporting interface.

If you're implementing client-side, we recommend using one of our SDKs. If you're implementing server-side, as part of a batch or streaming data pipeline, these APIs can be used as a low-level foundation to send data to Mixpanel.

See our [Client-Side vs Server-Side Tracking](/docs/getting-started/plan-your-implementation#need-to-start-tracking-product-data) guide for tradeoffs between the different integration approaches.

## Ingestion HTTP APIs

* [Events](/reference/import-events)
* [Identities](/reference/create-identity)
* [User Profiles](/reference/profile-set)
* [Group Profiles](/reference/group-set-property)
* [Lookup Tables](/reference/lookup-tables)


# Authentication
Source: https://docs.mixpanel.com/reference/ingestion-api-authentication



Most of our Ingestion API calls such as [Import Events](/reference/import-events), [Track Events](/reference/track-event), [User Profiles](/reference/profile-set), and [Group Profiles](/reference/group-set-property) only require a [Project Token](/reference/project-token). Because these APIs are often called from our client-side SDKs, we do not want to expose credentials, but we do need to know which project to send data to so we use the Project Token for that purpose. However, a few of the more powerful APIs such as [Lookup Tables](/reference/lookup-tables) **do require authentication**. For these, it's recommended to use a [Service Account](/reference/service-accounts). We also have legacy support for [Project Secret](/reference/project-secret) but suggest any new integrations use a Service Account.


# Query Saved Report
Source: https://docs.mixpanel.com/reference/insights-query

openapi/query.openapi.yaml GET /insights
Get data from your Insights reports. The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.



# Launch Experiment
Source: https://docs.mixpanel.com/reference/launch-experiment

openapi/experiments.openapi.yaml PUT /workspaces/{workspace_id}/experiments/{experiment_id}/launch



# Overview
Source: https://docs.mixpanel.com/reference/lexicon-schemas-api



Sync your internal data dictionary or tracking plan with Mixpanel using Schemas. A Schema is used to describe the data you are sending to Mixpanel and represents an individual entry into your data dictionary. Schemas that you upload will be used to populate Lexicon and provide additional context for your data across the query UI. A Schema represents a single entity (usually an event) and is defined with json-schema.

<Note>
  **Lexicon UI vs Lexicon Schemas API**

  The data returned from the Lexicon Schemas API is most likely *not* 1:1 with the data you see in Lexicon. This because **schemas are a subset of the data that appears in Lexicon**. The Lexicon UI shows you events & properties that either:

  1. have an associated schema **or**
  2. have been sent to your project in the last 30 days (sometimes the look-back period is shorter depending on your data volume).

  The Lexicon Schemas API only returns events with associated schemas. If an event that you see in Lexicon has no associated schema, it will not be returned by the Lexicon Schemas API. If a property on an event is not specified in the event schema, it will not be returned by the Lexicon Schemas API.
</Note>

<Note>
  **When is a Lexicon Schema created?**

  A schema is created and associated to an event in a few different ways:

  1. By uploading a schema through this API
  2. By importing Lexicon entries via CSV
  3. By adding metadata in the UI (such as adding a description, hiding/showing, adding tags, etc.)
</Note>

<Note>
  **How can I export all of my data from Lexicon?**

  As mentioned above, the Lexicon Schemas API is unlikely to return all of the data you see in Lexicon. If you want all of the data, you can do a CSV export from the Lexicon UI. The resulting CSV will contain events and properties that have associated schemas and events and properties that were sent in the last 30 days even if they do not have associated schemas.
</Note>

## Example

The following is an example of how an event can be described by a schema:

Event

```json theme={"system"}
{
      "event": "Added to Cart",
      "properties": {
          "item_name": "Blue Widget",
          "item_id": 12345,
          "item_price": 25.35
    }
}
```

Schema

```json theme={"system"}
{
    "$schema": "http://json-schema.org/draft-07/schema",
    "description": "Tracked when a user adds an item to their cart.",
    "required": [
        "item_name",
        "item_id",
        "item_price"
    ],
    "additionalProperties": true,
    "properties": {
        "item_name": {
            "type": "string",
            "description": "The name of the item",
            "examples": [
                "Blue Widget"
            ]
        },
        "item_id": {
            "type": "integer",
            "description": "The internal id of the item",
            "examples": [
                12345
            ]
        },
        "item_price": {
            "type": "number",
            "description": "The current price of the item",
            "examples": [
                25.35
            ]
        }
    }
}
```


# Authentication
Source: https://docs.mixpanel.com/reference/lexicon-schemas-api-authentication



## Service Account

<Note>
  **Roles & Permissions**

  To modify (create, edit, delete) a schema, the Service Account must have the role of admin or owner.
</Note>

[Service Account Authentication Details](/reference/service-accounts)

**Projects with[Classified Data](/docs/admin/data-governance/data-views-data-classification#data-classification)**

* The Service Account must have permission to access classified data.


# Limits
Source: https://docs.mixpanel.com/reference/limits



The Schemas API has the following limits:

* requests per organization per minute: 5
* events and properties updated per organization per minute: 4000
* total truncations/deletions per request: 3000

If you approach these limits, consider breaking your requests into smaller batches. These limits are typically reached when performing bulk create or update operations.


# Limits
Source: https://docs.mixpanel.com/reference/limits-1



The Groups Profile API imposes limits on the total number profile updates that can be sent per request to **2000** as well as limits each individual update in the request to a maximum of **1 MB**. If you are running up against these limits, we suggest breaking your request into smaller batches. Usually, these limits are only hit if you are attempting to do a bulk create/update.


# List Annotations
Source: https://docs.mixpanel.com/reference/list-all-annotations-for-project

openapi/annotations.openapi.yaml GET /projects/{projectId}/annotations
List all annotations in a project.



# List Schemas
Source: https://docs.mixpanel.com/reference/list-all-schemas-for-project

openapi/lexicon-schemas.openapi.yaml GET /projects/{projectId}/schemas
List all schemas in a project



# List Experiments
Source: https://docs.mixpanel.com/reference/list-experiments

openapi/experiments.openapi.yaml GET /workspaces/{workspace_id}/experiments



# List Feature Flags
Source: https://docs.mixpanel.com/reference/list-feature-flags-1

openapi/feature-flags-management.openapi.yaml GET /projects/{project_id}/workspaces/{workspace_id}/feature-flags



# List Lookup Tables
Source: https://docs.mixpanel.com/reference/list-lookup-tables

openapi/ingestion.openapi.yaml GET /lookup-tables
Get a list of Lookup Tables defined in the project.



# List Service Accounts For Project
Source: https://docs.mixpanel.com/reference/list-project-service-accounts

openapi/service-accounts.openapi.yaml GET /projects/{projectId}/service-accounts
Retrieve a list of service accounts that are members of the specified project



# Aggregate Event Counts
Source: https://docs.mixpanel.com/reference/list-recent-events

openapi/query.openapi.yaml GET /events
Get unique, total, or average data for a set of events over N days, weeks, or months.
The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.



# List for Entity and Name
Source: https://docs.mixpanel.com/reference/list-schemas-by-entity-and-name

openapi/lexicon-schemas.openapi.yaml GET /projects/{projectId}/schemas/{entityType}/{name}
Get the schema for a specific entity type and entity name



# List for Entity
Source: https://docs.mixpanel.com/reference/list-schemas-for-entity

openapi/lexicon-schemas.openapi.yaml GET /projects/{projectId}/schemas/{entityType}
Get all schemas for a specific entity type



# List Service Accounts
Source: https://docs.mixpanel.com/reference/list-service-accounts

openapi/service-accounts.openapi.yaml GET /organizations/{organizationId}/service-accounts
Return a list of all service accounts for your organization



# List Warehouse Imports
Source: https://docs.mixpanel.com/reference/list-warehouse-imports

openapi/warehouse-connectors.openapi.yaml GET /projects/{projectId}/warehouse-sources/imports
Returns a list of all warehouse imports configured for the project.
Each import includes metadata about the import configuration, sync status,
and job scheduling information. 



# List Pipelines
Source: https://docs.mixpanel.com/reference/list-warehouse-pipeline-jobs

openapi/data-pipelines.openapi.yaml GET /nessie/pipeline/jobs
This API endpoint returns the list of all the pipelines scheduled for a project.



# List Pipeline Logs
Source: https://docs.mixpanel.com/reference/list-warehouse-pipeline-sync-dates

openapi/data-pipelines.openapi.yaml GET /nessie/pipeline/timeline
This endpoint returns the timestamps of all syncs grouped by date.



# Lookup Tables
Source: https://docs.mixpanel.com/reference/lookup-tables



Lookup Tables are mutable tables that describe non-user entities like accounts, product SKUs, or geographies. These tables can be used to enrich events at query-time. In star schema terms: events are like facts and Lookup Tables are like dimensions.

Lookup Tables are [created via the Mixpanel UI](https://help.mixpanel.com/hc/en-us/articles/360044139291-Lookup-tables#stepbystep-guide). This API supports replacing the contents of an existing Lookup Table, which can be used to keep Mixpanel in sync with a source-of-truth system.

These APIs use [Service Accounts](/reference/service-accounts) for authentication.


# Overview
Source: https://docs.mixpanel.com/reference/overview



Mixpanel supports API endpoints that can query, export, and import data as well as manipulate Mixpanel metadata (such as data definitions).

The API endpoints are organized by the function that they support. The API structure is as follows:

### [**Ingestion API**](/reference/ingestion-api)

**Standard Server:** `api.mixpanel.com` **EU Residency Server:** `api-eu.mixpanel.com` **India Residency Server:** `api-in.mixpanel.com` Use the Ingestion API to get your data into Mixpanel. This includes live events, historical imports, and user profile data.

<Warning>
  To ensure data ingests into your project, use the correct Ingestion API subdomain for your project's data residency. For more information, you can learn more about: [EU Residency](/docs/privacy/eu-residency) and [IN Residency](/docs/privacy/in-residency).
</Warning>

### [**Query API**](/reference/query-api)

**Standard Server:** `mixpanel.com/api` **EU Residency Server:** `eu.mixpanel.com/api` **India Residency Server:** `in.mixpanel.com/api` Use the Query API to get the same calculated data that powers Mixpanel's web application. This includes Insights, Funnels, Retention, and custom JQL Queries.

### [**Raw Data Export API**](/reference/raw-data-export-api)

**Standard Server:** `data.mixpanel.com/api/2.0/export` **EU Residency Server:** `data-eu.mixpanel.com/api/2.0/export` **India Residency Server:** `data-in.mixpanel.com/api/2.0/export` Use the Raw Data Export API endpoint to obtain your event data. This API supports direct download or uploading to a cloud bucket.

### [**Data Pipelines API**](/reference/overview-2)

**Standard Server:** `data.mixpanel.com/api/2.0/nessie` **EU Residency Server:** `data-eu.mixpanel.com/api/2.0/nessie` **India Residency Server:** `data-in.mixpanel.com/api/2.0/nessie` Use the Data Pipelines API to export Mixpanel data to your own Data Warehouse. Mixpanel’s Data Pipelines product removes the need to build complex connectors, maintain exporting code, and apply ad-hoc data transformations.

### [**Lexicon Schemas API**](/reference/lexicon-schemas-api)

**Standard Server:** `mixpanel.com/api/app/projects` **EU Residency Server:** `eu.mixpanel.com/api/app/projects` **India Residency Server:** `in.mixpanel.com/api/app/projects` Use the Schemas API to manage your data definitions in Lexicon and Data Audit

### [**GDPR API**](/reference/gdpr-api)

**Standard Server:** `mixpanel.com/api/app/data-retrievals` **EU Residency Server:** `eu.mixpanel.com/api/app/data-retrievals` **India Residency Server:** `in.mixpanel.com/api/app/data-retrievals` The retrieval and deletion API calls are updated for version 3 and are made for GDPR and CCPA compliance.

### [**Warehouse Connectors API**](/reference/warehouse-connectors-api)

**Standard Server:** `mixpanel.com/api/app/projects` **EU Residency Server:** `eu.mixpanel.com/api/app/projects` **India Residency Server:** `in.mixpanel.com/api/app/projects` Use the Warehouse Connectors API to manually run a warehouse imports.

### [**Feature Flags API**](/reference/feature-flags-api)

**Standard Server:** `api.mixpanel.com/flags` **EU Residency Server:** `api-eu.mixpanel.com/flags` **India Residency Server:** `api-in.mixpanel.com/flags` Use the Feature Flags API to assign your users to variants for experiments, rollout, and releases.

<Warning>
  **TLS 1.0 and 1.1 Deprecation:** Starting April 2026, Mixpanel APIs will no longer accept connections using TLS 1.0 and 1.1 protocols. Please ensure your integrations are configured to use TLS 1.2 or higher. For more details, see the [TLS Deprecation Notice](/changelogs#2026-02-26).
</Warning>


# Overview
Source: https://docs.mixpanel.com/reference/overview-1



The Annotations API lets you manage your annotations programmatically. Annotations are text descriptions tied to a time that will show up in reports such as Insights to let users know something meaningful occurred at that time. You can use this API to get a list of your project's annotations, edit them, create them or delete them.

<Note>
  **Roles & Permissions**

  To modify annotations (create, delete, or edit), you or the Service Account being used must have the role of at least Analyst.
</Note>


# Overview
Source: https://docs.mixpanel.com/reference/overview-2



<Note>
  **Deprecated Version**

  This version of managing pipelines via API is Deprecated going forward. For the customers who earlier used these apis to create and manage can continue using it. Otherwise Go to Integrations page in mixpanel to create and manage pipelines via UI.
</Note>

These APIs help you manage Data Pipelines in Mixpanel. Learn more about our Data Pipelines add-on [here](/docs/data-pipelines)


# Patch Annotation
Source: https://docs.mixpanel.com/reference/patch-annotation-1

openapi/annotations.openapi.yaml PATCH /projects/{projectId}/annotations/{annotationId}
Patch an Annotation. Requires a role of at least Analyst.



# Pause Pipeline
Source: https://docs.mixpanel.com/reference/pause-warehouse-pipeline

openapi/data-pipelines.openapi.yaml POST /nessie/pipeline/pause
For a given pipeline name, this request pauses the pipeline which stops the ongoing jobs and prevents any future jobs to be scheduled for the pipeline



# Append to List Property
Source: https://docs.mixpanel.com/reference/profile-append-to-list-property

openapi/ingestion.openapi.yaml POST /engage#profile-list-append
Takes a JSON object containing keys and values, and appends each to a list associated with the corresponding property name. Appending to a property that doesn't exist will result in assigning a list with one element to that property.



# Update Multiple Profiles
Source: https://docs.mixpanel.com/reference/profile-batch-update

openapi/ingestion.openapi.yaml POST /engage#profile-batch-update
Send a batch of profile updates. Instead of sending a single JSON object as the data query parameter, send a JSON list of objects as the data parameter of an application/json POST or GET request body.

Refer to the respective user profile update commands (\$set, \$set_once, \$add, \$union, \$append, \$remove, \$unset, and \$delete) on syntax for their parameters.

<Note>
  This API will return a 200 OK even if there are data validation issues. To ensure the request actually succeeded, you need to check the response body.
</Note>


# Delete User Profile Property
Source: https://docs.mixpanel.com/reference/profile-delete-property

openapi/ingestion.openapi.yaml POST /engage#profile-unset
Takes a JSON list of string property names, and permanently removes the properties and their values from a profile.



# Increment Numerical Property
Source: https://docs.mixpanel.com/reference/profile-numerical-add

openapi/ingestion.openapi.yaml POST /engage#profile-numerical-add
Takes a JSON object containing keys and numerical values. \$add will increment the value of a user profile property. When processed, the property values are added to the existing values of the properties on the profile. If the property is not present on the profile, the value will be added to 0. It is possible to decrement by calling "\$add" with negative values. This is useful for maintaining the values of properties like "Number of Logins" or "Files Uploaded".



# Remove from User Profile List Property
Source: https://docs.mixpanel.com/reference/profile-remove-from-list-property

openapi/ingestion.openapi.yaml POST /engage#profile-list-remove
Takes a JSON object containing keys and values. The value in the request is removed from the existing list on the user profile. If it does not exist, no updates are made.



# Set User Profile Property
Source: https://docs.mixpanel.com/reference/profile-set

openapi/ingestion.openapi.yaml POST /engage#profile-set
Takes a JSON object containing names and values of profile properties. If the profile does not exist, it creates it with these properties. If it does exist, it sets the properties to these values, overwriting existing values.

<Note>
  This API will return a `200 OK` even if there are data validation issues. To ensure the request actually succeeded, you need to check the response body.
</Note>

<Note>
  This API does not support gzip encoding.
</Note>


# Set User Profile Property Once
Source: https://docs.mixpanel.com/reference/profile-set-property-once

openapi/ingestion.openapi.yaml POST /engage#profile-set-once
Works just like "$set", except it will not overwrite existing property values. This is useful for properties like "First login date".

Works just like "\$set", except it will not overwrite existing property values. This is useful for properties like "First login date".


# Project Secret [Deprecated]
Source: https://docs.mixpanel.com/reference/project-secret



<Warning>
  **Deprecation Warning**

  This authentication method has been deprecated and will be fully retired on **March 3, 2027**. Please migrate to [Service Accounts](/reference/service-accounts-api) instead, as they are the recommended authentication mechanism going forward.
</Warning>

Before we introduced Service Accounts, Project Secret was the standard authentication mechanism for importing and exporting data in your project.

Your Project Secret is very powerful so be sure to keep it secure. Do not share your secret in publicly accessible or insecure places such as source code or plain-text configs.

## Authenticating with a Project Secret

Project secret authentication is performed via [HTTP Basic Auth](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme). Provide your secret as the basic auth username value with an empty password. Make sure you use HTTPS and not HTTP - our API rejects requests made over HTTP since this sends your API Secret over the internet in plain text.

```sh theme={"system"}
curl https://api.mixpanel.com/import
    -u <api_secret>: \\ # trailing colon prevents a password prompt
    -d data=<encoded_event_data>
```

## Managing a Project's Secret

A project's secret can be found in the Access Keys section of a project's settings overview page: [https://mixpanel.com/settings/project/](https://mixpanel.com/settings/project/).

To learn more, view our [project settings guide](https://help.mixpanel.com/hc/en-us/articles/115004490503-Project-Settings).


# Project Token
Source: https://docs.mixpanel.com/reference/project-token



Every Mixpanel project has a unique alphanumerical token for collecting data. A project's token is not a secret value. In front-end implementation, such as our javascript library, this token will be available to anyone visiting your page.

With that in mind, it is important to note that a project's token is not a form of authorization. It is an identification sent along with each piece of data you send to your project.

## Sending data with a Project Token

For [Track Events](/reference/track-event), tokens are provided as values inside of the data sent to Mixpanel. Where this value is stored is dependent on the API endpoint used. Information on the specific location can be found in the Ingestion API's specification.

<CodeGroup>
  ```json Event Data theme={"system"}
  {
      "event": "Signup",
      "properties": {
        	"$distinct_id": "1234",
          "token": "projecttoken",
      }
  }
  ```

  ```json Profile Data theme={"system"}
  {
      "$token": "projecttoken",
      "$distinct_id": "1234",
      "$set": {
          "Favorite Show": "The Office"
      }
  }
  ```
</CodeGroup>

If you are are using our SDKs you will notice that that the project token is required when initializing the library. This token will automatically be included in the data sent out from that instance.

<CodeGroup>
  ```javascript Javascript wrap theme={"system"}
  <!-- start Mixpanel --><script type="text/javascript">(function(c,a){if(!a.__SV){var b=window;try{var d,m,j,k=b.location,f=k.hash;d=function(a,b){return(m=a.match(RegExp(b+"=([^&]*)")))?m[1]:null};f&&d(f,"state")&&(j=JSON.parse(decodeURIComponent(d(f,"state"))),"mpeditor"===j.action&&(b.sessionStorage.setItem("_mpcehash",f),history.replaceState(j.desiredHash||"",c.title,k.pathname+k.search)))}catch(n){}var l,h;window.mixpanel=a;a._i=[];a.init=function(b,d,g){function c(b,i){var a=i.split(".");2==a.length&&(b=b[a[0]],i=a[1]);b[i]=function(){b.push([i].concat(Array.prototype.slice.call(arguments,0)))}}var e=a;"undefined"!==typeof g?e=a[g]=[]:g="mixpanel";e.people=e.people||[];e.toString=function(b){var a="mixpanel";"mixpanel"!==g&&(a+="."+g);b||(a+=" (stub)");return a};e.people.toString=function(){return e.toString(1)+".people (stub)"};l="disable time_event track track_pageview track_links track_forms track_with_groups add_group set_group remove_group register register_once alias unregister identify name_tag set_config reset opt_in_tracking opt_out_tracking has_opted_in_tracking has_opted_out_tracking clear_opt_in_out_tracking people.set people.set_once people.unset people.increment people.append people.union people.track_charge people.clear_charges people.delete_user people.remove".split(" ");for(h=0;h<l.length;h++)c(e,l[h]);var f="set set_once union unset remove delete".split(" ");e.get_group=function(){function a(c){b[c]=function(){call2_args=arguments;call2=[c].concat(Array.prototype.slice.call(call2_args,0));e.push([d,call2])}}for(var b={},d=["get_group"].concat(Array.prototype.slice.call(arguments,0)),c=0;c<f.length;c++)a(f[c]);return b};a._i.push([b,d,g])};a.__SV=1.2;b=c.createElement("script");b.type="text/javascript";b.async=!0;b.src="undefined"!==typeof MIXPANEL_CUSTOM_LIB_URL?MIXPANEL_CUSTOM_LIB_URL:"file:"===c.location.protocol&&"//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js".match(/^\/\//)?"https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js":"//cdn.mxpnl.com/libs/mixpanel-2-latest.min.js";d=c.getElementsByTagName("script")[0];d.parentNode.insertBefore(b,d)}})(document,window.mixpanel||[]);
  mixpanel.init("projecttoken");
  </script>
  ```

  ```objectivec Objective-C theme={"system"}
  [Mixpanel sharedInstanceWithToken:@"projectoken"];
  ```

  ```swift Swift theme={"system"}
  Mixpanel.initialize(token: "projectoken")
  ```

  ```java Java theme={"system"}
  public static final String MIXPANEL_TOKEN = "projectoken";
  MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, MIXPANEL_TOKEN);
  ```

  ```python Python theme={"system"}
  from mixpanel import Mixpanel
  mp = Mixpanel("projectoken")
  ```
</CodeGroup>

For [Import Events](/reference/import-events), the token is provided in the header as the basic auth username value with an empty password.

```json Import Events theme={"system"}
--header 'authorization: Basic <base64 encoding of token without password>'
```

## Managing a Project's Token

A project's token can be found in the Access Keys section of a project's settings overview page: [https://mixpanel.com/settings/project/](https://mixpanel.com/settings/project/).

To learn more, view our [project settings guide](https://help.mixpanel.com/hc/en-us/articles/115004490503-Project-Settings).


# Overview
Source: https://docs.mixpanel.com/reference/query-api



The Query API allows you to obtain the same calculated and formatted results that you see from a report in our web app.

The query endpoints should serve as the starting point for exporting user information from Mixpanel. This is done through the /engage endpoint. See the Export section for information on exporting event data.

The Mixpanel Query API endpoints can:

* Filter or break down Events
* Return user profiles.
* Return an activity/event stream for a user.
* Return a cohort of users.
* And more!


# Authentication
Source: https://docs.mixpanel.com/reference/query-api-authentication



## Service Account

[Service Account Authentication Details](/reference/service-accounts)

<Check>
  This is the preferred authentication method for Query API.
</Check>

* Requests parameters must include a `project_id`.

**Projects with[Data Views](https://help.mixpanel.com/hc/en-us/articles/360043782572-Data-Views)**

* In addition to `project_id`, you should include the global data view's `workspace_id` as a request parameter.

**Projects with[Classified Data](https://help.mixpanel.com/hc/en-us/articles/360044295131-Data-Classification)**

* Your results may be filtered based on the Service Account's sensitivity settings.


# Aggregrated Event Property Values
Source: https://docs.mixpanel.com/reference/query-event-properties

openapi/query.openapi.yaml GET /events/properties
Get unique, total, or average data for of a single event and property over days, weeks, or months.
The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.



# Top Event Properties
Source: https://docs.mixpanel.com/reference/query-events-top-properties

openapi/query.openapi.yaml GET /events/properties/top
Get the top property names for an event. The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.



# Top Event Property Values
Source: https://docs.mixpanel.com/reference/query-events-top-property-values

openapi/query.openapi.yaml GET /events/properties/values
Get the top values for a property. The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.



# Custom JQL Query
Source: https://docs.mixpanel.com/reference/query-jql

openapi/query.openapi.yaml POST /jql

<Danger>
  JQL is currently in maintenance mode. We recommend discontinuing use of JQL and using an [alternate method](/docs/export-methods) to get the data you need. Below are alternatives for common use cases and you need help deciding the best method for you, reach out to [support](https://mixpanel.com/get-support).

  * Raw Event export: [Export API](/reference/raw-data-export-api) or [Data Pipelines](/docs/data-pipelines)
  * User Profile export: [Engage Query API](/reference/engage-query) or [Data Pipelines](/docs/data-pipelines)
  * Other reporting: [Query API](/reference/query-api) or in-app [Core Reports](/docs/reports)
</Danger>

The HTTP API is the lowest-level way to use JQL. At its core, the API is very simple: you write a script, and you post it to an API endpoint with some authentication parameters.

For longer scripts, you will likely want to keep the code in a file. If you had your script in a file called my\_query.js, you could run it using the following cURL command:

```sh theme={"system"}
curl https://mixpanel.com/api/query/jql \
     -u YOUR_API_SECRET: \
     --data-urlencode script@my_query.js
```

Example curl with the script directly inside of the curl:

```sh theme={"system"}
curl --request POST \
     --url https://mixpanel.com/api/query/jql \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data 'script=function main(){
  return Events(params)
    .groupBy(
      ["name"],
      mixpanel.reducer.count()
    )
}
' \
     --data 'params={
  "scriptParam": "paramValue"
}
'
```

Note

* The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.
* Queries will timeout after 2 minutes of run-time.
* You cannot make remote network requests (using XMLHttpRequest) from JavaScript.
* Queries to the JQL endpoint contribute to Query API rate limit and have their own individual limit as well. There is a maximum of 5 concurrent queries and of 60 queries per hour. There is also a 5 GB limit on data that can be processed in a single query, and a 2 GB limit on the resulting output data.


# Top Events
Source: https://docs.mixpanel.com/reference/query-months-top-event-names

openapi/query.openapi.yaml GET /events/names
Get a list of the most common events over the last 31 days. The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.



# Today's Top Events
Source: https://docs.mixpanel.com/reference/query-top-events

openapi/query.openapi.yaml GET /events/top
Get the top events for today, with their counts and the normalized percent change from yesterday.
The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.



# Rate Limits
Source: https://docs.mixpanel.com/reference/rate-limits



We enforce a rate limit on our API to ensure the integrity of our system as well as prevent a single project from monopolizing the available resources for other projects. These rate limits are scope per project.

Getting a 429 response code from our API means that you have reached our rate-limit.

The rate limits are as follows:

### [**Ingestion API**](/reference/ingestion-api)

2GB of uncompressed JSON/minute or \~30k events per second, measured on a rolling 1 minute basis. Please click [here](/reference/import-events#rate-limits) for more details.

### [**Query API**](/reference/query-api)

A maximum of 5 concurrent queries and 60 queries per hour.

### [**Raw Data Export API**](/reference/raw-data-export-api)

A maximum of 100 concurrent queries, 60 queries per hour, and 3 queries per second.

### [**Lexicon Schemas API**](/reference/lexicon-schemas-api)

A maximum of 5 requests per minute, under 4000 events and properties updated in each minute, and less than 3000 total truncations/deletions per request.

### You can reduce rate-limiting errors using one of the two approaches:

* Spread your queries out over a longer period of time.
* Consolidate multiple queries into a single query (for example, multiple queries filtering on a single property may be combined into a single segmentation query).


# Overview
Source: https://docs.mixpanel.com/reference/raw-data-export-api



The Mixpanel Export Data APIs allow you to export your raw data either manually or through a pipeline.

Please note that deduplication is not applied to raw data exports. If you export events via the API, you may see duplicates. It is recommended to apply deduplication logic (event name, distinct\_id, timestamp, \$insert\_id) to all exported data.

Example usage:

* If you receive a spike of 10K events but notice that only a few users contributed to it and would like to compare the data to another source.
* If you are exporting events from one project and importing them into another.
* If you are doing some very custom analysis Mixpanel cannot currently do. If this is the case, please [contact support](https://mixpanel.com/get-support) so we can either improve our product or possibly show you how you can perform this analysis within Mixpanel.


# Authentication
Source: https://docs.mixpanel.com/reference/raw-data-export-api-authentication



## Service Account

[Service Account Authentication Details](/reference/service-accounts)

Note that when you use Service Account authentication, you must specify the project\_id as a query parameter. E.g. `https://data.mixpanel.com/api/2.0/export?project_id=12345`

**Projects with [Classified Data](/docs/admin/data-governance/data-views-data-classification#data-classification)**

* The Service Account must have permission to access classified data.

## Project Secret

[Project Secret Authentication Details](/reference/project-secret)


# Download Data
Source: https://docs.mixpanel.com/reference/raw-event-export

openapi/export.openapi.yaml GET /export
Every data point sent to Mixpanel is stored as JSON in our data store. The raw export API allows you to download your event data as it is received and stored within Mixpanel, complete with all event properties (including distinct_id) and the exact timestamp the event was fired.
The raw export API has a rate limit of 60 queries per hour, 3 queries per second, and a maximum of 100 concurrent queries. If you exceed the rate limit, a 429 error will be returned.



# Remove Service Accounts From Projects
Source: https://docs.mixpanel.com/reference/remove-service-accounts-from-projects

openapi/service-accounts.openapi.yaml POST /organizations/{organizationId}/service-accounts/remove-from-project
Removes a list of service account ids from a list of project ids



# Replace a Lookup Table
Source: https://docs.mixpanel.com/reference/replace-lookup-table

openapi/ingestion.openapi.yaml PUT /lookup-tables/{id}

Lookup Tables must be [created via our UI](/docs/data-structure/lookup-tables#how-do-i-upload-a-lookup-table). Once a Lookup Table is created, its contents can be replaced via this API.

<CodeGroup>
  ```sh cURL theme={"system"}
  curl -XPUT 'https://api.mixpanel.com/lookup-tables/ID?project_id={YOUR_PROJECT_ID}' \
       -u 'SERVICE_ACCOUNT_USER:SERVICE_ACCOUNT_PASS' \
       -H 'Content-Type: text/csv' \
       --data 'id,artist,genre,is_platinum,name,num_listens,release_date,is_top_40
  c994bb,Drake,Pop,True,Hotline Bling,1700000000,2015-10-18T22:00:00,true
  d8d949,Gipsy Kings,Flamenco,False,Bamboleo,1170000,1987-07-12T05:00:00,false
  a43fb8,Daft Punk,House,False,Aerodynamic,41000000,2001-03-12T07:30:00,false
  '
  ```

  ```python Python theme={"system"}
  import requests

  data = """id,artist,genre,is_platinum,name,num_listens,release_date,is_top_40
  c994bb,Drake,Pop,True,Hotline Bling,1700000000,2015-10-18T22:00:00,true
  d8d949,Gipsy Kings,Flamenco,False,Bamboleo,1170000,1987-07-12T05:00:00,false
  a43fb8,Daft Punk,House,False,Aerodynamic,41000000,2001-03-12T07:30:00,false
  """

  id = "LOOKUP_TABLE_ID"
  project_id = "PROJECT_ID"

  resp = requests.put(
      f"https://api.mixpanel.com/lookup-tables/{id}?project_id={project_id}",
      headers={"Content-Type": "text/csv",
      auth=(SERVICE_ACCOUNT_USER, SERVICE_ACCOUNT_PASS),
      data=data
  )
  print(resp.json()
  ```
</CodeGroup>

### Validation

* The first column of the lookup table is assumed to be the ID of the row. All ID values must be unique.
* The first row of the lookup table is a header row. The values in the header must be unique, as each one uniquely identifies a column of the table. These will appear as properties of the lookup table in Mixpanel's UI.
* The CSV must be valid according to RFC4180.
* If the `Content-Encoding: gzip` header is supplied, the table will be decompressed before parsing.

#### Types

* Integers or floats will be parsed as numbers.
* RFC3339 timestamps (`2021-08-21T05:36:01Z`) will parsed as datetimes.
* `true` or `false` (case-insensitive) will be parsed as boolean.
* Empty fields (two adjacent commas) will be treated as `undefined`
* Comma separated, quoted strings in square brackets (`"[""Free"",""Paid"",""Enterprise""]"`) will be parsed as list of strings.
* All other values will be treated as strings.

#### Errors

Lookup Tables are replaced in their entirety or not replaced at all. When the Lookup Table fails to meet the above validation, we return an error that looks as follows:

```json theme={"system"}
{
  "error": "some data points in the request failed validation",
  "failed_records": [
    {
      "index": 2,
      "message": "invalid row: row indexes 1 and 2 have the same primary key"
    },
    {
      "index": 3,
      "message": "invalid row: wrong number of fields"
    }
  ],
  "status": 0
}
```

We will return at most the first 10 rows that failed validation.

### Limits

This endpoint will return a 429 error if called more than 100 times in a rolling 24 hour window. We recommend updating lookup tables at most hourly to stay within this limit.

This endpoint will return a 413 error if a Lookup Table exceeds 100MB uncompressed. In practice, this translates to 1-2M rows. If you have a lookup table that exceeds the limit, we recommend pruning the number of columns to those that are useful to analysis. Removing long URLs or user-generated content can bring a lookup table within this limit. If you still exceed the limit, please reach out to us at [apis@mixpanel.com](mailto:apis@mixpanel.com) -- we'd love to hear your use case!


# Request Signature [Deprecated]
Source: https://docs.mixpanel.com/reference/request-signature



<Danger>
  **Deprecation Warning**

  API authentication via request signature is an outdated authentication. The documentation below has been included for your reference. Please migrate existing code to use Service Account authentication.
</Danger>

Request signature authentication is the process of creating an encrypted token unique to a set of request parameters and their values. It was useful when requests were made insecurely or needed to be expirable. However, superior and more simplistic security practices have made this approach obsolete.

## Calculating a Signature

In order to generate a request signature you will need the following information:

**api\_key**: This is the token from the corresponding to the project you wish to consume from. **api\_secret**: This is a secret API key corresponding to the project. **expire**: UTC time in seconds; used to expire an API request. **all other request parameters**: All of the information for the API request being performed

Calculating the signature is done in parts:

1. Alphabetically sort all parameters being used in the request. This excludes your api\_secret
2. alphabetically sorted order, concatenate the parameter and parameter value joined by an equal sign. For example: `param1=value1param2=value2`
3. append the api\_secret to the string of concatenated parameters.
4. md5 hash the final string

The resulting hash is the request signature.

```sh theme={"system"}
# (pseudo code)
# all query parameters going to be sent out with the request
request_parameters = {
   api_key: '123',
   unit: 'hour',
   interval: '24',
   event: '["pages"]',
   expire: '1248499222',
}

sorted_parameter_names = sort(keys(request_parameters))
combined_params = ''

for param in sorted_parameter_names:
	combined_params += 	param + "=" + request_parameters[param]

request_signature = md5(combined_params + api_secret)request_signature = md5(combined_params + api_secret)
```

## Authenticating with a Request Signature

The generated signature needs to be provided with the parameters you used to calculate it. It will not work if any parameters or values change and it will not be valid after the expiry time.

Your URL should look similar to this however varying on the endpoint you are requesting data from:

Request with Signature

```txt theme={"system"}
https://mixpanel.com/api/2.0/events/
		&interval=7
		&expire=1275624968
		&api_key=xxxxx
		&type=average
		&event=%5B%22splash+features<%22%2C+%22account-page%22%5D
		&unit=day
    &sig=046ceec93983811dad0fb20f842c351a
```


# Resume Pipeline
Source: https://docs.mixpanel.com/reference/resume-warehouse-pipeline

openapi/data-pipelines.openapi.yaml POST /nessie/pipeline/resume
For a given pipeline name, this request resumes the pipeline if it's paused



# Query Frequency Report
Source: https://docs.mixpanel.com/reference/retention-frequency-query

openapi/query.openapi.yaml GET /retention/addiction

Get data about how frequently users are performing events.

Let's breakdown an example response. If you specify `day` as "unit" and `hour` as "addiction\_unit", you will get a response that looks like this:

```json theme={"system"}
{
  "2012-01-01": [
    305, 107, 60, 41, 32, 20, 12, 7, 4, 3, 3, 3, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1,
    1, 1
  ],
  "2012-01-02": [
    495, 204, 117, 77, 53, 36, 26, 20, 12, 7, 4, 3, 3, 1, 1, 1, 1, 0, 0, 0, 0,
    0, 0, 0
  ],
  "2012-01-03": [
    671, 324, 176, 122, 81, 63, 48, 31, 21, 14, 9, 5, 3, 1, 1, 1, 0, 0, 0, 0, 0,
    0, 0, 0
  ]
}
```

One day's worth of data is shown for each date, split into hours. On 2012-01-02, 495 users did the event `Viewed report` during at least 1 hour out of the next 24 hour period (the period specified by `unit`). 204 users did the event during at least 2 hours. 117 users did the event during at least 3 hours.

The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.


# Query Retention Report
Source: https://docs.mixpanel.com/reference/retention-query

openapi/query.openapi.yaml GET /retention

Get cohort analysis.

If you specify neither an `interval` nor a `unit`, the `interval` is 1 day. This means that each user gets 24 hours in each interval to do the specified event.

An example response with a `born_event` of 'event integration' and `event` of 'viewed report' might look like this:

```json theme={"system"}
{
  "2012-01-01": {
    "counts": [2, 1, 2],
    "first": 2
  },
  "2012-01-02": {
    "counts": [9, 7, 6],
    "first": 10
  },
  "2012-01-03": {
    "counts": [9, 6, 4],
    "first": 10
  }
}
```

These results indicate that on 2012-01-02, 10 users did the `born_event` ("event integration"), as indicated by the first field. If the `retention_type=compounded`, then first will instead indicate the number of users who did `event` ("viewed report") on the specified date. 9 of those users did `event` ("viewed report") within 24 hours (the "0th" interval) of doing the `born_event`. Seven of those did `event` between 24 and 48 hours (interval 1) of the `born_event`. These 7 are a subset of the initial 10, but not necessarily a subset of the 9 (retention is not a funnel; see the number increase between 72 and 96 hours). And finally, 6 users did `event` between 48 and 72 hours (interval 2) after the `born_event`.

In the Mixpanel retention UI, "First time" corresponds to `retention_type=birth`, and "Recurring" corresponds to `retention_type=compounded`.

The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.


# Run an Import
Source: https://docs.mixpanel.com/reference/run-an-import



Triggers an immediate sync for a given warehouse import.


# Run an import
Source: https://docs.mixpanel.com/reference/run-an-import-1

openapi/warehouse-connectors.openapi.yaml PUT /projects/{projectId}/warehouse-sources/imports/{importId}/manual-sync
Triggers an immediate sync for a given warehouse import.




# Segmentation Expressions
Source: https://docs.mixpanel.com/reference/segmentation-expressions



Segmentation Expressions are used in [Query API](/reference/query-api) and [Raw Data Export API](/reference/raw-data-export-api) to allow for more specificity when querying your data.

The power of segmentation comes from the ability to define custom expressions based on property names in the where and on parameters. An expression consists of a property, combined with one or more operators that can perform mathematical operations, logical operations, or typecasts. Expression are then applied in the where and on parameters of the segmentation API. The full grammar for expressions is given here:

```txt theme={"system"}
<expression> ::= 'properties["' <property> '"]'
                | <expression> <binary op> <expression>
                | <unary op> <expression>
                | <math op> '(' <expression> ')'
                | <typecast op> '(' <expression> ')'
                | '(' <expression> ')'
                | <boolean literal>
                | <numeric literal>
                | <string literal>
  <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' |
                  '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or'
   <unary op> ::= '-' | 'not'
    <math op> ::= 'floor' | 'round' | 'ceil'
<typecast op> ::= 'boolean' | 'number' | 'string'
   <property> ::= 'properties["' <property name> '"]'
```

## Examples

| Expression                                          | Description                                                                                                                                                                          |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `properties["account_id"] in [1,2,3,4]`             | Returns `true` if `account_id` event property is 1, 2, 3, or 4, otherwise `false`.                                                                                                   |
| `user["$email"] == "allison@example.com"`           | Returns `true` if `$email` user property is "[allison@example.com](mailto:allison@example.com)" otherwise `false`.                                                                   |
| `defined(properties["My Prop"])`                    | Returns `true` if `My Prop` event property has any value, otherwise `false`. This is the same as "is set" in the UI.                                                                 |
| `not defined(properties["city"])`                   | Returns `false` if `city` event property has any value, otherwise `true`. This is the same as "is not set" in the UI.                                                                |
| `event["$time"] >= datetime("YYYY-MM-DDT00:00:00")` | For the Event Export API: Returns `true` if the `$time` event property is on or after the given date, otherwise `false`. Replace `YYYY-MM-DD` with the date you want to filter from. |

## Typecast Operations

Internally, all properties of events have a type. This type is determined when we parse the event sent to us into a JSON object. Currently, there are three types, string, number, and boolean, which may be specified directly. A property may also have the values null and undefined, which are only handled internally. The default type is string. If you wish to treat an expression as another type, you may use the typecast operators to cast a property to a different type. For example, if `properties["signed up"]` has values of `"true"` and `"false"` as strings, and you wish to encode them as booleans, you may cast them by using the `boolean() typecast function: boolean(properties["signed up"])`.

The typecasting rules are described below.

## Casting to String

| Type          | Result                                                      |
| ------------- | ----------------------------------------------------------- |
| **String**    | Same String                                                 |
| **Number**    | String containing the decimal representation of the number. |
| **Boolean**   | "true" or "false"                                           |
| **null**      | null                                                        |
| **Undefined** | undefined                                                   |

## Casting to Number

| Type          | Result                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------ |
| **String**    | Attempts to interpret the string as a decimal. If this fails, the value becomes undefined. |
| **Number**    | Same number                                                                                |
| **Boolean**   | 1.0 if true, 0.0 if false                                                                  |
| **null**      | undefined                                                                                  |
| **undefined** | undefined                                                                                  |

## Binary Operations

The arithmetic operators `"-"`, `"*"`, `"/"`, `"%"` perform the subtraction, multiplication, division, and remainder operations, respectively. The division operator will return undefined if the divisor is 0. The sign of the value of the remainder will be equivalent to the dividend. All four of these operators expect both operands to be of the type number, or else the result is undefined.

The `"+"` operator behaves as addition if its two operands are of type number. However, if its two operands are of type string, it will concatenate the two strings. In other cases, the result is undefined.

The equals operator `"=="` will always return a boolean. When its two types are equal, it performs the standard equality comparison based on the values. If the types of its operands are not equal, false is returned. The not equals operator `"!="` returns false when the equals operator would return true and vice-versa.

The comparison operators `">"`, `">="`, `"<"`, and `"<="` returns a boolean value based on evaluating the comparison when its operands are both of type number. When its types are not equal, undefined is returned.

The `"in"` operator returns true if both operands are of type string and the first string is a substring of the second. When both operands are of differing types, undefined is returned.

The logical operators `"and"` and `"or"` accept boolean and undefined operands. An operand with type undefined evaluates as false. Any other types will result in an error.

## Unary and Math Operations

The `"-"` operator will negate an operand of type number, and return undefined otherwise.

The `"not"` operator will perform the logical not on an operand of type boolean. It will also evaluate an operand of type undefined as true. All other operands will be evaluated to undefined.

The `"floor"`, `"round"`, and `"ceil"` functions perform their mathematical operations on an operand of type number. On all other types, it will return undefined.


# Numerically Bucket
Source: https://docs.mixpanel.com/reference/segmentation-numeric-query

openapi/query.openapi.yaml GET /segmentation/numeric
Get data for an event, segmented and filtered by properties, with values placed into numeric buckets.
The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.

> ❗️The Segmentation Query API is in maintenance mode. We recommend discontinuing new use of this endpoint. To break down and filter event data, build an [Insights report](https://docs.mixpanel.com/docs/reports/insights) in-app and query it programmatically with the [Insights Query API](https://developer.mixpanel.com/reference/insights-query). For raw event data, see [export methods](https://docs.mixpanel.com/docs/export-methods). If you need help choosing the best method, reach out to [support](https://mixpanel.com/get-support).


# Query Segmentation Report
Source: https://docs.mixpanel.com/reference/segmentation-query

openapi/query.openapi.yaml GET /segmentation
Get data for an event, segmented and filtered by properties. The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.

> ❗️The Segmentation Query API is in maintenance mode. We recommend discontinuing new use of this endpoint. To break down and filter event data, build an [Insights report](https://docs.mixpanel.com/docs/reports/insights) in-app and query it programmatically with the [Insights Query API](https://developer.mixpanel.com/reference/insights-query). For raw event data, see [export methods](https://docs.mixpanel.com/docs/export-methods). If you need help choosing the best method, reach out to [support](https://mixpanel.com/get-support).


# Numerically Average
Source: https://docs.mixpanel.com/reference/segmentation-query-average

openapi/query.openapi.yaml GET /segmentation/average
Averages an expression for events per unit time. The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.

> ❗️The Segmentation Query API is in maintenance mode. We recommend discontinuing new use of this endpoint. To break down and filter event data, build an [Insights report](https://docs.mixpanel.com/docs/reports/insights) in-app and query it programmatically with the [Insights Query API](https://developer.mixpanel.com/reference/insights-query). For raw event data, see [export methods](https://docs.mixpanel.com/docs/export-methods). If you need help choosing the best method, reach out to [support](https://mixpanel.com/get-support).


# Numerically Sum
Source: https://docs.mixpanel.com/reference/segmentation-sum-query

openapi/query.openapi.yaml GET /segmentation/sum
Sums an expression for events per unit time. The Query API has a rate limit of 60 queries per hour and a maximum of 5 concurrent queries.

> ❗️The Segmentation Query API is in maintenance mode. We recommend discontinuing new use of this endpoint. To break down and filter event data, build an [Insights report](https://docs.mixpanel.com/docs/reports/insights) in-app and query it programmatically with the [Insights Query API](https://developer.mixpanel.com/reference/insights-query). For raw event data, see [export methods](https://docs.mixpanel.com/docs/export-methods). If you need help choosing the best method, reach out to [support](https://mixpanel.com/get-support).


# Service Accounts
Source: https://docs.mixpanel.com/reference/service-accounts



<Check>
  **Recommended Authentication**
</Check>

A service account is a special type of Mixpanel user intended to represent a non-human entity such as a script or back end service. Similar to a normal user it can be granted access to any number of projects and workspaces within an organization. Permissions are set by defining the role of the service account for each project or workspace. A service account can only belong to one organization.

## Authenticating with a Service Account

Service Account authentication is performed via [HTTP Basic Auth](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme). While the Basic access standard calls for a base64 encoding of the colon-joined credentials our authentication accepts both base64 encoding and plain-text.

Provide a service account's username and secret as the basic authentication credentials.

<CodeGroup>
  ```sh cURL Basic Auth theme={"system"}
  curl https://mixpanel.com/api/app/me \
  	--user "<serviceaccount_username>:<serviceaccount_secret>"
  ```

  ```shell cURL Header theme={"system"}
  curl https://mixpanel.com/api/app/me \
  	--header 'authorization: Basic <serviceaccount_username>:<serviceaccount_secret>'
  ```

  ```python Python Requests theme={"system"}
  import requests
  requests.get(
    'https://mixpanel.com/api/app/me', 
    auth=('<serviceaccount_username>', '<serviceaccount_secret>'),
  )
  ```
</CodeGroup>

## Managing Service Accounts

<Warning>
  **Owner or Admin Permissions Required**

  You must have Owner or Admin permissions to manage a project's Service Accounts. Learn more in our [permissions help doc](/docs/orgs-and-projects/roles-and-permissions#permissions).
</Warning>

<div>
  <div>
    <p>
      You can view and create service accounts in your organization in the Service Accounts tab in your <a href="https://mixpanel.com/settings/org#serviceaccounts">Organization settings</a>
    </p>

    <p>
      You will be asked to select the role and granted projects of the when creating a service account from the organization's settings page. Deleting a service account from the organization will immediately revoke access to all projects in the organization.
    </p>
  </div>

  <div>
    <img />
  </div>
</div>

<div>
  <div>
    <img />
  </div>

  <div>
    <p>
      You can also manage service accounts in your <a href="https://mixpanel.com/settings/project#serviceaccounts">project settings</a>.
    </p>
  </div>
</div>

Any service account you create from the project settings page will be automatically be assigned an organization member role. Deleting a service account will revoke access only from that project.

<div>
  <img />
</div>

<Warning>
  **Immediately store your credentials in a safe place**

  It's very important you save your service account secret somewhere secure as you won't be able to access it again after creation.
</Warning>

## Service Account Expiration

By default, service accounts have no expiration. However, when you create a service account you can optionally specify how long you want it to be valid for. This may provide increased security and force a credential rotation policy. After the credentials expire, API requests using the service account will not be authorized.

<Frame>
  <img />
</Frame>


# Overview
Source: https://docs.mixpanel.com/reference/service-accounts-api



The Service Accounts API lets you manage your service accounts programmatically. You can get a list of your organizations service accounts, see when they were last used, see when they expire, create new service accounts, delete service accounts, and add/remove service accounts to/from projects. This API is useful for automated key management and rotation.

<Note>
  **Roles & Permissions**

  To modify (create, delete) service accounts, the service account used for authentication must have the role of admin or owner.
</Note>


# Authentication
Source: https://docs.mixpanel.com/reference/service-accounts-api-authentication



## Service Account

<Note>
  **Roles & Permissions**

  To modify (create, delete) a service account, the service account used for authentication must have the role of admin or owner.
</Note>

[Service Account Authentication Details](/reference/authentication#service-accounts)

```sh theme={"system"}
curl --request GET \
     --url https://mixpanel.com/api/app/organizations/12345/service-accounts \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic dGVzdDp0ZXN0'
```


# Track Events
Source: https://docs.mixpanel.com/reference/track-event

openapi/ingestion.openapi.yaml POST /track

Track events to Mixpanel from client devices. We recommend using one of our client-side SDKs instead of using /track directly, as our SDKs provide queueing, retrying, batching, and more.

## When to use /track vs /import

Typically, we recommend using /import for server-side integrations as it is more scalable and supports ingesting historical data. We only recommend /track for client-side tracking in an environment for which we don't have SDK support or if you're sending data via some other untrusted environment (eg: third-party webhooks that send data to Mixpanel).

|                             | /track                                         | /import                                                               |
| --------------------------- | ---------------------------------------------- | --------------------------------------------------------------------- |
| Events per request          | 2000                                           | 2000                                                                  |
| Authentication              | Project Token, intended for untrusted clients. | Project Secret/Service Account, intended for server-side integration. |
| Compression                 | Gzip allowed                                   | Gzip allowed                                                          |
| Content-Type                | application/x-www-form-urlencoded              | application/json or application/x-ndjson                              |
| Ingesting historical events | Last 5 days only.                              | Any time after 1971-01-01.                                            |

## Limits

The limits for track are the same as /import, [see here](/reference/import-events#rate-limits).

Each event has the following size limits:

* Must be smaller than 1MB of uncompressed JSON.
* Must have fewer than 255 properties.
* All nested object properties must have fewer than 255 keys and max nesting depth is 3.
* All array properties must have fewer than 255 elements.

To ensure real-time ingestion and quality-of-service, we have a rate limit of 2GB of uncompressed JSON/minute or \~30k events per second, measured on a rolling 1 minute basis.

We recommend the following when it comes to sending data to our API at scale:

* Send data as quickly as possible with concurrent clients until the server returns 429. We see the best results with 10-20 concurrent clients sending 2K events per batch.
* When you see 429s, employ an [exponential backoff with jitter](https://docs.aws.amazon.com/general/latest/gr/api-retries.html) strategy. We recommend starting with a backoff of 2s and doubling backoff until 60s, with 1-5s of jitter.
* We recommend gzip compression and using `Content-Encoding: gzip` to reduce network egress and transfer time.
* In the rare event that our API returns a 502 or 503 status code, we recommend employing the same exponential backoff strategy as with 429s.
* Please do not retry validation errors (400 status code), as they will consistently fail and count toward the rate limit.

If you are an Enterprise customer that requires a higher rate limit, please reach out to your CSM with your `project_id` and use case.


# Unarchive Experiment
Source: https://docs.mixpanel.com/reference/unarchive-experiment

openapi/experiments.openapi.yaml DELETE /workspaces/{workspace_id}/experiments/{experiment_id}/archive



# Update Experiment
Source: https://docs.mixpanel.com/reference/update-experiment

openapi/experiments.openapi.yaml PATCH /workspaces/{workspace_id}/experiments/{experiment_id}



# Update Feature Flag
Source: https://docs.mixpanel.com/reference/update-feature-flag-1

openapi/feature-flags-management.openapi.yaml PUT /projects/{project_id}/workspaces/{workspace_id}/feature-flags/{flag_id}



# Update Warehouse Import
Source: https://docs.mixpanel.com/reference/update-warehouse-import

openapi/warehouse-connectors.openapi.yaml PATCH /projects/{projectId}/warehouse-sources/imports/{importId}
Update an existing warehouse import's settings.

### Patchable Fields

The following fields can be modified:

- **paused** (boolean, required): Pause or resume the import sync
- **run_every** (integer): Sync frequency in nanoseconds. Must be one of the following values:
  - `0`: API-triggered only (no scheduled sync)
  - `3600000000000`: Hourly
  - `86400000000000`: Daily
  - `604800000000000`: Weekly
- **databricks_params** (object): Databricks-specific cluster configuration (only for Databricks sources). Note: this is a full replacement, not a partial merge. Always provide the complete desired cluster configuration.

### Pause/Resume Behavior

- When `paused: true`, the import job will be stopped and no new syncs will be triggered
- When `paused: false`, the import job will be resumed with the specified frequency
- When resuming, you can optionally update `run_every`

### Databricks Configuration

For Databricks Jobs compute imports, you can update cluster configurations:
- `export_cluster_config`: Configuration for the data export job cluster




# Create/Replace One
Source: https://docs.mixpanel.com/reference/upload-schema-by-entity-and-name

openapi/lexicon-schemas.openapi.yaml POST /projects/{projectId}/schemas/{entityType}/{name}

Upload a schema for a single entity. If a schema already exists for a specified entity, it will be replaced by the one you upload.

<Warning>
  **Metadata merging behavior**

  If the new schema is missing `metadata` properties that are currently set in the existing schema for that entity, those properties will be merged into the new schema. For example, if your current schema has `{"metadata": {"com.mixpanel": {"hidden": true}}}` and you upload a new schema without "hidden", we will merge `"hidden": true` to your uploaded schema's metadata. If you want to remove that property, set the value to `null`.
</Warning>

<Note>
  **Adding a schema for User Profiles**

  To add a schema for your [User Profiles](https://help.mixpanel.com/hc/en-us/articles/115004501966-User-Profiles), specify the `entityType` as `profile` and the `name` as `$user`.
</Note>

### Example POST Body

```json theme={"system"}
{
    "$schema": "http://json-schema.org/draft-07/schema",
    "description": "Tracked when a user adds an item to their cart.",
    "required": [
        "item_name",
        "item_id",
        "item_price"
    ],
    "additionalProperties": true,
    "metadata": {
        "com.mixpanel": {
            "tags": [
                "Shopping",
                "KPIs"
            ],
            "displayName": "Item Purchased",
            "hidden": false,
            "dropped": false,
            "contacts": [
              "first.last@mixpanel.com"
            ],
            "teamContacts": [
              "Analytics Team"
            ]
        }
    },
    "properties": {
        "item_name": {
            "type": "string",
            "description": "The name of the item",
            "examples": [
                "Blue Widget"
            ],
            "metadata": {
              "com.mixpanel": {
                "displayName": "Item Name"
              }
            }
        },
        "item_id": {
            "type": "integer",
            "description": "The internal id of the item",
            "examples": [
                12345
            ],
            "metadata": {
              "com.mixpanel": {
                "displayName": "Item ID"
              }
            }
        },
        "item_price": {
            "type": "number",
            "description": "The current price of the item",
            "examples": [
                25.35
            ],
            "metadata": {
              "com.mixpanel": {
                "displayName": "Price"
              }
            }
        },
        "promo_id": {
            "type": "integer",
            "description": "The id of any promo in progress for this item",
            "examples": [
                82523,
                18382
            ],
            "metadata": {
              "com.mixpanel": {
                "displayName": "Promo ID"
              }
            }
        },
        "date_added_to_catalog": {
            "type": "string",
            "format": "date-time",
            "description": "The date this item was added to the store catalog",
            "examples": [
                "2015-03-05T15:25:23"
            ],
            "metadata": {
              "com.mixpanel": {
                "displayName": "Date Added"
              }
            }
        }
    }
}
```


# Create/Replace Multiple
Source: https://docs.mixpanel.com/reference/upload-schemas-for-project

openapi/lexicon-schemas.openapi.yaml POST /projects/{projectId}/schemas

Upload schemas in bulk to the specified project. If a schema already exists for a specified entity, it will be replaced by the one you upload.

<Warning>
  **Metadata merging behavior**

  If the new schema is missing `metadata` properties that are currently set in the existing schema for that entity, those properties will be merged into the new schema. For example, if your current schema has `{"metadata": {"com.mixpanel": {"hidden": true}}}` and you upload a new schema without "hidden", we will merge `"hidden": true` to your uploaded schema's metadata. If you want to remove that property, set the value to `null`.
</Warning>

<Note>
  **Adding a schema for User Profiles**

  To add a schema for your [User Profiles](https://help.mixpanel.com/hc/en-us/articles/115004501966-User-Profiles), specify the `entityType` as `profile` and the `name` as `$user`.
</Note>

### Example POST Body

```json theme={"system"}
{
  "entries": [
    {
      "entityType": "event",
      "name": "Added To Cart",
      "schemaJson": {
        "$schema": "http://json-schema.org/draft-07/schema",
        "description": "Tracked when a user adds an item to their cart.",
        "required": [
          "item_name",
          "item_id",
          "item_price"
        ],
        "additionalProperties": true,
        "metadata": {
          "com.mixpanel": {
            "tags": [
              "Shopping",
              "KPIs"
            ],
            "displayName": "Item Purchased",
            "hidden": false,
            "dropped": false,
            "contacts": [
              "first.last@mixpanel.com"
            ],
            "teamContacts": [
              "Analytics Team"
            ]
          }
        },
        "properties": {
          "item_name": {
            "type": "string",
            "description": "The name of the item",
            "examples": [
              "Blue Widget"
            ],
            "metadata": {
              "com.mixpanel": {
                "displayName": "Item Name"
              }
            }
          },
          "item_id": {
            "type": "integer",
            "description": "The internal id of the item",
            "examples": [
              12345
            ],
            "metadata": {
              "com.mixpanel": {
                "displayName": "Item ID"
              }
            }
          },
          "item_price": {
            "type": "number",
            "description": "The current price of the item",
            "examples": [
              25.35
            ],
            "metadata": {
              "com.mixpanel": {
                "displayName": "Price"
              }
            }
          },
          "promo_id": {
            "type": "integer",
            "description": "The id of any promo in progress for this item",
            "examples": [
              82523,
              18382
            ],
            "metadata": {
              "com.mixpanel": {
                "displayName": "Promo ID"
              }
            }
          },
          "date_added_to_catalog": {
            "type": "string",
            "format": "date-time",
            "description": "The date this item was added to the store catalog",
            "examples": [
              "2015-03-05T15:25:23"
            ],
            "metadata": {
              "com.mixpanel": {
                "displayName": "Date Added"
              }
            }
          }
        }
      }
    }
  ],
  "truncate": false
}
```


# Limits
Source: https://docs.mixpanel.com/reference/user-profile-limits



The User Profile API imposes limits on the total number profile updates that can be sent per request to **2000** as well as limit each individual update in the request to a maximum of **1 MB**. If you are running up against these limits, we suggest breaking your request into smaller batches. Usually these limits are only hit if you are attempting to do a bulk create/update.


# Union to User Profile List Property
Source: https://docs.mixpanel.com/reference/user-profile-union

openapi/ingestion.openapi.yaml POST /engage#profile-union
Adds the specified values to a list property on a user profile and ensures that those values only appear once. The profile is created if it does not exist.



# Overview
Source: https://docs.mixpanel.com/reference/warehouse-connectors-api



Warehouse Connectors allow you to connect a warehouse of your choice to import events, users, groups, and lookup tables.

Use Warehouse Connectors API to run a specific import manually.


# Authentication
Source: https://docs.mixpanel.com/reference/warehouse-connectors-api-authentication



A [service account](/reference/service-accounts) is necessary to authenticate Warehouse Connectors API requests. Once you have created a service account and obtained your user name and secret, you can make a request to trigger a warehouse import.

<CodeGroup>
  ```bash cURL Basic Auth theme={"system"}
  curl -X PUT https://mixpanel.com/api/app/projects/<your_project_id>/warehouse-sources/imports/<your_import_id>/manual-sync \
  	--user "<serviceaccount_username>:<serviceaccount_secret>"
  ```

  ```shell cURL Header theme={"system"}
  curl -X PUT https://mixpanel.com/api/app/projects/<your_project_id>/warehouse-sources/imports/<your_import_id>/manual-sync \
  	--header 'authorization: Basic <serviceaccount_username>:<serviceaccount_secret>'
  ```

  ```python Python Requests theme={"system"}
  import requests
  requests.put(
    'https://mixpanel.com/api/app/projects/<your_project_id>/warehouse-sources/imports/',
    auth=('<serviceaccount_username>', '<serviceaccount_secret>'),
  )
  ```
</CodeGroup>


# Frequently Asked Questions
Source: https://docs.mixpanel.com/troubleshooting/faqs



## General

<AccordionGroup>
  <Accordion title="What does Mixpanel do?">
    Mixpanel is a product analytics platform that helps businesses track user interactions with digital products such as websites and mobile apps. It provides detailed insights into user behavior, allowing teams to analyze usage patterns, measure engagement, and optimize the user experience. With features like event tracking, funnel analysis, cohort reports, and A/B testing, Mixpanel enables data-driven decision-making to improve product performance and growth.

    Mixpanel offers a variety of ingestion SDKs and import/export integrations to make it easy to collect and use product analytics data across platforms.

    [Learn more about Mixpanel](/docs/what-is-mixpanel) and [send your first event](/docs/quickstart).
  </Accordion>

  <Accordion title="Can I demo Mixpanel?">
    Mixpanel offers sample datasets representing a range of use cases (including B2B, AI, and e-commerce) to help you learn the platform's features effectively. To access these datasets, [create a Mixpanel account](https://mixpanel.com/signup/), log in, then select [Mixpanel Demo Sample Datasets](https://mixpanel.com/api/app/demo_project?show-demo-dataset-modal=true) from the project menu dropdown.

    You may also [book a demo with our team](https://mixpanel.com/contact-us/demo/).
  </Accordion>

  <Accordion title="How much does it cost to use Mixpanel?">
    Mixpanel offers flexible pricing through the Free, Growth, and Enterprise plans. You can explore the features available in each plan on our [pricing page](https://mixpanel.com/pricing/). The page includes a Plan Builder tool that helps you estimate your cost based on projected data usage.
  </Accordion>
</AccordionGroup>

## Sending Data to Mixpanel

<AccordionGroup>
  <Accordion title="Why can’t I see any data in my Mixpanel project?">
    There are several common reasons why you might not see any data in your Mixpanel project:

    1. **Incorrect Project Token** - Using the wrong project token in your initialization code will lead to your tracked data not arriving to your project. Always verify that the token matches [the token shown in your project settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens).
    2. **Mismatched Data Residency** - If your Mixpanel project data residency setting does not match the API endpoint you are sending data to, your data will **not be ingested**. If your project data residency is set to EU or India, make sure to route your data to the correct API server URL in your initialization code. Learn more about [EU Residency](/docs/privacy/eu-residency) and [India Residency](/docs/privacy/in-residency).
    3. **Implementation Issues** - Implementation errors can prevent Mixpanel SDK methods from triggering as expected. To help identify and resolve these issues during development, [enable debug mode in your SDK](/docs/tracking-best-practices/debugging#enable-debug-mode). This will provide logs of the Mixpanel requests being triggered, along with the associated payloads.

    Learn more about [debugging your implementation](/docs/tracking-best-practices/debugging).
  </Accordion>

  <Accordion title="What methods are available for importing data into Mixpanel?">
    You can use any [Mixpanel SDKs](/docs/tracking-methods/sdks) to track and send events directly from your applications, both on the client and server side.

    Mixpanel supports direct imports from data warehouses such as Snowflake, BigQuery, Redshift, and Databricks through [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors). You can set up [recurring syncs](/docs/tracking-methods/warehouse-connectors#sync-modes) to keep Mixpanel in sync with your warehouse data.

    If you use a CDP like Segment or Rudderstack, you can add Mixpanel as a downstream destination to receive your data. Learn more about [data ingestion integrations](/docs/tracking-methods/integrations).
  </Accordion>

  <Accordion title="How does ad-blockers affect Mixpanel tracking?">
    Ad-blockers can significantly affect Mixpanel tracking, particularly when using the client-side JavaScript SDK. These blockers and privacy extensions often target known analytics endpoints (such as Mixpanel's), preventing events from being sent and recorded. As a result, users with ad blockers enabled may not be tracked in Mixpanel, leading to discrepancies between backend data and Mixpanel reports. Depending on your audience and the types of blockers in use, an estimated 30% or more of client-side events may be impacted.

    To reduce the impact of ad-blockers, use server-side tracking for critical events (server-side requests are not subject to ad blocking) and implement a proxy server to route client-side requests through your own domain (making them less likely to be blocked).

    Read more about [the differences between client-side and server-side tracking](/docs/tracking-methods/choosing-the-right-method).
  </Accordion>

  <Accordion title="How do I exclude bots from my tracking?">
    By default, [Mixpanel's JavaScript SDK](/docs/tracking-methods/sdks/javascript) automatically blocks traffic from known web crawlers, as listed [here](https://github.com/mixpanel/mixpanel-js/blob/8ac526e5cb8563d11e2206046ab986c6491ac6d7/src/utils.js#L900C1-L925C3). All other traffic is processed normally and ingested into your project.

    To further control bot traffic, you can implement custom filtering in your code. This involves identifying common patterns among your bots and setting the super property `$ignore: true` to exclude those events at ingestion.

    Learn more about [managing bot traffic](/docs/tracking-best-practices/bot-traffic).
  </Accordion>

  <Accordion title="Why are my user profiles all set to the same location?">
    If all user profiles in Mixpanel display the same location, it is likely because you are sending data through a server-side implementation or a CDP (like Segment or Rudderstack). In these cases, Mixpanel uses the server's IP address for geolocation instead of the end user's, resulting in all users being assigned the same location (such as Boardman, Oregon for Segment or Ashburn, Virginia for Rudderstack).

    By default, Mixpanel updates a user's geolocation each time a user property is created or modified. If you don't explicitly include the user's real IP address in your payload, Mixpanel defaults to the server's IP.

    To resolve this, you can:

    * Pass the actual client IP using the `$ip`  in your payload,
    * Manually set geolocation properties like `$city`, `$region`, and `$country_code`, or
    * Set `$ip` to `0` to prevent Mixpanel from updating the geolocation entirely.

    Learn more about [geolocation](/docs/tracking-best-practices/geolocation) and other [server-side implementation best practices](/docs/tracking-best-practices/server-side-best-practices).
  </Accordion>

  <Accordion title="How do I override the default geolocation set by Mixpanel when sending data from a server?">
    By default, Mixpanel determines the geolocation of users and events based on the IP address of the request. When using client-side tracking, this reflects the end user's location. With server-side tracking, it reflects the server's location.

    To override the default geolocation set by Mixpanel, you can:

    * Pass the actual client IP using the `$ip`  in your payload
    * Manually set geolocation properties such as `$city`, `$region`, and `$country_code`
    * Specify the exact coordinates by setting the `$latitude` and `$longitude` properties in your payload

    Learn more about [geolocation](/docs/tracking-best-practices/geolocation).
  </Accordion>

  <Accordion title="How do I track downloads and installs from Apple App Store and Google Play Store?">
    Tracking downloads and installs from the Apple App Store and Google Play Store in Mixpanel cannot be done directly, as neither app store provides this data to Mixpanel out-of-the-box.

    **For Google Play Store (Android):** You can use the [**Play Install Referrer Library**](https://developer.android.com/google/play/installreferrer/library) to retrieve the referrer URL when the app is first opened. This allows you to capture some attribution data (such as campaign source) and send it to Mixpanel as event properties. However, this only works for a subset of attribution data and does not provide the total number of downloads—only installs where the app is opened and the referrer is available

    **For Apple App Store (iOS):** The App Store strips attribution data before the user downloads the app, so you cannot directly track the source or count of installs via Mixpanel. To track channel attribution on iOS, you need to use a mobile attribution partner (such as Adjust, AppsFlyer, or Branch). These partners can capture install and attribution data and send it to Mixpanel for analysis.

    Learn more about [Traffic Attribution](docs/tracking-best-practices/traffic-attribution) and our [attribution integration partners](https://mixpanel.com/partners/integrations?categories=attribution-deep-linking).
  </Accordion>

  <Accordion title="How do I track first-touch UTM tags?">
    To track first-touch UTM tags in Mixpanel, you can rely on the default behavior of the Mixpanel JavaScript SDK. When a user visits your site for the first time with UTM parameters in the URL, the SDK will:

    * Automatically capture the UTM parameters from the landing page URL (such as `utm_source`, `utm_medium`, `utm_campaign`, etc.) and add them to events fired from that page load.
    * Store these first-seen UTM parameters as user profile properties prefixed with `initial_` (e.g., `initial_utm_source`, `initial_utm_campaign`). These properties represent the first-touch attribution and will persist on the user profile for future reference.

    **No extra configuration is needed** for first-touch tracking if you are using the default SDK settings and identifying users normally. The UTM parameters will be persisted as [super properties](/docs/data-structure/events-and-properties#super-properties) in a last-touch manner and the initial values will be set on the user profile automatically in a first-touch manner.

    If you are using a server-side implementation or a third-party integration, you must manually set these UTM properties.

    We recommend disabling UTM persistence for compatibility with the [Attribution](/docs/features/computed-properties#attribution) feature. To disable UTM persistence, set `stop_utm_persistence: true` when initializing the SDK.

    Learn more about [UTM tracking](/docs/tracking-best-practices/traffic-attribution#web-attribution).
  </Accordion>

  <Accordion title="How do I track last-touch UTM tags?">
    By default, UTM parameters are persisted as [super properties](/docs/data-structure/events-and-properties#super-properties) in all events and is updated when a new UTM parameter is detected in subsequent page loads (which aligns with last-touch attribution).

    We recommend disabling UTM persistence for compatibility with the [Attribution](/docs/features/computed-properties#attribution) feature. To disable UTM persistence, set `stop_utm_persistence: true` when initializing the SDK.

    Learn more about UTM tracking [here](/docs/tracking-best-practices/traffic-attribution#web-attribution).
  </Accordion>

  <Accordion title="Why do I see Session Start and Session End events in my project?">
    **Session Start** and **Session End** events are automatically computed based on the events already in your project. These are **virtual events;** they are not sent from your application but are generated by Mixpanel at query time within the UI and reports. These virtual events do not count toward your data allowance.

    The definition of a session, when it starts and ends, depends on your project's session settings, which may be [timeout-based](/docs/features/sessions#timeout-based-sessions), [event-based](docs/features/sessions#event-based-sessions), or [property-based](/docs/features/sessions#property-based-sessions). You can use these virtual events in reports such as Insights, Funnels, and Flows. However, they do not appear in your raw events list and cannot be exported via the API, as they are not stored as actual events in your data store.

    Learn more about [Sessions](/docs/features/sessions).
  </Accordion>

  <Accordion title="What are super properties?">
    [Super properties](/docs/data-structure/events-and-properties#super-properties) in Mixpanel are event properties that you define once and are automatically included with every event tracked from the client-side SDKs. They are stored in the user's local storage or cookie, so you don't need to manually add them to each event. This is useful for properties that provide important context across multiple events, such as user type, app version, or campaign source.

    You can register super properties with the [JavaScript SDK](/docs/tracking-methods/sdks/javascript#setting-super-properties), [Android SDK](/docs/tracking-methods/sdks/android#setting-super-properties), [Swift SDK](/docs/tracking-methods/sdks/swift#setting-super-properties), [iOS SDK](/docs/tracking-methods/sdks/ios#setting-super-properties), and the [React SDK](/docs/tracking-methods/sdks/react-native#setting-super-properties).
  </Accordion>

  <Accordion title="How can I edit the event data inside my project?">
    You cannot directly edit the raw event data that has already been ingested into your Mixpanel project; events are immutable once received (unless imported via a [mirror sync warehouse connector](/docs/tracking-methods/warehouse-connectors#mirror)). However, you can [hide unwanted events](/docs/data-governance/lexicon#hiding-data) from appearing in your reports and delete unwanted data.

    Learn more about [Lexicon](/docs/data-governance/lexicon), [Data Deletion](/docs/data-governance/data-clean-up#2-deleting-problematic-data), and [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors).
  </Accordion>

  <Accordion title="How can I send data from my data warehouse to Mixpanel?">
    You can send data from your data warehouse to Mixpanel using [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors), which offer native integrations with Redshift, Snowflake, BigQuery, and Databricks. This codeless setup allows you to configure recurring syncs, ensuring Mixpanel stays up to date with your warehouse data.
  </Accordion>

  <Accordion title="How can I do a one-time import of historic events? How much does it cost?">
    To do an initial import of data into Mixpanel, there are several methods available:

    **1. SDKs (Software Development Kits)**: You can use [Mixpanel's SDKs](/docs/tracking-methods/sdks) to send data directly from your application. This is a common approach for ongoing event tracking, but it can also be used for initial imports if you replay historical events through the SDKs.

    **2. Import API**: Mixpanel provides an [Import API](/reference/import-events) that allows you to send data directly to Mixpanel. This method is managed by your team, and you can automate API calls to send data as needed.

    **3. Data Warehouse Connector(Add-on)**: Mixpanel offers a [data warehouse connector](/docs/tracking-methods/warehouse-connectors) as an add-on for organizations on the Enterprise plan, which allows you to point Mixpanel to your data warehouse table, and Mixpanel manages the sync and cadence of data import. This is a managed solution and is easier for teams that want Mixpanel to handle the process. Contact your account manager to learn more about the pricing.

    Learn more about the pricing for historical events on the [Billing & Pricing doc](/docs/pricing#is-old-event-data-billed-when-imported-to-mixpanel).
  </Accordion>

  <Accordion title="Why do I see CORS errors in the console when Mixpanel requests in my website?">
    CORS (Cross-Origin Resource Sharing) errors appear in your console when Mixpanel requests from your website are blocked by the browser's security policy. This typically happens because the Mixpanel server response does not include the necessary CORS headers (like `Access-Control-Allow-Origin`) to allow your domain to access the resource.

    Mixpanel requires you to send cross-origin HTTP requests (requests sent to a different server than the one hosting your web application), so you need to setup your environment to allow this. Use browser developer tools to inspect the failed request and see which headers are missing or mismatched.

    Learn more about [CORS errors](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS/Errors).
  </Accordion>

  <Accordion title="How do we send data to Mixpanel?">
    You can use [Mixpanel's SDKs](/docs/tracking-methods/sdks) to track and send events directly from your applications, both on the client and server side.

    Mixpanel supports direct imports from data warehouses such as Snowflake, BigQuery, Redshift, and Databricks through [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors). You can set up recurring syncs to keep Mixpanel in sync with your warehouse data.

    If you use a CDP like Segment or Rudderstack, you can add Mixpanel as a downstream destination to receive your data.

    Learn more about [Tracking Methods](/docs/tracking-methods).
  </Accordion>

  <Accordion title="Can Mixpanel integrate with our current data model or database?">
    Mixpanel is flexible and can integrate with most data models or databases, either directly or through data transformation and import methods.

    If your data is stored in a data warehouse (such as BigQuery, Redshift, Snowflake, or Databricks), Mixpanel's [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors) allow you to sync tables or views from your warehouse into Mixpanel. This integration is codeless and can keep your Mixpanel data in sync with your backend systems

    If you are using a CDP such as Segment or Rudderstack, you can set Mixpanel as a downstream destination to stream data from your existing sources.

    Learn more about [Tracking Methods](/docs/tracking-methods).
  </Accordion>

  <Accordion title="How do we handle sensitive or private data?">
    Mixpanel does not store personally identifiable information (PII) unless you explicitly choose to track it. You have full control over the data you send and should avoid including raw PII (such as names, email addresses, or phone numbers) unless absolutely necessary.

    Mixpanel also provides tools to help you honor user privacy, including options to support opt-out requests and manage data responsibly. Learn more about how to [protect user data](/docs/privacy/protecting-user-data).

    With [Data Views](/docs/data-governance/data-views-and-classification#data-views-overview), you can create filtered views of your project data and assign access to specific teams or users.

    Additionally, [Data Classification](/docs/data-governance/data-views-and-classification#data-classification) lets you mark certain properties as classified, restricting visibility to only authorized users within your project.
  </Accordion>

  <Accordion title="What is the best way to send both client-side and server-side events?">
    The best practice for sending both client-side and server-side events in Mixpanel is to use a **hybrid approach**:

    * **Track critical business events** (such as purchases, sign-ups, and revenue events) **on the server side**. This ensures greater accuracy and reliability, as server-side events are not impacted by ad blockers, network interruptions, or client-side manipulation. Use Mixpanel’s server-side SDKs or direct API ingestion for this purpose.
    * **Track user interactions and UI events** (such as button clicks and page views) **on the client side**. These events reflect real-time user behavior that only occurs in the browser or app and are best captured using Mixpanel’s client-side SDKs.

    Learn more about [choosing the right tracking method](/docs/tracking-methods/choosing-the-right-method).
  </Accordion>

  <Accordion title="How do we ensure the data is accurate and implementation is correct?">
    To ensure your Mixpanel data is accurate and your implementation is correct, follow these best practices:

    1. **Use Separate Development and Production Projects:** Always set up at least two Mixpanel projects, one for development and one for production. Implement and test all tracking in the development project first. This prevents test or incorrect data from polluting your production analytics. Learn more about setting up [developer environments](/docs/tracking-best-practices/developer-environments).
    2. **Validate Events and Properties:** Use Mixpanel's Events view to confirm that events are arriving as expected. Manually trigger events and search for them using user-level identifiers (like `distinct_id`). Inspect event properties for correctness, data type, and naming conventions (Mixpanel is case sensitive). Learn more about [debugging your implementation](/docs/tracking-best-practices/debugging).
    3. **Iterate and Update Tracking Plan:** After each product update or when adding new events, update your tracking plan, get sign-off from a data governance owner, and repeat the QA process in the development project before deploying to production. Learn more about [creating a tracking plan](/docs/tracking-best-practices/tracking-plan) and establishing [data standards](/docs/data-governance/data-standards).
  </Accordion>

  <Accordion title="How do I anonymize an actual known user?">
    Mixpanel does not require any identifying information about users. You can generate a hash of a unique user ID (such as your internal user ID) and use that hash as the user's ID when calling the `.identify()` method in the SDKs. This way, the user cannot be traced back to their real identity, but you can still analyze their behavior in aggregate. The hash should only be reversible by you, not by Mixpanel or anyone else.

    To anonymize a user who has already been tracked, first export all data associated with that user. Then, delete the user's data using Mixpanel's GDPR-compliant deletion methods. After reviewing the exported data, remove any personally identifiable information (PII), and reimport the sanitized data as needed once the deletion has been fully processed.

    Learn more about [anonymizing users](/docs/privacy/protecting-user-data#anonymizing-users) and submitting [GDPR requests](/docs/privacy/end-user-data-management).
  </Accordion>
</AccordionGroup>

## Identity Management in Mixpanel

<AccordionGroup>
  <Accordion title="What is a distinct_id?">
    A **distinct\_id** in Mixpanel is the unique identifier used to track a user across events and profile updates. This ID allows Mixpanel to attribute actions and properties to the correct user, ensuring accurate analytics and reporting.

    When two events have the same distinct\_id, they are considered to be performed by the same unique user. If two events have different distinct\_ids, they are treated as coming from different users.

    Learn more about [identity management](/docs/tracking-methods/id-management).
  </Accordion>

  <Accordion title="How is distinct_id generated?">
    On the client side, the Mixpanel SDK automatically generates a random, unique `distinct_id` for anonymous users. When a user registers or logs in, you can assign a known user ID (such as a database ID) by calling the `identify` method in the SDK. The ID is then stored in the cookie or local storage for persistence.

    On the server side, you are responsible for generating both anonymous and known user IDs, as well as ensuring their consistency and persistence across events.

    Learn more about [identifying users](/docs/tracking-methods/id-management/identifying-users-simplified).
  </Accordion>

  <Accordion title="Where is distinct_id stored?">
    On the client side, the `distinct_id` is stored in the end user's device using cookies or local storage. If the user clears this data (or you call `reset()`), the SDK generates a new `distinct_id`.

    On the server side, your server is responsible for generating, maintaining, and persisting the `distinct_id` across events to ensure consistent user tracking.

    Learn more about [identifying users](/docs/tracking-methods/id-management/identifying-users-simplified).
  </Accordion>

  <Accordion title="What is the best practice for handling user identity in a client-side implementation?">
    As a best practice for client-side identity management:

    1. **Call `identify()`** during both registration and login, using a consistent user ID in each case to ensure proper user identification.
    2. **Call `reset()`** on logout to clear cookies or local storage and generate a new ID. This prevents unintended merging of data from multiple users sharing the same device.
    3. **Include your user ID** as both a super property and a user property. Doing so makes it easier to query and export data.

    Learn more about [identifying users](/docs/tracking-methods/id-management/identifying-users-simplified).
  </Accordion>

  <Accordion title="What is the best practice for handling user identity in a server-side implementation?">
    In a server-side implementation, you must generate and manage user IDs yourself. When a user is anonymous, generate a unique Anonymous ID (such as a UUID) and store it.

    If your project is using the [Simplified API](/docs/tracking-methods/id-management/identifying-users-simplified): For anonymous events, set the `$device_id` event property to this Anonymous ID. When the user is authenticated and you know their User ID, include both `$user_id` (your internal user ID) and `$device_id` (the original Anonymous ID) in all events sent from the server. Mixpanel will merge a pair of `$user_id` and `$device_id` the first time they are received together on an event.

    If your project is using the [Original API](/docs/tracking-methods/id-management/identifying-users-original): For anonymous events, set the `distinct_id` event property to this Anonymous ID. When the user is authenticated and you know their User ID, send a `$identify` event containing both the anonymous ID and the user ID to merge them together.

    Learn more about [the difference between the two identity management APIs](/docs/tracking-methods/id-management#identity-merge-apis).
  </Accordion>

  <Accordion title="How do I setup cross-domain tracking with Mixpanel?(Original API)">
    To set up cross-domain tracking with Mixpanel for projects using the Original ID Merge API, you need to ensure that the same user is recognized across different domains. The recommended approach is to pass the Mixpanel `distinct_id` from one domain to the next domain, typically via URL parameters. Then call `identify()` on the next domain using the `distinct_id` from the previous domain. For example:

    **On the First Domain:**

    * Retrieve the current user's `distinct_id` using the Mixpanel SDK.
    * When redirecting or linking to the second domain, append the `distinct_id` as a URL parameter.

    ```jsx theme={"system"}
    // On the first domain*
    var distinctId = mixpanel.get_distinct_id();
    var destinationUrl = "https://second-domain.com";
    var urlWithDistinctId = destinationUrl + (destinationUrl.indexOf('?') !== -1 ? '&' : '?') + "distinct_id=" + encodeURIComponent(distinctId);
    window.location.href = urlWithDistinctId;
    ```

    **On the Second Domain:**

    * Extract the `distinct_id` from the URL parameters.
    * Use `mixpanel.identify(distinctId)` before sending any events.

    ```jsx theme={"system"}
    // On the second domain
    var urlParams = new URLSearchParams(window.location.search);
    var distinctId = urlParams.get('distinct_id');
    if (distinctId) {
      mixpanel.identify(distinctId);
    }
    ```
  </Accordion>

  <Accordion title="How do I setup cross-subdomain tracking with Mixpanel?">
    To set up cross-subdomain tracking with Mixpanel, you should configure the Mixpanel JavaScript SDK to use cookies for persistence and enable the cross-subdomain cookie option. This ensures that the same Mixpanel distinct\_id and super properties are shared as users move between subdomains.

    ```jsx theme={"system"}
    // enable cross-subdomain cookie tracking
    mixpanel.init('YOUR_PROJECT_TOKEN', {
      cross_subdomain_cookie: true,
      persistence: 'cookie'
    });
    ```
  </Accordion>

  <Accordion title="How do I setup consistent user tracking across multiple platforms, such as a website and an app?">
    To ensure consistent user tracking across multiple platforms, apply identity management best practices:

    1. Call `identify(<user_id>)` during user registration and sign-in to associate activity with the correct user.
    2. Call `reset()` upon user logout to clear the current session and prevent data from carrying over.
    3. Use the same `user_id` for each individual user across all platforms to maintain a unified profile.

    Learn more about [identifying users](/docs/tracking-methods/id-management/identifying-users-simplified).
  </Accordion>

  <Accordion title="Why is the distinct_id shown in Mixpanel different from the ID I used to identify the user?">
    If you are using the [Original ID Merge API](/docs/tracking-methods/id-management/identity-management#identity-merge-apis) (check your project API [here](https://mixpanel.com/settings/project/id-management)), our API chooses one of the IDs inside the identity cluster to serve as the canonical distinct\_id for the user, meaning that it can be set to your chosen user ID or one of the Mixpanel-generated anonymous ID. This is programmatically selected by Mixpanel and not user-configurable.

    You can use any of the distinct\_ids inside of the identity cluster for ingestion, but only the canonical distinct\_id is used in queries and exports. As a best practice, we recommend setting your chosen user ID as a super property and profile property to make querying easier.
  </Accordion>

  <Accordion title="Why do I see data from 2 different users under a single Mixpanel profile?">
    Seeing data from two different users under a single Mixpanel profile is most commonly caused by improper identity management - specifically, not calling `reset()` when users log out on shared devices.

    If multiple users use the same device and you do not call `reset()` when a user logs out, the next user who logs in will inherit the previous user's distinct\_id. When you then call `identify()` with the new user's ID, Mixpanel merges the previous and new IDs into a single identity cluster. This causes events from both users to appear under the same profile.

    Learn more about [identifying users](/docs/tracking-methods/id-management/identifying-users-simplified).

    If your backend or frontend sends events for different users but uses the same distinct\_id, Mixpanel will attribute all those events to a single user profile.
  </Accordion>

  <Accordion title="Why do I see 2 duplicated Mixpanel user profiles sharing the same email value?">
    Mixpanel identifies users based on the `distinct_id` value. If the same user receives two different IDs, Mixpanel treats them as separate users, even if they share other properties.

    For instance, when you send data from multiple sources—such as web, mobile, or third-party tools like Segment or Shopify—and each source assigns a different identifier (e.g., email, user ID, or device ID), Mixpanel generates distinct user profiles for each ID, regardless of matching properties like email.

    To resolve this issue, review all data sources and ensure that each user is consistently assigned a single unifying user ID during identification across every platform.
  </Accordion>

  <Accordion title="What dev lift is involved when migrating from Legacy ID merge to Original or Simplified?">
    The development effort required to migrate from Legacy ID Management to Original or Simplified ID Merge in Mixpanel depends on which version you are moving to:

    Migrating to **Original ID Merge** typically involves minimal effort if your implementation already follows best practices (calling `alias` at user registration and `identify` at login using supported SDKs). In this case, Mixpanel can enable the migration for you, and no additional development work is required on your end. To proceed, contact the Support team for assistance with transitioning from the legacy API to the Original ID Merge API.

    Migrating to **Simplified ID Merge** requires significantly more effort. This path involves setting up a new project, updating your codebase, migrating data, and releasing app updates. The process is manual, and your engineering team will need to manage each step directly.

    Both ID Merge APIs offer substantial improvements over the legacy implementation, and we recommend that most projects migrate to one of these updated options.

    You can view [a comparison of the two ID Merge APIs](/docs/tracking-methods/id-management#identity-merge-apis). For further guidance, please [reach out to the support team](https://mixpanel.com/get-support).
  </Accordion>

  <Accordion title="Are there limitations with using Simplified ID vs Original ID merge?">
    Please see a summary of the pros and cons when choosing between the 2 ID Merge API versions [here](/docs/tracking-methods/id-management#identity-merge-apis).
  </Accordion>

  <Accordion title="What happens if a user clears cookies or reinstalls the app?">
    When you use Mixpanel’s client-side SDKs (e.g., JavaScript, iOS Swift, Android), clearing cookies, localStorage, or uninstalling the app removes the `distinct_id`, `$device_id`, and super properties from the user’s device. If the user returns to your website or reinstalls the app, the SDK will generate a new random `distinct_id` and `$device_id`.

    Once you call `identify` with the user’s known identifier, Mixpanel will reconcile the data and attribute it to the correct user profile in the Mixpanel UI.
  </Accordion>

  <Accordion title="Is there a limit to the number of identities that can be merged?">
    Projects using the **Original ID Merge API** can merge up to 500 IDs within a single identity cluster.

    Projects using the **Simplified ID Merge API** can merge an unlimited number of `$device_id` under one identity cluster; however, each cluster can contain only one `$user_id`.

    You can view [a comparison of the two ID Merge APIs](/docs/tracking-methods/id-management#identity-merge-apis).
  </Accordion>

  <Accordion title="How does Mixpanel handle merging IDs and what are the best practices?">
    Mixpanel handles merging IDs through a process called **ID Merge**, which groups different identifiers (such as anonymous device IDs and authenticated user IDs) into a single "identity cluster." This ensures all events from the same user (across devices, platforms, and sessions) are linked to one user profile.

    As a best practice for client-side implementation, call `identify()` at registration and sign in using a consistent `$user_id`, and call `reset()` at logout.

    For server-side implementation, your server is responsible for generating IDs for your users and maintaining ID persistence across events.

    Learn more about [identifying users](/docs/tracking-methods/id-management/identifying-users-simplified).
  </Accordion>

  <Accordion title="How does Mixpanel ensure data privacy and compliance?">
    Mixpanel neither require nor collects any personally identifying information about users, such as email addresses or phone numbers (unless you specifically provide the information to us). It only needs to associate a sequence of events with a specific user ID. You determine the user ID and decide how to transmit it to Mixpanel.

    If you prefer to analyze aggregate user behavior without the ability to identify individual users, we recommend creating a hash of a unique user identifier and using that hash as the user ID when invoking the `.identify()` method in our SDKs.

    Learn more about [protecting user data](/docs/privacy/protecting-user-data).
  </Accordion>

  <Accordion title="How does Mixpanel attribute campaign data when identities are set or changed?">
    When a user's identity is set or changes (for example, when a user moves from being anonymous to authenticated), Mixpanel automatically merges the anonymous activity with the identified user profile. This process ensures that all events and campaign attribution data collected in those events (such as UTM tags) while the user was anonymous are unified with their known profile once their identity is established. This allows for a complete view of the user's journey, including campaign touchpoints before and after identification.
  </Accordion>
</AccordionGroup>

## Building Mixpanel Reports and Analyses

<AccordionGroup>
  <Accordion title="How do I get started and what should I analyze?">
    Check out [our Guides](/guides/onboarding-overview) for a walk-through on how to plan, implement, and analyze in Mixpanel!
  </Accordion>

  <Accordion title="What are the best practices for setting up trusted boards for users to view and use?">
    Admin and Owners can [pin boards for users](/docs/boards#step-1-navigating-boards) so they appear prominently for all users. You can also encourage users to favorite boards they use most often.
  </Accordion>

  <Accordion title="How do I know my report is “correct”?">
    If you are worried about a report being correct, first confirm that the data is being tracked as expected. From there, [review the docs](/docs/reports) about the specific report to make sure you understand the logic behind it. If something looks off, try to find an example of a specific user or event that you thought should/shouldn’t be included in the report and see if there’s anything about that event/user that would lead to the behavior seen (ie is there a filter on the report, filtering out the event?). If you still need help, reach out to [Support via the web form](https://mixpanel.com/get-support) with a link to the report and some context on what looks off.
  </Accordion>

  <Accordion title="What are other companies in my industry tracking and creating reports for in Mixpanel?">
    Companies across industries track and create reports focused on the metrics most relevant to their business models. Check out [these case studies](https://mixpanel.com/customers/all) from Mixpanel customers to get ideas about what to track and how Mixpanel is being used in your industry. We also have [templates](/docs/boards/templates) and demo datasets for various industries (accessed through the ? menu) that are a helpful starting point for tracking.
  </Accordion>

  <Accordion title="How can I standardize what events my users use to create reports?">
    Organizations on enterprise plans can set [data standards](/docs/data-governance/data-standards) and [approve events](/docs/data-governance/event-approval) to ensure that the events users are using to create reports are standardized. All plans can add a description and [other metadata in Lexicon](/docs/data-governance/lexicon) to help users find the right events to use.
  </Accordion>

  <Accordion title="How do I edit and duplicate reports?">
    The [Reports](/docs/reports) doc has a lot of great information about editing reports. You can duplicate a report through the overflow (…) menu in the upper-right-hand corner of the report builder.
  </Accordion>

  <Accordion title="How do I filter reports?">
    The [Filters](/docs/reports#filters) section of the Reports doc goes over how to add inline and global filters. The filters work a bit differently in a Funnel report, which you can read about [here](/docs/reports/funnels/funnels-advanced#filters).

    You can also add [board-level filters](/docs/boards#step-5-board-wide-date-ranges-and-filters) to apply a global filter across all the reports on the board.
  </Accordion>

  <Accordion title="How can I get automated insights from alerts and setup anomaly detection?">
    Growth and Enterprise plans can create custom alerts based on reports. When an alert fires, Mixpanel’s AI-powered [Root Cause Analysis feature](/docs/root-cause-analysis) automatically diagnoses what drove the change — validating the anomaly, ranking the dimensions that contributed most, and generating a Board with an AI-written interpretation, confidence level, and suggested next steps.

    Organizations with enterprise plans can also set up [anomaly detection alerts](/docs/features/alerts#anomaly-detection) to automatically monitor their metrics and notify you when significant anomalies occur.

    Learn more about custom alerts [here](/docs/features/alerts).
  </Accordion>

  <Accordion title="What are the common analysis types done in Mixpanel?">
    The most common analysis is done in the four core reports:

    * [Insights](/docs/reports/insights): Visualize trends and compositions within your data
    * [Funnels](/docs/reports/funnels/funnels-overview): Measure conversions through a series of events
    * [Retention](/docs/reports/retention): Measure engagement over time
    * [Flows](/docs/reports/flows): See frequent paths taken by users to or from any event

    Check out [templates](/docs/boards/templates) and demo datasets for various industries (accessed through the ? menu) to get a feel for popular metrics.
  </Accordion>

  <Accordion title="How can I collaborate and share within Mixpanel?">
    The [Sharing and Permissions](/docs/boards/sharing-and-permission) doc has information sharing reports. [Custom properties](/docs/features/custom-properties), [cohorts](/docs/users/cohorts), and [custom events](/docs/features/custom-events) can also be shared explicitly with users or across the project. You’ll be prompted to save and share those entities after creation.
  </Accordion>

  <Accordion title="What is the difference between a Metric and Behavior?">
    Metrics measure the performance, progress, or success of different aspects of your product or business. They are always measurements which are based on a single event, behavior, cohort, or profile.

    Behaviors are reusable definitions for Simple, Funnel, or Retention analyses. They allow teams to standardize definitions of key user flows and ensure consistency across different analyses.
  </Accordion>
</AccordionGroup>

## Exporting Data from Mixpanel

<AccordionGroup>
  <Accordion title="How do data pipeline exports work? How is the data structured and what can I expect?">
    Data Pipelines is a feature that exports data from your Mixpanel project to a Cloud Storage bucket or Data Warehouse of your choice. It is available as an add-on for Growth and Enterprise plans. You can read more about the setup and exported data in the [Data Pipelines doc](/docs/data-pipelines).
  </Accordion>

  <Accordion title="How can I export my data from Mixpanel?">
    Event data can be exported via the [Export API](/reference/raw-data-export-api), while user profile data can be exported via the [Engage API](/reference/engage-query). We also have a handy [Mixpanel-utils Python module](https://github.com/mixpanel/mixpanel-utils#export-events) that hits the APIs directly.

    Alternatively, you can purchase the [Data Pipelines](/docs/data-pipelines) add-on to export data directly to cloud storage or a data warehouse.

    Learn more about exporting data [here](/docs/export-methods).
  </Accordion>

  <Accordion title="Can I automate data exports (e.g., schedule CSV delivery or direct warehouse sync)?">
    If you have the [Data Pipelines](/docs/data-pipelines) add on, data will automatically be synced to your warehouse at the scheduled cadence (daily or hourly).

    At a board level, you can set up a [board subscription](/docs/boards#board-subscriptions) to automatically receive a snapshot of a board sent as an email or a Slack message. It isn’t possible to schedule a CSV delivery of a specific report within the UI. However, the [Query API](/reference/query-api) can be used by paid plans to export report data on your end.
  </Accordion>

  <Accordion title="Is there an additional cost for exporting data?">
    It depends on how you want to export the data! All plans can access the [Export API](/reference/raw-data-export-api) to export event data at no additional cost. Profile data can be exported from the [Engage API](/reference/engage-query) at no cost as well.

    The [Query API](/reference/query-api) is included for Growth and Enterprise plans. If you want to use [Data Pipelines](/docs/data-pipelines) to export the data, you would need to purchase it as an add-on.
  </Accordion>

  <Accordion title="Can I export specific data, such as cohorts, user lists, or raw events?">
    Yes! You can see a list of [specific APIs here](/reference/overview) to export event, report, and user data. A [cohort sync](/docs/cohort-sync) can be used to export cohorts. Learn more about exporting data [here](/docs/export-methods).
  </Accordion>

  <Accordion title="What if my data warehouse is not natively supported?">
    You can use a [reverse ETL (rETL) tool such as Census or Hightouch](/guides/implement/send-your-data#data-warehouses). These third-party tools allow you to transform and schedule syncs from your warehouse to Mixpanel, even if your warehouse isn’t directly supported. Another option is to use Mixpanel’s Import API to send data directly from your warehouse to Mixpanel.
  </Accordion>
</AccordionGroup>

## Manage your Mixpanel Projects and Teammates

<AccordionGroup>
  <Accordion title="How should we structure our Mixpanel projects?">
    It's recommended to set up at least two separate projects: one for Development data and another for Production data. This separation ensures that test data doesn’t mix with your live user data. The [Setup guide](/guides/plan/setup#development-and-production-project-setup) has more information.

    Organizations on an enterprise plan can also use [Data Views](/docs/data-governance/data-views-and-classification) within a single Mixpanel project. Data Views allow you to create focused “mini-projects” that display only the events and properties relevant to a specific team, function, or use case.
  </Accordion>

  <Accordion title="How do we keep things organized within a Mixpanel project for multiple teams?">
    Organizations on an enterprise plan can use [Data Views](/docs/data-governance/data-views-and-classification) to create focused “mini-projects” that display only the events and properties relevant to a specific team, function, or use case.

    Outside of data views, you can have teams implement standardized ways to name and describe reports to keep things organized.
  </Accordion>

  <Accordion title="Who should own and maintain Mixpanel projects?">
    It depends on your organization and goals. This blog post, [A guide to data governance for product teams](https://mixpanel.com/blog/what-is-data-governance/), goes into best practices for setting up product analytics. You can also check out the [Implement section](/guides/implement/establish-governance) of the guides.
  </Accordion>

  <Accordion title="How do we onboard new teammates and empower them to use Mixpanel?">
    The first step is giving them access to Mixpanel. The [Roles & Permissions](/docs/orgs-and-projects/roles-and-permissions#overview) doc has information about how to invite additional users. They can check out the [Launch guide](/guides/guides-by-topic/core-reports/create-boards) for a guided walkthrough of the Mixpanel features and reports.

    We also have a [training template](/docs/boards/templates#training-board-for-champions-to-use-to-educate-users) that can be set up in the project. This will walk the user through the reports in Mixpanel itself. You can set it up as a [pinned board](/docs/boards#step-1-navigating-boards) so its visible to all users.
  </Accordion>

  <Accordion title="How can we audit or review how our team is using Mixpanel?">
    Organization owners and admins can see information about Mixpanel usage in the Organization settings, under the ‘Mixpanel Usage’ tab. This lets you see active users and popular boards and reports.

    You can see specific event and property utilization in each [project's Lexicon](/docs/data-governance/lexicon).
  </Accordion>

  <Accordion title="How do we support and decentralize Mixpanel expertise within our organization?">
    Check out the following blog posts to learn more about how to support and decentralize Mixpanel expertise:

    * [5 ingredients for better data collaboration](https://mixpanel.com/blog/how-to-better-data-collaboration/)
    * [Data democratization explained: Benefits, challenges, and best practices](https://mixpanel.com/blog/data-democratization/)
    * [How to get product and analytics teams at large companies working together in lockstep](https://mixpanel.com/blog/product-and-analytics-teams-working-together-self-serve/)
    * [How to establish a product analytics practice](https://mixpanel.com/blog/establish-a-product-analytics-practice/)
  </Accordion>
</AccordionGroup>

## Protecting User Data and Privacy

<AccordionGroup>
  <Accordion title="How can users opt out of tracking?">
    When building your Mixpanel implementation, you can use the opt-out methods provided in Mixpanel’s client-side SDKs to offer users to ability to opt out of tracking. You can also initialize client-side SDKs to have users opted out by default until they opt in. The [Protecting User Data doc](/docs/privacy/protecting-user-data) has more information.
  </Accordion>

  <Accordion title="Where can I learn more about user privacy regulations and opting users out of tracking?">
    The [Privacy](/docs/privacy) section of the docs has information around privacy regulations. This includes the [Protecting User Data](/docs/privacy/protecting-user-data) doc, which goes into how to opt users out and includes FAQs. There is also the [GDPR compliance](/docs/privacy/gdpr-compliance) doc for GDPR-specific information.
  </Accordion>

  <Accordion title="How can we anonymize users and avoid sending PII?">
    Mixpanel does not know, or need to know, any identifying information about users (like email or phone number). Mixpanel only needs to know that a set of events were performed by a particular user ID. You choose the ID and you choose how you want to send that ID to Mixpanel. The [Protecting User Data](/docs/privacy/protecting-user-data) doc has more information.
  </Accordion>

  <Accordion title="How do we disable geolocation or prevent IP address usage?">
    The exact method will depend on the SDK being used. See the [Disabling Geolocation](/docs/privacy/protecting-user-data#disabling-geolocation) section of the docs for more information, along with the [Geolocation](/docs/tracking-best-practices/geolocation) doc.
  </Accordion>

  <Accordion title="How do we handle the accidental sending of PII?">
    If you accidentally send PII, you can use the data deletion feature to remove it. The [Data Clean-up](/docs/data-governance/data-clean-up#2-deleting-problematic-data) doc has more information. If that doesn’t work for your specific event data, have an organization or project owner open a ticket with [Support via the web form.](https://mixpanel.com/get-support)

    User profile data can be deleted via the [Engage API](/reference/delete-profile).
  </Accordion>
</AccordionGroup>