> ## 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.

# Track Event

> Record custom user events in real time with Userpilot's Track Event HTTP API to power analytics, segmentation, and personalized experiences.

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](https://run.userpilot.io/environment)

## Endpoint

```http theme={null}
[POST] https://analytex.userpilot.io/v1/track
```

<EnvironmentNote />

## 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

```json theme={null}
{
  "user_id": "unique_user_id",
  "event_name": "user_subscribed",
  "metadata": {
    "plan": "free",
    "created_at": "1519205055"
  }
}
```

## Example cURL Command

```bash theme={null}
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.

<Warning>
  Only primitive types (string, number, boolean, null) are supported in metadata.
</Warning>

<Tip>
  Use this endpoint to track any custom event relevant to your analytics or engagement workflows.
</Tip>

***

## 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               |

## Related

* [Identify User API](/api-references/real-time/identify-user) - Create users before tracking events
* [JavaScript SDK track()](/developer/installation/web) - Browser-based event tracking
* [Events Dashboard](/data-events/events-dashboard) - View tracked events
* [Funnel Reports](/product-analytics/reports/funnels) - Analyze event sequences

## FAQs

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="What data types can I send in metadata?">
    Only primitive types such as string, number, boolean, or null are supported currently and <br />nested objects/ arrays aren't supported.
  </Accordion>
</AccordionGroup>

<Frame>
  [For any questions or concerns please reach out to **support@userpilot.com**](mailto:support@userpilot.com)
</Frame>