Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt

Use this file to discover all available pages before exploring further.

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

HeaderValueRequired
Content-Typeapplication/jsonYes
AuthorizationToken {YOUR_API_KEY}Yes
X-API-Version2020-09-22Yes

​
Request Body

FieldTypeRequiredDescription
user_idstringYesIdentifier of the user associated with the event
event_namestringYesName of the event to track
metadataobjectNoKey-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

ErrorCauseSolution
401 UnauthorizedInvalid API keyVerify API key from Environment settings
400 Bad RequestMissing user_id or event_nameBoth fields are required
Event not appearingProcessing delayEvents may take up to 15 minutes to appear in dashboard
Event not triggering contentUser not identifiedEnsure user exists before tracking events