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

{
  "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

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.