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>"
  }
}
'

import requests

url = "https://api.mixpanel.com/import"

payload = {
    "event": "<string>",
    "properties": {
        "token": "<string>",
        "distinct_id": "<string>",
        "time": 123,
        "$insert_id": "<string>"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    event: '<string>',
    properties: {token: '<string>', distinct_id: '<string>', time: 123, $insert_id: '<string>'}
  })
};

fetch('https://api.mixpanel.com/import', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpanel.com/import",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'event' => '<string>',
    'properties' => [
        'token' => '<string>',
        'distinct_id' => '<string>',
        'time' => 123,
        '$insert_id' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpanel.com/import"

	payload := strings.NewReader("{\n  \"event\": \"<string>\",\n  \"properties\": {\n    \"token\": \"<string>\",\n    \"distinct_id\": \"<string>\",\n    \"time\": 123,\n    \"$insert_id\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mixpanel.com/import")
  .header("Content-Type", "application/json")
  .body("{\n  \"event\": \"<string>\",\n  \"properties\": {\n    \"token\": \"<string>\",\n    \"distinct_id\": \"<string>\",\n    \"time\": 123,\n    \"$insert_id\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpanel.com/import")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"event\": \"<string>\",\n  \"properties\": {\n    \"token\": \"<string>\",\n    \"distinct_id\": \"<string>\",\n    \"time\": 123,\n    \"$insert_id\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

string

required

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

string

default:"1"

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

string

default:"application/json"

The content type of the request body.Options:

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

string

Compression method for the request body.Options: gzip

Request Body

string

required

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

object

required

Event properties object

Show properties

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.

string

required

The unique identifier of the user who performed the event

string

required

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

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"
      }
    }
  ]'

import requests
import time
import uuid
from requests.auth import HTTPBasicAuth

events = [
    {
        "event": "Signed Up",
        "properties": {
            "time": int(time.time()),
            "distinct_id": "user123",
            "$insert_id": str(uuid.uuid4()),
            "signup_method": "email",
            "plan": "premium"
        }
    },
    {
        "event": "Purchase",
        "properties": {
            "time": int(time.time()),
            "distinct_id": "user123",
            "$insert_id": str(uuid.uuid4()),
            "amount": 29.99,
            "currency": "USD"
        }
    }
]

response = requests.post(
    'https://api.mixpanel.com/import',
    auth=HTTPBasicAuth('SERVICE_ACCOUNT_USERNAME', 'SERVICE_ACCOUNT_SECRET'),
    params={
        'project_id': 'YOUR_PROJECT_ID',
        'strict': '1'
    },
    json=events
)

print(response.json())

const events = [
  {
    event: 'Signed Up',
    properties: {
      time: Math.floor(Date.now() / 1000),
      distinct_id: 'user123',
      $insert_id: crypto.randomUUID(),
      signup_method: 'email',
      plan: 'premium'
    }
  },
  {
    event: 'Purchase',
    properties: {
      time: Math.floor(Date.now() / 1000),
      distinct_id: 'user123',
      $insert_id: crypto.randomUUID(),
      amount: 29.99,
      currency: 'USD'
    }
  }
];

const username = 'SERVICE_ACCOUNT_USERNAME';
const password = 'SERVICE_ACCOUNT_SECRET';
const auth = 'Basic ' + btoa(username + ':' + password);

fetch('https://api.mixpanel.com/import?strict=1&project_id=YOUR_PROJECT_ID', {
  method: 'POST',
  headers: {
    'Authorization': auth,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(events)
})
.then(response => response.json())
.then(data => console.log(data));

Response

integer

HTTP status code (200 for success)

integer

Number of events successfully imported

string

Status message (“OK” for success)

array

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

Show failed_records[]

integer

Index of the failed event in the request array

string

The $insert_id of the failed event

string

The field that caused the validation error

string

Description of the validation error

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

{
  "code": 400,
  "error": "Some data points in the request failed validation.",
  "status": "Bad Request",
  "num_records_imported": 1,
  "failed_records": [
    {
      "index": 0,
      "insert_id": "28a0f0a8-4e8c-4c4e-b8c1-832e9e5c5e5e",
      "field": "properties.time",
      "message": "'properties.time' is invalid: must be specified as seconds since epoch"
    }
  ]
}

{
  "code": 401,
  "error": "Invalid credentials",
  "status": "Unauthorized"
}

{
  "code": 413,
  "error": "request exceeds max limit of 2097152 bytes",
  "status": "Request Entity Too Large"
}

{
  "code": 429,
  "error": "Project exceeded rate limits. Please retry the request with exponential backoff.",
  "status": "Too Many Requests"
}

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

string

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

Request Body

string

required

The name of the event

object

required

Event properties

Show properties

string

required

Your project token

string

required

Unique identifier for the user

integer

Event timestamp in seconds or milliseconds since UTC epoch

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"
      }
    }
  ]'

const event = {
  event: 'Page View',
  properties: {
    token: 'YOUR_PROJECT_TOKEN',
    distinct_id: 'user123',
    time: Math.floor(Date.now() / 1000),
    page_name: 'Homepage'
  }
};

fetch('https://api.mixpanel.com/track', {
  method: 'POST',
  body: 'data=' + encodeURIComponent(JSON.stringify([event]))
});

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

⌘I

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>"
  }
}
'

import requests

url = "https://api.mixpanel.com/import"

payload = {
    "event": "<string>",
    "properties": {
        "token": "<string>",
        "distinct_id": "<string>",
        "time": 123,
        "$insert_id": "<string>"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    event: '<string>',
    properties: {token: '<string>', distinct_id: '<string>', time: 123, $insert_id: '<string>'}
  })
};

fetch('https://api.mixpanel.com/import', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpanel.com/import",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'event' => '<string>',
    'properties' => [
        'token' => '<string>',
        'distinct_id' => '<string>',
        'time' => 123,
        '$insert_id' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpanel.com/import"

	payload := strings.NewReader("{\n  \"event\": \"<string>\",\n  \"properties\": {\n    \"token\": \"<string>\",\n    \"distinct_id\": \"<string>\",\n    \"time\": 123,\n    \"$insert_id\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mixpanel.com/import")
  .header("Content-Type", "application/json")
  .body("{\n  \"event\": \"<string>\",\n  \"properties\": {\n    \"token\": \"<string>\",\n    \"distinct_id\": \"<string>\",\n    \"time\": 123,\n    \"$insert_id\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpanel.com/import")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"event\": \"<string>\",\n  \"properties\": {\n    \"token\": \"<string>\",\n    \"distinct_id\": \"<string>\",\n    \"time\": 123,\n    \"$insert_id\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

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

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

​Track Events

​Import Events

​Request Body

​Example Request

​Response

​Track Events (Client-Side)

​Request Body

​Example Request

​Response

​Best Practices

​Common Errors

Track Events

Import Events

Request Body

Example Request

Response

Track Events (Client-Side)

Request Body

Example Request

Response

Best Practices

Common Errors