> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mixpanel as a data source
> Bring event data from Mixpanel to Nekt.
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](https://developer.mixpanel.com/reference/raw-export) to replicate raw event data into Nekt.
## Configuring Mixpanel as a Source
In the [Sources](https://app.nekt.ai/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.
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](https://docs.nekt.com/get-started/core-concepts/triggers), 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](https://docs.nekt.com/get-started/core-concepts/resource-control).
* **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#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](https://app.nekt.ai/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](https://app.nekt.ai/catalog).
# Streams and Fields
The Mixpanel connector exposes one stream: **events**. It corresponds to the [Mixpanel Export API](https://developer.mixpanel.com/reference/raw-export) and returns one row per event.
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 | Unique identifier for the event. Generated from a hash of the event payload to ensure data integrity and proper deduplication. |
| `event` | String | The event name (e.g. `"Page View"`, `"Sign Up"`, `"Purchase"`). |
| `time` | Integer | Event timestamp. Stored in milliseconds (API is called with `time_in_ms: true`). |
| `properties` | String | Full set of event properties as a JSON string. Includes Mixpanel reserved properties (e.g. `$insert_id`, `time`, `distinct_id`, `$user_id`) and any custom properties you send. |
**Notes:**
* **Primary key**: The stream uses a hashed ID based on the event payload to ensure proper deduplication and data integrity.
* **Replication**: The stream uses `time` as the replication key. Incremental syncs request only events from the last replicated timestamp onward.
* **Pagination**: The connector requests data in **monthly** date ranges (from `start_date` or state to "now") to respect API behavior and avoid timeouts on large projects.
* **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).
**Example `properties` (conceptual):**
```json theme={null}
{
"$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 a hash of the event payload, `event` will be the event name, `time` will be `1704067200000`, 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 ordered by `time`.
```mermaid theme={null}
erDiagram
EVENTS {
string id PK
string event
integer time
string properties
}
```
# 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](https://app.nekt.ai/explorer) or downstream models, parse the JSON and expose the keys as separate columns. The example below selects common Mixpanel fields (`distinct_id`, `$user_id`, `utm_source`, `utm_campaign`, `revenue`) and the event timestamp; adjust the keys to match your own properties.
```sql theme={null}
SELECT
id,
event,
time,
from_unixtime(time / 1000) AS event_time,
json_extract_scalar(properties, '$.distinct_id') AS 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
time >= to_unixtime(current_date - interval '30' day) * 1000
```
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.
```sql theme={null}
SELECT
id,
event,
time,
TIMESTAMP_MILLIS(time) AS event_time,
JSON_VALUE(properties, '$.distinct_id') AS 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
time >= UNIX_MILLIS(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](https://docs.nekt.com/get-started/core-concepts/transformations) 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. |
| Duplicate or missing events | State or date range issue | For incremental syncs, check that state is being saved (e.g. successful run completion). For full syncs, ensure Start date covers the desired period. |
| Large extractions slow or timing out | Very high event volume in one project | The connector already paginates by month. If needed, reduce the sync frequency or split the project (e.g. by data pipeline) in Mixpanel. |
| 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. |
## Skills for agents
Mixpanel connector documentation as plain markdown, for use in AI agent contexts.