---
title: "Get workspace agent by ID"
method: GET
path: "/api/v2/workspaceagents/{workspaceagent}"
tags: ["Agents"]
---

# Get workspace agent by ID

`GET /api/v2/workspaceagents/{workspaceagent}`

## Path parameters

- `workspaceagent` string, uuid, required

## Response `200`

OK

- 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
      - `interval` integer — Interval specifies the seconds between each health check.
      - `threshold` integer — Threshold specifies the number of consecutive failed health checks before returning "unhealthy".
      - `url` string — URL specifies the endpoint to check for the app health.
    - `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.
      - `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
    - `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
  - `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

---

[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/versions/56b6e9f08540/schema)