Mixpanel is a product analytics platform that helps teams understand how users interact with their products. It tracks events, user properties, and funnels so you can analyze behavior and improve conversion. The Nekt connector uses the Mixpanel Data Export API to replicate raw event data into Nekt.

Configuring Mixpanel as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Mixpanel option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

You need Mixpanel API credentials with access to the Data Export API. Use a service account (username) and its secret for authentication. The following configurations are available:

Project ID: The Mixpanel project ID you want to extract events from. You can find it in your Mixpanel project settings (e.g. Settings > Project Settings > Project ID). This field is required.
Username: The username used to authenticate against the API. This is typically a service account username. Mixpanel recommends using a service account for programmatic access. This field is required.
Secret: The secret (password) for the service account or user. This value is stored securely and is never displayed after saving. This field is required.
Start date: The earliest date from which records will be synced. Used for the first full sync and when no previous state exists. Format: YYYY-MM-DD. This field is required.
Region: The data residency region of your Mixpanel project: United States (US), Europe (EU) or India (IN). Leave empty for US-hosted projects. Projects hosted in the EU or India must set this, otherwise Mixpanel answers the export with terminated early and the run fails.
Export window (days) (Advanced): Number of days covered by the first request to the Mixpanel Export API. Smaller windows keep each response short, so a dropped connection costs little to retry. Increase only for low-volume projects. The connector times this first request and sizes the remaining ones from that measurement (see the Pagination note under Streams and Fields). Default is 1.
Parallel export windows (Advanced): How many export windows to download at the same time. Raising this helps when a sync spends most of its time waiting on Mixpanel rather than working, which is the usual case for a large backfill. On a fast connection, extra windows may compete for the same processor instead. Default is 4, maximum is 16.

Once you’re done, click Next.

2. Select streams

The Mixpanel connector exposes a single stream: events. Choose whether to sync it. Select the stream and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for the table (which will contain the fetched events), and the type of sync.

Layer: Choose between the existing layers on your catalog. This is where you will find your new extracted table once the extraction runs successfully.
Folder: A folder can be created inside the selected layer to group all tables from this data source.
Table name: A default name is suggested; you can change it. You can add a prefix to all tables at once to speed up configuration.
Sync Type: You can choose between INCREMENTAL and FULL_TABLE.
- Incremental: Each run fetches only events since the last replicated timestamp. Recommended for ongoing syncs so you keep every event without re-reading full history.
- Full table: Each run re-exports events from the configured start date (or from the beginning). Use when you need to backfill or fully refresh the dataset.

Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted. For event data, common choices are:

Daily: Typical for analytics and reporting.
Every 12 hours or hourly: For more up-to-date event pipelines.
Weekly: For lighter reporting needs.

Optionally, you can define:

Delta Log Retention: How long to keep old states of the table. See Resource control.
Additional Full Sync: Run a full export periodically in addition to incremental syncs.

When you are ready, click Next to finalize the setup.

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once the run completes successfully, data will appear in your Catalog.

You need at least one successful source run to see the table in your Catalog.

Streams and Fields

The Mixpanel connector exposes one stream: events. It corresponds to the Mixpanel Export API and returns one row per event.

Events

Stream of raw analytics events from your Mixpanel project. Each record is a single event (e.g. page view, signup, purchase) with a unique insert ID, event name, timestamp, and a JSON blob of event properties.Key fields:

Field	Type	Description
`id`	String	Stable identifier for the event, derived from the fields Mixpanel uses to identify one: event name, distinct ID, timestamp and insert ID. Deduplicates the same event across re-syncs, which raw exports do not do themselves.
`event`	String	The event name (e.g. `"Page View"`, `"Sign Up"`, `"Purchase"`).
`time`	Integer	The event timestamp, in milliseconds since the Unix epoch, exactly as the Export API returns it.
`event_time`	DateTime	The event timestamp as a UTC timestamp, derived from `time`.
`distinct_id`	String	Mixpanel’s identifier for the user who triggered the event.
`insert_id`	String	The `$insert_id` Mixpanel uses to recognise duplicate events, when the sender supplied one. Empty for events sent without it.
`mp_processing_time_ms`	Integer	When Mixpanel’s servers processed the event, in milliseconds since the Unix epoch, as opposed to when it occurred. Orders repeat sends of the same event.
`properties`	String	Full set of event properties as a JSON string. Includes Mixpanel reserved properties and any custom properties you send.

Notes:

Primary keys: The stream uses id and event_time to ensure proper deduplication and data integrity.
Replication: The stream uses event_time as the replication key. Incremental syncs request only events from the last replicated timestamp onward. Because the Export API works in whole dates, the day containing the bookmark is downloaded again; events strictly before the bookmark are discarded before loading, so nothing is re-written.
Pagination: The connector requests data in short, configurable date ranges (defaulting to 1-day windows from start_date or state to “now”) to respect API behavior and avoid timeouts on large projects. The first window is downloaded alone and timed; that measurement sizes the remaining windows (between 1 and 90 days each) so that a quiet project spends fewer of its hourly requests while a busy project keeps every response short. The remaining windows are then downloaded concurrently, up to the Parallel export windows setting.
Untimed events: Mixpanel can occasionally return events without a time property. Because these cannot be placed in a timeline, deduplicated, or bookmarked, the connector skips them and logs a single warning summary at the end of the sync.
Properties: All event properties (including nested objects) are serialized into the properties JSON string. To use them in SQL or BI tools, parse JSON in your transformations (e.g. JSON_EXTRACT / json_extract or flatten into columns). Many core properties like distinct_id and $insert_id are already extracted into native columns for convenience.

Example properties (conceptual):

{
  "$insert_id": "abc-123",
  "time": 1704067200000,
  "distinct_id": "user_456",
  "$user_id": "user_456",
  "$device_id": "device_789",
  "utm_source": "google",
  "utm_campaign": "winter_sale",
  "revenue": 99.99
}

In the stream, id will be derived from the event’s identity fields, event will be the event name, time will be 1704067200000, event_time will be the corresponding UTC datetime, and the full object above will appear in properties as a string.

Data Model

The connector has a single stream. Events are identified by id and event_time, and they are ordered by event_time.

Transformation example: pivoting properties to columns

The properties column stores all event attributes as a single JSON string. To analyze dimensions like user ID, UTM fields, or revenue in Explorer or downstream models, parse the JSON and expose the keys as separate columns. The example below selects common Mixpanel fields ($user_id, utm_source, utm_campaign, revenue) from the properties, alongside native columns like distinct_id and event_time. Adjust the keys to match your own custom properties.

SQL transformation (AWS Athena / GCP BigQuery)

AWS (Athena)
GCP (BigQuery)

SELECT
   id,
   event,
   time,
   event_time,
   distinct_id,
   json_extract_scalar(properties, '$.$user_id')        AS user_id,
   json_extract_scalar(properties, '$.utm_source')      AS utm_source,
   json_extract_scalar(properties, '$.utm_campaign')    AS utm_campaign,
   CAST(json_extract_scalar(properties, '$.revenue') AS DOUBLE) AS revenue
FROM
   nekt_raw.mixpanel_events
WHERE
   event_time >= current_date - interval '30' day

Replace nekt_raw.mixpanel_events with your actual layer and table name. Use json_extract_scalar() for string properties; for numeric properties use CAST(json_extract_scalar(properties, '$.key') AS DOUBLE). Property names with $ (e.g. $user_id) are referenced as '$.$user_id' in the JSON path.

SELECT
   id,
   event,
   time,
   event_time,
   distinct_id,
   JSON_VALUE(properties, '$.$user_id')        AS user_id,
   JSON_VALUE(properties, '$.utm_source')       AS utm_source,
   JSON_VALUE(properties, '$.utm_campaign')    AS utm_campaign,
   SAFE_CAST(JSON_VALUE(properties, '$.revenue') AS FLOAT64) AS revenue
FROM
   `nekt_raw.mixpanel_events`
WHERE
   event_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)

Replace nekt_raw.mixpanel_events with your actual dataset and table name. Use JSON_VALUE() for string properties; for numeric properties use SAFE_CAST(JSON_VALUE(properties, '$.key') AS FLOAT64). Property names with $ (e.g. $user_id) are referenced as '$.$user_id' in the path.

You can run this as an ad-hoc query in Explorer or turn it into a transformation that writes to a new table so you have a flattened view of Mixpanel events for reporting and joins.

Troubleshooting

Issue	Possible cause	Solution
Authentication errors	Wrong username or secret	Verify service account (or user) and secret in Mixpanel (e.g. Project Settings > Service Accounts). Ensure the account has Data Export access.
No data / empty table	Start date in the future or no events in range	Check Start date and the project’s time zone. Confirm that the project has events in the requested date range in Mixpanel.
Run fails with “Mixpanel returned ‘terminated early‘“	Wrong data residency region	The project is hosted in a different region than the one configured. Set Region to EU or IN to match your Mixpanel project.
Duplicate or missing events	State, date range issue, or missing timestamps	For incremental syncs, check that state is being saved (e.g. successful run completion). For full syncs, ensure Start date covers the desired period. Events missing a `time` property in Mixpanel are skipped; the run log ends with a warning summarizing how many.
Run is slower than usual and the log mentions pacing or the hourly limit	Mixpanel’s export rate limit was reached	Expected behavior. Mixpanel allows 60 export requests per hour per project, so the connector spaces its requests and waits out `429 Too Many Requests` responses automatically. Long backfills take longer for this reason; no action is needed. Other integrations exporting from the same project share this budget.
Large extractions slow or timing out	Very high event volume in one project	The connector defaults to 1-day pagination windows to handle large volumes. Ensure the Export window (days) setting is kept small (default is 1). For backfills, raising Parallel export windows helps when the download from Mixpanel is the bottleneck. If needed, reduce the sync frequency or split the project.
Need custom properties in columns	Properties are in JSON string	Add a Query (SQL) or Notebook (Python) that parses `properties` and selects or flattens the fields you need.

Implementation Notes

Rate Limiting and Retries

The Mixpanel Raw Export API enforces strict per-project limits, most notably 60 export requests per hour and 3 requests per second. The connector paces its requests to stay within that budget (shared across all parallel windows) and handles 429 Too Many Requests responses by waiting as long as Mixpanel’s Retry-After header asks, or by following an escalating wait schedule when the header is absent, before sending the same request again. A download interrupted mid-window is retried as a unit, up to six more times over roughly 34 minutes, and the records already received are re-emitted safely because the target deduplicates on id. Because of this pacing and retry logic, historical backfills or full syncs spanning long periods may take significantly longer than usual to complete; this is expected and no user action is required.

Sync Progress Estimation

During full syncs or large backfills, Mixpanel does not provide a total event count upfront. To provide visibility into the extraction progress, the connector dynamically estimates the total record count based on the average volume of events in completed pagination windows. This estimate updates as the sync progresses, offering a reliable order-of-magnitude projection.

Performance Optimizations

The connector is specifically tuned to handle high event volumes efficiently. It leverages msgspec for rapid message serialization and bypasses redundant type conformance checks (since all extracted properties are mapped to string or integer fields), reducing CPU overhead and maximizing end-to-end throughput. Export windows are downloaded by parallel workers while records are parsed on a single consumer, so the concurrency overlaps network waits rather than competing for the processor.

Skills for agents

Download Mixpanel skills file

Mixpanel connector documentation as plain markdown, for use in AI agent contexts.

Get started

Context

Activate

Workspace

Resources

Mixpanel as a data source

Configuring Mixpanel as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Data Model

Transformation example: pivoting properties to columns

Troubleshooting

Implementation Notes

Rate Limiting and Retries

Sync Progress Estimation

Performance Optimizations

Skills for agents

Download Mixpanel skills file

​Configuring Mixpanel as a Source

​1. Add account access

​2. Select streams

​3. Configure data streams

​4. Configure data source

​5. Check your new source

​Streams and Fields

​Data Model

​Transformation example: pivoting properties to columns

​Troubleshooting

​Implementation Notes

​Rate Limiting and Retries

​Sync Progress Estimation

​Performance Optimizations

​Skills for agents

Download Mixpanel skills file

Configuring Mixpanel as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Data Model

Transformation example: pivoting properties to columns

Troubleshooting

Implementation Notes

Rate Limiting and Retries

Sync Progress Estimation

Performance Optimizations

Skills for agents