Skip to main content

Retrieve environment

Retrieve the preparation status and safe installed metadata of an environment by ID.

Endpoint

GET /agents/environments/{environment_id} Returns the current status and safe metadata of the specified environment. A successful call returns 200.

Path parameters

environment_id string (required)Environment ID from the create response; not a session ID, template ID, or sandbox IDNo request body.

Request example

curl -sS "$BASE_URL/agents/environments/ccarenv_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

Response fields

id stringEnvironment IDobject stringEnvironment object type, fixed as agent.environmenttype stringEnvironment type, fixed as openai_hostedstatus stringEnvironment status: pending, ready, connected, disconnected, suspended, expired, or failedfiles arraySafe metadata for installed files; file content is not returned.
id stringEnvironment file IDtype stringFile reference type, fixed as file_idpath stringFile path in the environmentsize_bytes integerFile size in bytesfile_id stringOriginal source file ID
skills arraySafe metadata for installed skills; package content is not returned.
type stringSkill reference type, fixed as skill_referencename stringSkill namedescription stringSkill descriptionskill_id stringSkill resource IDversion stringFrozen version
plugins arrayPlugin list; currently [] for managed environments; plugin fields in historical records do not mean plugins can be createdready means preparation is complete and a session can reference the environment. connected means the instance is connected, which does not guarantee that every subsequent command succeeds.

Response example

{
  "id": "ccarenv_xxx",
  "object": "agent.environment",
  "type": "openai_hosted",
  "status": "ready",
  "files": [],
  "skills": [],
  "plugins": []
}

Error codes

HTTP statusError type / codeSolution
404not_found_error / not_found_errorUse an environment ID that exists and is visible in the current workspace
503server_error / environment_unavailableRetry later. If it keeps failing, submit a ticket with x-request-id
The error body has the shape {"error":{"type","code","message","param"}}. Gateway errors can use a different structure. Keep the HTTP status, x-request-id, and environment ID for troubleshooting.