---
title: "List canvases"
method: GET
path: "/v1/canvases"
---

# List canvases

`GET /v1/canvases`

List all visible canvases in the workspace accessible with this service account. Trashed canvases and those that the service account is not permitted to view are not returned.

## Query parameters

- `project_key` string
- `creator` string
- `created_after` string, date-time — An ISO 8601 date-time string.
- `modified_after` string, date-time — An ISO 8601 date-time string.
- `tag_names` string

## Response `200`

Successful response

- object — Base response envelope for all successful API responses.
  - `success` true, required
  - `request_id` string, required
  - `result` object, required
    - `canvases` Canvas[], required — The list of canvases in the workspace.
      - `key` string, required — The unique identifier for the canvas
      - `name` string, required — The display name for the canvas
      - `created_at` string, date-time, required — An ISO 8601 date-time string.
      - `modified_at` string, date-time, required — An ISO 8601 date-time string.
      - `modified_by` string, nullable, required — The unique identifier for the user
      - `creator` string, required — The unique identifier for the user
      - `permissions` object[], required — The list of actors with assigned permissions for this canvas.
        - `key` string, required — The unique identifier for the actor.
        - `role` union, required — A canvas role.
          - 'analyst' — Canvas analyst.
          - 'editor' — Canvas editor.
          - 'viewer' — Canvas viewer.
          - 'presentation_viewer' — Canvas presentation viewer.
        - `type` union, required — The type of actor.
          - 'user' — A workspace member
          - 'group' — A workspace group
          - 'service_account' — A service account
          - 'workspace' — All workspace members
          - 'project' — A project permission
          - 'public' — A public permission (`viewer` or `presentation_viewer` only)
      - `permitted_actions` object, required — The actions you are allowed to perform in this canvas
        - `create_agent` boolean, required — Are you able to create an agent or not.
      - `preview` string, nullable, required — The preview URL
      - `project_key` string, required — The unique identifier for the project
      - `archived_at` string, date-time, required — An ISO 8601 date-time string.
      - `background` string — The canvas background color.
      - `cache_duration` number — The cache duration time for this canvas in seconds.
      - `automatic_cell_execution` boolean — Whether cells in this canvas execute automatically or not.
      - `refresh_schedule` string — A [cron expression](https://crontab.guru) representing the query refresh schedule.
      - `refresh_strategy` union — Which cells are executed during a scheduled refresh.
        - 'all' — Execute every cell.
        - 'automatic' — Skip cells that have execution disabled.
        - 'visible' — Skip hidden cells.
        - 'visible_automatic' — Skip hidden cells and cells that have execution disabled.
      - `refreshed_at` string, date-time — An ISO 8601 date-time string.
      - `tags` string[] — The tags for this canvas.

## 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)