HTTP API ReferenceLast updated May 15, 2025

Listen

The listen endpoint can be used to receive events whenever documents are modified. This endpoint follows the server-sent events protocol using the mime-type text/event-stream. The backend will hold the connection open and stream events as they occur for any documents matching the GROQ query.
In most cases, you should use the Live API instead for new projects.

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

Stream document mutation events

get/data/listen/{dataset}

Streams events whenever documents matching the GROQ query are modified. This is a live API adhering to the Server Sent Events standard.

Path parameters

datasetstringrequired
The dataset to stream events from

Query parameters

querystringrequired
The GROQ-query used to filter the events. Only the top-level filter portion of the query will be used, anything else including projection, subqueries, slicing or aggregation will be ignored.
$-paramsstring
includeResultbooleandefault: false
Include the resulting document in addition to the changes.
includePreviousRevisionbooleandefault: false
Include the document as it looked before the change.
includeMutationsbooleandefault: true
Include the mutations applied as part of the transaction.
visibilitystringdefault: "transaction"
Specifies whether events should be sent as soon as a transaction has been committed (transaction, default), or only after they are available for queries (query). Note that this is best-effort, and listeners with query may in certain cases (notably with deferred transactions) receive events that are not yet visible to queries. The visibility event field will indicate the actual visibility.
evs_preamblebooleandefault: false
Send a prolog of 2056 no-op characters for compatibility with older browsers.
effectFormatstring
If set to the only allowed value mendoza, an additional field effects is included in the returned payload with mutation effects in the Mendoza specification.
includeAllVersionsbooleandefault: false
Set to true to receive draft and version documents. Requires API version 2025-02-19.

Responses

Select response

200

Successfully started streaming operation

idstring
A unique id for this event, comprised of the transaction id and the document id
eventstring
The type of SSE message
dataobject
The message payload

Examplestext/event-stream

welcome

{
  "event": "welcome",
  "data": {
    "listenerName": "Ua6BR3GwQ14cnZXrgwCdsF"
  }
}