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

> Every span of one conversation, ordered by start time, with parent links so you can rebuild the tree.

Returns all spans recorded for a conversation. Each span carries `parent_span_id`, so you can nest them: a `polyai.turn` contains the LLM, function and retrieval spans that produced that turn. Function spans carry `span_id` values you can pass to [search function logs](https://docs.poly.ai/api-reference/traces/endpoint/search-logs.md) to read what that execution wrote.

## Request

### Headers

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

Account API key with read access to conversations.

### Path parameters

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

The conversation to fetch.

### 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 spans returned, at most 10,000.

**spans** `object[]`

Ordered by `timestamp` ascending.

**properties**

**timestamp** `datetime`

Span start, UTC.

**trace\_id** `string`

**span\_id** `string`

**parent\_span\_id** `string`

`null` on a root span. It can also name a span that is not in the response, because internal spans are filtered out; treat such spans as roots of their subtree.

**span\_name** `string`

See the [span names](https://docs.poly.ai/api-reference/traces/introduction.md#spans).

**span\_kind** `string`

OpenTelemetry span kind, for example `Internal` or `Client`.

**duration\_ns** `integer`

**duration\_ms** `number`

**status\_code** `string`

`Ok`, `Error` or `Unset`.

**conversation\_id** `string`

**project\_id** `string`

**turn\_index** `integer`

0-based turn. `null` on spans outside a turn.

**function\_name** `string`

Function spans only.

**function\_execution\_id** `string`

Function spans only.

**function\_originating\_turn\_index** `integer`

Function spans only: the turn that triggered the call.

**function\_attempt** `integer`

Function spans only: attempt number, higher on retries.

**prompt\_tokens** `integer`

LLM spans, when the provider reports token usage.

**cached\_tokens** `integer`

LLM spans, when reported: prompt tokens served from the provider's prefix cache.

**prefix\_cache\_hit\_ratio** `number`

LLM spans, when reported: share of the prompt served from the prefix cache, 0–1.

## Example

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.us.poly.ai/api/v1/traces/conversations/CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f?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": 9,
  "spans": [
    {
      "timestamp": "2026-10-27T15:07:34.930309",
      "trace_id": "04f15d938151e7a09877c39978e7875f",
      "span_id": "4519400991678f44",
      "parent_span_id": "fb4025dc254eb11f",
      "span_name": "polyai.turn",
      "span_kind": "Internal",
      "duration_ns": 19071851,
      "duration_ms": 19.071851,
      "status_code": "Unset",
      "conversation_id": "CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f",
      "project_id": "PROJECT-V258TF29",
      "turn_index": 0,
      "function_name": null,
      "function_execution_id": null,
      "function_originating_turn_index": null,
      "function_attempt": null,
      "prompt_tokens": null,
      "cached_tokens": null,
      "prefix_cache_hit_ratio": null
    }
  ]
}
```

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