Export API reference

The Export API lets you export all the non-deleted documents in a dataset, including drafts, release versions, and asset documents.

By default, this endpoint returns all the documents a user can access as a newline-delimited JSON (NDJSON) stream. The documents are in the state they were in when the request was made and are not affected by any changes in the dataset that happened after the request was made. The stream doesn't return documents in any guaranteed order.

In most cases, use the sanity datasets export CLI command or the @sanity/export npm package instead. Those have built-in features such as asset downloads and an option to exclude drafts. @sanity/export also supports cursor mode (mode: 'cursor') and follows the cursors for you.

Cursor mode for large datasets

For datasets with many documents (typically tens of thousands), network or other instabilities can cause the export stream to time out or be interrupted. In these cases, you can send a request with a nextCursor query parameter set to an empty string. The export runs for up to 30 seconds and returns documents ordered by _id. If the time runs out before the export finishes, the stream ends with a {"nextCursor": "..."} object. The cursor is an encoded representation of a position in an ordered document list of the dataset.

You can initiate a new export request with this value as the nextCursor parameter value to continue the export manually. The export is complete when a stream ends without a nextCursor object and without an error object (see below). The final request can return an empty stream. Note that any changes made between requests in "cursor mode" are reflected in the export, which can lead to inconsistencies, for example, if references have been changed in the dataset.

Errors during the stream

The response status is sent before the stream starts. If an error occurs after the first document is sent, the status stays 200 and the stream ends with an error object instead of a document, for example {"error":{"description":"Internal server error","type":"internalError"}}. Check the last line of every stream for an error key before treating the export as complete.

Authentication

An unauthenticated request returns only publicly available documents. If you include an authentication token, the export contains the documents that this token can access (for example, drafts, release versions, and system documents).

An unauthenticated request to a private dataset doesn't return an error. It returns a 200 response with an empty stream.