app.integration_sync_runs
TableRow level security on
Sync runs of a connection (Section 17): what moved, how many attempts it took and why it failed. A retryable failure moves the run to Retrying with exponential backoff until max_attempts, then Failed. One active run per connection and scope; the idempotency key makes enqueueing safe to repeat.
Primary key: id
| Column | Type | Nullable | Description |
|---|---|---|---|
| id | uuid | No | Primary key, UUID v7. |
| org_id | uuid | No | Owning org, derived from app.integration_connections on insert; never accepted from the caller and never changed.References app.organizations.id |
| integration_connection_id | uuid | No | Connection synced.References app.integration_connections.id |
| project_id | uuid | Yes | Project the run is limited to, when it is.References app.projects.id |
| sync_scope | app.integration_sync_scope | No | What the run moves; belongs to the connection's category. |
| direction | app.integration_sync_direction | No | Inbound, Outbound or Two Way. |
| sync_run_state | app.integration_sync_run_state | No | Run state. Changes only through the sync RPCs. |
| idempotency_key | text | No | Caller key that makes enqueueing idempotent per connection. |
| subject_entity | app.integration_entity | Yes | Kind of the one local row the run works on, when it works on one (a payroll run for Payroll Export). |
| subject_id | uuid | Yes | Local row the run works on, checked to exist in the same org. |
| source_uri | text | Yes | Platform storage path of the file the run imports (a ticketing CSV), when it imports one. |
| attempt | smallint | No | Attempts started so far. |
| max_attempts | smallint | No | Attempts allowed before the run fails for good (1 to 10). |
| next_attempt_at | timestamp with time zone | Yes | When a Queued or Retrying run is due. |
| started_at | timestamp with time zone | Yes | When the current or last attempt started. |
| finished_at | timestamp with time zone | Yes | When the run reached Succeeded, Failed or Canceled. |
| cursor_before | text | Yes | Provider cursor or watermark the run started from. |
| cursor_after | text | Yes | Provider cursor or watermark the next run starts from. |
| items_read | integer | No | Items read from the source. |
| items_written | integer | No | Items created or changed at the destination. |
| items_skipped | integer | No | Items unchanged since the last sync. |
| items_failed | integer | No | Items that failed; each has a row in app.integration_sync_errors. |
| error_code | text | Yes | Rule code of the last attempt's failure. |
| error_message | text | Yes | Provider message of the last attempt's failure. |
| job_id | uuid | Yes | Latest integration.sync job on the platform job queue (app.job_queue) for the run's next attempt. |
| deleted_at | timestamp with time zone | Yes | Soft delete time. A row with deleted_at set is ignored by every access helper. |
| created_at | timestamp with time zone | No | When the row was inserted. Set by the database. |
| created_by | uuid | Yes | Person who inserted the row, or null for a platform process. Set by the database.References app.people.id |
| updated_at | timestamp with time zone | No | When the row last changed. Set by the database. |
| updated_by | uuid | Yes | Person who last changed the row, or null for a platform process. Set by the database.References app.people.id |