Track Event

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.

Headers

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

Identify User API - Create users before tracking events
JavaScript SDK track() - Browser-based event tracking
Events Dashboard - View tracked events
Funnel Reports - Analyze event sequences

APIs

Real-time HTTP

Bulk Identify/Update

Bulk Import

Bulk Export

Bulk Delete

When to Use

Prerequisites

Endpoint

Headers

Request Body

Example

Example cURL Command

Response

Common Issues

​When to Use

​Prerequisites

​Endpoint

​Headers

​Request Body

​Example

​Example cURL Command

​Response

​Common Issues

​Related

When to Use

Prerequisites

Endpoint

Headers

Request Body

Example

Example cURL Command

Response

Common Issues

Related