Skip to main content
POST
/
import
Events
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>"
  }
}
'
{
  "code": 123,
  "num_records_imported": 123,
  "status": "<string>",
  "failed_records": [
    {
      "index": 123,
      "insert_id": "<string>",
      "field": "<string>",
      "message": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mixpanel/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
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)
{
  "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

​
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

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())
}
The Import API provides:
  • Better validation and error reporting
  • More secure (credentials not exposed to clients)
  • Support for historical data imports
Send up to 2000 events per request:
batch = []
for i in range(2000):
    batch.append(create_event(...))

response = requests.post(url, json=batch)
Use clear, consistent naming:
  • Good: “Signed Up”, “Purchase Completed”, “Video Played”
  • Bad: “event1”, “action”, “e”
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

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)
Error: Various validation errorsSolution: Ensure all required fields are present:
  • event name
  • properties.distinct_id
  • properties.time
  • properties.$insert_id (for /import)
Error: request exceeds max limit of 2097152 bytesSolution:
  • Reduce batch size (max 2000 events)
  • Use gzip compression
  • Split into multiple requests

Build docs developers (and LLMs) love

Get started for freeTalk to us