Skip to main content
POST
cURL
Beta. This endpoint is in beta. Its request schema can change before general availability, including in ways that require you to update your requests.
Runs an Insights query that you describe in the request body and returns the results. You choose the metrics, the time range, and optional filters, breakdowns, and comparisons—the same building blocks as an Insights report. To get the results of a report you’ve already saved, use Query Saved Report instead.

API server URL

Send requests to the server URL for your project’s data residency: For more about residency, see EU Data Residency and India Data Residency.

Authentication

Authenticate with a service account, sending its username and secret with HTTP basic authentication. Pass these query parameters:
  • project_id: the ID of the project to query. Required.
  • workspace_id: the ID of the data view to query. Include it if your project uses data views.

Version

Set the Mixpanel-Version header to the API version your request is written for. A version is a release date, YYYY-MM-DD. A version that isn’t released yet adds a preview channel: YYYY-MM-DD.alpha or YYYY-MM-DD.beta. During the beta, the only version is 2026-10-23.beta. If you omit the header, the request uses the latest released version. While no version is released, it uses the oldest beta version. An unknown, malformed, or retired version returns 400 Bad Request. The error message names the latest version.

Response format

The Accept header selects the response format:

Request body

A request body has two required fields and four optional ones: The reference below describes every field.

Example request

This request counts Sign Up events per day over the last 30 days:

Limits

A request can have up to 40 metrics, three breakdowns, and 10 filters.

OpenAPI spec

The reference below is generated from an OpenAPI 3.1 spec, which you can download to generate a client or to give to an AI tool: insights.openapi.json.

Authorizations

Authorization
string
header
required

Service Account

Headers

Mixpanel-Version
string

The API version, as a release date (YYYY-MM-DD), optionally followed by a preview channel (.alpha or .beta). Omitted, the latest released version is used.

Pattern: ^\d{4}-\d{2}-\d{2}(?:\.(?:alpha|beta))?$

Query Parameters

project_id
integer
required

The ID of the project to query.

workspace_id
integer

The ID of the workspace, if applicable.

Body

application/json

An Insights query: metrics calculated over a time range, with optional filters, breakdowns, and comparisons.

metrics
(EventMetric · object | FunnelMetric · object | RetentionMetric · object | CohortMetric · object | FormulaMetric · object)[]
required
Required array length: 1 - 40 elements
time
Time · object
required
filters
(PropertyFilter · object | CohortFilter · object)[] | null
Maximum array length: 10

Set type to property to filter on a property value, or cohort to filter on cohort membership.

breakdowns
(PropertyBreakdown · object | CohortBreakdown · object)[] | null
Maximum array length: 3

Groups results by a property's values.

The optional bucketing follows the property's type: datetime_unit for datetime, numeric_buckets for number, string_groups for string.

time_comparison
TimeComparison · object | null

An earlier window to run the same query over.

lift_comparison
LiftComparison · object | null

Reports each result as a change against a baseline rather than an absolute value.