---
title: "Data sync"
method: POST
path: "/data/sync"
tags: ["Data Sync", "beta"]
---

# Data sync

`POST /data/sync`

## Request

- Base URL: `https://happy-animal-123.convex.cloud/api/v1`
- URL: `https://happy-animal-123.convex.cloud/api/v1/data/sync`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `Authorization`
  - API key in header `Authorization`
  - API key in header `Authorization`

Paginated streamable export of some or all of a deployment's data.

Call this endpoint repeatedly, passing the opaque `pagination.nextCursor`
from each response back in the next request as `cursor`. Omit `cursor` on
the first call.

To do a one time data sync, keep fetching pages until reaching an `upToDate`
page. For a continuous streaming export, continue fetching pages
periodically. It's recommended to sleep between `upToDate` pages to reduce
overhead.

The caller must have the `deployment:data:view` permission.

## Request body

- DataSyncArgs: Arguments to the data sync (streaming export) API (`/api/v1/data/sync`).
  - `cursor` string, nullable: Opaque cursor returned by a previous call. Omit to start from scratch.
  - `selection` Selection
    - `_other` 'excluded' | 'included', required

## Response `200`

- DataSyncResponse: One page returned by the data sync API.
  - `status` union, required: The consistency state reported alongside a data sync page, discriminated by `type`.
    - DataSyncSnapshotting: The sync has not yet reached a consistent snapshot. The entries emitted so far are an incomplete initial traversal of the selected tables. Syncs begin in this state. The sync's progress can be monitored via `/data/list_active_syncs`, keyed by the response's `syncId`. Syncs may return to this state if the table selection has changes that requires large data sync.
      - `type` 'snapshotting', required: The literal string `snapshotting`, discriminating "snapshotting" status objects.
    - DataSyncStale: The entries emitted so far represent a consistent snapshot at a stale `snapshotTs`.
      - `type` 'stale', required: The literal string `stale`, discriminating "stale" status objects.
      - `snapshotTs` integer, required: The database timestamp at which the synced data is consistent.
    - DataSyncUpToDate: The sync is up to date and represents a latest consistent snapshot. For a streaming export in this state, it is recommended to backoff for some time, wait for more data, and then continue the streaming sync.
      - `type` 'upToDate', required: The literal string `upToDate`, discriminating "up to date" status objects.
      - `snapshotTs` integer, required: The database timestamp at which the synced data is consistent.
  - `truncates` DataSyncTruncate[], required: Tables truncated by this page. The consumer should drop everything it previously synced for each table, then apply `values` (which re-sync them from scratch). Logically applies before `values`. A table is truncated whenever it (re)enters the export from scratch — the first page it is synced (including on a cold start), when it is newly selected, or when it is replaced by a bulk operation such as `npx convex import` — and when it leaves the export after being deselected.
    - `component` string, required: The path of the component the table is in.
    - `table` string, required: The name of the truncated table.
  - `values` DataSyncValue[], required: Documents created, updated, or deleted in this page.
    - `component` string, required: The path of the component this entry is from.
    - `table` string, required: The name of the table this entry is from.
    - `ts` integer, required: The timestamp at which this revision was written.
    - `deleted` boolean, required: Whether the document was deleted (a tombstone).
    - `value` object, required: The fields of the document, including the built-in `_id` and `_creationTime`. For `deleted` documents, only `_id` is present.
  - `syncId` string, required: Unique id of the sync, assigned on the first page and stable across the sync's lifetime. Identifies this sync in `/data/list_active_syncs`.
  - `pagination` PaginationMetadata, required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable

---

[API](https://skmtc.dev/operatornest/apis/convex-deployment-api.md) · [All operations](https://skmtc.dev/operatornest/apis/convex-deployment-api/llms.txt) · [OpenAPI document](https://skmtc.dev/operatornest/apis/convex-deployment-api/revisions/bd0de6c553a7?raw)