> ## 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 events for users via HTTP API to monitor actions, feature usage, and engagement for analytics, segmentation, and content triggering.

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

<Note>
  The endpoint URL uses the `analytex` environment. For EU data residency, use
  `analytex-eu` instead. See [Environment
  Settings](https://run.userpilot.io/environment) for your specific endpoint.
</Note>

{" "}

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