> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userepo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync runs

> View sync history; queue manual syncs.

A **sync run** is one execution of a connector's sync logic — pull new items from the provider, normalize them, embed them, and store them.

***

## List sync runs

```http theme={null}
GET https://api.userepo.com/v1/sync-runs
```

Requires `sync:read`. Returns recent runs for the organization, newest first.

```json theme={null}
{
  "syncRuns": [
    {
      "id": "uuid",
      "connectorId": "uuid",
      "status": "succeeded",
      "fullResync": false,
      "startedAt": "2026-05-30T20:00:00Z",
      "finishedAt": "2026-05-30T20:00:14Z",
      "itemsDiscovered": 18,
      "itemsIngested": 3,
      "errorMessage": null,
      "createdAt": "2026-05-30T19:59:55Z"
    }
  ]
}
```

<ResponseField name="status" type="string">`queued` → `running` → `succeeded` | `failed`.</ResponseField>
<ResponseField name="itemsDiscovered" type="integer">How many source items the provider returned for this run.</ResponseField>
<ResponseField name="itemsIngested" type="integer">How many were actually new (or updated) and stored. The difference is items filtered out (already seen, archived, etc.).</ResponseField>
<ResponseField name="errorMessage" type="string | null">Surfaced from the underlying provider/connector error. Repo passes through provider error messages verbatim where possible.</ResponseField>

***

## Trigger a sync run

```http theme={null}
POST https://api.userepo.com/v1/sync-runs
```

Requires `sync:write`.

<ParamField body="connectorId" type="uuid" required>
  The source/connector to sync.
</ParamField>

<ParamField body="fullResync" type="boolean" default="false">
  If `true`, discard the sync cursor and re-ingest every source item. Useful after a schema change or to backfill missing access policies. Slower and uses more provider API quota.
</ParamField>

```json theme={null}
{
  "syncRun": {
    "id": "uuid",
    "connectorId": "uuid",
    "status": "queued",
    "fullResync": false,
    "createdAt": "2026-05-30T20:14:00Z"
  },
  "alreadyActive": false
}
```

If a sync run is already queued or running for this connector, the response returns the existing run with `alreadyActive: true` (HTTP 202). Repo enforces "at most one active run per connector" at the database level via a unique partial index — you can't accidentally double-queue.