---
title: "List canvas agents"
method: GET
path: "/v1/canvases/:canvas_key/agents"
---

# List canvas agents

`GET /v1/canvases/:canvas_key/agents`

List all agents in a canvas. The service account must have at least an editor role for this canvas.

## Path parameters

- `canvas_key` string, required

## Response `200`

Successful response

- object — Base response envelope for all successful API responses.
  - `success` true, required
  - `request_id` string, required
  - `result` object, required
    - `agents` object[], required — The list of agents in the canvas.
      - `url` string, required — The URL of the agent
      - `canvas_key` string, required — The unique identifier for the canvas
      - `agent_key` string, required — The unique identifier for an agent within a canvas
      - `status` union, required — The current status of the agent.
        - 'running' — The agent is processing the most recent user prompt.
        - 'completed' — The agent has finished executing.
        - 'error' — The agent encountered an unexpected error.
        - 'pending_permission' — The agent requires permission to continue. The user must be directed to the agent URL to approve the requested actions.
      - `responses` string[], required — The responses from the agent until now.
      - `duration` number, required — How long the agent has been executing (if still running), or how long the agent last took to execute (in milliseconds).
      - `error` string — The error state of the agent (if any).
      - `required_action` string — The next action required from the user (if any). If this field is present, the user should be directed to the agent URL to continue working.

## Other responses

- `4XX` — Client error. Possible status codes include: 400 (invalid request), 401 (missing or invalid API key), 403 (insufficient permissions), 404 (resource not found), 429 (rate limit exceeded).
- `5XX` — Internal server error.

---

[API](https://skmtc.net/count/apis/count-public-api.md) · [All operations](https://skmtc.net/count/apis/count-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/count/count-public-api/versions/858ed44750ff/schema)