---
title: "Run query"
method: POST
path: "/api/v1/queries"
tags: ["Queries"]
---

# Run query

`POST /api/v1/queries`

## Request

- Base URL: `https://api.getcortexapp.com`
- URL: `https://api.getcortexapp.com/api/v1/queries`
- Auth: HTTP bearer

Run a CQL query against up to 100 `entities`, or against one page of the catalog with `pageSize` and `pageToken`. A request with neither runs against every entity in the catalog. Starting November 10, 2026, it runs against the first page only, and the response's `nextPageToken` reads the next page. For more information about the types of queries you can run, take a look at our CQL Explorer in the app.

## Request body

- QueryRequest
  - `entities` string[]: Tags or Cortex IDs of the entities to run the query against, from 1 to 100. Omit to page through the catalog with `pageSize` and `pageToken` instead.
  - `pageSize` integer: Run the query against one page of at most this many entities, at most 1000. The response's `nextPageToken` reads the next page. Defaults to 1000 when `pageToken` is set.
  - `pageToken` string: The `nextPageToken` from the previous response, to run the query against the next page.
  - `query` string, required

## Response `200`

Successfully submitted query

- QueryResponse
  - `initiatedAt` string, date-time, required
  - `jobId` string, required: Id that can be used to request the status of the query. If you would like to re-run the query, you must re-run the query in the UI. See [retrieve query results](/docs/api/get-query-results)
  - `nextPageToken` string: Pass as `pageToken` to run the same query against the next page. Absent on the last page, and when the request did not page.
  - `query` string, required

## Other responses

- `400`: Bad request
- `409`: Conflict
- `429`: The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

## Changes

- **2026-11-03** `a7b058663c95`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cortex/apis/cortex-api/changes/api/v1/queries/post.md)

---

[API](https://skmtc.dev/cortex/apis/cortex-api.md) - [All operations](https://skmtc.dev/cortex/apis/cortex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cortex/apis/cortex-api/revisions/a7b058663c95?raw)