> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Events

> Track custom user events in your LLM application using LangWatch to support analytics, evaluations, and agent testing workflows.

Apart from the reserved pre-defined events, you can also define your own events relevant to your business to correlate with your LLM messages and threads to measure your product performance.

Custom events allow you to track any user interactions with your LLM application by sending numeric metrics and capturing additional details about the event. You can define any name for the event on the `event_type` field, and any metric names you want on `metrics` with numeric values, plus any extra details you want to capture on `event_details` with string values. Keep them consistent to visualize on the dashboard, where you can customize the display later on.

## REST API Specification

### Endpoint

`POST /api/track_event`

### Headers

* `X-Auth-Token`: Your LangWatch API key.

### Request Body

```javascript theme={null}
{
  "trace_id": "id of the message the event occurred",
  "event_type": "your_custom_event_type",
  "metrics": {
    "your_metric_key": 123 // Any numeric metric
  },
  "event_details": {
    "your_detail_key": "Any string detail"
  },
  "timestamp": 1617981376000 // Unix timestamp in milliseconds
}
```

### Example

```bash theme={null}
curl -X POST "https://app.langwatch.ai/api/track_event" \\
     -H "X-Auth-Token: your_api_key" \\
     -H "Content-Type: application/json" \\
     -d '{
       "trace_id": "trace_Yy0XWu6BOwwnrkLtQh9Ji",
       "event_type": "add_to_cart",
       "metrics": {
         "amount": 17.5
       },
       "event_details": {
         "product_id": "sku_123",
         "referral_source": "bot_suggested"
       },
       "timestamp": 1617981376000
     }'
```

You can send any event type with corresponding numeric metrics and string details. This flexibility allows you to tailor event tracking to your specific needs.

On the dashboard, you can visualize the tracked events on the "Events" tab when opening the trace details.

<img className="block" src="https://mintcdn.com/langwatch/yNF_rRIoKmcNweQl/images/custom-events.png?fit=max&auto=format&n=yNF_rRIoKmcNweQl&q=85&s=1d314126c88ed98ccebeb914d1d7c12f" alt="Custom Events details table" width="1280" height="371" data-path="images/custom-events.png" />