Update Session

Update a session’s alias, description or tracing.

This command does not change a session’s status. To close, reopen or delete a session use the dedicated lifecycle commands — Close Session, Reopen Session and Delete Session — which enforce the legal transitions and run the required background work. See Session Lifecycle.

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

Request Body

Parameter	Type	Required	Description
`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 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 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

{
  "command": "update_session",
  "session_id": "sess_001",
  "alias": "nightly-build",
  "description": "Nightly regression run",
  "tracing": { "log_data": true }
}

{
  "status": "success",
  "session": {
    "id": "sess_001",
    "alias": "nightly-build",
    "description": "Nightly regression run",
    "tracing": { "log_data": true },
    "status": "open"
  }
}

Overview

Workflow

Scheduler

ONNX

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

Request Body

Response

Errors

Example

​POST /revisions/:id/data/command (Command: update_session)

​Request Body

​Response

​Errors

​Example

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

Request Body

Response

Errors

Example