> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/api/api-reference/sync-jobs.md).

# Sync Jobs

Every sync run produces a read-only sync job that tracks extraction, loading, and error counts across the sync's tables. Use these endpoints to trigger runs, monitor job progress and per-table families, retrieve run errors, and cancel in-flight jobs.

### Sync job schema

## The SyncJob object

```json
{"openapi":"3.2.0","info":{"title":"Syncs","version":"1.0.0"},"components":{"schemas":{"SyncJob":{"type":"object","required":["_id","_syncId","_integrationId","status","runType","createdAt"],"description":"A sync job represents one execution of a sync. Sync jobs are read-only records\ncreated by the platform when a sync run is triggered (manually or on schedule). The job tracks\nextraction, loading, and error counts across all tables in the sync. `numTablesSynced` reflects\nonly the tables that actively participated in this run -- for a delta run it may be lower than\nthe total table count.","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Sync job id."},"flowExecutionGroupId":{"type":"string","readOnly":true,"description":"Correlation id grouping this job with its child table jobs."},"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration id this sync belongs to."},"_syncId":{"type":"string","format":"objectId","readOnly":true,"description":"Sync resource id."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the sync job record was created (queued)."},"startedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When execution actually began. Absent while the job is still queued."},"endedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When execution completed. Absent while the job is still running."},"purgeAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the job record will be purged from storage."},"status":{"type":"string","readOnly":true,"description":"Current lifecycle state. Cancel is asynchronous: the job stays non-terminal\nuntil in-flight work stops.","enum":["queued","running","canceling","completed","failed","canceled"]},"numErrors":{"type":"integer","readOnly":true,"description":"Total number of errors produced across all tables in this run."},"numLoadedRecords":{"type":"integer","readOnly":true,"description":"Total number of records loaded (written) to the data warehouse."},"numExtractedRecords":{"type":"integer","readOnly":true,"description":"Total number of records extracted from the source system."},"numTablesSynced":{"type":"integer","readOnly":true,"description":"Number of tables that were synced in this run."},"triggeredBy":{"type":"string","readOnly":true,"description":"Who or what triggered this sync run (e.g. `\"user:email\"`, `\"schedule\"`)."},"canceledBy":{"type":"string","readOnly":true,"description":"Who requested cancellation. Present once cancellation has been requested."},"runType":{"type":"string","readOnly":true,"description":"Whether this was a normal (delta) or full resync run.","enum":["normal","resync"]},"datasetIds":{"type":"array","readOnly":true,"description":"Datasets this run was scoped to. Absent when the run included every enabled dataset.","items":{"type":"string","format":"objectId"}}}}}}}
```

## Trigger a sync run

> Queues an on-demand run of a sync and returns identifiers for the new sync job. The\
> run is \*\*asynchronous\*\*: the response returns as soon as the job is queued. Use\
> \`GET /v1/syncJobs/{\_syncJobId}\` or \`GET /v1/syncs/{\_syncId}/syncJobs\` to poll for terminal status.\
> \
> A resync drops the delta checkpoint and reloads all data. Subset selection on a resync\
> is always accepted; on a normal run it is rejected unless the account has partial\
> normal sync enabled.\
> \
> Preconditions enforced by the platform:\
> \- The sync must not be disabled (\`422 invalid\_sync\`).\
> \- There must not be a job already queued or running for this sync (\`409 sync\_job\_already\_queued\`).\
> \
> The returned \`flowExecutionGroupId\` is a correlation key across jobs and errors. For\
> multi-table syncs, a single run creates one parent job with per-table children visible via\
> \`GET /v1/syncJobs/{\_syncJobId}/family\`.

```json
{"openapi":"3.2.0","info":{"title":"Syncs","version":"1.0.0"},"tags":[{"name":"Sync Jobs","description":"Every sync run produces a read-only sync job that tracks extraction, loading, and\nerror counts across the sync's tables. Use these endpoints to trigger runs,\nmonitor job progress and per-table families, retrieve run errors, and cancel\nin-flight jobs.\n\n## Sync job schema\n\n{% openapi-schemas spec=\"sync\" schemas=\"SyncJob\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SyncRunRequest":{"type":"object","description":"Optional request body for triggering a sync run. When omitted or sent as `{}`, the sync\nruns every enabled dataset as an incremental delta.","properties":{"runType":{"type":"string","description":"Controls whether the run is incremental or a full resync.","enum":["normal","resync"],"default":"normal"},"datasetIds":{"type":"array","minItems":1,"description":"Scopes this run to these datasets on the sync. Omit the field to run every\nenabled dataset; an empty array is rejected. Each id must belong to this sync\nand be enabled, and subset selection on a normal run is rejected unless the\naccount has partial normal sync enabled.","items":{"type":"string","format":"objectId"}}}},"SyncRunResponse":{"type":"object","description":"Response from `POST /v1/syncs/{_syncId}/run`. Contains identifiers for the newly queued sync run.\nUse `syncId` with `GET /v1/syncs/{_syncId}/syncJobs` or `flowExecutionGroupId` with\n`GET /v1/syncJobs/{_syncJobId}` to poll for run completion.","properties":{"syncId":{"type":"string","format":"objectId","readOnly":true,"description":"The sync resource id that was triggered."},"flowExecutionGroupId":{"type":"string","readOnly":true,"description":"Correlation id for this execution group. Groups the parent sync job and all child\ntable-level jobs spawned by this run."}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/syncs/{_syncId}/run":{"post":{"operationId":"runSync","tags":["Sync Jobs"],"summary":"Trigger a sync run","description":"Queues an on-demand run of a sync and returns identifiers for the new sync job. The\nrun is **asynchronous**: the response returns as soon as the job is queued. Use\n`GET /v1/syncJobs/{_syncJobId}` or `GET /v1/syncs/{_syncId}/syncJobs` to poll for terminal status.\n\nA resync drops the delta checkpoint and reloads all data. Subset selection on a resync\nis always accepted; on a normal run it is rejected unless the account has partial\nnormal sync enabled.\n\nPreconditions enforced by the platform:\n- The sync must not be disabled (`422 invalid_sync`).\n- There must not be a job already queued or running for this sync (`409 sync_job_already_queued`).\n\nThe returned `flowExecutionGroupId` is a correlation key across jobs and errors. For\nmulti-table syncs, a single run creates one parent job with per-table children visible via\n`GET /v1/syncJobs/{_syncJobId}/family`.","parameters":[{"name":"_syncId","in":"path","required":true,"description":"Sync id.","schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncRunRequest"}}}},"responses":{"200":{"description":"Sync run accepted and queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncRunResponse"}}}},"400":{"description":"Bad request. Invalid `runType`, invalid `datasetIds` shape, subset selection on a\nnormal run when that is not enabled for the account, or datasets that do not\nbelong to this sync / are disabled.\nError codes: `invalid_parameter`, `invalid_dataset_selection`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"Sync not found.\nError code: `invalid_ref`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A sync job is already queued or running for this sync.\nError code: `sync_job_already_queued`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The sync is disabled and cannot be run.\nError code: `invalid_sync`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## List sync jobs for a sync

> Returns parent sync jobs for the given sync, newest first. When a created-at filter is\
> set, \`queued\` and \`running\` jobs are pinned to the first pages even if they fall outside\
> the range; \`canceling\` jobs are not pinned. Follow \`Link\` header URLs as-is to page\
> through pinned jobs and then the date-filtered remainder.

```json
{"openapi":"3.2.0","info":{"title":"Syncs","version":"1.0.0"},"tags":[{"name":"Sync Jobs","description":"Every sync run produces a read-only sync job that tracks extraction, loading, and\nerror counts across the sync's tables. Use these endpoints to trigger runs,\nmonitor job progress and per-table families, retrieve run errors, and cancel\nin-flight jobs.\n\n## Sync job schema\n\n{% openapi-schemas spec=\"sync\" schemas=\"SyncJob\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SyncJobsResponse":{"type":"object","description":"One page of sync jobs for a given sync, plus the total number of jobs matching the query.","properties":{"data":{"type":"array","description":"Sync job records for this page, newest first.","items":{"$ref":"#/components/schemas/SyncJob"}},"totalCount":{"type":"integer","readOnly":true,"description":"Total number of sync jobs matching the query, including queued and running jobs pinned outside a date filter."}}},"SyncJob":{"type":"object","required":["_id","_syncId","_integrationId","status","runType","createdAt"],"description":"A sync job represents one execution of a sync. Sync jobs are read-only records\ncreated by the platform when a sync run is triggered (manually or on schedule). The job tracks\nextraction, loading, and error counts across all tables in the sync. `numTablesSynced` reflects\nonly the tables that actively participated in this run -- for a delta run it may be lower than\nthe total table count.","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Sync job id."},"flowExecutionGroupId":{"type":"string","readOnly":true,"description":"Correlation id grouping this job with its child table jobs."},"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration id this sync belongs to."},"_syncId":{"type":"string","format":"objectId","readOnly":true,"description":"Sync resource id."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the sync job record was created (queued)."},"startedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When execution actually began. Absent while the job is still queued."},"endedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When execution completed. Absent while the job is still running."},"purgeAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the job record will be purged from storage."},"status":{"type":"string","readOnly":true,"description":"Current lifecycle state. Cancel is asynchronous: the job stays non-terminal\nuntil in-flight work stops.","enum":["queued","running","canceling","completed","failed","canceled"]},"numErrors":{"type":"integer","readOnly":true,"description":"Total number of errors produced across all tables in this run."},"numLoadedRecords":{"type":"integer","readOnly":true,"description":"Total number of records loaded (written) to the data warehouse."},"numExtractedRecords":{"type":"integer","readOnly":true,"description":"Total number of records extracted from the source system."},"numTablesSynced":{"type":"integer","readOnly":true,"description":"Number of tables that were synced in this run."},"triggeredBy":{"type":"string","readOnly":true,"description":"Who or what triggered this sync run (e.g. `\"user:email\"`, `\"schedule\"`)."},"canceledBy":{"type":"string","readOnly":true,"description":"Who requested cancellation. Present once cancellation has been requested."},"runType":{"type":"string","readOnly":true,"description":"Whether this was a normal (delta) or full resync run.","enum":["normal","resync"]},"datasetIds":{"type":"array","readOnly":true,"description":"Datasets this run was scoped to. Absent when the run included every enabled dataset.","items":{"type":"string","format":"objectId"}}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/syncs/{_syncId}/syncJobs":{"get":{"operationId":"listSyncJobs","tags":["Sync Jobs"],"summary":"List sync jobs for a sync","description":"Returns parent sync jobs for the given sync, newest first. When a created-at filter is\nset, `queued` and `running` jobs are pinned to the first pages even if they fall outside\nthe range; `canceling` jobs are not pinned. Follow `Link` header URLs as-is to page\nthrough pinned jobs and then the date-filtered remainder.","parameters":[{"name":"_syncId","in":"path","required":true,"description":"Sync id.","schema":{"type":"string","format":"objectId"}},{"name":"pageSize","in":"query","required":false,"description":"Maximum number of jobs to return per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"after","in":"query","required":false,"description":"Opaque pagination cursor for the next page. Take it from the `after` value in\nthe `Link` response header's `rel=\"next\"` URL rather than constructing it.","schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"Opaque pagination cursor for the previous page. Take it from the `before` value in\nthe `Link` response header's `rel=\"prev\"` URL rather than constructing it.","schema":{"type":"string"}},{"name":"createdAt_gt","in":"query","required":false,"description":"Only return jobs created after this time. Accepts ISO 8601 or epoch milliseconds.","schema":{"type":"string"}},{"name":"createdAt_lte","in":"query","required":false,"description":"Only return jobs created at or before this time. Accepts ISO 8601 or epoch milliseconds.","schema":{"type":"string"}},{"name":"listPhase","in":"query","required":false,"description":"Pagination phase echoed in `Link` URLs when a date filter is present. Follow those\nURLs as-is rather than setting this yourself.","schema":{"type":"string","enum":["pinned","historical"]}}],"responses":{"200":{"description":"Page of sync jobs.","headers":{"Link":{"description":"RFC 5988 pagination links. Includes `<...>; rel=\"next\"` and/or\n`<...>; rel=\"prev\"` when more pages remain; absent on a single page.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJobsResponse"}}}},"400":{"description":"Invalid pagination cursor or query parameter.\nError code: `invalid_query_param`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"Sync not found.\nError code: `invalid_ref`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Cancel all in-progress sync jobs

> Cancels every queued or running sync job for the given sync, including the underlying\
> flow jobs for each run.\
> \
> If every job is already terminal, the request is rejected. If parent jobs are canceled\
> but no flow jobs remain, the response includes a confirmation message instead of an\
> empty success. A job whose cancellation is already in progress is not cancelled again.\
> To cancel a single specific job instead, use \`PUT /v1/syncJobs/{\_syncJobId}/cancel\`.

```json
{"openapi":"3.2.0","info":{"title":"Syncs","version":"1.0.0"},"tags":[{"name":"Sync Jobs","description":"Every sync run produces a read-only sync job that tracks extraction, loading, and\nerror counts across the sync's tables. Use these endpoints to trigger runs,\nmonitor job progress and per-table families, retrieve run errors, and cancel\nin-flight jobs.\n\n## Sync job schema\n\n{% openapi-schemas spec=\"sync\" schemas=\"SyncJob\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/syncs/{_syncId}/syncJobs/cancel":{"put":{"operationId":"cancelSyncJobs","tags":["Sync Jobs"],"summary":"Cancel all in-progress sync jobs","description":"Cancels every queued or running sync job for the given sync, including the underlying\nflow jobs for each run.\n\nIf every job is already terminal, the request is rejected. If parent jobs are canceled\nbut no flow jobs remain, the response includes a confirmation message instead of an\nempty success. A job whose cancellation is already in progress is not cancelled again.\nTo cancel a single specific job instead, use `PUT /v1/syncJobs/{_syncJobId}/cancel`.","parameters":[{"name":"_syncId","in":"path","required":true,"description":"Sync id.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Parent jobs canceled; no remaining flow jobs to cancel.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Confirmation that there were no remaining flow jobs to cancel."}}}}}},"204":{"description":"Cancellation accepted. No response body."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"No cancellable jobs found for this sync.\nError code: `sync_jobs_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cancellation is already in progress for the remaining jobs.\nError code: `sync_job_cancellation_in_progress`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get a sync job

> Returns a single sync job record. Sync jobs are read-only records created by the platform when\
> a sync run is triggered. The record includes status, timing, record counts, and error counts.\
> A gap between \`numExtractedRecords\` and \`numLoadedRecords\` indicates records that failed\
> during loading -- see \`numErrors\`.

```json
{"openapi":"3.2.0","info":{"title":"Syncs","version":"1.0.0"},"tags":[{"name":"Sync Jobs","description":"Every sync run produces a read-only sync job that tracks extraction, loading, and\nerror counts across the sync's tables. Use these endpoints to trigger runs,\nmonitor job progress and per-table families, retrieve run errors, and cancel\nin-flight jobs.\n\n## Sync job schema\n\n{% openapi-schemas spec=\"sync\" schemas=\"SyncJob\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SyncJob":{"type":"object","required":["_id","_syncId","_integrationId","status","runType","createdAt"],"description":"A sync job represents one execution of a sync. Sync jobs are read-only records\ncreated by the platform when a sync run is triggered (manually or on schedule). The job tracks\nextraction, loading, and error counts across all tables in the sync. `numTablesSynced` reflects\nonly the tables that actively participated in this run -- for a delta run it may be lower than\nthe total table count.","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Sync job id."},"flowExecutionGroupId":{"type":"string","readOnly":true,"description":"Correlation id grouping this job with its child table jobs."},"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration id this sync belongs to."},"_syncId":{"type":"string","format":"objectId","readOnly":true,"description":"Sync resource id."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the sync job record was created (queued)."},"startedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When execution actually began. Absent while the job is still queued."},"endedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When execution completed. Absent while the job is still running."},"purgeAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the job record will be purged from storage."},"status":{"type":"string","readOnly":true,"description":"Current lifecycle state. Cancel is asynchronous: the job stays non-terminal\nuntil in-flight work stops.","enum":["queued","running","canceling","completed","failed","canceled"]},"numErrors":{"type":"integer","readOnly":true,"description":"Total number of errors produced across all tables in this run."},"numLoadedRecords":{"type":"integer","readOnly":true,"description":"Total number of records loaded (written) to the data warehouse."},"numExtractedRecords":{"type":"integer","readOnly":true,"description":"Total number of records extracted from the source system."},"numTablesSynced":{"type":"integer","readOnly":true,"description":"Number of tables that were synced in this run."},"triggeredBy":{"type":"string","readOnly":true,"description":"Who or what triggered this sync run (e.g. `\"user:email\"`, `\"schedule\"`)."},"canceledBy":{"type":"string","readOnly":true,"description":"Who requested cancellation. Present once cancellation has been requested."},"runType":{"type":"string","readOnly":true,"description":"Whether this was a normal (delta) or full resync run.","enum":["normal","resync"]},"datasetIds":{"type":"array","readOnly":true,"description":"Datasets this run was scoped to. Absent when the run included every enabled dataset.","items":{"type":"string","format":"objectId"}}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/syncJobs/{_syncJobId}":{"get":{"operationId":"getSyncJobById","tags":["Sync Jobs"],"summary":"Get a sync job","description":"Returns a single sync job record. Sync jobs are read-only records created by the platform when\na sync run is triggered. The record includes status, timing, record counts, and error counts.\nA gap between `numExtractedRecords` and `numLoadedRecords` indicates records that failed\nduring loading -- see `numErrors`.","parameters":[{"name":"_syncJobId","in":"path","required":true,"description":"Sync job id.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"The sync job record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJob"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Get a sync job and its table-level children

> Returns the parent sync job with all of its per-table child jobs inlined under a \`tables\` array.\
> Each table entry contains its own status, record counts, error counts, and timing.\
> \
> A sync job family maps to one sync execution: the parent is the overall sync job and the children\
> represent each table that was synced as part of that run. Parent-level counters are the\
> authoritative totals; \`tables\[]\` provides the per-table breakdown. \`tables\` may be empty if\
> the job was canceled before any table work started.

```json
{"openapi":"3.2.0","info":{"title":"Syncs","version":"1.0.0"},"tags":[{"name":"Sync Jobs","description":"Every sync run produces a read-only sync job that tracks extraction, loading, and\nerror counts across the sync's tables. Use these endpoints to trigger runs,\nmonitor job progress and per-table families, retrieve run errors, and cancel\nin-flight jobs.\n\n## Sync job schema\n\n{% openapi-schemas spec=\"sync\" schemas=\"SyncJob\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SyncJobFamily":{"type":"object","description":"A sync job family consisting of the parent sync job and its per-table child jobs. Each entry in\n`tables` represents one table that was synced as part of this run, with its own status, record\ncounts, and timing. The parent-level counters are the authoritative totals; `tables[]` provides\nthe per-table breakdown. `tables` may be empty if the job was canceled before any table work\nstarted.","allOf":[{"$ref":"#/components/schemas/SyncJob"},{"type":"object","properties":{"tables":{"type":"array","description":"Per-table child job records for this sync run.","items":{"$ref":"#/components/schemas/SyncTableJob"}}}}]},"SyncJob":{"type":"object","required":["_id","_syncId","_integrationId","status","runType","createdAt"],"description":"A sync job represents one execution of a sync. Sync jobs are read-only records\ncreated by the platform when a sync run is triggered (manually or on schedule). The job tracks\nextraction, loading, and error counts across all tables in the sync. `numTablesSynced` reflects\nonly the tables that actively participated in this run -- for a delta run it may be lower than\nthe total table count.","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Sync job id."},"flowExecutionGroupId":{"type":"string","readOnly":true,"description":"Correlation id grouping this job with its child table jobs."},"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration id this sync belongs to."},"_syncId":{"type":"string","format":"objectId","readOnly":true,"description":"Sync resource id."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the sync job record was created (queued)."},"startedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When execution actually began. Absent while the job is still queued."},"endedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When execution completed. Absent while the job is still running."},"purgeAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the job record will be purged from storage."},"status":{"type":"string","readOnly":true,"description":"Current lifecycle state. Cancel is asynchronous: the job stays non-terminal\nuntil in-flight work stops.","enum":["queued","running","canceling","completed","failed","canceled"]},"numErrors":{"type":"integer","readOnly":true,"description":"Total number of errors produced across all tables in this run."},"numLoadedRecords":{"type":"integer","readOnly":true,"description":"Total number of records loaded (written) to the data warehouse."},"numExtractedRecords":{"type":"integer","readOnly":true,"description":"Total number of records extracted from the source system."},"numTablesSynced":{"type":"integer","readOnly":true,"description":"Number of tables that were synced in this run."},"triggeredBy":{"type":"string","readOnly":true,"description":"Who or what triggered this sync run (e.g. `\"user:email\"`, `\"schedule\"`)."},"canceledBy":{"type":"string","readOnly":true,"description":"Who requested cancellation. Present once cancellation has been requested."},"runType":{"type":"string","readOnly":true,"description":"Whether this was a normal (delta) or full resync run.","enum":["normal","resync"]},"datasetIds":{"type":"array","readOnly":true,"description":"Datasets this run was scoped to. Absent when the run included every enabled dataset.","items":{"type":"string","format":"objectId"}}}},"SyncTableJob":{"type":"object","description":"A child job representing one table's extraction and load within a parent sync run. Each table\njob tracks its own record counts, error counts, and timing independently.","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Child table job id."},"tableName":{"type":"string","readOnly":true,"description":"Name of the table being synced (e.g. `\"contacts\"`, `\"orders\"`)."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"When this child job was created."},"status":{"type":"string","readOnly":true,"description":"Current lifecycle state of this table's sync. Table jobs start as `queued`, move\nto `running` when extraction begins, and end as `completed`, `failed`, or\n`canceled`.","enum":["queued","running","completed","failed","canceled"]},"numErrors":{"type":"integer","readOnly":true,"description":"Number of errors encountered syncing this table."},"numLoadedRecords":{"type":"integer","readOnly":true,"description":"Number of records loaded into the warehouse for this table."},"numExtractedRecords":{"type":"integer","readOnly":true,"description":"Number of records extracted from the source for this table."},"isNormalizedTable":{"type":"boolean","readOnly":true,"description":"When true, this table is a normalized child table split out from\nnested data in the source dataset rather than a source table itself.\nPresent only when true — omitted from the response when false."},"startedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When extraction began for this table. Absent if not yet started."},"endedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When loading completed for this table. Absent if still running."}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/syncJobs/{_syncJobId}/family":{"get":{"operationId":"getSyncJobFamily","tags":["Sync Jobs"],"summary":"Get a sync job and its table-level children","description":"Returns the parent sync job with all of its per-table child jobs inlined under a `tables` array.\nEach table entry contains its own status, record counts, error counts, and timing.\n\nA sync job family maps to one sync execution: the parent is the overall sync job and the children\nrepresent each table that was synced as part of that run. Parent-level counters are the\nauthoritative totals; `tables[]` provides the per-table breakdown. `tables` may be empty if\nthe job was canceled before any table work started.","parameters":[{"name":"_syncJobId","in":"path","required":true,"description":"Sync job id (parent job).","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Sync job family (parent with per-table children).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncJobFamily"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## List errors for a sync job

> Returns errors produced during extraction or loading for the given parent sync job,\
> scoped to individual tables.\
> \
> Use \`\_childJobId\` to filter to a single table. Without it, errors across all tables\
> in the run are returned. To find a child job id, call\
> \`GET /v1/syncJobs/{\_syncJobId}/family\` and read \`tables\[].\_id\`.

```json
{"openapi":"3.2.0","info":{"title":"Syncs","version":"1.0.0"},"tags":[{"name":"Sync Jobs","description":"Every sync run produces a read-only sync job that tracks extraction, loading, and\nerror counts across the sync's tables. Use these endpoints to trigger runs,\nmonitor job progress and per-table families, retrieve run errors, and cancel\nin-flight jobs.\n\n## Sync job schema\n\n{% openapi-schemas spec=\"sync\" schemas=\"SyncJob\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SyncError":{"type":"object","description":"An individual error record from a sync run. Errors are scoped to a specific table (identified by\n`tableName` and `_datasetId`) within a sync execution. `_parentSyncJobId` links to the parent\nsync job and `_childSyncJobId` links to the table-level child.","properties":{"scope":{"type":"string","readOnly":true,"description":"Pipeline scope where the error occurred (e.g. `\"extract\"`, `\"load\"`)."},"source":{"type":"string","readOnly":true,"description":"System or component that produced the error."},"code":{"type":"string","readOnly":true,"description":"Machine-readable error code."},"message":{"type":"string","readOnly":true,"description":"Human-readable error message."},"_datasetId":{"type":"string","format":"objectId","readOnly":true,"description":"Dataset id associated with this error."},"_syncId":{"type":"string","format":"objectId","readOnly":true,"description":"Sync resource id."},"_parentSyncJobId":{"type":"string","format":"objectId","readOnly":true,"description":"Parent sync job id."},"_childSyncJobId":{"type":"string","format":"objectId","readOnly":true,"description":"Child (table-level) sync job id."},"flowExecutionGroupId":{"type":"string","readOnly":true,"description":"Correlation id for the execution group."},"stage":{"type":"string","readOnly":true,"description":"Pipeline stage where the error occurred."},"datasetName":{"type":"string","readOnly":true,"description":"Human-readable dataset name."},"tableName":{"type":"string","readOnly":true,"description":"Table name where the error occurred."},"occurredAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the error occurred."}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/syncJobs/{_parentJobId}/errors":{"get":{"operationId":"listSyncJobErrors","tags":["Sync Jobs"],"summary":"List errors for a sync job","description":"Returns errors produced during extraction or loading for the given parent sync job,\nscoped to individual tables.\n\nUse `_childJobId` to filter to a single table. Without it, errors across all tables\nin the run are returned. To find a child job id, call\n`GET /v1/syncJobs/{_syncJobId}/family` and read `tables[]._id`.","parameters":[{"name":"_parentJobId","in":"path","required":true,"description":"Parent sync job id.","schema":{"type":"string","format":"objectId"}},{"name":"_childJobId","in":"query","required":false,"description":"Child (table-level) job id to filter errors to a single table.\nObtain this from the `tables[]._id` field in the job family response.","schema":{"type":"string","format":"objectId"}},{"name":"pageSize","in":"query","required":false,"description":"Maximum number of errors to return per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"after","in":"query","required":false,"description":"Opaque pagination cursor for the next page. Take it from the `after` value in\nthe `Link` response header's `rel=\"next\"` URL rather than constructing it.","schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"Opaque pagination cursor for the previous page. Take it from the `before` value in\nthe `Link` response header's `rel=\"prev\"` URL rather than constructing it.","schema":{"type":"string"}}],"responses":{"200":{"description":"Array of sync error records.","headers":{"X-Total-Count":{"description":"Total number of errors matching the query, ignoring the current page.","schema":{"type":"integer"}},"Link":{"description":"RFC 5988 pagination links. Includes `<...>; rel=\"next\"` and/or\n`<...>; rel=\"prev\"` when more pages remain; absent on a single page.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SyncError"}}}}},"400":{"description":"Invalid pagination cursor or query parameter.\nError code: `invalid_query_param`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Cancel a single sync job

> Cancels a specific sync job by id, including its underlying flow jobs.\
> \
> Only queued or running jobs can be canceled. Terminal jobs cannot. A job whose\
> cancellation is already in progress is not cancelled again. If the parent is canceled\
> but no flow jobs remain, the response includes a confirmation message instead of an\
> empty success. To cancel all in-progress jobs for a sync at once, use\
> \`PUT /v1/syncs/{\_syncId}/syncJobs/cancel\`.

```json
{"openapi":"3.2.0","info":{"title":"Syncs","version":"1.0.0"},"tags":[{"name":"Sync Jobs","description":"Every sync run produces a read-only sync job that tracks extraction, loading, and\nerror counts across the sync's tables. Use these endpoints to trigger runs,\nmonitor job progress and per-table families, retrieve run errors, and cancel\nin-flight jobs.\n\n## Sync job schema\n\n{% openapi-schemas spec=\"sync\" schemas=\"SyncJob\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/syncJobs/{_syncJobId}/cancel":{"put":{"operationId":"cancelSyncJob","tags":["Sync Jobs"],"summary":"Cancel a single sync job","description":"Cancels a specific sync job by id, including its underlying flow jobs.\n\nOnly queued or running jobs can be canceled. Terminal jobs cannot. A job whose\ncancellation is already in progress is not cancelled again. If the parent is canceled\nbut no flow jobs remain, the response includes a confirmation message instead of an\nempty success. To cancel all in-progress jobs for a sync at once, use\n`PUT /v1/syncs/{_syncId}/syncJobs/cancel`.","parameters":[{"name":"_syncJobId","in":"path","required":true,"description":"Sync job id to cancel.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Parent job canceled; no remaining flow jobs to cancel.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Confirmation that there were no remaining flow jobs to cancel."}}}}}},"204":{"description":"Cancellation accepted. No response body."},"401":{"$ref":"#/components/responses/401-unauthorized"},"403":{"description":"The sync job is already in a terminal state and cannot be canceled.\nError code: `sync_job_not_cancellable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/404-not-found"},"409":{"description":"Cancellation is already in progress for this job.\nError code: `sync_job_cancellation_in_progress`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get the latest sync job for each sync in an integration

> Returns the most recent sync job for each sync resource belonging to the given integration.\
> The response is a bare JSON array with one \`SyncJob\` entry per sync.\
> \
> Returns an empty response when no sync jobs exist for any sync in the integration. Each entry\
> in the array represents the latest run of a different sync; use \`\_syncId\` on each returned job\
> to correlate back to the sync resource. The response is a bare array, not wrapped in a \`data\`\
> envelope.

```json
{"openapi":"3.2.0","info":{"title":"Syncs","version":"1.0.0"},"tags":[{"name":"Sync Jobs","description":"Every sync run produces a read-only sync job that tracks extraction, loading, and\nerror counts across the sync's tables. Use these endpoints to trigger runs,\nmonitor job progress and per-table families, retrieve run errors, and cancel\nin-flight jobs.\n\n## Sync job schema\n\n{% openapi-schemas spec=\"sync\" schemas=\"SyncJob\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SyncJob":{"type":"object","required":["_id","_syncId","_integrationId","status","runType","createdAt"],"description":"A sync job represents one execution of a sync. Sync jobs are read-only records\ncreated by the platform when a sync run is triggered (manually or on schedule). The job tracks\nextraction, loading, and error counts across all tables in the sync. `numTablesSynced` reflects\nonly the tables that actively participated in this run -- for a delta run it may be lower than\nthe total table count.","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Sync job id."},"flowExecutionGroupId":{"type":"string","readOnly":true,"description":"Correlation id grouping this job with its child table jobs."},"_integrationId":{"type":"string","format":"objectId","readOnly":true,"description":"Integration id this sync belongs to."},"_syncId":{"type":"string","format":"objectId","readOnly":true,"description":"Sync resource id."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the sync job record was created (queued)."},"startedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When execution actually began. Absent while the job is still queued."},"endedAt":{"type":"string","format":"date-time","readOnly":true,"description":"When execution completed. Absent while the job is still running."},"purgeAt":{"type":"string","format":"date-time","readOnly":true,"description":"When the job record will be purged from storage."},"status":{"type":"string","readOnly":true,"description":"Current lifecycle state. Cancel is asynchronous: the job stays non-terminal\nuntil in-flight work stops.","enum":["queued","running","canceling","completed","failed","canceled"]},"numErrors":{"type":"integer","readOnly":true,"description":"Total number of errors produced across all tables in this run."},"numLoadedRecords":{"type":"integer","readOnly":true,"description":"Total number of records loaded (written) to the data warehouse."},"numExtractedRecords":{"type":"integer","readOnly":true,"description":"Total number of records extracted from the source system."},"numTablesSynced":{"type":"integer","readOnly":true,"description":"Number of tables that were synced in this run."},"triggeredBy":{"type":"string","readOnly":true,"description":"Who or what triggered this sync run (e.g. `\"user:email\"`, `\"schedule\"`)."},"canceledBy":{"type":"string","readOnly":true,"description":"Who requested cancellation. Present once cancellation has been requested."},"runType":{"type":"string","readOnly":true,"description":"Whether this was a normal (delta) or full resync run.","enum":["normal","resync"]},"datasetIds":{"type":"array","readOnly":true,"description":"Datasets this run was scoped to. Absent when the run included every enabled dataset.","items":{"type":"string","format":"objectId"}}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/integrations/{_integrationId}/syncJobs/latest":{"get":{"operationId":"getLatestSyncJobsForIntegration","tags":["Sync Jobs"],"summary":"Get the latest sync job for each sync in an integration","description":"Returns the most recent sync job for each sync resource belonging to the given integration.\nThe response is a bare JSON array with one `SyncJob` entry per sync.\n\nReturns an empty response when no sync jobs exist for any sync in the integration. Each entry\nin the array represents the latest run of a different sync; use `_syncId` on each returned job\nto correlate back to the sync resource. The response is a bare array, not wrapped in a `data`\nenvelope.","parameters":[{"name":"_integrationId","in":"path","required":true,"description":"Integration id.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Array of latest sync jobs (one per sync in the integration).","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SyncJob"}}}}},"204":{"description":"No sync jobs exist for any sync in this integration."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"Integration not found or not sync-enabled.\nError codes: `sync_job_invalid_integration_id` (integration exists but has no syncs),\n`sync_job_missing_integration` (integration does not exist).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/api/api-reference/sync-jobs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.