HTTP API ReferenceLast updated January 9, 2026

Query API reference

Reference documentation for the Query HTTP endpoint.

The Query API lets you query Sanity Content Lake with GROQ.

You can also send queries to the CDN endpoint for edge-cached results:

Note: While you can use the HTTP API endpoint directly, we recommend using a client library if you can.

Authentication

Requests to drafts, versions, or content in private datasets must be authenticated.

Base API server URL

Sanity API base URL

https://{projectId}.api.sanity.io/{apiVersion}

Variables

projectIdstringdefault: "projectId"
Project ID
apiVersionstringdefault: "v2025-02-19"
API version

Endpoints

Query using GET method

get/data/query/{dataset}

The basic query API endpoint. Due to limitations in some browsers, we've put the max limit on GET queries at 11 KB. If your URL is longer than that, you must submit the query as a POST.

Note: When a document is not found, GROQ still evaluates to a value. Thus, you don't get 404 errors through this endpoint. Some examples:

*[_id == "missing"] results in []
count(*[_type == "typoType"]) results in 0
*[_id == "missing"][0] results in null
*[_id == "missing"][0].someProp also results in null

Path parameters

datasetstringrequired
Dataset name

Query parameters

querystringrequired
The GROQ query itself
Example:*[_type == 'movie']
explain
Whether to include the query execution plan as plain text in an explain field
resultSourceMapboolean
If true, the query result will include content source map metadata
perspectivestring
Runs the query against the selected perspective:
- drafts: Query runs as if all draft documents and changes were published.
- published: Query runs as if no draft documents or changes exist.
- raw: Query runs without distinguishing between drafts, release versions, or published documents.
- Release stack: You can also pass a comma-separated list of release names from Content Releases to create a custom perspective
tagstring
Request tags are values assigned to API and CDN requests that can be used to filter and aggregate log data within request logs from your Sanity Content Lake. Learn more in the request tags documentation.
returnQuerybooleandefault: true
If false, the response will not include the submitted query
$-prefixedstring
GROQ-queries may also use parameters. In the query these will be prefixed by a dollar sign. These are submitted as normal url-params.

Responses

Select response

200

Successful query response

msnumber
Server-side processing time
querystring
Submitted query
result
Query result (can be any valid JSON value)
syncTagsarray
Show child attributes
items
- string

Examplesapplication/json

arrayResult

{
  "ms": 12,
  "query": "*[_type == 'movie']",
  "result": [
    {
      "_id": "movie1",
      "title": "Inception"
    }
  ],
  "syncTags": [
    "movie1"
  ]
}

Query using POST method

post/data/query/{dataset}

Queries longer than 11kB can't be submitted using the GET method, so they must be POSTed. Queries sent using the POST method will also be cached on the CDN.

Path parameters

datasetstringrequired
Dataset name

Request body `application/json`

querystringrequired
The GROQ query
paramsobject
The params-part is optional. You don't use the $-prefixes when submitting as json

Examplesapplication/json

basicQuery

{
  "query": "*[_type == 'movie']"
}

Responses

Select response

200

Successful query response

msnumber
Server-side processing time
querystring
Submitted query
result
Query result (can be any valid JSON value)
syncTagsarray
Show child attributes
items
- string

Endpoints

Query using GET method

get/data/query/{dataset}

The basic query API endpoint. Due to limitations in some browsers, we've put the max limit on GET queries at 11 KB. If your URL is longer than that, you must submit the query as a POST.

Note: When a document is not found, GROQ still evaluates to a value. Thus, you don't get 404 errors through this endpoint. Some examples:

*[_id == "missing"] results in []
count(*[_type == "typoType"]) results in 0
*[_id == "missing"][0] results in null
*[_id == "missing"][0].someProp also results in null

Path parameters

datasetstringrequired
Dataset name

Query parameters

querystringrequired
The GROQ query itself
Example:*[_type == 'movie']
explain
Whether to include the query execution plan as plain text in an explain field
resultSourceMapboolean
If true, the query result will include content source map metadata
perspectivestring
Runs the query against the selected perspective:
- drafts: Query runs as if all draft documents and changes were published.
- published: Query runs as if no draft documents or changes exist.
- raw: Query runs without distinguishing between drafts, release versions, or published documents.
- Release stack: You can also pass a comma-separated list of release names from Content Releases to create a custom perspective
tagstring
Request tags are values assigned to API and CDN requests that can be used to filter and aggregate log data within request logs from your Sanity Content Lake. Learn more in the request tags documentation.
returnQuerybooleandefault: true
If false, the response will not include the submitted query
$-prefixedstring
GROQ-queries may also use parameters. In the query these will be prefixed by a dollar sign. These are submitted as normal url-params.

Responses

Select response

200

Successful query response

msnumber
Server-side processing time
querystring
Submitted query
result
Query result (can be any valid JSON value)
syncTagsarray
Show child attributes
items
- string

Examplesapplication/json

arrayResult

{
  "ms": 12,
  "query": "*[_type == 'movie']",
  "result": [
    {
      "_id": "movie1",
      "title": "Inception"
    }
  ],
  "syncTags": [
    "movie1"
  ]
}

Query using POST method

post/data/query/{dataset}

Queries longer than 11kB can't be submitted using the GET method, so they must be POSTed. Queries sent using the POST method will also be cached on the CDN.

Path parameters

datasetstringrequired
Dataset name

Request body `application/json`

querystringrequired
The GROQ query
paramsobject
The params-part is optional. You don't use the $-prefixes when submitting as json

Examplesapplication/json

basicQuery

{
  "query": "*[_type == 'movie']"
}

Responses

Select response

200

Successful query response

msnumber
Server-side processing time
querystring
Submitted query
result
Query result (can be any valid JSON value)
syncTagsarray
Show child attributes
items
- string

Authentication

Base API server URL

Variables

Authentication

Base API server URL

Variables

Endpoints

Query using GET method

Path parameters

Query parameters

Responses

items

Query using POST method

Path parameters

Request body application/json

Responses

items

Endpoints

Query using GET method

Path parameters

Query parameters

Responses

items

Query using POST method

Path parameters

Request body application/json

Responses

items

Request body `application/json`

Request body `application/json`