Sign in
Agents

Update an agent session

Updates session metadata, model, reasoning effort, or service tier. Model settings apply to subsequent turns. Omitted fields are unchanged. See managing sessions.

post/agents/sessions/{session_id}

Path parameters

session_idstring required

The ID of the session.

Request body

metadataobject nullable

Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters.

Response

The updated session.

metadataobject required

Custom string key-value pairs attached to the session.

idstring required

The ID of the session.

object'agent.session' required

The object type. Always agent.session.

created_atinteger required

The Unix timestamp, in seconds, when the session was created.

last_active_atinteger required

The Unix timestamp, in seconds, when the session was last active.

status'idle' | 'in_progress' | 'requires_action' | 'failed' required

The current status of a session.

errorstring nullable required

The error that caused the session to fail, if any.

vault_idsstring[] required

The IDs of vaults made available to the session.

Changes

Changed in 4 of the 163 revisions of this API.14

  • 82d76d5c86cf11See the full diff
    • ●

      added the new ultrafast enum value to the / response property for the response status

      response-property-enum-value-added

    • ○

      added the new ultrafast enum value to the request property /////

      request-property-enum-value-added

  • 454462775dc01See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

  • 454462775dc01See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

  • f2dae1a9aced1See the full diff
    • ○

      endpoint added

      endpoint-added