HTTP API Reference

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}

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

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

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

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

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