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

Retrieve an agent environment

GET
/agents/environments/{environment_id}

Retrieves an execution environment’s connection status and safe installed metadata. See environment lifecycle.

Path Parameters
environment_id: string
minLength0
maxLength1048576
Returns
EnvironmentInfo object { id, files, object, 4 more }

Safe metadata for a first-class execution environment.

id: string

The ID of the environment.

minLength0
files: array of HostedEnvironmentFile

Files installed in the environment, without their contents.

One of the following:
HostedEnvironmentFileID object { id, file_id, path, 2 more }

A file copied from the OpenAI Files API.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
file_id: string

The ID of the uploaded file.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "file_id"

The type of the object. Always file_id.

Inline object { id, path, size_bytes, type }

A file supplied inline when the session was created.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "inline"

The type of the object. Always inline.

object: "agent.environment"

The object type. Always agent.environment.

plugins: array of HostedPlugin { description, name, type }

Plugins installed in the environment, without their archive contents.

description: string

The installed plugin description.

minLength0
name: string

The installed plugin name.

minLength0
type: "inline"

The type of the object. Always inline.

skills: array of HostedSkill

Skills installed in the environment, without their archive contents.

One of the following:
HostedSkillReference object { description, name, skill_id, 2 more }

A skill installed from the Skills API.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
skill_id: string

The referenced skill ID.

minLength0
type: "skill_reference"

The type of the object. Always skill_reference.

version: string

The concrete skill version installed for this session.

minLength0
Inline object { description, name, type }

A skill installed from an inline ZIP archive.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
type: "inline"

The type of the object. Always inline.

status: "pending" or "ready" or "connected" or 4 more

The current environment connection status.

One of the following:
"pending"
"ready"

Provisioning succeeded and the environment is available for attachment or use.

"connected"
"disconnected"
"suspended"

The sandbox is stopped and can be resumed from its private checkpoint.

"expired"
"failed"
type: "openai_hosted" or "self_hosted"

Whether the environment is hosted by OpenAI or by the application.

One of the following:
"openai_hosted"
"self_hosted"

Retrieve an agent environment

curl https://api.openai.com/v1/agents/environments/$ENVIRONMENT_ID \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"
200 example
{
  "id": "id",
  "files": [
    {
      "id": "id",
      "file_id": "file_id",
      "path": "path",
      "size_bytes": 0,
      "type": "file_id"
    }
  ],
  "object": "agent.environment",
  "plugins": [
    {
      "description": "description",
      "name": "name",
      "type": "inline"
    }
  ],
  "skills": [
    {
      "description": "description",
      "name": "name",
      "skill_id": "skill_id",
      "type": "skill_reference",
      "version": "version"
    }
  ],
  "status": "pending",
  "type": "openai_hosted"
}
Returns Examples
200 example
{
  "id": "id",
  "files": [
    {
      "id": "id",
      "file_id": "file_id",
      "path": "path",
      "size_bytes": 0,
      "type": "file_id"
    }
  ],
  "object": "agent.environment",
  "plugins": [
    {
      "description": "description",
      "name": "name",
      "type": "inline"
    }
  ],
  "skills": [
    {
      "description": "description",
      "name": "name",
      "skill_id": "skill_id",
      "type": "skill_reference",
      "version": "version"
    }
  ],
  "status": "pending",
  "type": "openai_hosted"
}