---
title: "List agent environments"
method: GET
path: "/agents/environments"
tags: ["Agents"]
---

# List agent environments

`GET /agents/environments`

## Request

- Base URL: `https://api.openai.com/v1`
- URL: `https://api.openai.com/v1/agents/environments`
- Auth: HTTP bearer

Lists OpenAI-hosted environments owned by the authenticated principal. Requires access to the prewarming beta.

## Query parameters

- `limit` integer
- `order` 'asc' | 'desc': The order in which paginated resources are returned.
- `after` string
- `type` 'openai_hosted': The hosting type of an execution environment.

## Response `200`

A page of owned environments.

- AgentEnvironmentListResource: A page of Agents API resources, with IDs for retrieving additional pages.
  - `object` 'list', required: The object type, which is always `list`.
  - `data` PublicEnvironmentResource[], required: The resources returned in this page, in the requested sort order.
    - `type` 'openai_hosted' | 'self_hosted', required: The kind of execution environment.
    - `id` string, required: The ID of the environment.
    - `object` 'agent.environment', required: The object type. Always `agent.environment`.
    - `status` 'pending' | 'ready' | 'connected' | 'disconnected' | 'suspended' | 'expired' | 'failed', required: The public lifecycle status of an execution environment.
    - `files` HostedEnvironmentFileResource[], required: Files installed in the environment, without 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.
    - `skills` HostedSkillResource[], required: Skills installed in the environment, without 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, without 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.
  - `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 environment or referenced resource was not found.
- `409`: The request conflicted with the current environment state.
- `500`: An internal error occurred.
- `503`: The service is temporarily unavailable.

## Changes

- **2026-10-08** `c686bf249e4c`: 1 warning
  - added the new `suspended` enum value to the `data/items/status` response property for the response status `200`
- **2026-10-08** `4ce25559b07f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openai/apis/openapi/changes/agents/environments/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/b7f3ab500153?raw)