Events

Track user events and behaviors

POST /import

Events

cURL

curl --request POST \
  --url https://api.mixpanel.com/import \
  --header 'Content-Type: application/json' \
  --data '
{
  "event": "<string>",
  "properties": {
    "token": "<string>",
    "distinct_id": "<string>",
    "time": 123,
    "$insert_id": "<string>"
  }
}
'

200

{
  "code": 123,
  "num_records_imported": 123,
  "status": "<string>",
  "failed_records": [
    {
      "index": 123,
      "insert_id": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

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

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

200 Success

{
  "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.

ip · 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

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 epoch

Solution: 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 errors

Solution: 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 bytes

Solution:

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