OPopenai
Agents

Update an agent session

Changed on

Updates session tools, 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}

Request

  • Base URL
    https://api.openai.com/v1
  • URL
    https://api.openai.com/v1/agents/sessions/{session_id}
  • Auth
    HTTP bearer

Path parameters

session_idstring required

The ID of the session.

Request body

review'none' | 'auto_review'

Review applied to eligible actions in a session.

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.

review'none' | 'auto_review'

The configured action review mode.

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