---
title: "List environments"
method: GET
path: "/agent/environments"
tags: ["agent"]
---

# List environments

`GET /agent/environments`

Retrieve cloud environments accessible to the authenticated principal.
Returns environments the caller owns, has been granted guest access to,
or has accessed via link sharing.

## Query parameters

- `sort_by` 'name' | 'last_updated'

## Response `200`

List of accessible environments

- ListEnvironmentsResponse
  - `environments` CloudEnvironment[], required — List of accessible cloud environments
    - `uid` string, required — Unique identifier for the environment
    - `config` CloudEnvironmentConfig, required — Configuration for a cloud environment used by scheduled agents
      - `name` string — Human-readable name for the environment
      - `description` string, nullable — Optional description of the environment
      - `docker_image` string — Docker image to use (e.g., "ubuntu:latest" or "registry/repo:tag")
      - `github_repos` GitHubRepo[] — List of GitHub repositories to clone into the environment
        - `owner` string, required — GitHub repository owner (user or organization)
        - `repo` string, required — GitHub repository name
      - `setup_commands` string[] — Shell commands to run during environment setup
      - `providers` ProvidersConfig — Optional cloud provider configurations for automatic auth
        - `gcp` GcpProviderConfig — GCP Workload Identity Federation settings
          - `project_number` string, required — GCP project number
          - `workload_identity_federation_pool_id` string, required — Workload Identity Federation pool ID
          - `workload_identity_federation_provider_id` string, required — Workload Identity Federation provider ID
          - `service_account_email` string — Optional GCP service account email to impersonate
        - `aws` AwsProviderConfig — AWS IAM role assumption settings
          - `role_arn` string, required — AWS IAM role ARN to assume
      - `failure_session_retention_minutes` integer, nullable — When set (1–60 minutes), a failed run using this environment keeps its session open for this many minutes so it can be inspected. null or absent means immediate teardown (disabled by default). The window is an idle window held open by the agent process itself: working in the session pushes the deadline out, so a session in active use is not torn down mid-debug. It ends early if the run's sandbox reaches its own deadline first. This policy applies to future failures of runs using this environment; it does not change the window a currently-failed run was already started with. Opting in keeps injected environment data (including secrets) alive and incurs compute usage for as long as the session is held open.
    - `last_updated` string, date-time, required — Timestamp when the environment was last updated (RFC3339)
    - `last_task_run_timestamp` string, date-time, nullable — Timestamp of the most recent task run in this environment (RFC3339)
    - `last_task_created` EnvironmentLastTask — Summary of the most recently created task for an environment
      - `id` string, required — Unique identifier of the task
      - `title` string, required — Title of the task
      - `state` 'QUEUED' | 'PENDING' | 'CLAIMED' | 'INPROGRESS' | 'SUCCEEDED' | 'FAILED' | 'BLOCKED' | 'ERROR' | 'CANCELLED', required — Current state of the run: - QUEUED: Run is waiting to be picked up - PENDING: Run is being prepared - CLAIMED: Run has been claimed by a worker - INPROGRESS: Run is actively being executed - SUCCEEDED: Run completed successfully - FAILED: Run failed - BLOCKED: Run is blocked (e.g., awaiting user input or approval) - ERROR: Run encountered an error - CANCELLED: Run was cancelled by user
      - `created_at` string, date-time, required — When the task was created (RFC3339)
      - `updated_at` string, date-time, required — When the task was last updated (RFC3339)
      - `started_at` string, date-time, nullable — When the task started running (RFC3339), null if not yet started
    - `setup_failed` boolean, required — True when the most recent task failed during setup before it started running
    - `scope` Scope — Ownership scope for a resource (team or personal)
      - `type` 'User' | 'Team', required — Type of ownership ("User" for personal, "Team" for team-owned)
      - `uid` string — UID of the owning user or team
    - `creator` RunCreatorInfo
      - `type` 'user' | 'service_account' — Type of the creator principal
      - `uid` string — Unique identifier of the creator
      - `display_name` string — Display name of the creator
      - `email` string — Email address of the creator
      - `photo_url` string, uri — URL to the creator's photo
    - `last_editor` RunCreatorInfo
      - `type` 'user' | 'service_account' — Type of the creator principal
      - `uid` string — Unique identifier of the creator
      - `display_name` string — Display name of the creator
      - `email` string — Email address of the creator
      - `photo_url` string, uri — URL to the creator's photo

## Other responses

- `401` — Authentication required
- `500` — Internal server error

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/warp/oz-agent-api/revisions/a0daf9e59774/schema)