---
title: "Run a query"
method: POST
path: "/v1/queries"
---

# Run a query

`POST /v1/queries`

Run a new query in a given context - one of the `sql` or `structured` parameters must be present. This service account must have analyst permissions in the chosen context. A reference to the created query job is returned. If the same query is submitted multiple times, the same job reference may be returned if caching is enabled.

## Request body

- object
  - `context` object, required — The context to run the query in. This context determines which data sources the query has access to. The service account must have an analyst role in this context.
    - `type` union, required — The type of context
      - 'canvas' — Run a query in a canvas context
      - 'project' — Run a query in a project context
    - `context_key` string, required — The unique identifier for the context.
  - `source` object, required — The data source to run the query against. The source must be available in the chosen context.
    - `type` union, required — The data source to query.
      - 'connection' — A database connection.
      - 'catalog' — A Count Metrics catalog.
    - `source_key` string, nullable, required — The unique identifier for the connection
  - `sql` string — A SQL query definition, which can only be used to query a database connection source
  - `structured` object — A structured query definition, which can only be used to query a catalog source. Read more about the expression syntax [here](https://learn.count.co/data-exploration-and-problem-solving/visual-and-low-code-cells/calculations-in-visuals-and-low-code-cells), which is a reduced subset of Postgres-like SQL.
    - `dataset` string, required — The name of the dataset to query. This should always be the name of a dataset, not a view.
    - `selects` object[], required — A list of expressions to select
      - `view` string, required — The name of the view that the field comes from.
      - `expression` string, required — The name of a field, or an expression for a calculated field. Names of fields should always be qualified with view names, in case there are multiple fields with the same name in different views.
    - `filters` object — Optional filters to apply to the result.
      - `combine` union, required — How multiple filters should be combined
        - 'and' — Combine using the AND boolean operation.
        - 'or' — Combine using the OR boolean operation
      - `filters` object[], required — The list of filters
        - `value` union, required — The filter value
          - number — A numeric value
          - string — A string value
          - boolean — A boolean value
        - `operator` union, required — The filter operation
          - '=' — Equal to.
          - '!=' — Not equal to.
          - '>' — Greater than.
          - '<' — Less than.
          - '>=' — Greater or equal.
          - '<=' — Less or equal
        - `field` string, required — The name of a field
        - `view` string, required — The name of the view that the field comes from
  - `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-service-production.skmtc.workers.dev/v1/apis/count/count-public-api/revisions/8bfa1b92c91d/schema)