# Sessions and usage

> Read a conversation’s transcript, recording and timings, and a flow’s usage over time.

Source: https://voxio.in/docs/sessions-usage · voxioagent 2.0.0 · Index: https://voxio.in/docs/llms.txt

Reading needs only the flow key. Pass it on each call, or set it as the client's default `flowKey`.

## Read a session

Read one session by its id:

```js
const record = await voxio.sessions.get("SESSION_ID", { flowKey: "YOUR_FLOW_KEY" });

record.transcription;        // → [{ role: "user", content: "Hi" }, …]
record.recordingUrl;         // when recording was on
record.startTime;            // ISO 8601
record.totalConnectedTime;   // seconds
```

Replace the following:

- `SESSION_ID`: the session's id. It's on the browser session (`session.sessionId`), in the `ended` event and in every [webhook](https://voxio.in/docs/webhooks.md)
- `YOUR_FLOW_KEY`: the key of the flow the session belongs to

## Read usage

Read a flow's totals for a period, broken down by hour, day, week or month:

```js
const usage = await voxio.sessions.usage({
  flowKey: "YOUR_FLOW_KEY",
  from: "2026-10-01",
  to: "2026-10-31",
  bucket: "day",
});

usage.totals.sessions;                // → 412
usage.totals["connected-minutes"];    // → 1873
usage.buckets;                        // one entry per day, with the same fields
```

Each total and each bucket has these fields:

| Field | What it counts |
| --- | --- |
| `sessions` | Sessions. |
| `connected-seconds`, `connected-minutes` | Time on the line. |
| `ai-seconds`, `human-seconds` | Time each side spent talking. |
| `ai-tokens`, `human-tokens`, `total-tokens` | Tokens on each side. |
| `time-ratio`, `token-ratio` | Agent divided by human, or `null`. |

## Next steps

- [Webhooks](https://voxio.in/docs/webhooks.md): get each session as it happens instead of reading it later.
- [Server SDK](https://voxio.in/docs/server.md): set a default flow key on the client.