---
title: "Run a cell"
method: POST
path: "/v1/queries/canvases/:canvas_key/cells/:cell_key"
---

# Run a cell

`POST /v1/queries/canvases/:canvas_key/cells/:cell_key`

## Request

- Base URL: `https://api.app.count.co/v1`
- URL: `https://api.app.count.co/v1/v1/queries/canvases/:canvas_key/cells/:cell_key`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/count/apis/count-public-api/docs/v1/queries/canvases/:canvas_key/cells/:cell_key/post.ts> (a function with typed inputs; its response is checked against the schema)

Execute a cell in a canvas. This service account must be permitted to view the chosen canvas. If the same cell is executed multiple times, the same job reference may be returned if caching is enabled.

## Path parameters

- `canvas_key` string, required
- `cell_key` string, required

## Request body

- object
  - `cache_strategy` union: Define the caching behaviour for this query.
    - 'force': Always run a new query
    - 'cached-only': Never run a new query
    - 'default': Return cached results if available, otherwise run a new query
  - `external_results` object[]: For DuckDB queries, the list of external results that should be queried. If not provided, the query will return an error.
    - `cell_key` string, required: The unique identifier for a cell in a canvas
    - `cell_name` string, required: The name of the cell.
    - `job_key` string: The unique identifier for the query job. Optional for upstream CSV cells, which are resolved automatically.

## Response `200`

Successful response

- object: Base response envelope for all successful API responses.
  - `success` true, required
  - `request_id` string, required
  - `result` object, required
    - `job_key` string, required: The unique identifier for the query job
    - `status` union, required: The current status of the job
      - 'running': The query has been submitted, but the results are not ready to be fetched yet.
      - 'completed': The query has finished, and results are ready to be fetched.
      - 'error': The query failed during compilation, submission, or execution.
    - `compiled_sql` string: The SQL query that was constructed (if available).
    - `error` string: An error encountered during query compilation, submission, or execution.

## 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.dev/count/apis/count-public-api.md) - [All operations](https://skmtc.dev/count/apis/count-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/count/apis/count-public-api/revisions/030b9f68e8f5?raw)