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