Mixpanel

Mixpanel is the supported way to import product usage from a product analytics tool. Sonora runs aggregate queries against your project and stores one value per account per day for each metric you define. It never reads raw events, and it never exports them.

Authentication uses a Mixpanel service account scoped to a single project. You create it, paste its secret into Sonora once, and Sonora stores it encrypted. The secret is never shown again, anywhere.

What Sonora reads

A Mixpanel connection imports product usage only. Customer records have to come from a CRM connection (Salesforce or HubSpot) or another customer source. Mixpanel usage then matches to those customers through an event property that names the account.

You define metrics in Sonora, not in Mixpanel. Each metric is one event plus a way to count it:

• Users — distinct users who did the event, per account. Sonora counts them separately per day, per ISO week (starting Monday) and per calendar month, so weekly and monthly active users are true distinct counts, never the days added up. (The exception is a named-event filter of the kind Any event refuses: one clause testing both event and profile properties, or the two combined with or. That metric imports daily counts only, and its weekly and monthly views show the average day.) This is “active users per account”, the metric most worth having.
• Events — how many times the event happened, per account per day. Sonora adds days up into weeks and months.

A metric can also count across any event instead of one. Users with any activity per account per day is the closest thing to Mixpanel’s “Session Start”, which exists only inside Mixpanel’s own reports and cannot be queried. Use it when no single event stands for “used the product”.

Each metric costs one Mixpanel query per sync, whatever the number of accounts. Ten metrics is ten queries whether you have forty customers or four thousand.

Prerequisites

• Owner or Admin on the Mixpanel project, needed once to create the service account
• An event property on your tracked events that identifies the customer account (for example company_id, account_id, or company_domain)
• A configured customer source in Sonora to match those account values against

You do not need Mixpanel’s Group Analytics add-on. Sonora segments on a plain event property and counts distinct users within each segment.

Setup

1. Create a project-scoped service account

1. In Mixpanel, open Project Settings → Service Accounts. Use the project settings, not the organization’s: an organization-level service account can reach every project in the organization.
2. Click Add Service Account.
3. Give it the Consumer role. Consumer is view-only, which is all Sonora needs.
4. Optionally set an expiration date. Mixpanel gives no other warning before an expired account stops working, so if you set one, record it in Sonora in the next step.
5. Copy the username and the secret. Mixpanel shows the secret exactly once. If you lose it, create a new service account; there is no way to reveal it later.

2. Find the project ID and data residency

• The project ID is the number in Project Settings → Overview. It is not the project name.
• The data residency region is also on that page: US, EU, or India. Sonora must send requests to the matching host. The wrong region fails authentication rather than redirecting.
• Note the project timezone on the same page. Mixpanel reports every day in that timezone, and Sonora uses it to place each day correctly.

3. Connect in Sonora

In Settings → Integrations → Mixpanel → Configure:

1. Enter the project ID, choose the data residency region, and enter the project timezone as an IANA name (for example America/Los_Angeles).
2. Paste the service account username and secret. Record the expiry if you set one.
3. Click Test Connection. The test checks the username, secret, project ID, and region together, because any one of them can be wrong on its own.

4. Tell Sonora how accounts are named

Under Accounts:

• Account property — the event property whose value identifies the customer account.
• The property holds — what kind of value it is, so Sonora knows how to match it:
  • Salesforce account ID or HubSpot company ID when your app stamps CRM IDs onto events
  • Email domain when the property holds a domain, an email address, or a URL
  • Company name when it holds the customer’s name
• Default product — the Sonora product these metrics describe. Individual metrics can override it.

Events whose account property is missing are skipped, not attributed to anyone.

5. Define metrics

Click Load event names to pull the list of events from your project, then add a row per metric: a name, an event, and whether to count Users or Events. An optional filter accepts a Mixpanel segmentation expression, for example properties["plan"] == "enterprise" or, on a profile property, user["user_type"] == "customer".

Turn on Any event to count across every event in the project. Its filter may test event properties and profile properties, but a clause tests one or the other, and the clauses combine with and only: properties["plan"] == "enterprise" and user["user_type"] == "customer" works, properties["plan"] == "enterprise" or user["user_type"] == "customer" does not.

Start with distinct users of your core event. That gives you weekly active users per customer once a few days have synced.

6. Choose a window and, optionally, a backfill

• Trailing window — how many days each sync re-queries (default 7). Late-arriving events land on the next sync without any special handling.
• Backfill from — an optional start date for history. Sonora fetches history one month at a time across several syncs so it stays inside Mixpanel’s hourly query budget. A 12-month backfill of 10 metrics finishes in about three daily syncs. The Accounts panel shows how far the backfill has reached.

A daily schedule is the right fit. Sonora keeps well under Mixpanel’s limit of 60 queries per hour per project, but that budget is shared with anything else your team runs against the same project.

Rotating the secret

Paste the new secret into the secret field, save, and test. Nothing else needs to change. The stored secret is kept whenever you save the configuration without typing a new one.

Troubleshooting

“Mixpanel rejected the service account” — Check the username and secret, then check the region. A project stored in the EU or India fails authentication on the US host with exactly this error.

“Mixpanel refused access to this project” — The service account is valid but not for this project. Confirm the project ID is the number from Project Settings, and that the service account was created inside this project.

“Service account has passed its declared expiry” — Mixpanel expired the account on the date you recorded. Create a new service account and paste its secret.

Days look shifted by one — The project timezone in Sonora does not match the one in Mixpanel’s Project Settings. Correct it and re-sync; the trailing window rewrites the affected days.

The import failed with “returned only the first 10,000 accounts” — Mixpanel caps a query at 10,000 account segments, and accounts past the cap are missing rather than zero. Narrow the metric with a filter, or split it across products, so each query stays under the cap.

Many accounts not matched — Check that the account property really holds what you said it holds. A property that carries an internal ID matches nothing when it is declared as a Salesforce ID; declaring it as a company name or domain, if that is what your customers are keyed by, usually resolves it.