Run Sync

Trigger a data synchronization job for a source connection

POST /v1/source-connections/{id}/run

Run Sync

cURL

curl --request POST \
  --url https://api.example.com/v1/source-connections/{id}/run

200

{
  "id": "<string>",
  "source_connection_id": "<string>",
  "status": "<string>",
  "started_at": "<string>",
  "completed_at": "<string>",
  "duration_seconds": 123,
  "entities_inserted": 123,
  "entities_updated": 123,
  "entities_deleted": 123,
  "entities_failed": 123,
  "error": "<string>"
}

Overview

Start an asynchronous sync job that pulls the latest data from the connected source. The job runs in the background and you can monitor its progress using the jobs endpoint.

For continuous sync connections, this performs an incremental sync by default. Use force_full_sync=true to perform a complete re-sync of all data.

Path Parameters

id · string · required

Unique UUID identifier of the source connection to sync

Example: “550e8400-e29b-41d4-a716-446655440000”

Query Parameters

force_full_sync · boolean · default: false

Force a full sync ignoring cursor data

Only applies to continuous sync connections. Non-continuous connections always perform full syncs.

Response

Returns a sync job object.

id · string · required

Unique UUID identifier of the sync job

source_connection_id · string · required

ID of the source connection this job belongs to

status · string · required

Current status: PENDING, RUNNING, COMPLETED, FAILED, CANCELLED, or CANCELLING

started_at · string

When the job started execution (ISO 8601)

completed_at · string

When the job finished (ISO 8601). Null if still running.

duration_seconds · number

Total execution time in seconds. Null if still running.

entities_inserted · integer · required

Number of new entities created during this sync

entities_updated · integer · required

Number of existing entities updated during this sync

entities_deleted · integer · required

Number of entities removed during this sync

entities_failed · integer · required

Number of entities that failed to process

error · string

Error message if the job failed

Example Request

cURL

curl -X POST "https://api.airweave.ai/v1/source-connections/550e8400-e29b-41d4-a716-446655440000/run" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "source_connection_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "started_at": null,
  "completed_at": null,
  "duration_seconds": null,
  "entities_inserted": 0,
  "entities_updated": 0,
  "entities_deleted": 0,
  "entities_failed": 0,
  "error": null,
  "error_details": null
}

Job Statuses

• PENDING: Job is queued, waiting for the worker to pick it up
• RUNNING: Sync is actively pulling and processing data
• COMPLETED: Sync finished successfully
• FAILED: Sync encountered an unrecoverable error
• CANCELLING: Cancellation has been requested. Worker is stopping.
• CANCELLED: Sync was cancelled

Error Responses

404 Not Found

Source connection with the specified ID does not exist

409 Conflict

A sync is already running for this connection