> ## 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 the standalone environments bound to an agent, newest first. Only environments this API key's organisation started are returned; those owned by an execution or an astro conversation are private to those owners. Terminal environments are excluded unless `includeTerminal` is set.



## 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: Execution
  - name: Files
  - name: Agent Profiles
  - name: Agent Profile Pools
  - name: Workflows
  - name: Schema
  - name: Documentation
  - name: Context
  - name: Admin Customer Activity
paths:
  /environments:
    get:
      tags:
        - Environments
      summary: List environments
      description: >-
        List the standalone environments bound to an agent, newest first. Only
        environments this API key's organisation started are returned; those
        owned by an execution or an astro conversation are private to those
        owners. Terminal environments are excluded unless `includeTerminal` is
        set.
      operationId: EnvironmentsList
      parameters:
        - description: >-
            The agent whose environments to list. Gates access, and supplies the
            organisation.
          explode: false
          in: query
          name: agentId
          required: true
          schema:
            $ref: '#/components/schemas/Common.uuid'
        - description: >-
            Include stopped, failed and dead environments. Omit for running
            environments only.
          explode: false
          in: query
          name: includeTerminal
          schema:
            type: boolean
      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.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
        message:
          type: string
      required:
        - code
        - message
      type: object
    Common.UnauthorizedErrorBody:
      properties:
        code:
          enum:
            - 401
          type: number
          x-enum-varnames:
            - Unauthorized
        message:
          type: string
      required:
        - code
        - message
      type: object
    Common.ForbiddenErrorBody:
      properties:
        code:
          enum:
            - 403
          type: number
          x-enum-varnames:
            - Forbidden
        message:
          type: string
      required:
        - code
        - message
      type: object
    Common.NotFoundErrorBody:
      properties:
        code:
          enum:
            - 404
          type: number
          x-enum-varnames:
            - NotFound
        message:
          type: string
      required:
        - code
        - message
      type: object
    Common.InternalServerErrorBody:
      properties:
        code:
          enum:
            - 500
          type: number
          x-enum-varnames:
            - InternalServerError
        message:
          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'
          description: Profile snapshot the environment was booted against, if any.
        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.
        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
    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 (warm pools, org sessions) joins as a member rather than as
        another optional column.
      discriminator:
        mapping:
          astro:
            $ref: '#/components/schemas/Agents.Environment.AstroEnvironmentOwner'
          execution:
            $ref: '#/components/schemas/Agents.Environment.ExecutionEnvironmentOwner'
          external:
            $ref: '#/components/schemas/Agents.Environment.ExternalEnvironmentOwner'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/Agents.Environment.ExecutionEnvironmentOwner'
        - $ref: '#/components/schemas/Agents.Environment.AstroEnvironmentOwner'
        - $ref: '#/components/schemas/Agents.Environment.ExternalEnvironmentOwner'
      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'
          description: The agent the conversation is building.
        chatId:
          allOf:
            - $ref: '#/components/schemas/Common.uuid'
          description: The astro chat that booted the environment.
        type:
          enum:
            - astro
          type: string
      required:
        - type
        - agentId
        - 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'
          description: The agent the execution runs on behalf of.
        executionId:
          allOf:
            - $ref: '#/components/schemas/Common.uuid'
          description: The execution that booted the environment.
        type:
          enum:
            - execution
          type: string
      required:
        - type
        - agentId
        - 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'
          description: The agent the environment is bound to.
        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
      required:
        - type
        - agentId
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-Asteroid-Agents-Api-Key
      type: apiKey

````