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
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.
Sync id.
Optional request body for triggering a sync run. When omitted or sent as {}, the sync
runs every enabled dataset as an incremental delta.
Controls whether the run is incremental or a full resync.
normalPossible values: Scopes this run to these datasets on the sync. Omit the field to run every enabled dataset; an empty array is rejected. Each id must belong to this sync and be enabled, and subset selection on a normal run is rejected unless the account has partial normal sync enabled.
["6a559b547885d8f93921c2ba","6a559b547885d8f93921c2bb"]Sync run accepted and queued.
Response from POST /v1/syncs/{_syncId}/run. Contains identifiers for the newly queued sync run.
Use syncId with GET /v1/syncs/{_syncId}/syncJobs or flowExecutionGroupId with
GET /v1/syncJobs/{_syncJobId} to poll for run completion.
The sync resource id that was triggered.
682094fa7eb7fc3e7ab7a4a0Correlation id for this execution group. Groups the parent sync job and all child table-level jobs spawned by this run.
6821c01c39db7c2b9cdc0e29Bad request. Invalid runType, invalid datasetIds shape, subset selection on a
normal run when that is not enabled for the account, or datasets that do not
belong to this sync / are disabled.
Error codes: invalid_parameter, invalid_dataset_selection.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Sync not found.
Error code: invalid_ref.
A sync job is already queued or running for this sync.
Error code: sync_job_already_queued.
The sync is disabled and cannot be run.
Error code: invalid_sync.
POST /v1/syncs/{_syncId}/run HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2
{}{
"syncId": "682094fa7eb7fc3e7ab7a4a0",
"flowExecutionGroupId": "6821c01c39db7c2b9cdc0e29"
}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.
Sync id.
Maximum number of jobs to return per page.
100Example: 25Opaque pagination cursor for the next page. Take it from the after value in
the Link response header's rel="next" URL rather than constructing it.
Opaque pagination cursor for the previous page. Take it from the before value in
the Link response header's rel="prev" URL rather than constructing it.
Only return jobs created after this time. Accepts ISO 8601 or epoch milliseconds.
2026-04-01T00:00:00.000ZOnly return jobs created at or before this time. Accepts ISO 8601 or epoch milliseconds.
2026-04-30T23:59:59.000ZPagination phase echoed in Link URLs when a date filter is present. Follow those
URLs as-is rather than setting this yourself.
Page of sync jobs.
Invalid pagination cursor or query parameter.
Error code: invalid_query_param.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Sync not found.
Error code: invalid_ref.
GET /v1/syncs/{_syncId}/syncJobs HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"_id": "6821c01c39db7c2b9cdc0e30",
"flowExecutionGroupId": "6821c01c39db7c2b9cdc0e29",
"_integrationId": "67d7b6e69e4b1371e5d1e2a1",
"_syncId": "682094fa7eb7fc3e7ab7a4a0",
"createdAt": "2026-04-28T14:30:00.000Z",
"startedAt": "2026-04-28T14:30:01.123Z",
"endedAt": "2026-04-28T14:35:12.456Z",
"purgeAt": "2026-07-28T14:35:12.456Z",
"status": "completed",
"numErrors": 0,
"numLoadedRecords": 12450,
"numExtractedRecords": 12450,
"numTablesSynced": 3,
"triggeredBy": "user:tyler.lamparter@celigo.com",
"runType": "normal"
},
{
"_id": "6821b00a39db7c2b9cdc0d10",
"flowExecutionGroupId": "6821b00a39db7c2b9cdc0d09",
"_integrationId": "67d7b6e69e4b1371e5d1e2a1",
"_syncId": "682094fa7eb7fc3e7ab7a4a0",
"createdAt": "2026-04-27T08:00:00.000Z",
"startedAt": "2026-04-27T08:00:02.000Z",
"endedAt": "2026-04-27T08:12:45.000Z",
"purgeAt": "2026-07-27T08:12:45.000Z",
"status": "completed",
"numErrors": 2,
"numLoadedRecords": 11980,
"numExtractedRecords": 11982,
"numTablesSynced": 3,
"triggeredBy": "schedule",
"runType": "resync",
"datasetIds": [
"6a559b547885d8f93921c2ba"
]
}
],
"totalCount": 2
}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.
Sync id.
Parent jobs canceled; no remaining flow jobs to cancel.
Confirmation that there were no remaining flow jobs to cancel.
No more jobs to cancelCancellation accepted. No response body.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
No cancellable jobs found for this sync.
Error code: sync_jobs_not_found.
Cancellation is already in progress for the remaining jobs.
Error code: sync_job_cancellation_in_progress.
PUT /v1/syncs/{_syncId}/syncJobs/cancel HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"message": "No more jobs to cancel"
}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.
Sync job id.
The sync job record.
A sync job represents one execution of a sync. Sync jobs are read-only records
created by the platform when a sync run is triggered (manually or on schedule). The job tracks
extraction, loading, and error counts across all tables in the sync. numTablesSynced reflects
only the tables that actively participated in this run -- for a delta run it may be lower than
the total table count.
Sync job id.
6821c01c39db7c2b9cdc0e30Correlation id grouping this job with its child table jobs.
6821c01c39db7c2b9cdc0e29Integration id this sync belongs to.
67d7b6e69e4b1371e5d1e2a1Sync resource id.
682094fa7eb7fc3e7ab7a4a0When the sync job record was created (queued).
2026-04-28T14:30:00.000ZWhen execution actually began. Absent while the job is still queued.
2026-04-28T14:30:01.123ZWhen execution completed. Absent while the job is still running.
2026-04-28T14:35:12.456ZWhen the job record will be purged from storage.
2026-07-28T14:35:12.456ZCurrent lifecycle state. Cancel is asynchronous: the job stays non-terminal until in-flight work stops.
Total number of errors produced across all tables in this run.
Total number of records loaded (written) to the data warehouse.
12450Total number of records extracted from the source system.
12450Number of tables that were synced in this run.
3Who or what triggered this sync run (e.g. "user:email", "schedule").
user:tyler.lamparter@celigo.comWho requested cancellation. Present once cancellation has been requested.
user:tyler.lamparter@celigo.comWhether this was a normal (delta) or full resync run.
Datasets this run was scoped to. Absent when the run included every enabled dataset.
["6a559b547885d8f93921c2ba","6a559b547885d8f93921c2bb"]Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/syncJobs/{_syncJobId} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"_id": "6821c01c39db7c2b9cdc0e30",
"flowExecutionGroupId": "6821c01c39db7c2b9cdc0e29",
"_integrationId": "67d7b6e69e4b1371e5d1e2a1",
"_syncId": "682094fa7eb7fc3e7ab7a4a0",
"createdAt": "2026-04-28T14:30:00.000Z",
"startedAt": "2026-04-28T14:30:01.123Z",
"endedAt": "2026-04-28T14:35:12.456Z",
"purgeAt": "2026-07-28T14:35:12.456Z",
"status": "completed",
"numErrors": 0,
"numLoadedRecords": 12450,
"numExtractedRecords": 12450,
"numTablesSynced": 3,
"triggeredBy": "user:tyler.lamparter@celigo.com",
"runType": "normal"
}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.
Sync job id (parent job).
Sync job family (parent with per-table children).
A sync job represents one execution of a sync. Sync jobs are read-only records
created by the platform when a sync run is triggered (manually or on schedule). The job tracks
extraction, loading, and error counts across all tables in the sync. numTablesSynced reflects
only the tables that actively participated in this run -- for a delta run it may be lower than
the total table count.
Sync job id.
6821c01c39db7c2b9cdc0e30Correlation id grouping this job with its child table jobs.
6821c01c39db7c2b9cdc0e29Integration id this sync belongs to.
67d7b6e69e4b1371e5d1e2a1Sync resource id.
682094fa7eb7fc3e7ab7a4a0When the sync job record was created (queued).
2026-04-28T14:30:00.000ZWhen execution actually began. Absent while the job is still queued.
2026-04-28T14:30:01.123ZWhen execution completed. Absent while the job is still running.
2026-04-28T14:35:12.456ZWhen the job record will be purged from storage.
2026-07-28T14:35:12.456ZCurrent lifecycle state. Cancel is asynchronous: the job stays non-terminal until in-flight work stops.
Total number of errors produced across all tables in this run.
Total number of records loaded (written) to the data warehouse.
12450Total number of records extracted from the source system.
12450Number of tables that were synced in this run.
3Who or what triggered this sync run (e.g. "user:email", "schedule").
user:tyler.lamparter@celigo.comWho requested cancellation. Present once cancellation has been requested.
user:tyler.lamparter@celigo.comWhether this was a normal (delta) or full resync run.
Datasets this run was scoped to. Absent when the run included every enabled dataset.
["6a559b547885d8f93921c2ba","6a559b547885d8f93921c2bb"]Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/syncJobs/{_syncJobId}/family HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"_id": "6821c01c39db7c2b9cdc0e30",
"flowExecutionGroupId": "6821c01c39db7c2b9cdc0e29",
"_integrationId": "67d7b6e69e4b1371e5d1e2a1",
"_syncId": "682094fa7eb7fc3e7ab7a4a0",
"createdAt": "2026-04-28T14:30:00.000Z",
"startedAt": "2026-04-28T14:30:01.123Z",
"endedAt": "2026-04-28T14:35:12.456Z",
"purgeAt": "2026-07-28T14:35:12.456Z",
"status": "completed",
"numErrors": 0,
"numLoadedRecords": 12450,
"numExtractedRecords": 12450,
"numTablesSynced": 2,
"triggeredBy": "schedule",
"runType": "normal",
"tables": [
{
"_id": "6821c01c39db7c2b9cdc0e31",
"tableName": "contacts",
"createdAt": "2026-04-28T14:30:01.200Z",
"status": "completed",
"numErrors": 0,
"numLoadedRecords": 8200,
"numExtractedRecords": 8200,
"startedAt": "2026-04-28T14:30:01.300Z",
"endedAt": "2026-04-28T14:33:45.100Z"
},
{
"_id": "6821c01c39db7c2b9cdc0e32",
"tableName": "accounts",
"createdAt": "2026-04-28T14:30:01.250Z",
"status": "completed",
"numErrors": 0,
"numLoadedRecords": 4250,
"numExtractedRecords": 4250,
"startedAt": "2026-04-28T14:30:01.350Z",
"endedAt": "2026-04-28T14:35:12.400Z"
}
]
}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.
Parent sync job id.
Child (table-level) job id to filter errors to a single table.
Obtain this from the tables[]._id field in the job family response.
6821c01c39db7c2b9cdc0e31Maximum number of errors to return per page.
100Example: 25Opaque pagination cursor for the next page. Take it from the after value in
the Link response header's rel="next" URL rather than constructing it.
Opaque pagination cursor for the previous page. Take it from the before value in
the Link response header's rel="prev" URL rather than constructing it.
Array of sync error records.
Invalid pagination cursor or query parameter.
Error code: invalid_query_param.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/syncJobs/{_parentJobId}/errors HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"scope": "extract",
"source": "salesforce",
"code": "INVALID_FIELD",
"message": "No such column 'Custom_Field__c' on entity 'Account'.",
"_datasetId": "6821c01c39db7c2b9cdc0e35",
"_syncId": "682094fa7eb7fc3e7ab7a4a0",
"_parentSyncJobId": "6821c01c39db7c2b9cdc0e30",
"_childSyncJobId": "6821c01c39db7c2b9cdc0e31",
"flowExecutionGroupId": "6821c01c39db7c2b9cdc0e29",
"stage": "extraction",
"datasetName": "Salesforce Accounts",
"tableName": "accounts",
"occurredAt": "2026-04-28T14:31:22.789Z"
},
{
"scope": "load",
"source": "snowflake",
"code": "DUPLICATE_KEY",
"message": "Duplicate key value violates unique constraint on 'contacts.email'.",
"_datasetId": "6821c01c39db7c2b9cdc0e36",
"_syncId": "682094fa7eb7fc3e7ab7a4a0",
"_parentSyncJobId": "6821c01c39db7c2b9cdc0e30",
"_childSyncJobId": "6821c01c39db7c2b9cdc0e32",
"flowExecutionGroupId": "6821c01c39db7c2b9cdc0e29",
"stage": "loading",
"datasetName": "Salesforce Contacts",
"tableName": "contacts",
"occurredAt": "2026-04-28T14:32:05.123Z"
}
]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.
Sync job id to cancel.
Parent job canceled; no remaining flow jobs to cancel.
Confirmation that there were no remaining flow jobs to cancel.
No more jobs to cancelCancellation accepted. No response body.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
The sync job is already in a terminal state and cannot be canceled.
Error code: sync_job_not_cancellable.
Not found. The requested resource does not exist or is not visible to the caller.
Cancellation is already in progress for this job.
Error code: sync_job_cancellation_in_progress.
PUT /v1/syncJobs/{_syncJobId}/cancel HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"message": "No more jobs to cancel"
}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.
Integration id.
Array of latest sync jobs (one per sync in the integration).
A sync job represents one execution of a sync. Sync jobs are read-only records
created by the platform when a sync run is triggered (manually or on schedule). The job tracks
extraction, loading, and error counts across all tables in the sync. numTablesSynced reflects
only the tables that actively participated in this run -- for a delta run it may be lower than
the total table count.
Sync job id.
6821c01c39db7c2b9cdc0e30Correlation id grouping this job with its child table jobs.
6821c01c39db7c2b9cdc0e29Integration id this sync belongs to.
67d7b6e69e4b1371e5d1e2a1Sync resource id.
682094fa7eb7fc3e7ab7a4a0When the sync job record was created (queued).
2026-04-28T14:30:00.000ZWhen execution actually began. Absent while the job is still queued.
2026-04-28T14:30:01.123ZWhen execution completed. Absent while the job is still running.
2026-04-28T14:35:12.456ZWhen the job record will be purged from storage.
2026-07-28T14:35:12.456ZCurrent lifecycle state. Cancel is asynchronous: the job stays non-terminal until in-flight work stops.
Total number of errors produced across all tables in this run.
Total number of records loaded (written) to the data warehouse.
12450Total number of records extracted from the source system.
12450Number of tables that were synced in this run.
3Who or what triggered this sync run (e.g. "user:email", "schedule").
user:tyler.lamparter@celigo.comWho requested cancellation. Present once cancellation has been requested.
user:tyler.lamparter@celigo.comWhether this was a normal (delta) or full resync run.
Datasets this run was scoped to. Absent when the run included every enabled dataset.
["6a559b547885d8f93921c2ba","6a559b547885d8f93921c2bb"]No sync jobs exist for any sync in this integration.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Integration not found or not sync-enabled.
Error codes: sync_job_invalid_integration_id (integration exists but has no syncs),
sync_job_missing_integration (integration does not exist).
GET /v1/integrations/{_integrationId}/syncJobs/latest HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"_id": "6821c01c39db7c2b9cdc0e30",
"flowExecutionGroupId": "6821c01c39db7c2b9cdc0e29",
"_integrationId": "67d7b6e69e4b1371e5d1e2a1",
"_syncId": "682094fa7eb7fc3e7ab7a4a0",
"createdAt": "2026-04-28T14:30:00.000Z",
"startedAt": "2026-04-28T14:30:01.123Z",
"endedAt": "2026-04-28T14:35:12.456Z",
"purgeAt": "2026-07-28T14:35:12.456Z",
"status": "completed",
"numErrors": 0,
"numLoadedRecords": 12450,
"numExtractedRecords": 12450,
"numTablesSynced": 3,
"triggeredBy": "schedule",
"runType": "normal"
},
{
"_id": "6821d22e39db7c2b9cdc1050",
"flowExecutionGroupId": "6821d22e39db7c2b9cdc1049",
"_integrationId": "67d7b6e69e4b1371e5d1e2a1",
"_syncId": "682094fb7eb7fc3e7ab7a4b1",
"createdAt": "2026-04-29T02:00:00.000Z",
"startedAt": "2026-04-29T02:00:01.000Z",
"endedAt": "2026-04-29T02:08:33.000Z",
"purgeAt": "2026-07-29T02:08:33.000Z",
"status": "completed",
"numErrors": 1,
"numLoadedRecords": 5600,
"numExtractedRecords": 5601,
"numTablesSynced": 2,
"triggeredBy": "schedule",
"runType": "normal"
}
]Last updated
Was this helpful?