# Mixpanel

Mixpanel is a product analytics platform that helps teams understand user behavior. The Sling Mixpanel connector extracts data from the Mixpanel API, supporting raw event exports and user profiles.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials are accepted:

**Secrets:**

* `username` **(required)** -> Service Account Username
* `secret` **(required)** -> Service Account Secret
* `project_id` **(required)** -> Mixpanel Project ID

**Inputs (optional):**

* `anchor_date` -> Starting date for first sync (defaults to 1 year ago)
* `base_url` -> Override the base URL (defaults to `https://mixpanel.com`)
* `export_base_url` -> Override the export base URL (defaults to `https://data.mixpanel.com`)

### Getting Your Credentials

1. Log in to [Mixpanel](https://mixpanel.com)
2. Go to **Settings** (gear icon) → **Organization Settings** → **Service Accounts**
3. Click **Add Service Account**
4. Give the account a name (e.g., "Sling Integration") and select the **Consumer** role
5. Click **Create** and note the **Username** and **Secret**
6. Go to **Settings** → **Project Settings** to find your **Project ID** (also visible in the URL)

{% hint style="info" %}
**Data Residency:** If your Mixpanel project is in the EU data center, set `base_url` to `https://eu.mixpanel.com` and `export_base_url` to `https://data-eu.mixpanel.com`.
{% endhint %}

{% hint style="warning" %}
**Important:** Service account credentials grant access to your Mixpanel project data. Keep your secret secure and never share it publicly.
{% endhint %}

### Using `sling conns`

Here are examples of setting a connection named `MIXPANEL`. We must provide the `type=api` property:

{% code overflow="wrap" %}

```bash
sling conns set MIXPANEL type=api spec=mixpanel secrets='{ username: "your_service_account_username", secret: "your_service_account_secret", project_id: "your_project_id" }'
```

{% endcode %}

### Environment Variable

{% code overflow="wrap" %}

```bash
export MIXPANEL='{ type: api, spec: mixpanel, secrets: { username: "your_service_account_username", secret: "your_service_account_secret", project_id: "your_project_id" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  MIXPANEL:
    type: api
    spec: mixpanel
    secrets:
      username: "your_service_account_username"
      secret: "your_service_account_secret"
      project_id: "your_project_id"
```

## Replication

Here's an example replication configuration to sync Mixpanel data to a PostgreSQL database:

```yaml
source: MIXPANEL
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: mixpanel.{stream_name}

streams:
  engage:
  export:
    mode: incremental
```

## Endpoints

| Endpoint  | Description                             | Incremental | Depends On |
| --------- | --------------------------------------- | ----------- | ---------- |
| `engage`  | User profiles (people)                  | No          | —          |
| `export`  | Raw events by date range                | Yes         | —          |
| `cohorts` | Cohort definitions (requires paid plan) | No          | —          |

To discover available endpoints:

```bash
sling conns discover MIXPANEL
```

### Endpoint Details

**`engage`** — Returns all user profiles in the project, including custom properties, last seen timestamps, and geographic data. Uses session-based pagination to iterate through all profiles.

**`export`** — Returns raw events by date range. Iterates day by day from the anchor date (or last sync date) to yesterday. Supports incremental sync — after the first full extraction, subsequent runs only fetch new days. Supports backfill via the `range` source option.

**`cohorts`** — Returns all cohort definitions in the project. This endpoint requires a paid Mixpanel plan (returns 402 on free plans). Disabled by default.

## Incremental Sync

The `export` endpoint supports incremental sync using date-based iteration:

* **First run:** Fetches all events from the `anchor_date` (default: 1 year ago) to yesterday
* **Subsequent runs:** Only fetches events from the last synced date onward

To customize the starting date:

```yaml
connections:
  MIXPANEL:
    type: api
    spec: mixpanel
    secrets:
      username: "..."
      secret: "..."
      project_id: "..."
    inputs:
      anchor_date: "2024-01-01"
```

### Backfill

To backfill a specific date range, use the `range` source option:

```yaml
source: MIXPANEL
target: MY_POSTGRES

defaults:
  object: mixpanel.{stream_name}

streams:
  export:
    mode: incremental
    source_options:
      range: "2024-01-01,2024-06-30"
```

The `engage` endpoint runs in full-refresh mode since user profiles represent the current state.

## Rate Limiting

The Mixpanel API enforces rate limits, especially on the free plan:

* **Export API:** Strict rate limits on the data export endpoint
* **Query API (engage, cohorts):** Separate rate limit pool

The connector automatically:

* Uses conservative rate limiting (1 request/second)
* Processes export dates sequentially (concurrency of 1) to respect rate limits
* Retries with exponential backoff on 429 (rate limit) responses
* Allows up to 5 retry attempts with a base backoff of 10 seconds

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).
