> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Mixpanel

> Sync product analytics data from Mixpanel: raw events, user and group profiles, cohorts, funnels, and annotations.

Sync product analytics data from Mixpanel: raw events, user and group profiles, cohorts, funnels, and annotations.

<Tabs>
  <Tab title="Overview">
    Connect Parable to Mixpanel for product analytics using HTTP Basic authentication with an organization service account. Parable syncs raw events, user profiles, cohorts, funnels, and optionally annotations and group profiles.

    #### Events & people

    Raw event export and People / Engage profiles

    #### Definitions

    Cohorts, funnel list, annotations

    | Field                    | Required         | Notes                                             |
    | ------------------------ | ---------------- | ------------------------------------------------- |
    | Service Account Username | Yes              | Basic auth username                               |
    | Service Account Secret   | Yes              | Basic auth password; shown once at creation       |
    | Project ID               | Yes              | Sent as `project_id` on Query and Export requests |
    | Query base URL           | No (defaults US) | Engage, cohorts, funnels, annotations             |
    | Export base URL          | No (defaults US) | Raw event export only                             |
    | Data Group ID            | No               | Required for `group_profiles`                     |

    | Tap              | Sync                         | Notes                                           |
    | ---------------- | ---------------------------- | ----------------------------------------------- |
    | `raw_events`     | Incremental date windows     | Export API; JSONL; up to 30-day windows         |
    | `user_profiles`  | Incremental via `$last_seen` | Engage POST form body + session/page pagination |
    | `cohorts`        | Full                         | Cohort list                                     |
    | `funnels_list`   | Full                         | Funnel definitions                              |
    | `annotations`    | Full                         | Off by default                                  |
    | `group_profiles` | Full                         | Off by default; needs Data Group ID             |

    ## Data streams

    This Provider Plugin defines 6 data streams.

    | Stream           | Description                                                                                                                                                                           | Sync        |
    | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
    | `raw_events`     | Raw Mixpanel events as newline-delimited JSON from the Export API. Date-window incremental sync via from\_date/to\_date; each line is one tracked event with its full properties bag. | incremental |
    | `user_profiles`  | Mixpanel People (user) profiles via the Engage API. Incremental by \$last\_seen using a where filter; session\_id + page hybrid pagination.                                           | incremental |
    | `cohorts`        | Saved cohort definitions from Mixpanel. Full sync; the cohort list is small and has no incremental cursor.                                                                            | full        |
    | `funnels_list`   | List of saved funnel definitions from Mixpanel. Full sync; enumerates funnels by id and name.                                                                                         | full        |
    | `annotations`    | Project annotations (notes attached to dates on Mixpanel charts). Full sync; opt-in.                                                                                                  | full        |
    | `group_profiles` | Mixpanel Group Analytics profiles via the Engage API with a data\_group\_id. Full sync; session\_id + page hybrid pagination. Requires Group Analytics; opt-in.                       | full        |
  </Tab>

  <Tab title="Setup Guide">
    ### Mixpanel

    #### What You'll Need

    | Credential                   | What it is                                                        |
    | ---------------------------- | ----------------------------------------------------------------- |
    | **Service Account Username** | Username from Mixpanel Organization Settings → Service Accounts   |
    | **Service Account Secret**   | Secret shown once when the service account is created             |
    | **Project ID**               | Numeric Mixpanel project ID                                       |
    | **Query / Export base URLs** | Regional hosts for your project's data residency (defaults to US) |
    | **Data Group ID**            | Optional. Required only if syncing group profiles                 |

    > **Info:** **Setup access in Mixpanel.** These steps require **Organization Owner or Admin**, or a colleague with equivalent permissions who can create credentials for you.
    >
    > If that is not you, ask your Mixpanel administrator.

    * Organization **Owner** or **Admin** to create service accounts
    * Service account granted at least **Analyst** (or equivalent read) access on the target project
    * Your project's **Project ID** and data residency region (US, EU, or India)

    #### Step 1: Create a service account

    1. Sign in to Mixpanel as an organization Owner or Admin.
    2. Open **Organization Settings → Service Accounts** (or go to <a href="https://mixpanel.com/settings/org#serviceaccounts" target="_blank" rel="noopener noreferrer">mixpanel.com/settings/org#serviceaccounts</a>).
    3. Click **Create Service Account**.
    4. Choose a name (for example `parable-sync`) and grant the account access to the project(s) Parable should read.
    5. Copy the **Username** and **Secret**.

    > **Warning:** **Copy your Service Account Secret now!**
    >
    > This is the only time it will be displayed. Store it in a secure password manager before closing this page.

    #### Step 2: Find your Project ID and residency

    1. Open **Organization Settings → Projects**, or **Project Settings** for the active project.
    2. Copy the **Project ID** (numeric).
    3. Note **Data Residency** (US, EU, or India). Hosts must match residency:

    | Region       | Query base URL                      | Export base URL                |
    | ------------ | ----------------------------------- | ------------------------------ |
    | US (default) | `https://mixpanel.com/api/query`    | `https://data.mixpanel.com`    |
    | EU           | `https://eu.mixpanel.com/api/query` | `https://data-eu.mixpanel.com` |
    | India        | `https://in.mixpanel.com/api/query` | `https://data-in.mixpanel.com` |

    #### Step 3: Optional — Group Analytics data group ID

    Only needed if you enable the `group_profiles` tap.

    1. In Mixpanel, open Group Analytics settings for the project.
    2. Copy the **data group ID** for the group key you want to sync.
    3. Keep it for the Parable form's **Data Group ID** field.

    #### Step 4: Enter values in the form

    1. In Parable, open **Platform → Providers** and choose the Provider to add.
    2. Select **Mixpanel**.
    3. Enter **Service Account Username**, **Service Account Secret**, and **Project ID**.
    4. If not US residency, set **Query base URL** and **Export base URL** from the table above.
    5. (Optional) Enter **Data Group ID** for group profiles.
    6. Click **Save & test connection**.

    Use prompts so secrets do not land in shell history:

    ```bash Test Engage with Basic auth theme={null}
    read -rs -p "Service account username: " MP_USER && echo
    read -rs -p "Service account secret: " MP_SECRET && echo
    read -p "Project ID: " MP_PROJECT
    read -p "Query base URL [https://mixpanel.com/api/query]: " MP_BASE
    MP_BASE="${MP_BASE:-https://mixpanel.com/api/query}"
    curl --silent --user "${MP_USER}:${MP_SECRET}" \
      -X POST "${MP_BASE}/engage?project_id=${MP_PROJECT}" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      --data ""
    unset MP_USER MP_SECRET MP_PROJECT MP_BASE
    ```

    > **Success:** **Success!** If you received a `200 OK` response with a JSON body containing `results` (may be empty), your credentials are configured correctly. You can now configure this Provider in Parable.

    > **Tip:** **Rate Limits:** Mixpanel query/export quotas vary by plan. Parable is configured for about **0.5 requests/second** and respects `Retry-After`.
    >
    > Parable handles rate limiting automatically with exponential backoff, but initial syncs of large event windows may take longer.
  </Tab>

  <Tab title="Permissions">
    <AccordionGroup>
      <Accordion id="provider-permission-tap-mixpanel-annotations-a316432dd38d" title="Annotations" icon="comment-dots" iconType="sharp-duotone-solid">
        Developer identifier: `annotations`

        Annotations contain project annotations (notes attached to dates on Mixpanel charts). Full sync; opt-in.

        * **Enables:** place project notes on the dates to which Mixpanel attaches them.
        * **Scope:** Reads the declared collection through `GET /annotations` as a full snapshot. Results are limited to the configured Mixpanel project and service-account access.

        <AccordionGroup>
          <Accordion id="provider-permission-field-mixpanel-annotations-date-43e7a39803f2" title="Date" icon="globe" iconType="sharp-duotone-solid">
            Developer identifier: `annotations.date`

            Date records the date the annotation is attached to. It anchors the named event or boundary on the record's timeline.

            * **Enables:** place annotation records on a timeline by date and select the records within an explicit reporting window.
            * **Interpretation:** The provider supplies `date` per mixpanel annotation record as a timestamp at the precision returned by the provider; missing values mean the event or boundary was not reported.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-annotations-description-7d842f5e1834" title="Description" icon="shield-check" iconType="sharp-duotone-solid">
            Developer identifier: `annotations.description`

            Description records annotation text. It keeps the exact text, label, or authored value needed to interpret the record.

            * **Enables:** inspect the exact description value attached to each mixpanel annotation record.
            * **Interpretation:** The provider supplies `description` at mixpanel annotation granularity in the format stated by its description; omitted or redacted content remains unknown.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-annotations-id-03f37dc946a4" title="ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `annotations.id`

            ID is the unique annotation identifier. It supplies the declared record identity used when repeated ingestions represent the same source row.

            * **Enables:** recognize repeated ingestions of the same mixpanel annotation source row before constructing its represented state.
            * **Interpretation:** The provider supplies `id` at one value per mixpanel annotation record, and `x-transformDedupKey` explicitly marks it as the record key.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-annotations-project-id-7b92e77f0f0d" title="Project ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `annotations.project_id`

            Project ID identifies Mixpanel project ID the annotation belongs to. It is needed to resolve references that repeat the same provider identifier.

            * **Enables:** match annotation records to provider records that carry the same project ID, without assuming that this field alone makes every row unique.
            * **Interpretation:** The provider supplies `project_id` as a record-level identifier on `MixpanelAnnotation`. It is not a uniqueness guarantee unless a connector directive says so.
          </Accordion>
        </AccordionGroup>
      </Accordion>

      <Accordion id="provider-permission-tap-mixpanel-cohorts-e830fff4b415" title="Cohorts" icon="people-group" iconType="sharp-duotone-solid">
        Developer identifier: `cohorts`

        Cohorts contain saved cohort definitions from Mixpanel. Full sync; the cohort list is small and has no incremental cursor.

        * **Enables:** catalog saved cohort definitions for interpreting cohort references in Mixpanel.
        * **Scope:** Reads the declared collection through `GET /cohorts/list` as a full snapshot. Results are limited to the configured Mixpanel project and service-account access.

        <AccordionGroup>
          <Accordion id="provider-permission-field-mixpanel-cohorts-count-7f4a22dbc50b" title="Count" icon="globe" iconType="sharp-duotone-solid">
            Developer identifier: `cohorts.count`

            Count reports the number of users currently matching the cohort. It preserves the stated measure at this record's granularity.

            * **Enables:** measure the provider-reported count for each mixpanel cohort record.
            * **Interpretation:** The provider supplies `count` at mixpanel cohort granularity as a count at one value per record; zero and missing are not interchangeable.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-cohorts-created-4143fdf6f175" title="Created" icon="location-crosshairs" iconType="sharp-duotone-solid">
            Developer identifier: `cohorts.created`

            Created records the timestamp when the cohort was created. It anchors the named event or boundary on the record's timeline.

            * **Enables:** place cohort records on a timeline by created and select the records within an explicit reporting window.
            * **Interpretation:** The provider supplies `created` per mixpanel cohort record as a timestamp at the precision returned by the provider; missing values mean the event or boundary was not reported.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-cohorts-data-group-id-d2c34738089b" title="Data Group ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `cohorts.data_group_id`

            Data Group ID identifies data group identifier when the cohort is a group cohort. It is needed to resolve references that repeat the same provider identifier.

            * **Enables:** match cohort records to provider records that carry the same data group ID, without assuming that this field alone makes every row unique.
            * **Interpretation:** The provider supplies `data_group_id` as a record-level identifier on `MixpanelCohort`. It is not a uniqueness guarantee unless a connector directive says so.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-cohorts-description-e9b51c50b685" title="Description" icon="shield-check" iconType="sharp-duotone-solid">
            Developer identifier: `cohorts.description`

            Description records cohort description. It keeps the exact text, label, or authored value needed to interpret the record.

            * **Enables:** inspect the exact description value attached to each mixpanel cohort record.
            * **Interpretation:** The provider supplies `description` at mixpanel cohort granularity in the format stated by its description; omitted or redacted content remains unknown.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-cohorts-id-8dddb544cfb3" title="ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `cohorts.id`

            ID is the unique cohort identifier. It supplies the declared record identity used when repeated ingestions represent the same source row.

            * **Enables:** recognize repeated ingestions of the same mixpanel cohort source row before constructing its represented state.
            * **Interpretation:** The provider supplies `id` at one value per mixpanel cohort record, and `x-transformDedupKey` explicitly marks it as the record key.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-cohorts-is-visible-9665963c5f5d" title="Is Visible" icon="chart-pie" iconType="sharp-duotone-solid">
            Developer identifier: `cohorts.is_visible`

            Is Visible indicates whether the cohort appears in the Mixpanel UI. It preserves the provider's integer-encoded visibility condition.

            * **Enables:** separate UI-visible cohorts from cohorts the provider marks as hidden.
            * **Interpretation:** The provider supplies `is_visible` as an integer flag, not a quantity; preserve the provider encoding and keep zero distinct from missing.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-cohorts-name-644c16bd6078" title="Name" icon="user-shield" iconType="sharp-duotone-solid">
            Developer identifier: `cohorts.name`

            Name records cohort name. It keeps the exact text, label, or authored value needed to interpret the record.

            * **Enables:** inspect the exact name value attached to each mixpanel cohort record.
            * **Interpretation:** The provider supplies `name` at mixpanel cohort granularity in the format stated by its description; omitted or redacted content remains unknown.
          </Accordion>
        </AccordionGroup>
      </Accordion>

      <Accordion id="provider-permission-tap-mixpanel-funnels-list-3e9d079b0028" title="Funnels List" icon="chart-column" iconType="sharp-duotone-solid">
        Developer identifier: `funnels_list`

        Funnels List contains the saved funnel definitions returned by Mixpanel.

        * **Enables:** resolve saved funnel identifiers to their Mixpanel names.
        * **Scope:** Reads the declared collection through `GET /funnels/list` as a full snapshot. Results are limited to the configured Mixpanel project and service-account access.

        <AccordionGroup>
          <Accordion id="provider-permission-field-mixpanel-funnels-list-funnel-id-7ec699ce2297" title="Funnel ID" icon="address-book" iconType="sharp-duotone-solid">
            Developer identifier: `funnels_list.funnel_id`

            Funnel ID is the unique funnel identifier. It supplies the declared record identity used when repeated ingestions represent the same source row.

            * **Enables:** recognize repeated ingestions of the same mixpanel funnel source row before constructing its represented state.
            * **Interpretation:** The provider supplies `funnel_id` at one value per mixpanel funnel record, and `x-transformDedupKey` explicitly marks it as the record key.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-funnels-list-name-d70b5dd189f4" title="Name" icon="user-shield" iconType="sharp-duotone-solid">
            Developer identifier: `funnels_list.name`

            Name records funnel name. It keeps the exact text, label, or authored value needed to interpret the record.

            * **Enables:** inspect the exact name value attached to each mixpanel funnel record.
            * **Interpretation:** The provider supplies `name` at mixpanel funnel granularity in the format stated by its description; omitted or redacted content remains unknown.
          </Accordion>
        </AccordionGroup>
      </Accordion>

      <Accordion id="provider-permission-tap-mixpanel-group-profiles-44a3a3d434b1" title="Group Profiles" icon="shield-check" iconType="sharp-duotone-solid">
        Developer identifier: `group_profiles`

        Group Profiles contain the property map returned for each Mixpanel Group Analytics entity.

        * **Enables:** segment Group Analytics profiles by the provider-supplied group properties.
        * **Scope:** Reads the declared collection through `POST /engage` as a full snapshot. The operation requires Group Analytics and is opt-in; projects without that feature return no group profiles.

        <AccordionGroup>
          <Accordion id="provider-permission-field-mixpanel-group-profiles-distinct-id-de85a024c7e5" title="$distinct ID" icon="address-book" iconType="sharp-duotone-solid">
            Developer identifier: `group_profiles.$distinct_id`

            \$distinct ID is the unique identifier of the group profile. It supplies the declared record identity used when repeated ingestions represent the same source row.

            * **Enables:** recognize repeated ingestions of the same mixpanel group profile source row before constructing its represented state.
            * **Interpretation:** The provider supplies `$distinct_id` at one value per mixpanel group profile record, and `x-transformDedupKey` explicitly marks it as the record key.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-group-profiles-group-id-b433403c0907" title="$group ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `group_profiles.$group_id`

            \$group ID captures the group ID value. It is needed to resolve references that repeat the same provider identifier.

            * **Enables:** match group profile records to provider records that carry the same \$group ID, without assuming that this field alone makes every row unique.
            * **Interpretation:** The provider supplies `$group_id` as a record-level identifier on `MixpanelGroupProfile`. It is not a uniqueness guarantee unless a connector directive says so.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-group-profiles-group-key-c07b1b4eb016" title="$group Key" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `group_profiles.$group_key`

            \$group Key captures the group key (property) this group is keyed on. It is needed to resolve references that repeat the same provider identifier.

            * **Enables:** match group profile records to provider records that carry the same \$group key, without assuming that this field alone makes every row unique.
            * **Interpretation:** The provider supplies `$group_key` as a record-level identifier on `MixpanelGroupProfile`. It is not a uniqueness guarantee unless a connector directive says so.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-group-profiles-properties-aa3a37b2fd80" title="$properties" icon="chart-line" iconType="sharp-duotone-solid">
            Developer identifier: `group_profiles.$properties`

            \$properties captures the group profile property bag. It retains configured attributes whose keys or shape are not fixed by this base schema.

            * **Enables:** interpret \$properties according to the provider and Workspace configuration that produced each group profile record.
            * **Interpretation:** Keys and value shapes within `$properties` can vary with provider and customer configuration; consumers must inspect the observed Workspace schema rather than assume a fixed contract.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-group-profiles-properties-last-seen-176c07c61cf6" title="$last Seen" icon="map-location-dot" iconType="sharp-duotone-solid">
            Developer identifier: `group_profiles.$properties.$last_seen`

            \$last Seen records the timestamp when the group was last seen. It anchors the named event or boundary on the record's timeline.

            * **Enables:** place group profile records on a timeline by \$last seen and select the records within an explicit reporting window.
            * **Interpretation:** The provider supplies `$last_seen` per mixpanel group profile property record as a timestamp at the precision returned by the provider; missing values mean the event or boundary was not reported.
          </Accordion>
        </AccordionGroup>
      </Accordion>

      <Accordion id="provider-permission-tap-mixpanel-raw-events-50366ce7640f" title="Raw Events" icon="calendar-days" iconType="sharp-duotone-solid">
        Developer identifier: `raw_events`

        Raw Events contain raw Mixpanel events as newline-delimited JSON from the Export API. Date-window incremental sync via `from_date`/`to_date`; each line is one tracked event with its full properties bag.

        * **Enables:** measure occurrences of tracked product events using each event's timestamp, name, and property bag.
        * **Scope:** Reads provider changes through `GET {exportBaseUrl}/api/2.0/export` using the declared incremental request boundary. Results are limited to the configured Mixpanel project and service-account access.

        <AccordionGroup>
          <Accordion id="provider-permission-field-mixpanel-raw-events-event-deac438e5b21" title="Event" icon="passport" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.event`

            Event captures the name of the tracked event. It keeps the exact text, label, or authored value needed to interpret the record.

            * **Enables:** inspect the exact event value attached to each mixpanel raw event record.
            * **Interpretation:** The provider supplies `event` at mixpanel raw event granularity in the format stated by its description; omitted or redacted content remains unknown.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-id-686b3ca59824" title="ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.id`

            ID identifies synthetic deduplication key hashed from `$insert_id`, time, event, `distinct_id`, and `device_id`. It supplies the declared record identity used when repeated ingestions represent the same source row.

            * **Enables:** recognize repeated ingestions of the same mixpanel raw event source row before constructing its represented state.
            * **Interpretation:** Parable generates `id` at one value per mixpanel raw event record, and `x-transformDedupKey` explicitly marks it as the record key.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-6689f874413c" title="Properties" icon="ranking-star" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties`

            Properties captures the event property bag. It retains configured attributes whose keys or shape are not fixed by this base schema.

            * **Enables:** interpret properties according to the provider and Workspace configuration that produced each raw event record.
            * **Interpretation:** Keys and value shapes within `properties` can vary with provider and customer configuration; consumers must inspect the observed Workspace schema rather than assume a fixed contract.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-browser-11850d1bb39c" title="$browser" icon="arrow-trend-down" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.$browser`

            \$browser records browser used when the event was sent. It preserves the client environment reported with the event.

            * **Enables:** count Mixpanel events by the reported \$browser client environment.
            * **Interpretation:** Mixpanel supplies `$browser` per tracked event from client metadata; missing values do not identify an operating system or browser.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-city-ef5395f368e1" title="$city" icon="location-crosshairs" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.$city`

            \$city records city derived from IP geolocation at event time. It preserves the geographic, locale, time-zone, or coordinate context represented by the field.

            * **Enables:** segment raw event records by the recorded \$city without inferring a person's physical presence.
            * **Interpretation:** The provider supplies `$city` as location or localization context per mixpanel event property record; it does not establish a person's real-time physical location.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-insert-id-5f19f7366ba5" title="$insert ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.$insert_id`

            \$insert ID is the unique ID assigned to the event. It is needed to resolve references that repeat the same provider identifier.

            * **Enables:** match raw event records to provider records that carry the same \$insert ID, without assuming that this field alone makes every row unique.
            * **Interpretation:** The provider supplies `$insert_id` as a record-level identifier on `MixpanelEventProperties`. It is not a uniqueness guarantee unless a connector directive says so.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-lib-version-fe2e39292ec1" title="$lib Version" icon="percent" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.$lib_version`

            \$lib Version records version of the Mixpanel SDK library used to send the event. It preserves the configuration or technical value needed to explain how the provider object is defined.

            * **Enables:** inspect the exact \$lib version when validating the configuration or technical definition of a mixpanel event property record.
            * **Interpretation:** The provider supplies `$lib_version` as configuration or technical metadata on `MixpanelEventProperties`; consumers must preserve the exact syntax and documented vocabulary.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-os-3adc616ff8ac" title="$OS" icon="chart-pie" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.$os`

            \$OS records operating system of the device that sent the event. It preserves the client environment reported with the event.

            * **Enables:** count Mixpanel events by the reported \$OS client environment.
            * **Interpretation:** Mixpanel supplies `$os` per tracked event from client metadata; missing values do not identify an operating system or browser.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-user-id-249c4dd7e7bf" title="$user ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.$user_id`

            \$user ID identifies identified user ID (post identity-merge), when present. It is needed to resolve references that repeat the same provider identifier.

            * **Enables:** match raw event records to provider records that carry the same \$user ID, without assuming that this field alone makes every row unique.
            * **Interpretation:** The provider supplies `$user_id` as a record-level identifier on `MixpanelEventProperties`. It is not a uniqueness guarantee unless a connector directive says so.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-device-id-f478ee5c0631" title="Device ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.device_id`

            Device ID identifies device identifier when the event is not yet identified to a `distinct_id`. It is needed to resolve references that repeat the same provider identifier.

            * **Enables:** match raw event records to provider records that carry the same device ID, without assuming that this field alone makes every row unique.
            * **Interpretation:** The provider supplies `device_id` as a record-level identifier on `MixpanelEventProperties`. It is not a uniqueness guarantee unless a connector directive says so.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-distinct-id-d33acd110bb1" title="Distinct ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.distinct_id`

            Distinct ID is the unique identifier of the user who triggered the event, when present. It is needed to resolve references that repeat the same provider identifier.

            * **Enables:** match raw event records to provider records that carry the same distinct ID, without assuming that this field alone makes every row unique.
            * **Interpretation:** The provider supplies `distinct_id` as a record-level identifier on `MixpanelEventProperties`. It is not a uniqueness guarantee unless a connector directive says so.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-email-fa625b904bc3" title="Email" icon="comments" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.email`

            Email records email property carried on the event, when present. It keeps the provider-reported person or account context attached to the record.

            * **Enables:** attribute the mixpanel event property record to the provider-reported person or account represented by email.
            * **Interpretation:** The provider supplies `email` as identity or attribution context on each mixpanel event property record. Names and contact values can change and are not stable identifiers unless the provider documents them as such.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-mp-country-code-6d9af34d6d4c" title="Mp Country Code" icon="earth-americas" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.mp_country_code`

            Mp Country Code records ISO 3166-1 alpha-2 country code derived from IP geolocation. It preserves the configuration or technical value needed to explain how the provider object is defined.

            * **Enables:** inspect the exact mp country code when validating the configuration or technical definition of a mixpanel event property record.
            * **Interpretation:** The provider supplies `mp_country_code` as configuration or technical metadata on `MixpanelEventProperties`; consumers must preserve the exact syntax and documented vocabulary.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-project-id-50f0d5cbc983" title="Project ID" icon="id-card" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.project_id`

            Project ID identifies Mixpanel project ID the event belongs to. It is needed to resolve references that repeat the same provider identifier.

            * **Enables:** match raw event records to provider records that carry the same project ID, without assuming that this field alone makes every row unique.
            * **Interpretation:** The provider supplies `project_id` as a record-level identifier on `MixpanelEventProperties`. It is not a uniqueness guarantee unless a connector directive says so.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-time-463ca9355b54" title="Time" icon="headset" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.time`

            Time records the instant when the event occurred as a Unix timestamp in seconds. It anchors the raw event on the activity timeline.

            * **Enables:** order events chronologically and select activity within an explicit reporting window.
            * **Interpretation:** The provider supplies `time` as seconds since the Unix epoch; it represents an instant, not an elapsed duration or interval.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-properties-user-email-5f6f6fe9bb0b" title="User Email" icon="envelope" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.properties.user_email`

            User Email records user email carried on the event, when present. It keeps the provider-reported person or account context attached to the record.

            * **Enables:** attribute the mixpanel event property record to the provider-reported actor represented by user email.
            * **Interpretation:** The provider supplies `user_email` as identity or attribution context on each mixpanel event property record. Names and contact values can change and are not stable identifiers unless the provider documents them as such.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-raw-events-time-56298e8ac68f" title="Time" icon="earth-americas" iconType="sharp-duotone-solid">
            Developer identifier: `raw_events.time`

            Time records unix timestamp in seconds when the event occurred (mirrors properties.time; root-visible for promote ordering and quality `event_time`). It anchors the named event or boundary on the record's timeline.

            * **Enables:** place raw event records on a timeline by time and select the records within an explicit reporting window.
            * **Interpretation:** The provider supplies `time` per mixpanel raw event record as a timestamp at the precision returned by the provider; missing values mean the event or boundary was not reported.
          </Accordion>
        </AccordionGroup>
      </Accordion>

      <Accordion id="provider-permission-tap-mixpanel-user-profiles-992a1748e96a" title="User Profiles" icon="lock" iconType="sharp-duotone-solid">
        Developer identifier: `user_profiles`

        User Profiles contain Mixpanel People (user) profiles via the Engage API. Incremental by `$last_seen` using a where filter; `session_id` + page hybrid pagination.

        * **Enables:** segment Mixpanel People profiles by provider-supplied profile attributes and last-seen time.
        * **Scope:** Reads provider changes through `POST /engage` using the declared incremental request boundary. Results are limited to the configured Mixpanel project and service-account access.

        <AccordionGroup>
          <Accordion id="provider-permission-field-mixpanel-user-profiles-distinct-id-3e05c9e64304" title="$distinct ID" icon="address-book" iconType="sharp-duotone-solid">
            Developer identifier: `user_profiles.$distinct_id`

            \$distinct ID is the unique identifier of the user profile. It supplies the declared record identity used when repeated ingestions represent the same source row.

            * **Enables:** recognize repeated ingestions of the same mixpanel user profile source row before constructing its represented state.
            * **Interpretation:** The provider supplies `$distinct_id` at one value per mixpanel user profile record, and `x-transformDedupKey` explicitly marks it as the record key.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-user-profiles-properties-40d73bd8c823" title="$properties" icon="chart-line" iconType="sharp-duotone-solid">
            Developer identifier: `user_profiles.$properties`

            \$properties captures the user profile property bag. It retains configured attributes whose keys or shape are not fixed by this base schema.

            * **Enables:** interpret \$properties according to the provider and Workspace configuration that produced each user profile record.
            * **Interpretation:** Keys and value shapes within `$properties` can vary with provider and customer configuration; consumers must inspect the observed Workspace schema rather than assume a fixed contract.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-user-profiles-properties-city-56cd494fbdd6" title="$city" icon="location-crosshairs" iconType="sharp-duotone-solid">
            Developer identifier: `user_profiles.$properties.$city`

            \$city records city derived from IP geolocation. It preserves the geographic, locale, time-zone, or coordinate context represented by the field.

            * **Enables:** segment user profile records by the recorded \$city without inferring a person's physical presence.
            * **Interpretation:** The provider supplies `$city` as location or localization context per mixpanel user profile property record; it does not establish a person's real-time physical location.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-user-profiles-properties-country-code-69fd6df1539a" title="$country Code" icon="globe" iconType="sharp-duotone-solid">
            Developer identifier: `user_profiles.$properties.$country_code`

            \$country Code records ISO 3166-1 alpha-2 country code derived from IP geolocation. It preserves the configuration or technical value needed to explain how the provider object is defined.

            * **Enables:** inspect the exact \$country code when validating the configuration or technical definition of a mixpanel user profile property record.
            * **Interpretation:** The provider supplies `$country_code` as configuration or technical metadata on `MixpanelUserProfileProperties`; consumers must preserve the exact syntax and documented vocabulary.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-user-profiles-properties-created-c8c74f3f50d6" title="$created" icon="location-crosshairs" iconType="sharp-duotone-solid">
            Developer identifier: `user_profiles.$properties.$created`

            \$created records the timestamp when the profile was created. It anchors the named event or boundary on the record's timeline.

            * **Enables:** place user profile records on a timeline by \$created and select the records within an explicit reporting window.
            * **Interpretation:** The provider supplies `$created` per mixpanel user profile property record as a timestamp at the precision returned by the provider; missing values mean the event or boundary was not reported.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-user-profiles-properties-email-e0e7e9b31ad4" title="$email" icon="comments" iconType="sharp-duotone-solid">
            Developer identifier: `user_profiles.$properties.$email`

            \$email records user email address. It keeps the provider-reported person or account context attached to the record.

            * **Enables:** attribute the mixpanel user profile property record to the provider-reported person or account represented by \$email.
            * **Interpretation:** The provider supplies `$email` as identity or attribution context on each mixpanel user profile property record. Names and contact values can change and are not stable identifiers unless the provider documents them as such.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-user-profiles-properties-first-name-7e588354af11" title="$first Name" icon="arrow-trend-up" iconType="sharp-duotone-solid">
            Developer identifier: `user_profiles.$properties.$first_name`

            \$first Name records user first name. It keeps the provider-reported person or account context attached to the record.

            * **Enables:** attribute the mixpanel user profile property record to the provider-reported person or account represented by \$first name.
            * **Interpretation:** The provider supplies `$first_name` as identity or attribution context on each mixpanel user profile property record. Names and contact values can change and are not stable identifiers unless the provider documents them as such.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-user-profiles-properties-last-name-dfcb4da63cfe" title="$last Name" icon="chart-column" iconType="sharp-duotone-solid">
            Developer identifier: `user_profiles.$properties.$last_name`

            \$last Name records user last name. It keeps the provider-reported person or account context attached to the record.

            * **Enables:** attribute the mixpanel user profile property record to the provider-reported person or account represented by \$last name.
            * **Interpretation:** The provider supplies `$last_name` as identity or attribution context on each mixpanel user profile property record. Names and contact values can change and are not stable identifiers unless the provider documents them as such.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-user-profiles-properties-last-seen-ecf56fdf1408" title="$last Seen" icon="map-location-dot" iconType="sharp-duotone-solid">
            Developer identifier: `user_profiles.$properties.$last_seen`

            \$last Seen records the timestamp when the user was last seen. Incremental cursor. It anchors the named event or boundary on the record's timeline.

            * **Enables:** place user profile records on a timeline by \$last seen and select the records within an explicit reporting window.
            * **Interpretation:** The provider supplies `$last_seen` per mixpanel user profile property record as a timestamp at the precision returned by the provider; missing values mean the event or boundary was not reported.
          </Accordion>

          <Accordion id="provider-permission-field-mixpanel-user-profiles-properties-phone-5d39bf6033b2" title="$phone" icon="phone" iconType="sharp-duotone-solid">
            Developer identifier: `user_profiles.$properties.$phone`

            \$phone records user phone number. It keeps the provider-reported person or account context attached to the record.

            * **Enables:** attribute the mixpanel user profile property record to the provider-reported person or account represented by \$phone.
            * **Interpretation:** The provider supplies `$phone` as identity or attribution context on each mixpanel user profile property record. Names and contact values can change and are not stable identifiers unless the provider documents them as such.
          </Accordion>
        </AccordionGroup>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Troubleshooting">
    | Error                            | Meaning                        | Solution                                                  |
    | -------------------------------- | ------------------------------ | --------------------------------------------------------- |
    | `401 Unauthorized`               | Bad username or secret         | Recreate the service account; secret is shown once        |
    | `403 Forbidden`                  | No access to the project       | Grant the service account a project role with read access |
    | `400 Bad Request`                | Bad Project ID or params       | Confirm Project ID and regional hosts match residency     |
    | Empty `raw_events`               | No events in the date window   | Widen the sync window or confirm the project has events   |
    | `group_profiles` skipped / empty | Missing or wrong Data Group ID | Set Data Group ID; Group Analytics must be enabled        |

    #### Common Issues

    #### Wrong region hosts

    If Project ID is correct but requests fail or return empty, confirm Query and Export base URLs match the project's data residency (US / EU / India).

    #### Service account cannot see the project

    Creating the account at the org is not enough — grant it membership on the specific project with a read-capable role.

    **[Service Accounts](https://docs.mixpanel.com/docs/orgs-and-projects/managing-roles#service-accounts)** — Roles and creation

    **[Authentication](https://developer.mixpanel.com/reference/service-accounts-api-authentication)** — HTTP Basic auth with service accounts

    **[Raw Export API](https://developer.mixpanel.com/reference/raw-event-export)** — Endpoint used by `raw_events`

    **[Data residency](https://docs.mixpanel.com/docs/privacy/resident-data)** — Regional Query and Export hosts
  </Tab>
</Tabs>