> ## 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.

# Update Session

Update a session's alias, description or tracing.

<Note>
  This command does not change a session's `status`. To close, reopen or delete a session use the
  dedicated lifecycle commands — [Close Session](/blob-types/workflow/operations/close-session),
  [Reopen Session](/blob-types/workflow/operations/reopen-session) and
  [Delete Session](/blob-types/workflow/operations/delete-session) — which enforce the legal
  transitions and run the required background work. See
  [Session Lifecycle](/blob-types/workflow/workflows/session-lifecycle).
</Note>

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

### Request Body

| Parameter     | Type   | Required | Description                                                                                            |
| :------------ | :----- | :------- | :----------------------------------------------------------------------------------------------------- |
| `engine`      | string | Yes      | Must be `workflow_blobhub`.                                                                            |
| `command`     | string | Yes      | Must be `update_session`.                                                                              |
| `session_id`  | string | Yes      | The ID or alias of the session.                                                                        |
| `alias`       | string | No       | New alias for the session. 6–42 chars, lowercase (`a`–`z`, `0`–`9`, `_`, `-`), unique in the revision. |
| `description` | string | No       | New description, at most 256 characters.                                                               |
| `tracing`     | object | No       | New tracing configuration, written whole. One field, below.                                            |

`tracing` accepts exactly one field and rejects any other:

| Field      | Type    | Description                                                                      |
| :--------- | :------ | :------------------------------------------------------------------------------- |
| `log_data` | boolean | Whether an execution event keeps the `data` payload it carries. Default `false`. |

A session's tracing is what its executions inherit —
[Create Execution](/blob-types/workflow/operations/create-execution) layers its own `tracing` over the
session's — so turning `log_data` on affects executions started afterwards, not ones already running. It is
also written whole rather than merged into what is stored, so `"tracing": {}` clears the block outright
instead of leaving `log_data` as it was. Behaviour returns to the default, since an absent `log_data` reads as
`false` — but the stored value is exactly `{}`, so the session comes back carrying `"tracing": {}` rather than
`"tracing": { "log_data": false }`.

An absent key means "leave unchanged"; a key present with an empty value does not. `"description": ""` and
`"tracing": {}` are writes.

A request carrying none of `alias`, `description` and `tracing` is a legal no-op: it returns the session
unchanged, and it is the one form of this command that a session which is no longer `open` still accepts.
Supplying any of the three makes it a mutating call, and every mutating call is gated on `status: "open"` —
not just a rename.

The alias and the other two are two separate writes, alias first, so a request carrying both is not atomic.
An `alias_in_use` rejection means nothing was written; a failure after the rename can leave the new alias in
place without the description or tracing beside it.

See [Alias Grammar](/blob-types/scheduler/overview#alias-grammar) for the character rules, length
limits, the id-shape restriction, and which commands accept an alias in place of an id.

### Response

| Parameter | Type   | Description                                |
| :-------- | :----- | :----------------------------------------- |
| `session` | object | The session as it stands after the update. |

The updated session comes back in full, the same way the lifecycle commands return it. A request that
supplies nothing to change still returns it, unmodified.

### Errors

| Status | Error                  | Cause                                                                                                                       |
| :----- | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request_body` | An alias outside the grammar, a description over 256 characters, an unknown `tracing` field, or an unknown top-level field. |
| 409    | `session_not_open`     | The session is not `open` and the request supplies a field to change.                                                       |
| 400    | `alias_in_use`         | The alias is already taken in this revision.                                                                                |
| 403    | `forbidden`            | Missing write access, or the session is gone.                                                                               |

### Example

<CodeGroup>
  ```json Request theme={null}
  {
    "engine": "workflow_blobhub",
    "command": "update_session",
    "session_id": "sess_001",
    "alias": "nightly-build",
    "description": "Nightly regression run",
    "tracing": { "log_data": true }
  }
  ```

  ```json Response theme={null}
  {
    "status": "success",
    "session": {
      "id": "sess_001",
      "alias": "nightly-build",
      "description": "Nightly regression run",
      "tracing": { "log_data": true },
      "status": "open"
    }
  }
  ```
</CodeGroup>