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

# Get conversation timeline

> One row per turn and span name, with start, end, duration and error count, in order.

Collapses a conversation's spans into a chronological timeline: for each turn and span name, when the first such span started, when the last one ended, how long they ran in total, and how many failed. Lighter than [fetching every span](https://docs.poly.ai/api-reference/traces/endpoint/get-conversation-trace.md) when you want a per-turn latency picture.

## Request

### Headers

**X-API-KEY** `string` *required*

Account API key with read access to conversations.

### Path parameters

**conversation\_id** `string` *required*

The conversation to summarise.

### Query parameters

**project\_id** `string`

The agent the conversation belongs to. Optional with an account API key.

## Response

**conversation\_id** `string`

**project\_id** `string`

**total** `integer`

Number of entries.

**entries** `object[]`

Ordered by `turn_index`, then `start_time`.

**properties**

**turn\_index** `integer`

`null` for spans outside a turn.

**span\_name** `string`

**start\_time** `datetime`

Earliest start among the group's spans, UTC.

**end\_time** `datetime`

Latest end among the group's spans, UTC.

**duration\_ns** `integer`

Sum of the group's span durations. Can be less than `end_time - start_time` when the spans do not run back to back.

**duration\_ms** `number`

**error\_count** `integer`

Spans in the group with status `Error`.

## Example

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.us.poly.ai/api/v1/traces/conversations/CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f/timeline?project_id=PROJECT-V258TF29" \
  -H "X-API-KEY: YOUR_API_KEY"
```

```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "conversation_id": "CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f",
  "project_id": "PROJECT-V258TF29",
  "total": 8,
  "entries": [
    {
      "turn_index": 0,
      "span_name": "polyai.turn",
      "start_time": "2026-10-27T15:07:34.930309",
      "end_time": "2026-10-27T15:07:34.949381",
      "duration_ns": 19071851,
      "duration_ms": 19.071851,
      "error_count": 0
    },
    {
      "turn_index": 0,
      "span_name": "polyai.goose.llemur.call",
      "start_time": "2026-10-27T15:07:34.930317",
      "end_time": "2026-10-27T15:07:34.946786",
      "duration_ns": 16468707,
      "duration_ms": 16.468707,
      "error_count": 0
    }
  ]
}
```

## Errors

| Status | Meaning |
| - | - |
| `401` | Missing or invalid API key. |
| `403` | The key cannot read conversations. |
| `404` | The conversation has no spans, or belongs to another account. |
| `502` | The trace backend did not answer. |