# Reading data

Fetch sessions, transcripts, traces, spans, and analysis results back out of Brizz over HTTP.

Brizz's platform API reads back everything the SDK sent in, plus what Brizz computed from it — conversations, traces, spans, costs, and detected problems. Use it to pull a conversation into your own tooling, or to follow up on an [outbound webhook](/docs/api/webhooks.md), whose payload carries identifiers and expects you to fetch the content yourself.

## Base URL and authentication

```
https://platform.brizz.dev/api/v1
```

Every request takes a **Platform API key** as `Token` — not `Bearer`, and not a telemetry key. See [Authentication](/docs/api/overview.md#authentication) for why the distinction matters and where to create the key.

```bash
curl "https://platform.brizz.dev/api/v1/telemetry/otel/sessions/my-agent/SESSION_ID/transcript" \
  -H "Authorization: Token $BRIZZ_PLATFORM_API_KEY"
```

Requests are scoped to the key's tenant and to the projects its owner can see. `{serviceName}` throughout is the trace service name — the same value a webhook payload carries as `data.service_name`.

## Read a session

Given a service name and a session id — the two fields a `session.matured` webhook gives you — this is the endpoint to start from:

`GET /telemetry/otel/sessions/{serviceName}/{sessionId}/transcript`

Parameters:

- `limit` — items per page. Default 100, maximum 500.
- `offset` — pagination offset.
- `content` — `lean` (default) previews heavy tool inputs and results and reports their original lengths; `full` returns them inline. Start with `lean` and drill into single items.

```bash
curl "https://platform.brizz.dev/api/v1/telemetry/otel/sessions/my-agent/sess_abc123/transcript?limit=200" \
  -H "Authorization: Token $BRIZZ_PLATFORM_API_KEY"
```

Success response — conversation items in the order the dashboard renders them, with counts and pagination alongside.

Prefer `/transcript` over the dashboard's `/conversation` endpoint. `/transcript` reads persisted conversation items rather than reprocessing raw spans on every request, it pages over items rather than spans, and — the part that matters to a webhook receiver — it reports whether the data is ready instead of silently returning less than exists.

Always check `status` before treating a response as final:

| `status` | Meaning | What to do |
|---|---|---|
| `complete` | Every span the session produced has been through the pipeline. | Use it. |
| `partial` | Items exist, but the session has spans newer than anything materialized — the tail is still coming. | Use what's there if you want, then re-read after `retryAfterSeconds`. |
| `processing` | The session has spans but nothing materialized yet. `items` is empty. | Wait `retryAfterSeconds` and retry. Do **not** read this as "no data". |

```json
{ "status": "processing", "retryAfterSeconds": 15 }
```

`retryAfterSeconds` accompanies both `partial` and `processing`; honor it rather than picking your own interval. Watch `truncated` too — when `true`, the session exceeded the per-read item cap and the tail is missing regardless of paging.

### Other session reads

All of these hang off `https://platform.brizz.dev/api/v1/telemetry/otel/sessions/{serviceName}/{sessionId}`:

| Purpose | Endpoint |
|---|---|
| One transcript item in full, with reasoning and raw span attributes | `GET …/transcript/items/{itemId}` |
| The traces that make up the session | `GET …/traces` |
| Raw spans | `GET …/spans` |
| Span hierarchy | `GET …/tree`, `GET …/graph` |
| Events emitted during the session | `GET …/events` |
| AI-written summary | `GET …/tldr` |
| Problems Brizz detected | `GET …/problem-analysis` |
| Cost breakdown | `GET …/cost-by-model`, `GET …/tool-costs` |
| Tool schemas seen in the session | `GET …/tool-schemas` |

Session metrics and intents are keyed differently:

| Purpose | Endpoint |
|---|---|
| Metrics computed for the session | `GET /telemetry/metrics/session/{serviceName}/{sessionId}` |
| One metric by name | `GET /telemetry/metrics/session/{sessionId}/{metricName}` |
| Intents matched to the session | `GET /telemetry/otel/sessions/{sessionId}/intents?trace_service_name={serviceName}` |

### Session metadata

There is no `GET /telemetry/otel/sessions/{serviceName}/{sessionId}`. To fetch a single session's row — status, timings, labels, metric rollups — query the list endpoint with a filter:

```bash
curl -X POST "https://platform.brizz.dev/api/v1/telemetry/otel/sessions/filtered" \
  -H "Authorization: Token $BRIZZ_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceName": "my-agent",
    "filters": [{"field": "sessionId", "operator": "equals", "value": "sess_abc123"}],
    "limit": 1,
    "skipTotalCount": true
  }'
```

The same endpoint without the `sessionId` filter is how you search sessions by time range, label, or metric.

## Read a trace

Given a service name and a trace id — what a `trace.matured` webhook gives you:

| Purpose | Endpoint |
|---|---|
| The trace | `GET /telemetry/otel/trace/{traceId}?serviceName={serviceName}` |
| Its spans | `GET /telemetry/otel/spans/{serviceName}/{traceId}` |
| One span | `GET /telemetry/otel/spans/{spanId}` |
| Its events | `GET /telemetry/otel/events/{serviceName}/{traceId}` |
| Metrics computed for it | `GET /telemetry/metrics/trace/{traceId}` |

```bash
curl "https://platform.brizz.dev/api/v1/telemetry/otel/trace/TRACE_ID?serviceName=my-agent" \
  -H "Authorization: Token $BRIZZ_PLATFORM_API_KEY"
```

:::warning
Two things to get right here. The path is **singular** — `/telemetry/otel/trace/{traceId}`; there is no `GET /telemetry/otel/traces/{traceId}` and it returns `404`, because the plural `traces` path is the bulk query `POST /telemetry/otel/traces/filtered`. And unlike the spans and events endpoints below it, this one takes the service name as a **query parameter** rather than a path segment — omit it and you get `400 — serviceName query parameter is required`. Both mistakes fail loudly rather than returning an empty result, so they surface the first time you run the call.
:::

## Read analysis results

Issues and findings are the deduplicated problem signals Brizz derives across sessions, rather than anything tied to a single one:

| Purpose | Endpoint |
|---|---|
| Search issues | `POST /telemetry/otel/issues/filtered` |
| Issue statistics | `POST /telemetry/otel/issues/{serviceName}/stats` |
| One issue's breakdown | `GET /telemetry/otel/issues/{issueId}/breakdown?service_name={serviceName}` |
| Search findings | `POST /telemetry/otel/findings/filtered` |
| Finding statistics | `GET /telemetry/otel/findings/{serviceName}/stats` |

Both `filtered` endpoints identify the service in the request body, but spell the field differently: sessions and traces take `serviceName`, issues and findings take `service_name`.

## Common errors

- **401** — missing key, a telemetry key instead of a Platform API key, or a Platform API key sent as `Bearer` instead of `Token`.
- **403** — the key's role or its owner's project membership doesn't cover this service.
- **404** — no such session, trace, or span in your tenant.
- **402** — your plan doesn't include this endpoint. Intents and journeys are the reads most likely to return this.

## See also

- [API overview](/docs/api/overview.md) — the two hosts, the two credentials, and the error model.
- [Outbound webhooks](/docs/api/webhooks.md) — get told when a session or trace is ready to read.
- [MCP server](/docs/integrations/mcp-server/overview.md) — the same reads exposed to AI agents as tools, if you'd rather not write HTTP calls.
- [Telemetry ingestion](/docs/api/telemetry.md) — the write side, on a different host with a different credential.

Support: support@brizz.ai