> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Close Session

Freeze a session: stop anything still running in it and make it read-only, while preserving all of
its contents. A closed session can be returned to service with
[Reopen Session](/blob-types/workflow/operations/reopen-session).

## **POST** `/revisions/:id/data/command` (Command: `close_session`)

Requires the **write** role on the blob.

### Request Body

| Parameter    | Type   | Required | Description                 |
| :----------- | :----- | :------- | :-------------------------- |
| `engine`     | string | Yes      | Must be `workflow_blobhub`. |
| `command`    | string | Yes      | Must be `close_session`.    |
| `session_id` | string | Yes      | The ID of the session.      |

### Response

| Parameter | Type   | Description                                  |
| :-------- | :----- | :------------------------------------------- |
| `session` | object | The session, with `status` set to `closing`. |

The command returns as soon as the session is marked `closing`. Writes are rejected from that moment
on, but the close itself completes in the background — see
[Asynchronous behavior](#asynchronous-behavior).

### Errors

| Status | Error              | Cause                                         |
| :----- | :----------------- | :-------------------------------------------- |
| 409    | `session_not_open` | The session is not `open`.                    |
| 403    | `forbidden`        | Missing write access, or the session is gone. |

### Example

<CodeGroup>
  ```json Request theme={null}
  {
    "engine": "workflow_blobhub",
    "command": "close_session",
    "session_id": "sess_001"
  }
  ```

  ```json Response theme={null}
  {
    "session": {
      "id": "sess_001",
      "status": "closing"
    }
  }
  ```
</CodeGroup>

## Asynchronous behavior

Closing happens in two stages:

1. **Immediately** — the session becomes `closing` and every mutating operation on it, including
   `create_execution`, starts returning `409` `session_not_open`.
2. **In the background** — every execution still running in the session is stopped and awaited. Once
   they are all terminal, the session becomes `closed` and `session_closed` is emitted.

Do not assume the session is `closed` when the command returns. Wait for the `session_closed` event
or poll [Get Session](/blob-types/workflow/operations/get-session). With executions to stop this
typically takes tens of seconds; with nothing running it is near-immediate.

<Note>
  Executions stopped this way end with status `stopped` and do **not** emit `execution_ended` — that
  event is reserved for executions that complete on their own.
</Note>

Reads are unaffected in every stage: a closed session's objects, threads, graphs and execution
history all remain fully readable. See
[Session Lifecycle](/blob-types/workflow/workflows/session-lifecycle) for the complete model.