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

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

FAQs

What's the difference between the Track Event API and SDK's userpilot.track()?

Use the Track Event API for server-side events, actions that don’t happen in a browser and use the JavaScript SDK’s userpilot.track() when the action happens in your web app and you need the event available immediately for content triggering.

How long does it take for a tracked event to appear in the dashboard?

Events may take up to 15 minutes to appear due to processing delay. If an event still hasn’t shown up after that, check that the request returned 202 Accepted and that user_id matches an already-identified user.

What data types can I send in metadata?

Only primitive types such as string, number, boolean, or null are supported currently and
nested objects/ arrays aren’t supported.

For any questions or concerns please reach out to support@userpilot.com

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

FAQs

​When to Use

​Prerequisites

​Endpoint

​Headers

​Request Body

​Example

​Example cURL Command

​Response

​Common Issues

​Related

​FAQs

When to Use

Prerequisites

Endpoint

Headers

Request Body

Example

Example cURL Command

Response

Common Issues

Related

FAQs