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

# Traces API

> Log, list, and retrieve AI call traces.

## Log a Trace

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.trainlyai.com/v1/{project_id}/traces \
    -H "Authorization: Bearer tk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "Translate to French: Hello world",
      "output": "Bonjour le monde",
      "model": "gpt-4o",
      "latency_ms": 612.3,
      "tags": ["translation"],
      "token_usage": {
        "prompt_tokens": 18,
        "completion_tokens": 8,
        "total_tokens": 26
      },
      "status": "success"
    }'
  ```
</CodeGroup>

`POST /v1/{project_id}/traces`

### Request Body

| Parameter           | Type          | Required | Description                                                         |
| ------------------- | ------------- | -------- | ------------------------------------------------------------------- |
| `input`             | string        | Yes      | The prompt or input sent to the model                               |
| `output`            | string        | Yes      | The model's response                                                |
| `model`             | string        | No       | Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)        |
| `latency_ms`        | float         | No       | End-to-end latency in milliseconds                                  |
| `tags`              | list\[string] | No       | Arbitrary tags for filtering                                        |
| `token_usage`       | object        | No       | Token counts: `prompt_tokens`, `completion_tokens`, `total_tokens`  |
| `metadata`          | object        | No       | Arbitrary key-value metadata                                        |
| `custom_attributes` | object        | No       | Custom structured attributes for filtering and grouping             |
| `version`           | string        | No       | Prompt or model version string                                      |
| `session_id`        | string        | No       | Group related traces into a session                                 |
| `spans`             | list          | No       | Sub-operation spans with name, start/end timestamps, and attributes |
| `cost`              | float         | No       | Total cost in USD for this call                                     |
| `tool_calls`        | list          | No       | Tool/function calls made during the trace                           |
| `status`            | string        | No       | `"success"` or `"error"` (default: `"success"`)                     |
| `error`             | string        | No       | Error message if `status` is `"error"`                              |

### Response

```json theme={null}
{
  "trace_id": "trc_9f8e7d6c5b4a",
  "status": "created"
}
```

***

## List Traces

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.trainlyai.com/v1/{project_id}/analytics/traces?limit=50&status=error&start_date=2026-04-01T00:00:00Z" \
    -H "Authorization: Bearer tk_your_api_key"
  ```
</CodeGroup>

`GET /v1/{project_id}/analytics/traces`

### Query Parameters

| Parameter    | Type   | Default | Description                        |
| ------------ | ------ | ------- | ---------------------------------- |
| `limit`      | int    | 100     | Max traces to return (1-1000)      |
| `status`     | string | —       | Filter by `"success"` or `"error"` |
| `start_date` | string | —       | ISO 8601 datetime lower bound      |
| `end_date`   | string | —       | ISO 8601 datetime upper bound      |

### Response

```json theme={null}
[
  {
    "trace_id": "trc_9f8e7d6c5b4a",
    "input": "Translate to French: Hello world",
    "output": "Bonjour le monde",
    "model": "gpt-4o",
    "latency_ms": 612.3,
    "status": "success",
    "tags": ["translation"],
    "token_usage": {
      "prompt_tokens": 18,
      "completion_tokens": 8,
      "total_tokens": 26
    },
    "cost": 0.00034,
    "created_at": "2026-04-07T14:23:01Z"
  }
]
```

***

## Get Trace Details

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.trainlyai.com/v1/{project_id}/analytics/traces/trc_9f8e7d6c5b4a" \
    -H "Authorization: Bearer tk_your_api_key"
  ```
</CodeGroup>

`GET /v1/{project_id}/analytics/traces/{trace_id}`

### Response

```json theme={null}
{
  "trace_id": "trc_9f8e7d6c5b4a",
  "input": "Translate to French: Hello world",
  "output": "Bonjour le monde",
  "model": "gpt-4o",
  "latency_ms": 612.3,
  "status": "success",
  "tags": ["translation"],
  "token_usage": {
    "prompt_tokens": 18,
    "completion_tokens": 8,
    "total_tokens": 26
  },
  "metadata": {},
  "custom_attributes": {},
  "version": "v1.2.0",
  "session_id": "sess_abc123",
  "cost": 0.00034,
  "tool_calls": [],
  "spans": [
    {
      "name": "llm_call",
      "start_ms": 0,
      "end_ms": 610,
      "attributes": { "provider": "openai" }
    }
  ],
  "created_at": "2026-04-07T14:23:01Z"
}
```