---
title: "List workspaces"
method: GET
path: "/api/v2/workspaces"
tags: ["Workspaces"]
---

# List workspaces

`GET /api/v2/workspaces`

## Query parameters

- `q` string
- `limit` integer
- `offset` integer

## Response `200`

OK

- CodersdkWorkspacesResponse
  - `count` integer
  - `workspaces` CodersdkWorkspace[]
    - `allow_renames` boolean
    - `automatic_updates` 'always' | 'never'
    - `autostart_schedule` string
    - `created_at` string, date-time
    - `deleting_at` string, date-time — DeletingAt indicates the time at which the workspace will be permanently deleted. A workspace is eligible for deletion if it is dormant (a non-nil dormant_at value) and a value has been specified for time_til_dormant_autodelete on its template.
    - `dormant_at` string, date-time — DormantAt being non-nil indicates a workspace that is dormant. A dormant workspace is no longer accessible must be activated. It is subject to deletion if it breaches the duration of the time_til_ field on its template.
    - `favorite` boolean
    - `health` CodersdkWorkspaceHealth
      - `failing_agents` string[] — FailingAgents lists the IDs of the agents that are failing, if any.
      - `healthy` boolean — Healthy is true if the workspace is healthy.
    - `id` string, uuid
    - `is_prebuild` boolean — IsPrebuild indicates whether the workspace is a prebuilt workspace. Prebuilt workspaces are owned by the prebuilds system user and have specific behavior, such as being managed differently from regular workspaces. Once a prebuilt workspace is claimed by a user, it transitions to a regular workspace, and IsPrebuild returns false.
    - `last_used_at` string, date-time
    - `latest_app_status` CodersdkWorkspaceAppStatus
      - `agent_id` string, uuid
      - `app_id` string, uuid
      - `created_at` string, date-time
      - `icon` string — Deprecated: This field is unused and will be removed in a future version. Icon is an external URL to an icon that will be rendered in the UI.
      - `id` string, uuid
      - `message` string
      - `needs_user_attention` boolean — Deprecated: This field is unused and will be removed in a future version. NeedsUserAttention specifies whether the status needs user attention.
      - `state` 'working' | 'idle' | 'complete' | 'failure'
      - `uri` string — URI is the URI of the resource that the status is for. e.g. https://github.com/org/repo/pull/123 e.g. file:///path/to/file
      - `workspace_id` string, uuid
    - `latest_build` CodersdkWorkspaceBuild
      - `build_number` integer
      - `created_at` string, date-time
      - `daily_cost` integer
      - `deadline` string, date-time
      - `has_ai_task` boolean — Deprecated: This field has been deprecated in favor of Task WorkspaceID.
      - `has_external_agent` boolean
      - `id` string, uuid
      - `initiator_id` string, uuid
      - `initiator_name` string
      - `job` CodersdkProvisionerJob
        - `available_workers` string[]
        - `canceled_at` string, date-time
        - `completed_at` string, date-time
        - `created_at` string, date-time
        - `error` string
        - `error_code` 'REQUIRED_TEMPLATE_VARIABLES' | 'INSUFFICIENT_QUOTA'
        - `file_id` string, uuid
        - `id` string, uuid
        - `initiator_id` string, uuid
        - `input` CodersdkProvisionerJobInput
          - `error` string
          - `template_version_id` string, uuid
          - `workspace_build_id` string, uuid
        - `logs_overflowed` boolean
        - `metadata` CodersdkProvisionerJobMetadata
          - `template_display_name` string
          - `template_icon` string
          - `template_id` string, uuid
          - `template_name` string
          - `template_version_name` string
          - `workspace_build_transition` 'start' | 'stop' | 'delete'
          - `workspace_id` string, uuid
          - `workspace_name` string
        - `organization_id` string, uuid
        - `queue_position` integer
        - `queue_size` integer
        - `started_at` string, date-time
        - `status` 'pending' | 'running' | 'succeeded' | 'canceling' | 'canceled' | 'failed' | 'unknown'
        - `tags` object
        - `type` 'template_version_import' | 'workspace_build' | 'template_version_dry_run'
        - `worker_id` string, uuid
        - `worker_name` string
      - `matched_provisioners` CodersdkMatchedProvisioners
        - `available` integer — Available is the number of provisioner daemons that are available to take jobs. This may be less than the count if some provisioners are busy or have been stopped.
        - `count` integer — Count is the number of provisioner daemons that matched the given tags. If the count is 0, it means no provisioner daemons matched the requested tags.
        - `most_recently_seen` string, date-time — MostRecentlySeen is the most recently seen time of the set of matched provisioners. If no provisioners matched, this field will be null.
      - `max_deadline` string, date-time
      - `reason` 'initiator' | 'autostart' | 'autostop' | 'dormancy' | 'dashboard' | 'cli' | 'ssh_connection' | 'vscode_connection' | 'jetbrains_connection' | 'task_auto_pause' | 'task_manual_pause' | 'task_resume'
      - `resources` CodersdkWorkspaceResource[]
        - `agents` CodersdkWorkspaceAgent[]
          - `api_version` string
          - `apps` CodersdkWorkspaceApp[]
            - `command` string
            - `display_name` string — DisplayName is a friendly name for the app.
            - `external` boolean — External specifies whether the URL should be opened externally on the client or not.
            - `group` string
            - `health` 'disabled' | 'initializing' | 'healthy' | 'unhealthy'
            - `healthcheck` CodersdkHealthcheck
              - …
            - `hidden` boolean
            - `icon` string — Icon is a relative path or external URL that specifies an icon to be displayed in the dashboard.
            - `id` string, uuid
            - `open_in` 'slim-window' | 'tab'
            - `sharing_level` 'owner' | 'authenticated' | 'organization' | 'public'
            - `slug` string — Slug is a unique identifier within the agent.
            - `statuses` CodersdkWorkspaceAppStatus[] — Statuses is a list of statuses for the app.
              - …
            - `subdomain` boolean — Subdomain denotes whether the app should be accessed via a path on the `coder server` or via a hostname-based dev URL. If this is set to true and there is no app wildcard configured on the server, the app will not be accessible in the UI.
            - `subdomain_name` string — SubdomainName is the application domain exposed on the `coder server`.
            - `tooltip` string — Tooltip is an optional markdown supported field that is displayed when hovering over workspace apps in the UI.
            - `url` string — URL is the address being proxied to inside the workspace. If external is specified, this will be opened on the client.
          - `architecture` string
          - `connection_timeout_seconds` integer
          - `created_at` string, date-time
          - `directory` string
          - `disconnected_at` string, date-time
          - `display_apps` CodersdkDisplayApp[]
          - `environment_variables` object
          - `expanded_directory` string
          - `first_connected_at` string, date-time
          - `health` CodersdkWorkspaceAgentHealth
            - `healthy` boolean — Healthy is true if the agent is healthy.
            - `reason` string — Reason is a human-readable explanation of the agent's health. It is empty if Healthy is true.
          - `id` string, uuid
          - `instance_id` string
          - `last_connected_at` string, date-time
          - `latency` object — DERPLatency is mapped by region name (e.g. "New York City", "Seattle").
          - `lifecycle_state` 'created' | 'starting' | 'start_timeout' | 'start_error' | 'ready' | 'shutting_down' | 'shutdown_timeout' | 'shutdown_error' | 'off'
          - `log_sources` CodersdkWorkspaceAgentLogSource[]
            - `created_at` string, date-time
            - `display_name` string
            - `icon` string
            - `id` string, uuid
            - `workspace_agent_id` string, uuid
          - `logs_length` integer
          - `logs_overflowed` boolean
          - `metadata` CodersdkWorkspaceAgentMetadata[] — Metadata is only populated on the workspaces list endpoint when the request opts in with the include_agent_metadata search key, and it only carries the requested keys. The description's script is always empty here: it can be long, and list consumers want values.
            - `description` CodersdkWorkspaceAgentMetadataDescription
              - …
            - `result` CodersdkWorkspaceAgentMetadataResult
              - …
          - `name` string
          - `operating_system` string
          - `parent_id` UuidNullUUID
            - `uuid` string
            - `valid` boolean — Valid is true if UUID is not NULL
          - `ready_at` string, date-time
          - `resource_id` string, uuid
          - `scripts` CodersdkWorkspaceAgentScript[]
            - `cron` string
            - `display_name` string
            - `exit_code` integer
            - `id` string, uuid
            - `log_path` string
            - `log_source_id` string, uuid
            - `run_on_start` boolean
            - `run_on_stop` boolean
            - `script` string
            - `start_blocks_login` boolean
            - `status` 'ok' | 'exit_failure' | 'timed_out' | 'pipes_left_open'
            - `timeout` integer
          - `started_at` string, date-time
          - `startup_script_behavior` 'blocking' | 'non-blocking'
          - `status` 'connecting' | 'connected' | 'disconnected' | 'timeout'
          - `subsystems` CodersdkAgentSubsystem[]
          - `troubleshooting_url` string
          - `updated_at` string, date-time
          - `version` string
        - `created_at` string, date-time
        - `daily_cost` integer
        - `hide` boolean
        - `icon` string
        - `id` string, uuid
        - `job_id` string, uuid
        - `metadata` CodersdkWorkspaceResourceMetadata[]
          - `key` string
          - `sensitive` boolean
          - `value` string
        - `name` string
        - `type` string
        - `workspace_transition` 'start' | 'stop' | 'delete'
      - `status` 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'canceling' | 'canceled' | 'deleting' | 'deleted'
      - `template_version_id` string, uuid
      - `template_version_name` string
      - `template_version_preset_id` string, uuid
      - `transition` 'start' | 'stop' | 'delete'
      - `updated_at` string, date-time
      - `workspace_id` string, uuid
      - `workspace_name` string
      - `workspace_owner_avatar_url` string
      - `workspace_owner_id` string, uuid
      - `workspace_owner_name` string — WorkspaceOwnerName is the username of the owner of the workspace.
    - `name` string
    - `next_start_at` string, date-time
    - `organization_id` string, uuid
    - `organization_name` string
    - `outdated` boolean
    - `owner_avatar_url` string
    - `owner_id` string, uuid
    - `owner_name` string — OwnerName is the username of the owner of the workspace.
    - `shared_with` CodersdkSharedWorkspaceActor[]
      - `actor_type` 'group' | 'user'
      - `avatar_url` string, uri
      - `id` string, uuid
      - `name` string
      - `roles` CodersdkWorkspaceRole[]
    - `task_id` UuidNullUUID
      - `uuid` string
      - `valid` boolean — Valid is true if UUID is not NULL
    - `template_active_version_id` string, uuid
    - `template_allow_user_cancel_workspace_jobs` boolean
    - `template_display_name` string
    - `template_icon` string
    - `template_id` string, uuid
    - `template_name` string
    - `template_require_active_version` boolean
    - `template_use_classic_parameter_flow` boolean
    - `ttl_ms` integer
    - `updated_at` string, date-time

---

[API](https://skmtc.net/coder/apis/coder-api.md) · [All operations](https://skmtc.net/coder/apis/coder-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/coder/coder-api/revisions/50a77af44008/schema)