Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Update an agent session

client.beta.agents.sessions.update(stringsessionID, SessionUpdateParams { agent, metadata, spend_control } body?, RequestOptionsoptions?): AgentSession { id, agent, created_at, 10 more }
POST/agents/sessions/{session_id}

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

ParametersExpand Collapse
sessionID: string
minLength0
maxLength1048576
body: SessionUpdateParams { agent, metadata, spend_control }
ReturnsExpand Collapse
AgentSession { id, agent, created_at, 10 more }

A Managed Agents session.

id: string

The ID of the session.

minLength0
agent: Agent { id, instructions, model, 6 more }

The agent running in the session.

created_at: number

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

formatint64
environment: Environment

The execution environment for the session.

error: string | null

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

minLength0
last_active_at: number

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

formatint64
metadata: Record<string, string>

Custom string key-value pairs attached to the session.

object: "agent.session"

The object type. Always agent.session.

required_actions: Array<SessionRequiredActionResourceComputerUseApprovalRequest { request, request_id, turn_id, type } | SessionRequiredActionResourceFunctionCall { arguments, call_id, name, 2 more } | SessionRequiredActionResourceEnvironmentConnection { environment_id, type } >

Actions that must be completed before the session can continue.

status: "idle" | "in_progress" | "requires_action" | "failed"

The current status of the session.

usage: TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more } | null

Best-effort token usage for the session, or null if unknown. Recorded usage may change.

vault_ids: Array<string>

The IDs of vaults made available to the session.

spend_control?: SpendControl { consumed, limit }

Configured spending limit and best-effort consumption, in USD cents. Unlimited sessions omit this object.

Update an agent session

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});

const agentSession = await client.beta.agents.sessions.update('session_id');

console.log(agentSession.id);
{
  "id": "id",
  "agent": {
    "id": "id",
    "instructions": "instructions",
    "model": "model",
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 1
    },
    "name": "name",
    "reasoning": {
      "effort": "none",
      "summary": "concise"
    },
    "service_tier": "auto",
    "text": {
      "format": {
        "type": "text"
      },
      "verbosity": "low"
    },
    "tools": [
      {
        "defer_loading": true,
        "description": "description",
        "name": "name",
        "parameters": {
          "foo": "bar"
        },
        "type": "function"
      }
    ]
  },
  "created_at": 0,
  "environment": {
    "type": "none"
  },
  "error": "error",
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "object": "agent.session",
  "required_actions": [
    {
      "request": {
        "credential_origin": "credential_origin",
        "fields": [
          {
            "id": "id",
            "label": "label",
            "required": true,
            "type": "type"
          }
        ],
        "options": [
          {
            "id": "id",
            "field_ids": [
              "string"
            ],
            "label": "label"
          }
        ],
        "reason": "reason",
        "type": "browser_authentication"
      },
      "request_id": "request_id",
      "turn_id": "turn_id",
      "type": "computer_use_approval_request"
    }
  ],
  "status": "idle",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "vault_ids": [
    "string"
  ],
  "spend_control": {
    "consumed": 0,
    "limit": 1
  }
}
Returns Examples
{
  "id": "id",
  "agent": {
    "id": "id",
    "instructions": "instructions",
    "model": "model",
    "multi_agent": {
      "enabled": true,
      "max_concurrent_subagents": 1
    },
    "name": "name",
    "reasoning": {
      "effort": "none",
      "summary": "concise"
    },
    "service_tier": "auto",
    "text": {
      "format": {
        "type": "text"
      },
      "verbosity": "low"
    },
    "tools": [
      {
        "defer_loading": true,
        "description": "description",
        "name": "name",
        "parameters": {
          "foo": "bar"
        },
        "type": "function"
      }
    ]
  },
  "created_at": 0,
  "environment": {
    "type": "none"
  },
  "error": "error",
  "last_active_at": 0,
  "metadata": {
    "foo": "string"
  },
  "object": "agent.session",
  "required_actions": [
    {
      "request": {
        "credential_origin": "credential_origin",
        "fields": [
          {
            "id": "id",
            "label": "label",
            "required": true,
            "type": "type"
          }
        ],
        "options": [
          {
            "id": "id",
            "field_ids": [
              "string"
            ],
            "label": "label"
          }
        ],
        "reason": "reason",
        "type": "browser_authentication"
      },
      "request_id": "request_id",
      "turn_id": "turn_id",
      "type": "computer_use_approval_request"
    }
  ],
  "status": "idle",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  },
  "vault_ids": [
    "string"
  ],
  "spend_control": {
    "consumed": 0,
    "limit": 1
  }
}