---
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
    - `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.net/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.net/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/warp/oz-agent-api/versions/97be876c33e3/schema)