--- title: "Retrieve an agent session" method: GET path: "/agents/sessions/{session_id}" tags: ["Agents"] --- # Retrieve an agent session `GET /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 Retrieves the current state of a managed agent session. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). ## Path parameters - `session_id` string, required ## Response `200` The requested 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: Respond to a computer-use request. - `type` 'computer_use_approval_request', required: The type of the object. Always `computer_use_approval_request`. - `turn_id` string, required: The turn that requested approval. - `request_id` string, required: The registered request ID to echo when responding. - `request` union, required - object: A registered form awaiting the application's response. - `type` 'browser_authentication', required: The type of the object. Always `browser_authentication`. - `reason` string, nullable, required: Why the agent needs the user to sign in. - `credential_origin` string, nullable, required: The registered form or frame origin where values will be entered. - `fields` BrowserAuthenticationFieldResource[], required: Controls to render. All submitted values are sensitive. - … - `options` BrowserAuthenticationOptionResource[], required: Sign-in methods. Empty for a plain form. - … - object: A browser origin awaiting the application's approval decision. - `type` 'browser_origin_access', required: The type of the object. Always `browser_origin_access`. - `reason` string, nullable, required: The browser's explanation for this request, or null when unavailable. - `origin` string, required: The origin the browser needs permission to access. - 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`. - object: Browser use in an OpenAI-hosted session. - `type` 'computer_use', required: The type of the object. Always `computer_use`. - `include_screenshots` boolean, required: Whether computer tool outputs include screenshots. - object: Lets the agent manage its own scheduled wakeups. - `type` 'automations', required: The type of the object. Always `automations`. - `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. - `compaction` CompactionResource: The effective settings for compacting the agent's context. - `async` boolean, required: Whether context is compacted in the background. Defaults to true. - `experimental` ExperimentalConfigResource: The effective experimental settings for an agent. - `time_awareness` boolean, required: Whether the model receives periodic current-time reminders. - `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. - `container_size` 'small' | 'medium' | 'large': The effective CPU and memory tier of an OpenAI-hosted 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. - `desktop` DesktopResource, required: The effective desktop configuration for an OpenAI-hosted environment. - `enabled` boolean, required: Whether the environment provisions a desktop and browser proxy. - `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` InputTokensDetailsResource2, 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` OutputTokensDetailsResource2, 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-10-29** `0a26f104d35f`: 1 info - added the optional property `agent/experimental` to the response with the `200` status - **2026-10-28** `81bec64c97ee`: 1 info - added the optional property `agent/compaction` to the response with the `200` status - **2026-10-23** `edf54d38a1a0`: 1 breaking, 1 info - added `#/components/schemas/AgentToolResourceAutomations` to the `agent/tools/items/` response property `oneOf` list for the response status `200` - added `automations` discriminator mapping keys to the `agent/tools/items/` response property for the response status `200` - **2026-10-16** `d9e93345b02a`: 1 warning - removed the optional property `spend_control` from the response with the `200` status - **2026-10-08** `a95c419c9257`: 1 info - added the optional property `spend_control` to the response with the `200` status [Operation history](https://skmtc.dev/omnistack-sh/apis/openai-api/changes/agents/sessions/:session_id/get.md) --- [API](https://skmtc.dev/omnistack-sh/apis/openai-api.md) - [All operations](https://skmtc.dev/omnistack-sh/apis/openai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnistack-sh/apis/openai-api/revisions/0a26f104d35f?raw)