# Conversations

> List conversations, and open one with its turns, findings and scores.

Four `GET` endpoints, for pulling conversations and their evidence into your own warehouse or dashboard. A read-scoped key, on the same host as everything else.

## The endpoints

| | |
|---|---|
| `GET /v1/threads` | The list, newest first, cursor paged |
| `GET /v1/threads/{thread_id}` | One conversation's own record |
| `GET /v1/threads/{thread_id}/sessions` | The calls or chats inside it |
| `GET /v1/sessions/{session_id}` | One call or chat in full, with its evidence |

## Listing conversations

```bash
curl "https://app.evidova.com/v1/threads?limit=50&channel=voice" \
  -H "authorization: Bearer ak_live_..."
```

| | |
|---|---|
| state | The conversation's lifecycle state |
| client_id | One client. A client-limited key may name only its own |
| channel | voice or chat |
| from, to | The window to read |
| limit | 1 to 200. Defaults to 50 |
| cursor | The next_cursor from the previous page |

The response is `{ items, next_cursor }`. A null `next_cursor` is the last page.

## What comes back

### One conversation

| | |
|---|---|
| id, contact_key | Ours, and the key that groups repeat contact from one customer |
| agent_id, client_id | Which agent spoke, and whose customer it was |
| state, outcome, funnel_stage | Where it ended up, and how far it got |
| first_event_at, last_event_at | The window it spans |
| facts | What we extracted from it |

### One session, in full

`GET /v1/sessions/{session_id}` is the leaf, and the one worth linking to from your own tooling. It returns the transcript plus everything we concluded from it.

| | |
|---|---|
| transcript | The turns, in order |
| findings | Which rule broke on which turn |
| scores | The numbers, per score area |
| tool_events | What the agent called, and what came back |
| latency, latency_flags | Reply times, and which ones we called slow |
| versions | Which rules version and which instrument produced the above |

> A key limited to one client gets `404` for a conversation belonging to another, not `403`. The surface never confirms that a row it will not serve exists.

---

Source: https://evidova.com/docs/api/conversations