Stream Sync Job Logs

Subscribe to real-time sync job progress via Server-Sent Events

GET /v1/sync/job/{job_id}/subscribe

Stream Sync Job Logs

cURL

curl --request GET \
  --url https://api.example.com/v1/sync/job/{job_id}/subscribe

200

{
  "connected": {},
  "heartbeat": {},
  "message": {},
  "error": {}
}

Overview

Stream real-time progress updates for a sync job using Server-Sent Events (SSE). This endpoint provides live updates as the sync processes entities.

Features:

• Real-time progress updates as entities are processed
• Automatic heartbeat every 30 seconds to keep connection alive
• Connection status events
• Graceful error handling

Use Cases:

• Build real-time sync progress UIs
• Monitor long-running sync operations
• Debug sync issues with live feedback
• Track entity processing in real-time

Path Parameters

job_id · string · required

Unique UUID identifier of the sync job to monitor

Example: “770e8400-e29b-41d4-a716-446655440002”

Response

Returns a Server-Sent Events (SSE) stream with text/event-stream content type.

Event Types

connected · event

Initial connection confirmation event

Show payload

{
  "type": "connected",
  "job_id": "770e8400-e29b-41d4-a716-446655440002"
}

heartbeat · event

Periodic heartbeat to keep connection alive (every 30 seconds)

Show payload

{
  "type": "heartbeat"
}

message · event

Sync progress update with entity processing statistics

Show payload example

{
  "type": "progress",
  "job_id": "770e8400-e29b-41d4-a716-446655440002",
  "entities_inserted": 45,
  "entities_updated": 12,
  "entities_deleted": 3,
  "status": "in_progress"
}

error · event

Error event if something goes wrong

Show payload

{
  "type": "error",
  "message": "Error description"
}

Example Request

cURL

curl -N https://api.airweave.ai/v1/sync/job/770e8400-e29b-41d4-a716-446655440002/subscribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream"

Example Event Stream

data: {"type": "connected", "job_id": "770e8400-e29b-41d4-a716-446655440002"}

data: {"type": "progress", "job_id": "770e8400-e29b-41d4-a716-446655440002", "entities_inserted": 10, "entities_updated": 2, "status": "in_progress"}

data: {"type": "heartbeat"}

data: {"type": "progress", "job_id": "770e8400-e29b-41d4-a716-446655440002", "entities_inserted": 45, "entities_updated": 12, "status": "completed"}

Connection Management

• Heartbeat: Events are sent every 30 seconds to prevent connection timeout
• Auto-reconnect: Clients should implement reconnection logic for dropped connections
• Graceful closure: Connection closes automatically when sync completes or fails
• Error handling: Error events are sent before closing on exceptions

Headers

The response includes these headers:

• Content-Type: text/event-stream
• Cache-Control: no-cache, no-transform
• Connection: keep-alive
• X-Accel-Buffering: no (disables Nginx buffering)

Error Responses

404 Not Found

Sync job with the specified ID does not exist

401 Unauthorized

Missing or invalid authentication