The Track Event API allows you to record custom events for users in real time. Use this API to monitor user actions, feature usage, and engagement for analytics and personalized experiences.
When to Use
Use the HTTP Track API when:
- Recording events from server-side code (e.g., payment completed, subscription changed)
- Tracking actions that don’t happen in a browser
- Syncing events from external systems (CRM, billing, support)
Use the JavaScript SDK userpilot.track() instead when:
- User performs action in your web application
- You need the event immediately available for content triggering
Prerequisites
- User must already exist in Userpilot (identified via SDK or API)
- Userpilot API Key from Settings > Environment
Endpoint
[POST] https://analytex.userpilot.io/v1/track
The endpoint URL uses the analytex environment. For EU data residency, use
analytex-eu instead. See Environment
Settings for your specific endpoint. | Header | Value | Required |
|---|
Content-Type | application/json | Yes |
Authorization | Token {YOUR_API_KEY} | Yes |
X-API-Version | 2020-09-22 | Yes |
Request Body
| Field | Type | Required | Description |
|---|
user_id | string | Yes | Identifier of the user associated with the event |
event_name | string | Yes | Name of the event to track |
metadata | object | No | Key-value pairs providing additional event details |
Example
{
"user_id": "unique_user_id",
"event_name": "user_subscribed",
"metadata": {
"plan": "free",
"created_at": "1519205055"
}
}
Example cURL Command
curl -X POST https://analytex.userpilot.io/v1/track \
-H 'Content-Type: application/json' \
-H 'Authorization: Token {YOUR_API_KEY}' \
-H 'X-API-Version: 2020-09-22' \
-d '{
"user_id": "unique_user_id",
"event_name": "user_subscribed",
"metadata": {
"plan": "free",
"created_at": "1519205055"
}
}'
Response
A successful event tracking returns HTTP status code 202 Accepted.
- Only primitive types (string, number, boolean, null) are supported in
metadata.
Use this endpoint to track any custom event relevant to your analytics or
engagement workflows.
Common Issues
| Error | Cause | Solution |
|---|
| 401 Unauthorized | Invalid API key | Verify API key from Environment settings |
| 400 Bad Request | Missing user_id or event_name | Both fields are required |
| Event not appearing | Processing delay | Events may take up to 15 minutes to appear in dashboard |
| Event not triggering content | User not identified | Ensure user exists before tracking events |
