--- title: Sessions | Luma Agents description: A session is one conversation with the agent, recorded on one ordered event log. --- A session keeps one numbered **event log**. Everything you send and everything the agent does is an event on it, in order, starting at `seq` 1. You write to the log through one route. You read it live on the stream, page through it afterwards, or receive it on a webhook, and all three carry the same events with the same ids. ## How a turn looks on the log When you send a message, the agent works on it in a turn. If it starts generations, the session stays busy after its text ends, and picks up again on its own when they finish. The [Quickstart](/agents/quickstart/index.md) shows every event of a real turn; this is the busy, resume and idle cycle within it. 1. 1**Busy**`session.status_running`continuation: false. The agent starts on your message 2. 2**Generating**`job.started`One per image or video. The agent can keep talking while they run 3. 3**Resumes**`session.status_running`continuation: true, once the generations finish 4. 4**Results**`job.completed`Each carries its outputs 5. 5**Idle**`session.status_idle`stop\_reason says what to do next The continuation's session.status\_running arrives just before the job.completed events that woke it (seq 13 and 14 in the Quickstart run). `session.status_idle` is the event that means the agent has stopped. Its `stop_reason.type` tells you what to do next: | `stop_reason.type` | Means | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `end_turn` | The turn finished. Send the next message when you have one. | | `requires_action` | The session is waiting on you, for example a [client tool](/agents/tools/index.md) or an app’s review step. `stop_reason.pending` lists each item. See [Approvals and review](/agents/approvals/index.md). | | `budget_reached` | A spending cap stopped the turn. See [Budgets and usage](/agents/budgets/index.md). | | `interrupted` | A `user.interrupt` or a cancel stopped the turn. | | `error` | The turn failed. The `session.error` before it says how. | A session pauses for a person only when you set it up to: a [client tool](/agents/tools/index.md) your UI answers, or a [workflow app](/agents/workflow-apps/index.md) with a review step. While it waits, the turn is suspended, not finished, and it continues when you answer. [Approvals and review](/agents/approvals/index.md) shows how to answer. `GET /v1/sessions/$SESSION_ID` returns the same state as a snapshot: `status` (`running`, `idle` or `terminated`) and what the session is waiting on in `pending`. A client that has just connected reads where things stand from there. To read the log live or page through it, see [Streaming](/agents/streaming/index.md). The rules for everything you send are in the [Reference](/agents/reference/index.md#send-input). Every event type is listed in the [Reference](/agents/reference/index.md). ## Interrupt a turn Send `user.interrupt` to stop the current turn. The session stays open for the next message. - [cURL](#tab-panel-0-0) - [Python](#tab-panel-0-1) - [TypeScript](#tab-panel-0-2) ```bash curl -s -X POST https://agents.lumalabs.ai/v1/sessions/$SESSION_ID/events \ -H "Authorization: Bearer $SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "events": [ { "type": "user.interrupt", "idempotency_key": "stop-42-1" } ] }' ``` ```python import json import urllib.request request = urllib.request.Request( f"https://agents.lumalabs.ai/v1/sessions/{session_id}/events", method="POST", data=json.dumps({"events": [{"type": "user.interrupt", "idempotency_key": "stop-42-1"}]}).encode(), headers={"Authorization": f"Bearer {session_token}", "Content-Type": "application/json"}, ) with urllib.request.urlopen(request) as response: print(json.load(response)["data"][0]) ``` ```typescript const response = await fetch( `https://agents.lumalabs.ai/v1/sessions/${sessionId}/events`, { method: "POST", headers: { Authorization: `Bearer ${sessionToken}`, "Content-Type": "application/json", }, body: JSON.stringify({ events: [{ type: "user.interrupt", idempotency_key: "stop-42-1" }], }), }, ); console.log((await response.json()).data[0]); ``` The acknowledgement lists `cancelled_run_ids`. Add `target_run_id` to stop one run instead of the whole turn. If it is refused with `SESSION.ORCHESTRATION_UNAVAILABLE`, retry with the same key. ## Closing and expiry `DELETE /v1/sessions/$SESSION_ID` closes a session. It refuses new work and ends with `session.status_terminated` and `reason: "closed"`. Closing does not stop generations already started. They keep running and are charged. Send `user.interrupt` first, then close. A session lives for `expires_in_seconds`, 24 hours by default and up to 7 days. At expiry it emits `session.status_terminated` with `reason: "expired"`, and later calls answer `410 SESSION.EXPIRED`. ## Next - [Streaming](/agents/streaming/index.md): follow the log live. - [Approvals and review](/agents/approvals/index.md): answer a session that is waiting on your user. - [Budgets and usage](/agents/budgets/index.md): cap what a session can spend.