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
`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 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 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

{
  "engine": "workflow_blobhub",
  "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