A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Mixpanel API is how an app or AI agent works with a Mixpanel project: recording events, updating the people and group profiles those events belong to, and running segmentation, funnel, and retention reports over what has been collected. Sending data in is authenticated with a project token, while reading reports and exporting raw data uses a service account whose project role, like Consumer, Analyst, Admin, or Owner, decides what it can reach. Mixpanel has no per-method permissions, so that one role governs the whole read side.
How an app or AI agent connects to Mixpanel determines what it can reach. There is a route for sending data in, a route for running reports and reading raw data back out, and a hosted server that exposes Mixpanel tools to agents, and each is governed by the credential behind it: a project token for sending data, or a service account whose project role decides what it can read.
The Ingestion API sends data into a project, at https://api.mixpanel.com (with regional hosts for the EU and India). It records events through Track Events and Import Events, and updates user and group profiles through the engage and groups endpoints. Calls identify the project with a project token in the request body and accept JSON, with gzip compression supported for batches.
The Query API runs reports, like segmentation, funnels, retention, insights, and JQL, at https://mixpanel.com/api/query, returning computed results. The raw Export API streams the underlying events for a date range as newline-delimited JSON, on a separate host at https://data.mixpanel.com/api/2.0/export. Both authenticate with a service account over HTTP Basic auth and require the project_id.
A first-party, hosted Model Context Protocol server lets AI agents and LLM clients query Mixpanel in natural language. It runs at regional endpoints (https://mcp.mixpanel.com/mcp for the US, plus EU and India variants) and exposes tools for insights, funnels, flows, retention, dashboards, metrics, session replays, and data discovery. It authenticates with OAuth, where a person signs in through a browser, or with a service account for automated use. Most tools are generally available, with Experiments and Feature Flags in open beta.
The project token identifies which project data belongs to. It is sent in the body of ingestion calls, as $token on profile updates or as the token on events, and is the only credential the Ingestion API needs. A token can send data but cannot read reports or export data.
A service account is a non-human Mixpanel user with a username and a secret, designed for scripts and automated workflows. It authenticates the Query and Export APIs over HTTP Basic auth, with the project_id supplied as a parameter. Its project role, one of Consumer, Analyst, Admin, or Owner, governs everything it can do; there are no per-method scopes. The secret is shown only once, when the account is created.
The legacy project secret is sent as the HTTP Basic auth username, with an empty password, and authenticates Query and Export calls without a project_id parameter. Mixpanel is deprecating it in favour of service accounts, which scope access by role and can be rotated independently.
The Mixpanel API splits into two halves: sending data in, like recording events and updating the people and groups that data is attached to, and reading insight back out, like running segmentation, funnel, retention, and insights reports or exporting raw events. Sending data in needs only a project token, while reading reports needs a service account, and what that account can reach depends on the role it holds.
Methods for sending events into a project and managing identity.
Methods for setting and updating the people that events belong to.
Methods for setting and updating group profiles, like accounts or companies.
Methods for running segmentation, funnel, retention, insights, and JQL reports.
Methods for downloading the raw underlying events and querying profiles.
Methods for reading and writing the data dictionary that describes events and properties.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Events (ingestion)Methods for sending events into a project and managing identity.4 | ||||||
| POST | /track | Record one or more events as they happen, identified by a project token. | write | — | Current | |
Ingestion needs only the project token, not a service account. Mixpanel has no per-method scope. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
| POST | /import | Import a batch of historical or server-side events, with per-event validation. | write | — | Current | |
Accepts a project token or a service account. With strict validation on, failures come back as a per-event error array inside a 200. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitUp to 2,000 events and 10MB per request SourceOfficial documentation ↗ | ||||||
| POST | /track#create-identity | Link an anonymous device id to a known user id so their activity is merged. | write | — | Current | |
Part of the identity-management ingestion flow; project token only. Acts onidentity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
| POST | /import#identity-merge | Merge two identities into a single user, combining their event history. | write | — | Current | |
Irreversibly combines two profiles' history. Project token only. Acts onidentity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
People profiles (ingestion)Methods for setting and updating the people that events belong to.6 | ||||||
| POST | /engage#profile-set | Set or overwrite properties on a person's profile, creating it if needed. | write | — | Current | |
The $token in the body identifies the project. No per-method scope. Acts onuser_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
| POST | /engage#profile-set-once | Set profile properties only if they are not already set, never overwriting. | write | — | Current | |
Useful for first-seen values like signup date. Project token only. Acts onuser_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
| POST | /engage#profile-numerical-add | Increment a numeric profile property by a given amount. | write | — | Current | |
Atomic increment, for counters like total purchases. Project token only. Acts onuser_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
| POST | /engage#profile-append-to-list | Append a value to a list property on a person's profile. | write | — | Current | |
Adds to a list without replacing it. Project token only. Acts onuser_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
| POST | /engage#profile-delete | Permanently delete a person's profile. | write | — | Current | |
Removes the profile; does not delete the person's events. Project token only. Acts onuser_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
| POST | /engage#profile-batch-update | Update many people profiles in a single batched request. | write | — | Current | |
Batches up to 2,000 profile updates per request. Project token only. Acts onuser_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitUp to 2,000 profiles per request SourceOfficial documentation ↗ | ||||||
Group profiles (ingestion)Methods for setting and updating group profiles, like accounts or companies.4 | ||||||
| POST | /groups#group-set | Set or overwrite properties on a group profile, like an account or company. | write | — | Current | |
Group profiles support group analytics. Project token only. Acts ongroup_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
| POST | /groups#group-union | Add values to a list property on a group profile without duplicates. | write | — | Current | |
Union merges values into a list, de-duplicated. Project token only. Acts ongroup_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
| POST | /groups#group-delete | Permanently delete a group profile. | write | — | Current | |
Removes the group profile. Project token only. Acts ongroup_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPart of the 2GB/min ingestion ceiling SourceOfficial documentation ↗ | ||||||
| POST | /groups#group-batch-update | Update many group profiles in a single batched request. | write | — | Current | |
Batches group profile updates. Project token only. Acts ongroup_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitUp to 2,000 groups per request SourceOfficial documentation ↗ | ||||||
Query (reports)Methods for running segmentation, funnel, retention, insights, and JQL reports.8 | ||||||
| GET | /api/query/segmentation | Run a segmentation report, counting an event broken down by a property over time. | read | — | Current | |
Needs a service account; reach is set by its project role, not a per-method scope. Acts onsegmentation_report Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against 60 queries/hour, 5 concurrent SourceOfficial documentation ↗ | ||||||
| GET | /api/query/funnels | Run a saved funnel report, measuring conversion across an ordered series of steps. | read | — | Current | |
Service account; role governs access. Acts onfunnel_report Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against 60 queries/hour, 5 concurrent SourceOfficial documentation ↗ | ||||||
| GET | /api/query/funnels/list | List the saved funnels in a project, with their ids and names. | read | — | Current | |
Service account; used to find a funnel_id for the funnels query. Acts onfunnel Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against 60 queries/hour, 5 concurrent SourceOfficial documentation ↗ | ||||||
| GET | /api/query/retention | Run a retention report, measuring how many users return after a starting action. | read | — | Current | |
Service account; role governs access. Acts onretention_report Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against 60 queries/hour, 5 concurrent SourceOfficial documentation ↗ | ||||||
| GET | /api/query/insights | Run a saved Insights report and return its computed result. | read | — | Current | |
Service account; role governs access. Acts oninsights_report Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against 60 queries/hour, 5 concurrent SourceOfficial documentation ↗ | ||||||
| POST | /api/query/jql | Run a custom JavaScript Query Language script against the project's raw event and profile data. | read | — | Current | |
The most flexible read; runs arbitrary analysis over the whole dataset. Service account; role governs access. Acts onjql_query Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against 60 queries/hour, 5 concurrent SourceOfficial documentation ↗ | ||||||
| GET | /api/query/events | Return aggregated counts for a set of events over a date range. | read | — | Current | |
Service account; role governs access. Acts onevent_counts Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against 60 queries/hour, 5 concurrent SourceOfficial documentation ↗ | ||||||
| GET | /api/query/events/properties/toplevel | Return the most common properties recorded on a given event. | read | — | Current | |
Service account; used to discover an event's schema before querying it. Acts onevent_properties Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against 60 queries/hour, 5 concurrent SourceOfficial documentation ↗ | ||||||
Export (raw data)Methods for downloading the raw underlying events and querying profiles.2 | ||||||
| GET | /api/query/engage | Query stored people profiles, filtered by property or cohort, paging with a session_id. | read | — | Current | |
Reads stored profile data back out, including personal properties. Service account; role governs access. Acts onuser_profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts against 60 queries/hour, 5 concurrent SourceOfficial documentation ↗ | ||||||
| GET | /api/2.0/export | Stream the raw underlying events for a date range as newline-delimited JSON. | read | — | Current | |
Returns row-level events, the rawest read. On its own host (data.mixpanel.com) with a tighter limit. Service account; role governs access. Acts onraw_event Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit60 queries/hour, 3/sec, 100 concurrent SourceOfficial documentation ↗ | ||||||
Lexicon (schemas)Methods for reading and writing the data dictionary that describes events and properties.3 | ||||||
| GET | /api/app/projects/{projectId}/schemas | List the Lexicon schemas that describe a project's events and properties. | read | — | Current | |
Reads the data dictionary. Service account; role governs access. Acts onschema Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit5 requests/min SourceOfficial documentation ↗ | ||||||
| POST | /api/app/projects/{projectId}/schemas/{entityType}/{name} | Create or replace the schema definition for a single event or property. | write | — | Current | |
Changes how an event or property is described project-wide. Service account; role governs access. Acts onschema Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit5 requests/min, under 4,000 updates/min SourceOfficial documentation ↗ | ||||||
| DELETE | /api/app/projects/{projectId}/schemas/{entityType}/{name} | Delete the schema definition for a single event or property. | write | — | Current | |
Removes a schema definition. Service account; role governs access. Acts onschema Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit5 requests/min SourceOfficial documentation ↗ | ||||||
Mixpanel does not push events out to a registered endpoint. It is built to receive data, so an integration learns about activity by running a query or exporting events, not by waiting for a callback.
| Event | What it signals | Triggered by |
|---|
Mixpanel limits the two halves of its API differently: a high-throughput ceiling on how much data can be sent in per minute, and a much tighter ceiling on how many reports can be run per hour.
Mixpanel meters its two halves separately. The Ingestion API allows 2GB of uncompressed JSON per minute, roughly 30,000 events per second, measured on a rolling one-minute window, and a single /import request takes up to 2,000 events and 10MB uncompressed. The Query API is far tighter: 60 queries per hour with at most 5 running at once. The raw Export API allows 60 queries per hour, 3 per second, and up to 100 concurrent. The Lexicon schemas API allows 5 requests per minute. Going over any limit returns HTTP 429, and Mixpanel recommends exponential backoff with jitter.
Reports return a complete result set for the requested window rather than a cursor-paged feed, so the unit of work is the query, not the page. The raw Export API streams events as newline-delimited JSON for the requested date range, read as a stream rather than in fixed pages. Profile queries (engage) page through results with a session_id and a page number.
A single /import request accepts at most 2,000 events and 10MB uncompressed per call. Individual event and profile properties have their own field-size limits. The Lexicon schemas API caps updates at under 4,000 events and properties per minute and fewer than 3,000 truncations or deletions per request.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | ingestion error array | An ingestion request was accepted at the HTTP level but individual events may still have failed. With strict validation on, the response lists per-event errors, like a missing event name or an invalid token, rather than failing the whole call with a status code. | Read the per-event error array in the body, fix the offending events, and resend only those. Do not assume a 200 means every event was stored. |
| 400 | Bad Request | The request was malformed: invalid JSON, a missing required parameter, or a batch that breaks a size or shape rule. | Validate the payload against the endpoint's schema and the 2,000-event, 10MB batch limits, then resend. |
| 401 | Unauthorized | Authentication failed: a missing or wrong project token on ingestion, or invalid service account credentials on a query. | Confirm the token or service account username and secret are correct and meant for this project, and rotate the secret if it is compromised. |
| 403 | Forbidden | The credential is valid but lacks the project role the request needs, for example a Consumer service account attempting an export, or it is not attached to the project. | Grant the service account the project role the request requires, or attach it to the project, then retry. |
| 413 | Payload Too Large | An ingestion batch exceeded the per-request size limit of 2,000 events or 10MB uncompressed. | Split the batch into smaller requests under the limits and resend. |
| 429 | Too Many Requests | A rate limit was hit: the 2GB-per-minute ingestion ceiling, the 60-per-hour query limit, or the export per-second or concurrency caps. | Back off exponentially with jitter, starting around 2 seconds and doubling up to 60 seconds, then resend. |
| 500 | Server Error | An error on Mixpanel's side, which can also appear as 502, 503, or 504. It is rare. | Retry with backoff, and contact Mixpanel support if it persists. |
Mixpanel does not use dated version numbers. There is a single, continuously updated API, with changes shipped through release notes rather than a version an integration pins to.
Mixpanel does not pin a dated API version. The Ingestion, Query, and Export APIs are continuously updated, and notable changes ship through the changelog rather than a version an integration selects. Some paths carry a numeric segment, like /api/2.0/export, but that is part of the path, not a selectable version.
Mixpanel shipped a re-architected experimentation system alongside feature flagging, with API methods to create, launch, and conclude experiments and to manage and evaluate feature flags. The matching MCP tools are in open beta.
Starting April 2026, Mixpanel APIs no longer accept connections using TLS 1.0 or 1.1. Integrations must use TLS 1.2 or higher.
Warehouse Connectors gained Mirror mode, which keeps Mixpanel in sync with a source warehouse by reflecting additions, updates, and deletions. Supported for Snowflake, BigQuery, and Databricks.
Mixpanel launched a first-party Model Context Protocol server, letting AI assistants query analytics data in natural language. It authenticates with OAuth or a service account and runs at regional endpoints.
There is no version to pin; track the changelog for new methods and deprecations.
Mixpanel changelog ↗Bollard AI sits between a team's AI agents and Mixpanel. Grant each agent exactly the access it needs, send-in or read-back, report by report, and every call is checked and logged.