> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt > Use this file to discover all available pages before exploring further. # List environments > List an organisation's standalone environments, newest first — both agent-bound and organization-owned. Those owned by an execution or an astro conversation are private to those owners. Terminal environments are excluded unless `lifecycle` says otherwise. ## OpenAPI ````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml get /environments openapi: 3.1.0 info: title: Agent Service version: v1 servers: - description: V2 API url: https://odyssey.asteroid.ai/agents/v2 security: - ApiKeyAuth: [] tags: - name: Agents - name: Environments - name: Schedules - name: Execution - name: Files - name: Profiles - name: Profile Groups - name: Agent Profiles - name: Agent Profile Pools - name: Workflows - name: Execution Batches - name: Scheduled Executions - name: Schema - name: Documentation - name: Context - name: Admin Customer Activity - name: Reference - name: Workflow Tags - name: Secrets - name: Vault - name: Insights - name: Workflow Versions paths: /environments: get: tags: - Environments summary: List environments description: >- List an organisation's standalone environments, newest first — both agent-bound and organization-owned. Those owned by an execution or an astro conversation are private to those owners. Terminal environments are excluded unless `lifecycle` says otherwise. operationId: EnvironmentsList parameters: - description: >- The organisation whose environments to list. The caller must belong to it. Defaults to the one organization the caller acts in, such as an API key's. Required when the caller belongs to several. explode: false in: query name: organizationId schema: $ref: '#/components/schemas/Common.uuid' - deprecated: true description: 'Deprecated: use workflowId. Only environments bound to this agent.' explode: false in: query name: agentId schema: $ref: '#/components/schemas/Common.uuid' x-hidden: true x-hidden: true - description: >- Only environments bound to this workflow. Omit for every standalone environment in the organisation, the unbound ones included. explode: false in: query name: workflowId schema: $ref: '#/components/schemas/Common.uuid' - description: >- Which lifecycle states to return. Omit for running environments only. explode: false in: query name: lifecycle schema: $ref: '#/components/schemas/Agents.Environment.EnvironmentLifecycle' responses: '200': content: application/json: schema: $ref: >- #/components/schemas/Agents.Environment.ListEnvironmentsResponse description: The request has succeeded. '400': content: application/json: schema: $ref: '#/components/schemas/Common.BadRequestErrorBody' description: The server could not understand the request due to invalid syntax. '401': content: application/json: schema: $ref: '#/components/schemas/Common.UnauthorizedErrorBody' description: Access is unauthorized. '403': content: application/json: schema: $ref: '#/components/schemas/Common.ForbiddenErrorBody' description: Access is forbidden. '404': content: application/json: schema: $ref: '#/components/schemas/Common.NotFoundErrorBody' description: The server cannot find the requested resource. '500': content: application/json: schema: $ref: '#/components/schemas/Common.InternalServerErrorBody' description: Server error components: schemas: Common.uuid: format: uuid type: string Agents.Environment.EnvironmentLifecycle: description: >- Which lifecycle states a list should return. A coarser handle than the status enum, and the one a caller actually wants: what is still usable, what is finished, or everything. enum: - running - terminal - all type: string Agents.Environment.ListEnvironmentsResponse: description: >- Response for the list endpoint, ordered by createdAt DESC. Empty array when nothing matches the filters. properties: environments: description: The matching environments. items: $ref: '#/components/schemas/Agents.Environment.EnvironmentSummary' type: array required: - environments type: object Common.BadRequestErrorBody: properties: code: enum: - 400 type: number x-enum-varnames: - BadRequest detail: description: Explanation of this occurrence. Same text as message type: string errors: description: The parameters that failed validation, when known items: $ref: '#/components/schemas/Common.FieldError' type: array instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.UnauthorizedErrorBody: properties: code: enum: - 401 type: number x-enum-varnames: - Unauthorized detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.ForbiddenErrorBody: properties: code: enum: - 403 type: number x-enum-varnames: - Forbidden detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.NotFoundErrorBody: properties: code: enum: - 404 type: number x-enum-varnames: - NotFound detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.InternalServerErrorBody: properties: code: enum: - 500 type: number x-enum-varnames: - InternalServerError detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: description: The HTTP status code format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Agents.Environment.EnvironmentSummary: description: >- An environment as it appears in a list. Carries everything a row needs; the provider `state` is fetched with the environment itself, because resolving it mints a signed recording URL per environment and a list would mint one per row. properties: agentProfileId: allOf: - $ref: '#/components/schemas/Common.uuid' deprecated: true description: >- Deprecated: use profileId. Profile snapshot the environment was booted against, if any. x-hidden: true createdAt: description: When the environment row was created. format: date-time type: string environmentType: allOf: - $ref: '#/components/schemas/Agents.Workflow.EnvironmentType' description: Browser or OS. expiresAt: description: >- When the reaper will tear the environment down if no graceful Stop arrives first. format: date-time type: string hasRecording: description: >- Whether a playable recording has been persisted (GCS object or provider URL). The playable URL itself is minted on the by-id read. type: boolean id: allOf: - $ref: '#/components/schemas/Common.uuid' description: Environment identifier. organizationId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The organisation the environment belongs to. osType: allOf: - $ref: '#/components/schemas/Agents.Workflow.OsType' description: >- Operating system for OS environments. Absent for browser environments; linux when an OS environment predates explicit osType storage. owner: allOf: - $ref: '#/components/schemas/Agents.Environment.EnvironmentOwner' description: Who the environment belongs to, and the identity that owner carries. profileId: allOf: - $ref: '#/components/schemas/Common.uuid' description: Profile snapshot the environment was booted against, if any. readyAt: description: When the environment first became ready, if it reached that state. format: date-time type: string status: allOf: - $ref: '#/components/schemas/Agents.Environment.EnvironmentStatus' description: >- Current status, terminal states included. Lists exclude terminal environments unless `includeTerminal` is set. stoppedAt: description: When the environment reached a terminal state. Set after Stop runs. format: date-time type: string required: - id - organizationId - owner - environmentType - status - hasRecording - createdAt - expiresAt type: object Common.FieldError: description: A problem with one request parameter properties: detail: description: What is wrong with it type: string parameter: description: The query or path parameter name type: string required: - parameter - detail type: object Agents.Workflow.EnvironmentType: description: Type of execution environment enum: - browser - os type: string Agents.Workflow.OsType: description: Operating system the environment sandbox runs enum: - linux - windows type: string Agents.Environment.EnvironmentOwner: description: >- Who the environment belongs to. Discriminated on `type`, mirroring the storage-side agent_environment.owner_type, so each owner kind carries exactly the identity it has — an execution id only exists for execution-owned envs, a chat id only for astro-owned ones. A future owner kind joins as a member rather than as another optional column. discriminator: mapping: astro: '#/components/schemas/Agents.Environment.AstroEnvironmentOwner' execution: '#/components/schemas/Agents.Environment.ExecutionEnvironmentOwner' external: '#/components/schemas/Agents.Environment.ExternalEnvironmentOwner' organization: '#/components/schemas/Agents.Environment.OrganizationEnvironmentOwner' warm_pool: '#/components/schemas/Agents.Environment.WarmPoolEnvironmentOwner' propertyName: type oneOf: - $ref: '#/components/schemas/Agents.Environment.ExecutionEnvironmentOwner' - $ref: '#/components/schemas/Agents.Environment.AstroEnvironmentOwner' - $ref: '#/components/schemas/Agents.Environment.ExternalEnvironmentOwner' - $ref: '#/components/schemas/Agents.Environment.OrganizationEnvironmentOwner' - $ref: '#/components/schemas/Agents.Environment.WarmPoolEnvironmentOwner' type: object Agents.Environment.EnvironmentStatus: description: Every state an environment can be in, terminal included. enum: - requested - provisioning - ready - stopping - stopped - failed - dead type: string Agents.Environment.AstroEnvironmentOwner: description: >- An astro build conversation owns the environment: it lives as long as the chat driving it. properties: agentId: allOf: - $ref: '#/components/schemas/Common.uuid' deprecated: true description: 'Deprecated: use workflowId. The agent the conversation is building.' x-hidden: true chatId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The astro chat that booted the environment. type: enum: - astro type: string workflowId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The workflow the conversation is building. required: - type - agentId - workflowId - chatId type: object Agents.Environment.ExecutionEnvironmentOwner: description: >- An execution owns the environment: it was booted to run that execution and dies with it. properties: agentId: allOf: - $ref: '#/components/schemas/Common.uuid' deprecated: true description: >- Deprecated: use workflowId. The agent the execution runs on behalf of. x-hidden: true executionId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The execution that booted the environment. type: enum: - execution type: string workflowId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The workflow the execution runs. required: - type - agentId - workflowId - executionId type: object Agents.Environment.ExternalEnvironmentOwner: description: >- A standalone environment: it belongs to the organisation rather than to a chat or an execution, and outlives both. Booted by an API key today; the agent binding arrives with the workflow it was started from. properties: agentId: allOf: - $ref: '#/components/schemas/Common.uuid' deprecated: true description: 'Deprecated: use workflowId. The agent the environment is bound to.' x-hidden: true createdByApiKeyId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- The API key that booted it, when one did. Absent for environments booted by a signed-in user. type: enum: - external type: string workflowId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The workflow the environment is bound to. required: - type - agentId - workflowId type: object Agents.Environment.OrganizationEnvironmentOwner: description: >- An environment owned by the organisation itself: it has no agent binding at all — the organisation on the environment is its whole identity. properties: type: enum: - organization type: string required: - type type: object Agents.Environment.WarmPoolEnvironmentOwner: description: >- A warm pool owns the environment for its whole life; executions borrow it without ever taking ownership. properties: type: enum: - warm_pool type: string warmPoolId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The warm pool the environment belongs to. required: - type - warmPoolId type: object securitySchemes: ApiKeyAuth: in: header name: X-Api-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.