---
title: Sync API
description: Start a source sync, follow its event stream, reconnect safely, and distinguish accepted work from final state.
species: reference
---
# Sync API

Triggering a sync requires `apps:manage`. Reading its progress stream requires `data:read`.

## Start a sync

```endpoint
POST /sources/{id}/sync
```

Accepts a sync request for the source and returns an asynchronous resource. Acceptance means the request is recorded, not that table commits have finished.

A paused or deleted source is refused. If the source already has live work, the response reports the conflict instead of starting a duplicate run.

Use an `Idempotency-Key` when retrying after a lost response. Bind the key to one source and request body.

## Stream progress

```endpoint
GET /sources/{id}/sync/stream
```

The Server-Sent Events stream reports progress and the durable sync outcome. Reconnect using `Last-Event-ID` when the transport closes. Treat the source resource's latest sync as the final authority after reconnecting.

Events can include table name, phase, completed and total counts, and terminal outcome. Clients must ignore additive event fields.

## After completion

A successful terminal event means the run's table commits finished. Related tables can complete at different times, so freshness-sensitive automation should inspect the committed `_synced_at` values or the catalog after terminal state.

Use [source error logs](/v2/docs/api/logs) when a run fails and [Syncing](/v2/docs/concepts/syncing) for merge and delete semantics.