---
updatedAt: 2026-06-03T21:28:36.000Z
agentTools:
projectIndex: https://developers.heap.io/llms.txt
---
# Track
Use this API to send custom events to Heap server-side. We recommend using this for events that need to exactly match your backend, such as completed order transaction info, or events that are not available for Heap to capture on the client-side.
**NOTE: It is required that you use either the `identity` or `user_id` param, but not both.**
> ❗️ Limitations
>
> * Requests are limited to 30 requests per 30 seconds per identity per app\_id.
> * It is required that you use either the `identity` or `user_id` param, but not both.
> * Please note: `fetch`, `jQuery`, and `XMLHttpRequest` options are not currently supported.
> 🚧 If your Heap data is in an EU datacenter, the correct endpoint is:
>
> (**NOT** heapanalytics.com)
> ❗️ **Reserved property keys**
>
> Do not use `user_id`, `session_id`, or `screen_name` as keys inside the `properties` object. `user_id` and `session_id` are reserved top-level request fields — reusing them inside `properties` may produce unexpected behavior. `screen_name` conflicts with Heap's autocaptured Screen Name property on mobile and may cause confusion in reports.
## Array property values
The `properties` object can contain array values. Upon ingestion, array values are converted to strings with a `||` delimiter. In the example below, the array is stored as the string`"vanilla||chocolate||strawberry"`. The converted string value can be up to 1024 characters, any characters beyond this limit will be truncated.
```curl
curl -X POST \
-H "Content-Type: application/json" \
-d '{
"app_id": "11",
"identity": "heappo@heap.io",
"event": "Send Transactional Email",
"timestamp": "2017-03-10T22:21:56+00:00",
"properties": {
"subject": "Welcome to My App!",
"variation": "A",
"flavors": ["vanilla", "chocolate", "strawberry"]
}
}' \
https://heapanalytics.com/api/track
```
## Leverage properties with custom events
We recommend naming custom events broadly and using properties to distinguish between different types of events. This makes analysis in Heap easier, and additional events can be labeled in Heap to create subsets of any broader events.
:white\_check\_mark: For example, if you want to send error events into Heap, we recommend:
`heap.track('Error', {message: 'Authentication Failed'});`
`heap.track('Error', {message: 'Field Validation'});`
:x: Instead of:
`heap.track('Error: Authentication Failed');`
`heap.track('Error: Field Validation');`
{`
Did you find what you were looking for?
`}
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "server-side-api",
"version": "1.0"
},
"servers": [
{
"url": "https://heapanalytics.com/"
}
],
"security": [
{}
],
"paths": {
"/api/track": {
"post": {
"summary": "Track",
"description": "Use this API to send custom events to Heap server-side. We recommend using this for events that need to exactly match your backend, such as completed order transaction info, or events that are not available for Heap to capture on the client-side.
**NOTE: It is required that you use either the `identity` or `user_id` param, but not both.**",
"operationId": "track-1",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"app_id",
"event"
],
"properties": {
"app_id": {
"type": "string",
"description": "The environment ID corresponding to one of your environments."
},
"event": {
"type": "string",
"description": "The name of the server-side event. Limited to 1024 characters."
},
"identity": {
"type": "string",
"description": "An identity, typically corresponding to an existing user. If no such identity exists, then a new user will be created with that identity. Case-sensitive string, limited to 255 characters."
},
"user_id": {
"type": "string",
"description": "The user_id from the Heap SDK. The user_id must be the string representation of a number between zero and 2^53 - 1. user_id may be specified instead of identity, but both cannot be provided at the same time."
},
"session_id": {
"type": "string",
"description": "An identifier corresponding to a user's session"
},
"properties": {
"type": "object",
"description": "An object with key-value properties you want associated with the event. Each key and property must either be a number or string with fewer than 1024 characters.",
"properties": {
"example_name": {
"type": "string",
"default": "example_value"
}
}
},
"timestamp": {
"type": "string",
"description": "ISO8601 e.g. \"2017-03-10T22:21:56+00:00\". Defaults to the current time if not provided."
},
"idempotency_key": {
"type": "string",
"description": "A unique ID that will be hashed to Heap's event ID keyspace, to prevent duplication of events. Subsequent calls with the same idempotency key will not update data."
}
}
}
}
}
},
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{}"
}
},
"schema": {
"type": "object",
"properties": {}
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{}"
}
},
"schema": {
"type": "object",
"properties": {}
}
}
}
}
},
"x-readme": {
"code-samples": [
{
"language": "curl",
"code": "curl \\\n -X POST \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"app_id\": \"11\",\n \"identity\": \"alice@example.com\",\n \"event\": \"Send Transactional Email\",\n \"timestamp\": \"2017-03-10T22:21:56+00:00\", \n \"properties\": {\n \"subject\": \"Welcome to My App!\",\n \"variation\": \"A\"\n }\n }' \\\n https://heapanalytics.com/api/track"
}
],
"samples-languages": [
"curl"
]
}
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```