--- title: "Update an agent session" method: POST path: "/agents/sessions/{session_id}" tags: ["Agents"] --- # Update an agent session `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](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). ## Path parameters - `session_id` string, required ## Request body - UpdateAgentSessionParams — Fields to update on an existing session. - `agent` UpdateSessionAgentParam — Model settings that can change after session creation. - `model` string — The model for subsequent turns. Omit to keep the current model. - `reasoning` UpdateSessionReasoningParam — Reasoning effort for subsequent turns. The reasoning summary stays unchanged. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' — The amount of reasoning effort the model should use. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast' — The service tier used for model requests. - `metadata` object, 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 `200` The updated session. - SessionResource — A Managed Agents session. - `metadata` object, required — Custom string key-value pairs attached to the session. - `id` string, required — The ID of the session. - `object` 'agent.session', required — The object type. Always `agent.session`. - `created_at` integer, required — The Unix timestamp, in seconds, when the session was created. - `last_active_at` integer, 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. - `required_actions` SessionRequiredActionResource[], required — Actions that must be completed before the session can continue. - union — An action that must be completed before a session can continue. - object — Run a function tool and submit its result. - `type` 'function_call', required — The type of the object. Always `function_call`. - `turn_id` string, required — The ID of the turn that requested the function call. - `call_id` string, required — The ID to include when submitting the function result. - `name` string, required — The function name. - `arguments` unknown, required - object — Reconnect a session environment. - `type` 'environment_connection', required — The type of the object. Always `environment_connection`. - `environment_id` string, required — The ID of the environment to reconnect. - `error` string, nullable, required — The error that caused the session to fail, if any. - `agent` SessionAgentResource, required — The effective agent configuration for a session. - `id` string, required — The ID of the agent. - `name` string, nullable, required — The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value. - `model` string, required — The model used by the agent. - `reasoning` ReasoningResource, required — The reasoning configuration used by an agent. - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', required — The amount of reasoning effort used by an agent. - `summary` 'concise' | 'detailed' | 'auto', required — The reasoning summary format requested from an agent. - `text` TextResource, required — The text configuration used by an agent. - `format` union, required — The effective output format for generated text. - object — Generates ordinary text without a structured-output constraint. - `type` 'text', required — The type of the object. Always `text`. - object — Constrains generated text to a JSON Schema. - `type` 'json_schema', required — The type of the object. Always `json_schema`. - `schema` object, required — The JSON Schema that generated text must match. - `verbosity` 'low' | 'medium' | 'high', required — The amount of text produced by an agent. - `service_tier` 'auto' | 'default' | 'flex' | 'priority' | 'fast' | 'ultrafast', required — The service-tier policy configured for an agent. - `instructions` string, nullable, required — Custom instructions appended to the agent's default base instructions. - `tools` AgentToolResource[], required — Tools available to the agent. - union — A tool available to the agent. - object — A function defined by the application. - `type` 'function', required — The type of the object. Always `function`. - `name` string, required — The name of the function. - `description` string, required — A description of what the function does. - `parameters` object, required — A JSON Schema object describing the function's arguments. - `defer_loading` boolean, required — Whether the function is deferred and discovered through tool search. - object — Enables calling tools from model-generated code. - `type` 'programmatic_tool_calling', required — The type of the object. Always `programmatic_tool_calling`. - `enabled` boolean, required — Whether tools can be called from model-generated code. - object — Tools provided by a remote MCP server. - `type` 'mcp', required — The type of the object. Always `mcp`. - `server_label` string, required — A label used to identify the MCP server in tool calls. - `credential_id` string, nullable, required — The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL. - `transport` union, required — The transport used to connect to an MCP server. - object — Connects to an MCP server over HTTP. - … - object — Starts an MCP server as a local process. - … - `request_metadata` object, required — Metadata included with requests to this MCP server. - `allowed_tools` string[], nullable, required — The MCP tools the agent may call. - `required` boolean, required — Whether this MCP server must initialize before the first turn. - `connection_origin` 'service' | 'environment', required — Where outbound MCP HTTP connections originate. - object — Web search. - `type` 'web_search', required — The type of the object. Always `web_search`. - `mode` 'disabled' | 'cached' | 'live', required — The source used for web search results. - `context_size` 'low' | 'medium' | 'high', required — The amount of web search context made available to the model. - `allowed_domains` string[], nullable, required — Allowed search domains, or `null` when the search is unrestricted. - `location` WebSearchLocationResource, required — Approximate user location used to localize web search results. - `country` string, nullable, required — The two-letter ISO country code, such as `US`. - `region` string, nullable, required — The region or state name. - `city` string, nullable, required — The city name. - `timezone` string, nullable, required — The IANA timezone, such as `America/Los_Angeles`. - `multi_agent` MultiAgentConfigResource, required — The resolved configuration for creating and coordinating subagents. - `enabled` boolean, required — Whether subagent tools are enabled. Defaults to false. - `max_concurrent_subagents` integer, nullable, required — Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled. - `environment` union, required — The execution environment for a session. - object — The session talks to CCA without selecting or provisioning an execution environment. - `type` 'none', required — The type of the object. Always `none`. - object — An environment hosted by OpenAI. - `type` 'openai_hosted', required — The type of the object. Always `openai_hosted`. - `id` string, required — The public ID of the environment. - `packages` EnvironmentPackagesResource, required — Packages installed in an OpenAI-hosted environment. - `python` string[], required — Python packages installed in the environment. - `system` string[], required — System packages installed in the environment. - `npm` string[], required — npm packages installed globally in the environment. - `network` NetworkPolicyResource, required — Network access for an OpenAI-hosted environment. - `access` 'enabled' | 'disabled' | 'restricted', required — The network access mode for an OpenAI-hosted environment. - `allowed_domains` string[], required — Domains the environment may access when network access is restricted. - `capability_directories` string[], required — Directories that contain capabilities exposed to the agent. - `skills` HostedSkillResource[], required — Skills installed in the environment, excluding their archive contents. - union — A skill installed in an OpenAI-hosted environment. - object — A skill installed from the Skills API. - `type` 'skill_reference', required — The type of the object. Always `skill_reference`. - `skill_id` string, required — The referenced skill ID. - `version` string, required — The concrete skill version installed for this session. - `name` string, required — The installed skill name. - `description` string, required — The installed skill description. - object — A skill installed from an inline ZIP archive. - `type` 'inline', required — The type of the object. Always `inline`. - `name` string, required — The installed skill name. - `description` string, required — The installed skill description. - `plugins` HostedPluginResource[], required — Plugins installed in the environment, excluding their archive contents. - `type` 'inline', required — The type of the object. Always `inline`. - `name` string, required — The installed plugin name. - `description` string, required — The installed plugin description. - `files` HostedEnvironmentFileResource[], required — Files available in the environment, excluding their contents. - union — Metadata for a file materialized in an OpenAI-hosted execution environment. - object — A file copied from the OpenAI Files API. - `type` 'file_id', required — The type of the object. Always `file_id`. - `id` string, required — The session-scoped ID of the file in the execution environment. - `file_id` string, required — The ID of the uploaded file. - `path` string, required — The file's absolute path inside the environment. - `size_bytes` integer, required — The decoded file size in bytes. - object — A file supplied inline when the session was created. - `type` 'inline', required — The type of the object. Always `inline`. - `id` string, required — The session-scoped ID of the file in the execution environment. - `path` string, required — The file's absolute path inside the environment. - `size_bytes` integer, required — The decoded file size in bytes. - object — An environment hosted by the application. - `type` 'self_hosted', required — The type of the object. Always `self_hosted`. - `remote_url` string, required — Pass this URL unchanged to `codex exec-server --remote` when connecting this environment. - `id` string, required — The public ID of the environment. - `workspace_directory` string, required — The absolute project directory inside the environment. Defaults to `/workspace`. - `capability_directories` string[], required — Directories that contain capabilities exposed to the agent. - `vault_ids` string[], required — The IDs of vaults made available to the session. - `usage` TokenUsageResource, required — Recorded token usage for a session or turn. Usage is best effort and may change. - `input_tokens` integer, required — The number of input tokens used by the agent. - `input_tokens_details` InputTokensDetailsResource, required — A breakdown of input token usage for a session or turn. - `cached_tokens` integer, required — The number of input tokens retrieved from the prompt cache. - `output_tokens` integer, required — The number of output tokens generated by the agent. - `output_tokens_details` OutputTokensDetailsResource, required — A breakdown of output token usage for a session or turn. - `reasoning_tokens` integer, required — The number of output tokens used for reasoning. - `total_tokens` integer, required — The total number of input and output tokens used by the agent. ## Other responses - `400` — The request was invalid. - `401` — Authentication or project context was missing. - `403` — The API key lacks the required permission. - `404` — The requested session or event was not found. - `409` — The request conflicted with the current session state. - `500` — An internal error occurred. - `503` — The service is temporarily unavailable. ## Changes - **2026-09-25** `82d76d5c86cf` — 1 warning, 1 info - added the new `ultrafast` enum value to the `agent/service_tier` response property for the response status `200` - added the new `ultrafast` enum value to the request property `agent/service_tier/anyOf[#/components/schemas/ServiceTierParam]/` - **2026-09-16** `454462775dc0` — 1 info - added the new optional request property `agent` - **2026-09-16** `454462775dc0` — 1 info - added the new optional request property `agent` - **2026-09-10** `f2dae1a9aced` — 1 info - endpoint added [Change history](https://skmtc.dev/openai/apis/openapi/changes/agents/sessions/:session_id/post.md) --- [API](https://skmtc.dev/openai/apis/openapi.md) · [All operations](https://skmtc.dev/openai/apis/openapi/llms.txt) · [OpenAPI document](https://skmtc.dev/openai/apis/openapi/revisions/d86203de41ae?raw)