Track Events

Events represent user actions in your application. Use the Ingestion API to send events to Mixpanel for analysis.

Import Events

The Import API provides server-side event tracking with full validation and detailed error reporting.

project_id

string

required

Your Mixpanel project ID (required when using service account authentication)

strict

string

default:"1"

When set to 1 (recommended), Mixpanel validates the batch and returns errors per event that failed.Options: 0 or 1

Content-Type

string

default:"application/json"

The content type of the request body.Options:

application/json: Standard JSON array
application/x-ndjson: Newline-delimited JSON

Content-Encoding

string

Compression method for the request body.Options: gzip

Request Body

event

string

required

The name of the event (e.g., “Signed Up”, “Purchase Complete”)

properties

object

required

Event properties object

Show properties

time

integer

required

Event timestamp in seconds or milliseconds since UTC epoch. If set in the future, it will be overwritten with the current time at ingestion.

distinct_id

string

required

The unique identifier of the user who performed the event

$insert_id

string

required

A unique identifier for the event, used for deduplication. Events with identical (event, time, distinct_id, $insert_id) are considered duplicates.

[custom properties]

any

Any additional custom properties for the event

Example Request

curl https://api.mixpanel.com/import?strict=1&project_id=YOUR_PROJECT_ID \
  -u SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET \
  -H "Content-Type: application/json" \
  -d '[
    {
      "event": "Signed Up",
      "properties": {
        "time": 1609459200,
        "distinct_id": "user123",
        "$insert_id": "28a0f0a8-4e8c-4c4e-b8c1-832e9e5c5e5e",
        "signup_method": "email",
        "plan": "premium"
      }
    },
    {
      "event": "Purchase",
      "properties": {
        "time": 1609459260,
        "distinct_id": "user123",
        "$insert_id": "3f9a2c5b-7d1e-4b2a-9c3d-4e5f6a7b8c9d",
        "amount": 29.99,
        "currency": "USD",
        "item_name": "Premium Plan"
      }
    }
  ]'

Response

code

integer

HTTP status code (200 for success)

num_records_imported

integer

Number of events successfully imported

status

string

Status message (“OK” for success)

failed_records

array

Array of failed events (only present when strict=1 and some events failed)

Show failed_records[]

index

integer

Index of the failed event in the request array

insert_id

string

The $insert_id of the failed event

field

string

The field that caused the validation error

message

string

Description of the validation error

{
  "code": 200,
  "num_records_imported": 2,
  "status": "OK"
}

Track Events (Client-Side)

The Track API is designed for client-side event tracking using your project token.

string

If set to 1, uses the IP address of the request to determine geolocation

verbose

string

If set to 1, returns a verbose JSON response instead of simple 1 or 0

Request Body

event

string

required

The name of the event

properties

object

required

Event properties

Show properties

token

string

required

Your project token

distinct_id

string

required

Unique identifier for the user

time

integer

Event timestamp in seconds or milliseconds since UTC epoch

$insert_id

string

Unique identifier for deduplication

Example Request

curl https://api.mixpanel.com/track \
  --data-urlencode data='[
    {
      "event": "Page View",
      "properties": {
        "token": "YOUR_PROJECT_TOKEN",
        "distinct_id": "user123",
        "time": 1609459200,
        "page_name": "Homepage",
        "referrer": "google.com"
      }
    }
  ]'

Response

Returns 1 for success, 0 for failure.

Best Practices

Always use $insert_id for deduplication

This ensures events aren’t duplicated if a request is retried:

import uuid

properties = {
    "$insert_id": str(uuid.uuid4()),
    "distinct_id": "user123",
    "time": int(time.time())
}

Use server-side tracking when possible

The Import API provides:

Better validation and error reporting
More secure (credentials not exposed to clients)
Support for historical data imports

Batch events for better performance

Send up to 2000 events per request:

batch = []
for i in range(2000):
    batch.append(create_event(...))

response = requests.post(url, json=batch)

Use meaningful event names

Use clear, consistent naming:

Good: “Signed Up”, “Purchase Completed”, “Video Played”
Bad: “event1”, “action”, “e”

Include relevant context in properties

Add properties that help analyze the event:

{
  "event": "Purchase Completed",
  "properties": {
    "amount": 29.99,
    "currency": "USD",
    "item_name": "Premium Plan",
    "payment_method": "credit_card",
    "coupon_code": "SAVE10"
  }
}

Common Errors

Invalid timestamp

Error: 'properties.time' is invalid: must be specified as seconds since epochSolution: Ensure timestamps are in seconds (not milliseconds) or milliseconds (with 13 digits)

# Correct: seconds
"time": int(time.time())

# Correct: milliseconds
"time": int(time.time() * 1000)

Missing required fields

Error: Various validation errorsSolution: Ensure all required fields are present:

event name
properties.distinct_id
properties.time
properties.$insert_id (for /import)

Payload too large

Error: request exceeds max limit of 2097152 bytesSolution:

Reduce batch size (max 2000 events)
Use gzip compression
Split into multiple requests

Getting Started

Ingestion API

Query API

Data Pipelines API

Management APIs

Compliance APIs

Events

Track Events

Import Events

Request Body

Example Request

Response

Track Events (Client-Side)

Request Body

Example Request

Response

Best Practices

Common Errors

Build docs developers (and LLMs) love

Getting Started

Ingestion API

Query API

Data Pipelines API

Management APIs

Compliance APIs

​Track Events

​Import Events

​Request Body

​Example Request

​Response

​Track Events (Client-Side)

​Request Body

​Example Request

​Response

​Best Practices

​Common Errors

Build docs developers (and LLMs) love

Track Events

Import Events

Request Body

Example Request

Response

Track Events (Client-Side)

Request Body

Example Request

Response

Best Practices

Common Errors