--- title: "List agent sessions" method: GET path: "/agents/sessions" tags: ["Agents"] --- # List agent sessions `GET /agents/sessions` Lists managed agent sessions using ID-based pagination and the requested sort order. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage). ## Query parameters - `limit` integer, nullable - `order` 'asc' | 'desc' — The order in which paginated resources are returned. - `agent_id` string - `after` string ## Response `200` A page of sessions. - SessionListResource — A page of Agents API resources, with IDs for retrieving additional pages. - `object` 'list', required — The object type, which is always `list`. - `data` SessionResource[], required — The resources returned in this page, in the requested sort order. - `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', 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. - … - `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. - … - `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. - … - object — A skill installed from an inline ZIP archive. - … - `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. - … - object — A file supplied inline when the session was created. - … - 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. - `first_id` string, nullable, required — The ID of the first resource in `data`, or `null` if the page is empty. - `last_id` string, nullable, required — The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters. - `has_more` boolean, required — Whether there are more resources to retrieve after this page. ## 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-10** `f2dae1a9aced` — 1 info - endpoint added [Change history](https://skmtc.dev/openai/apis/openapi/changes/agents/sessions/get.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/f44c092d9892?raw)