Track Events API (/track)

POST

track

Track Events

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

import requests

url = "https://{region}.mixpanel.com/track"

payload = [
    {
        "event": "<string>",
        "properties": {
            "token": "<string>",
            "time": 123,
            "distinct_id": "<string>",
            "$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>', time: 123, distinct_id: '<string>', $insert_id: '<string>'}
    }
  ])
};

fetch('https://{region}.mixpanel.com/track', 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://{region}.mixpanel.com/track",
  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>',
                'time' => 123,
                'distinct_id' => '<string>',
                '$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://{region}.mixpanel.com/track"

	payload := strings.NewReader("[\n  {\n    \"event\": \"<string>\",\n    \"properties\": {\n      \"token\": \"<string>\",\n      \"time\": 123,\n      \"distinct_id\": \"<string>\",\n      \"$insert_id\": \"<string>\"\n    }\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://{region}.mixpanel.com/track")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"event\": \"<string>\",\n    \"properties\": {\n      \"token\": \"<string>\",\n      \"time\": 123,\n      \"distinct_id\": \"<string>\",\n      \"$insert_id\": \"<string>\"\n    }\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{region}.mixpanel.com/track")

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  {\n    \"event\": \"<string>\",\n    \"properties\": {\n      \"token\": \"<string>\",\n      \"time\": 123,\n      \"distinct_id\": \"<string>\",\n      \"$insert_id\": \"<string>\"\n    }\n  }\n]"

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

Track events to Mixpanel from client devices. We recommend using one of our client-side SDKs instead of using /track directly, as our SDKs provide queueing, retrying, batching, and more.

When to use /track vs /import

Typically, we recommend using /import for server-side integrations as it is more scalable and supports ingesting historical data. We only recommend /track for client-side tracking in an environment for which we don’t have SDK support or if you’re sending data via some other untrusted environment (eg: third-party webhooks that send data to Mixpanel).

	/track	/import
Events per request	2000	2000
Authentication	Project Token, intended for untrusted clients.	Project Secret/Service Account, intended for server-side integration.
Compression	Gzip allowed	Gzip allowed
Content-Type	application/x-www-form-urlencoded	application/json or application/x-ndjson
Ingesting historical events	Last 5 days only.	Any time after 1971-01-01.

Limits

The limits for track are the same as /import, see here. Each event has the following size limits:

Must be smaller than 1MB of uncompressed JSON.
Must have fewer than 255 properties.
All nested object properties must have fewer than 255 keys and max nesting depth is 3.
All array properties must have fewer than 255 elements.

To ensure real-time ingestion and quality-of-service, we have a rate limit of 2GB of uncompressed JSON/minute or ~30k events per second, measured on a rolling 1 minute basis. We recommend the following when it comes to sending data to our API at scale:

Send data as quickly as possible with concurrent clients until the server returns 429. We see the best results with 10-20 concurrent clients sending 2K events per batch.
When you see 429s, employ an exponential backoff with jitter strategy. We recommend starting with a backoff of 2s and doubling backoff until 60s, with 1-5s of jitter.
We recommend gzip compression and using Content-Encoding: gzip to reduce network egress and transfer time.
In the rare event that our API returns a 502 or 503 status code, we recommend employing the same exponential backoff strategy as with 429s.
Please do not retry validation errors (400 status code), as they will consistently fail and count toward the rate limit.

If you are an Enterprise customer that requires a higher rate limit, please reach out to your CSM with your project_id and use case.

Query Parameters

integer

If present and equal to 1, Mixpanel will use the ip address of the incoming request and compute a distinct_id using a hash function if no distinct_id is provided. This is different from providing a properties.ip value in the Event Object.

Required range: 0 <= x <= 1

verbose

integer

If present and equal to 1, Mixpanel will respond with a JSON Object describing the success or failure of the tracking call. The returned object will have two keys: status, with the value 1 on success and 0 on failure, and error, with a string-valued error message if the request wasn't successful. This is useful for debugging during implementation.

Required range: 0 <= x <= 1

img

integer

If present and equal to 1, Mixpanel will serve a 1x1 transparent pixel image as a response to the request. This is useful for adding Pixel Tracking in places that javascript is not supported.

Required range: 0 <= x <= 1

callback

string

If present, Mixpanel will return a content-type: text/javascript with a body that calls a function by value provided. This is useful for creating local callbacks to a successful track call in JavaScript.

Body

application/json

Minimum array length: 1

event

string

required

The name of the event.

properties

properties · object

required

A JSON object containing properties of the event.

Show child attributes

Response

1 - One or more objects provided are valid. This does not signify a valid project token or secret.
0 - No data objects in the body are valid.

The response is of type enum<integer>.

Available options:

1,

0

Track Events

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

import requests

url = "https://{region}.mixpanel.com/track"

payload = [
    {
        "event": "<string>",
        "properties": {
            "token": "<string>",
            "time": 123,
            "distinct_id": "<string>",
            "$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>', time: 123, distinct_id: '<string>', $insert_id: '<string>'}
    }
  ])
};

fetch('https://{region}.mixpanel.com/track', 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://{region}.mixpanel.com/track",
  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>',
                'time' => 123,
                'distinct_id' => '<string>',
                '$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://{region}.mixpanel.com/track"

	payload := strings.NewReader("[\n  {\n    \"event\": \"<string>\",\n    \"properties\": {\n      \"token\": \"<string>\",\n      \"time\": 123,\n      \"distinct_id\": \"<string>\",\n      \"$insert_id\": \"<string>\"\n    }\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://{region}.mixpanel.com/track")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"event\": \"<string>\",\n    \"properties\": {\n      \"token\": \"<string>\",\n      \"time\": 123,\n      \"distinct_id\": \"<string>\",\n      \"$insert_id\": \"<string>\"\n    }\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{region}.mixpanel.com/track")

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  {\n    \"event\": \"<string>\",\n    \"properties\": {\n      \"token\": \"<string>\",\n      \"time\": 123,\n      \"distinct_id\": \"<string>\",\n      \"$insert_id\": \"<string>\"\n    }\n  }\n]"

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

MIXPANEL APIs

INGESTION API

IDENTITY API

QUERY API

EVENT EXPORT API

LEXICON SCHEMAS API

DATA PIPELINES API

SERVICE ACCOUNTS API

ANNOTATIONS API

GDPR API

WAREHOUSE CONNECTORS API

FEATURE FLAGS API

FEATURE FLAGS MANAGEMENT API

EXPERIMENTS API

PLATFORM API

Track Events API (/track)

When to use /track vs /import

Limits

Query Parameters

Body

Response

​When to use /track vs /import

​Limits

Query Parameters

Body

Response

When to use /track vs /import

Limits