# Sessions

One conversation per computer on the API channel.

A session is a conversation with Sai on one computer. Every message you send through the API lands in the same session for that computer, so a follow-up message continues the last task's context.

## The API channel

Sai has several channels: the desktop app, the `sai` CLI, messaging integrations and this API. Each channel keeps its own session per computer. A message sent over the API never appears in the desktop app's conversation, and the other way round.

The API's channel is named `api`. Endpoints that read or rotate a session take `channel: "api"`.

## Session ids

`POST /message` returns the `sessionId` its message landed in. You use it to poll `GET /events`. The id stays the same across messages until you start a new session.

## The session's model

Each session runs on one model, `auto` unless you set one. Pass `model` on `POST /message` to change it; the choice is written to the session before the message lands and stays until you pass another. See [Models](/documentation/api-reference/models).

## Starting fresh

`POST /new-session` with `channel: "api"` rotates the conversation on a computer. The next message starts with no context. See [New session](/documentation/api-reference/new-session).

## Token usage

`GET /events` reports `usage` for the current task and `sessionUsage` for the whole session (see [Token usage](/documentation/api-reference/events#token-usage)). Each task is counted on its own, so tasks in the same session compare fine. But a long session carries its earlier tasks in Sai's context, and that context is re-read on every step: start a new session when you want each run's input to stand alone.

## One task at a time

A computer runs one task at a time. If you send a message while Sai is busy, the API accepts it and parks it as a steer for the running task:

```json
{ "sessionId": "cs_01HZY", "machineId": "m_7f2a", "queued": true }
```

`queued: true` means the message was folded into the running turn, not started as a new one. Poll the same `sessionId`.

## Status

`GET /events` reports one of four states for the session:

| `status`         | Meaning                                                                     |
| ---------------- | --------------------------------------------------------------------------- |
| `running`        | Sai is working. Keep polling.                                               |
| `needs_approval` | An approval is pending. See [Approvals](/documentation/concepts/approvals). |
| `idle`           | The turn is finished. `text` holds the answer.                              |
| `error`          | The turn failed. The `error` event holds `errorText`.                       |

## What a caller can see

No screenshots travel over this API. What you get for a task is one progress line per step (the agent's own one-line title for it), the first line of each console message a step printed, and the final `text`. That is the whole record. Sai puts what it sees on the screen into those lines. To watch the computer itself, open the session in the Sai app.

## Reading history

`GET /context?machineId=...&channel=api` returns recent messages from the API session. `GET /sessions?machineId=...&channel=api` lists sessions on a computer. Both default to the CLI's channel when `channel` is omitted, so always pass it.

> **Note**
>
> The `channel` parameter on `/context`, `/sessions` and `/session` is available from October 1.