---
title: "Sync a Batch"
method: POST
path: "/api/v1/data-collection/batches/{batch_id}/sync"
tags: ["aiTaskBuilder"]
---

# Sync a Batch

`POST /api/v1/data-collection/batches/{batch_id}/sync`

Triggers an asynchronous sync job that materialises tasks for any datapoints appended to the
batch's attached dataset since it was set up (or since the last sync). Returns immediately
with a `sync_id`; the work is performed by a background worker.

The batch must be in `READY` status and have an attached dataset. Syncs for the same batch are
serialised, so a new sync picks up wherever the previous one left off.

Poll `GET /batches/{batch_id}/syncs/{sync_id}` until the returned job reaches a terminal
status (`complete` or `failed`).

## Path parameters

- `batch_id` string, uuid, required

## Headers

- `Authorization` string, required

## Response `202`

Sync job accepted and queued. The returned job has status `queued`; poll the sync-status
endpoint for progress.

- SyncJob — Tracks the asynchronous materialisation of tasks for datapoints appended to a batch's dataset since setup or the last sync. Created by `POST /batches/{batch_id}/sync`; poll `GET /batches/{batch_id}/syncs/{sync_id}` until a terminal status (`complete` or `failed`). The shape depends on `status`: the fields below marked as terminal-only are present only for the corresponding status.
  - `batch_id` string, uuid, required — The batch this sync job belongs to.
  - `dataset_id` string, uuid, required — The dataset whose appended datapoints are being synced.
  - `sync_id` string, uuid, required — The unique identifier of the sync job.
  - `created_at` string, date-time, required — When the sync job was created (ISO 8601, UTC).
  - `updated_at` string, date-time, required — When the sync job was last updated (ISO 8601, UTC).
  - `status` 'queued' | 'processing' | 'complete' | 'failed', required — Current status of the sync job.
  - `tasks_created` integer — Number of tasks created this sync. Present when status is `complete`.
  - `datapoints_processed` integer — Number of datapoints processed this sync. Present when status is `complete`.
  - `groups_created` integer — Number of new task groups created this sync. Present when status is `complete`.
  - `groups_expanded` integer — Number of existing task groups grown this sync. Non-zero only for predetermined-grouping batches; always `0` for tasks-per-group batches. Present when status is `complete`.
  - `reason` string — Human-readable reason for failure. Present when status is `failed`.

## Other responses

- `400` — Error

---

[API](https://skmtc.net/prolific/apis/api-reference.md) · [All operations](https://skmtc.net/prolific/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prolific/api-reference/versions/5c53371c41a0/schema)