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.
By default the run type is "normal" (incremental delta). Pass runType: "resync" to force a full re-extraction from the source, which drops the delta checkpoint and reloads all data.
Preconditions enforced by the platform:
The sync must not be disabled (
422 invalid_sync).There must not be a job already queued 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
with runType: "normal" (incremental delta). Pass runType: "resync" to force a full re-extraction
from the source system, discarding the current delta checkpoint.
Controls whether the run is incremental or a full resync.
normalPossible values: 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 value.
Error code: invalid_parameter.
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 all sync job records for the given sync, ordered by creation time (most recent first). The response wraps the array in a data field alongside a totalCount.
Note: although the response shape suggests pagination (totalCount), the limit, offset, and status query parameters are silently ignored by the server as of this writing. The endpoint always returns the complete list of jobs.
Sync id.
List of sync jobs.
Paginated list of sync jobs for a given sync. Contains the array of job records and a total count.
Note: although the response includes totalCount, the limit and offset query parameters
on the list endpoint are silently ignored by the server as of this writing. The response always
returns all jobs.
Total number of sync jobs for this sync (across all pages).
1Unauthorized. 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": "normal"
}
],
"totalCount": 2
}Cancels all currently running or queued sync jobs for the given sync. This is a bulk cancel that affects every in-progress job associated with the sync.
If there are no cancellable jobs (all jobs are already in a terminal state), the request is rejected. To cancel a single specific job instead, use PUT /v1/syncJobs/{_syncJobId}/cancel.
Sync id.
All running sync jobs have been canceled. No response body.
No content
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.
PUT /v1/syncs/{_syncId}/syncJobs/cancel HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
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. Jobs start as queued when a run is accepted, move to
running once a worker picks them up, and end as completed, failed, or
canceled.
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 or what canceled this run. Only present when status is canceled.
user:tyler.lamparter@celigo.comWhether this was a normal (delta) or full resync run.
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. Jobs start as queued when a run is accepted, move to
running once a worker picks them up, and end as completed, failed, or
canceled.
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 or what canceled this run. Only present when status is canceled.
user:tyler.lamparter@celigo.comWhether this was a normal (delta) or full resync run.
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 an array of error records for the given parent sync job. Errors are produced during extraction or loading and are scoped to individual tables.
The response includes an x-total-count header with the total number of errors (useful when filtering by child job).
Use the _childJobId query parameter to filter errors to a single table's child job. 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. Each error also carries a tableName field for client-side grouping. The response is a bare array, not wrapped in a data envelope.
Parent sync job id.
Optional child (table-level) job id to filter errors to a single table.
Obtain this from the tables[]._id field in the job family response.
6821c01c39db7c2b9cdc0e31Array of sync error records.
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.
Only jobs that are still in progress (running) can be canceled. Jobs already in a terminal state (completed, failed, canceled) cannot be canceled. To cancel all running jobs for a sync at once, use PUT /v1/syncs/{_syncId}/syncJobs/cancel instead.
Sync job id to cancel.
Sync job canceled successfully. No response body.
No content
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.
PUT /v1/syncJobs/{_syncJobId}/cancel HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
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. Jobs start as queued when a run is accepted, move to
running once a worker picks them up, and end as completed, failed, or
canceled.
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 or what canceled this run. Only present when status is canceled.
user:tyler.lamparter@celigo.comWhether this was a normal (delta) or full resync run.
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?