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 parametersenvironment_idstring (required)Environment ID from the create response; not a session ID, template ID, or sandbox IDNo request body. | Request example |
Response fieldsidstringEnvironment 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.
Properties 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 IDarraySafe metadata for installed skills; package content is not returned.
Properties type stringSkill reference type, fixed as skill_referencename stringSkill namedescription stringSkill descriptionskill_id stringSkill resource IDversion stringFrozen versionarrayPlugin 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 |
Error codes
| HTTP status | Error type / code | Solution |
|---|---|---|
404 | not_found_error / not_found_error | Use an environment ID that exists and is visible in the current workspace |
503 | server_error / environment_unavailable | Retry later. If it keeps failing, submit a ticket with x-request-id |
{"error":{"type","code","message","param"}}. Gateway errors can use a different structure. Keep the HTTP status, x-request-id, and environment ID for troubleshooting.