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:

https://{projectId}.apicdn.sanity.io/v{YYYY-MM-DD}/data/query/{dataset}

The CDN only serves the published and raw perspectives. Send queries that use drafts or release perspectives to the API endpoint.

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

Sanity API CDN base URL (edge-cached results, published and raw perspectives only)

https://{projectId}.apicdn.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. Some browsers and proxies limit URL length. Send queries longer than 11 KB as a POST; @sanity/client switches to POST when the encoded query string reaches 11,264 characters.

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

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. Set to only to return the plan without running the query; result is then null.

  • resultSourceMap

    If true, the response includes a resultSourceMap field with content source map metadata. Set to withKeyArraySelector to use _key-based array selectors in source paths.

  • perspectivestringdefault: "published"

    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: A comma-separated list of release IDs, optionally including drafts, to create a custom perspective. Earlier entries take precedence. The list can contain up to 200 entries. Requires API version v2025-02-19 or later; earlier versions return a 400 error.

    Defaults to published in API version v2025-02-19 and later. Earlier API versions default to raw.

    The CDN endpoint only accepts published and raw. Any other perspective returns a 400 error.

    For POST requests, pass perspective as a URL query parameter. The request body doesn't accept it.

  • 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

  • cacheModestring

    Set to noStale to disable stale-while-revalidate on CDN responses. Use it for live queries that must not serve stale data after the cache expires.

  • lastLiveEventIdstring

    The ID of the last event received from the Live Content API. The CDN uses it to serve a response that is at least as fresh as that event.

  • $-prefixedstring

    GROQ queries may also use parameters. In the query these will be prefixed by a dollar sign. Submit each parameter as a URL parameter with a JSON-encoded value, for example $language="es". An unquoted string value returns a 400 error.

Responses

200

Successful query response

  • msnumber

    Server-side processing time

  • querystring

    Submitted query. Omitted when returnQuery is false.

  • result

    Query result (can be any valid JSON value)

  • syncTagsarray
    Show child attributes
    items
    • string
  • explainstring

    Query execution plan as plain text. Only present when explain is set.

  • resultSourceMapobject

    Content source map metadata for the result. Only present when resultSourceMap is set.

Examplesapplication/json
arrayResult
{
  "ms": 12,
  "query": "*[_type == 'movie']",
  "result": [
    {
      "_id": "movie1",
      "title": "Inception"
    }
  ],
  "syncTags": [
    "s1:hil1xQ"
  ]
}

Query using POST method

post/data/query/{dataset}

Use POST for long queries or large parameter values. @sanity/client sends queries as a POST when the encoded query string reaches 11,264 characters. Queries sent using the POST method will also be cached on the CDN.

The request body only accepts query, params, and returnQuery. Pass other options, such as perspective, explain, resultSourceMap, and tag, as URL query parameters. Unknown body fields return a 400 error.

Path parameters

Query parameters

  • explain

    Whether to include the query execution plan as plain text in an explain field. Set to only to return the plan without running the query; result is then null.

  • resultSourceMap

    If true, the response includes a resultSourceMap field with content source map metadata. Set to withKeyArraySelector to use _key-based array selectors in source paths.

  • perspectivestringdefault: "published"

    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: A comma-separated list of release IDs, optionally including drafts, to create a custom perspective. Earlier entries take precedence. The list can contain up to 200 entries. Requires API version v2025-02-19 or later; earlier versions return a 400 error.

    Defaults to published in API version v2025-02-19 and later. Earlier API versions default to raw.

    The CDN endpoint only accepts published and raw. Any other perspective returns a 400 error.

    For POST requests, pass perspective as a URL query parameter. The request body doesn't accept it.

  • 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

  • cacheModestring

    Set to noStale to disable stale-while-revalidate on CDN responses. Use it for live queries that must not serve stale data after the cache expires.

  • lastLiveEventIdstring

    The ID of the last event received from the Live Content API. The CDN uses it to serve a response that is at least as fresh as that event.

Request body application/json

  • querystringrequired

    The GROQ query

  • paramsobject

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

  • returnQuerybooleandefault: true

    If false, the response will not include the submitted query

Examplesapplication/json
basicQuery
{
  "query": "*[_type == 'movie']"
}

Responses

200

Successful query response

  • msnumber

    Server-side processing time

  • querystring

    Submitted query. Omitted when returnQuery is false.

  • result

    Query result (can be any valid JSON value)

  • syncTagsarray
    Show child attributes
    items
    • string
  • explainstring

    Query execution plan as plain text. Only present when explain is set.

  • resultSourceMapobject

    Content source map metadata for the result. Only present when resultSourceMap is set.

sanity.ioAll Systems Operational© Sanity 2026
Change site theme