Sync Runs

Every time a sync executes — whether on schedule, manually triggered, or via the API — it produces a sync run record. Sync runs provide detailed visibility into what happened during each execution: how many rows were processed, how many succeeded or failed, and how long it took.

Viewing Sync Runs

Run History

Navigate to a sync’s detail page and click the Runs tab to see the complete run history. Each run shows:

Run Detail View

Click on a specific run to see the full detail view, which includes:

• Summary metrics — Total rows, creates, updates, deletes, errors
• Timeline — Step-by-step progression of the run (query, change detection, destination writes)
• Error details — Per-row error messages for failed records
• Performance metrics — Query time, processing time, API call duration

Run Statuses

Completed with Errors

A run can complete successfully overall while having individual row-level errors. For example, if 10,000 rows are processed and 50 fail due to validation issues, the run status is Completed with a note that 50 rows had errors.

This is different from a Failed run, where the entire execution was aborted.

Run Metrics

Row Counts

┌─────────────────────────────────────────────────────┐
│                  Sync Run Summary                    │
├─────────────────┬───────────────────────────────────┤
│ Total Processed │ 15,432                            │
│ Created         │  1,205  ████████                  │
│ Updated         │ 13,891  ██████████████████████████ │
│ Deleted         │      0                            │
│ Failed          │    336  ██                        │
│ Skipped         │      0                            │
├─────────────────┼───────────────────────────────────┤
│ Duration        │ 4m 23s                            │
│ Query Time      │ 45s                               │
│ Processing Time │ 3m 38s                            │
└─────────────────┴───────────────────────────────────┘

Duration Breakdown

Each run’s duration is broken down into phases:

1. Query execution — Time spent running the model SQL against the warehouse
2. Change detection — Time spent comparing current results to the previous snapshot
3. Destination writes — Time spent sending data to the destination API
4. Finalization — Time spent updating the snapshot and recording results

Trend Analysis

The run history view shows trends over time:

• Row count trend — How the total number of processed rows changes between runs
• Error rate trend — Percentage of failed rows over time
• Duration trend — Whether runs are getting faster or slower

Sudden changes in these trends can indicate:

• Row count spike — New data loaded into the warehouse, or a model query change
• Row count drop — Data deleted from the warehouse, or a filter change in the model
• Error rate increase — Destination schema change, data quality issue, or API limit hit
• Duration increase — Growing dataset, warehouse performance degradation, or destination throttling

Error Details

Row-Level Errors

When individual rows fail to sync, the error detail view shows:

Each error includes:

• The primary key value of the failed row
• The error message from the destination API
• The field that caused the error (if available)

System-Level Errors

If the entire run fails, the error detail shows the system-level error:

Monitoring Sync Runs

Dashboard

The Insights > Sync Health dashboard provides an overview of all sync runs across your workspace:

• Total runs in the last 24 hours / 7 days / 30 days
• Success rate percentage
• Average duration
• Total rows synced
• Syncs with errors

Notifications

SignalSmith can send notifications for sync run events:

• Run completed — Notification when a run finishes (optional)
• Run failed — Alert when a run fails (enabled by default)
• High error rate — Alert when the row-level error rate exceeds a threshold
• Consecutive failures — Alert after multiple consecutive run failures

Notifications can be delivered via:

• Email
• Slack (via webhook integration)
• Custom webhook

API Access

List Runs

curl https://your-workspace.signalsmith.dev/api/v1/syncs/{sync_id}/runs \
  -H "Authorization: Bearer $API_TOKEN"

Response:

{
  "data": [
    {
      "id": "run_abc123",
      "sync_id": "sync_xyz789",
      "status": "completed",
      "trigger": "schedule",
      "started_at": "2025-01-15T09:00:00Z",
      "completed_at": "2025-01-15T09:04:23Z",
      "duration_seconds": 263,
      "rows_processed": 15432,
      "rows_created": 1205,
      "rows_updated": 13891,
      "rows_deleted": 0,
      "rows_failed": 336
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 156
  }
}

Get Run Details

curl https://your-workspace.signalsmith.dev/api/v1/syncs/{sync_id}/runs/{run_id} \
  -H "Authorization: Bearer $API_TOKEN"

Get Run Errors

curl https://your-workspace.signalsmith.dev/api/v1/syncs/{sync_id}/runs/{run_id}/errors \
  -H "Authorization: Bearer $API_TOKEN"

Response:

{
  "data": [
    {
      "row_id": "usr_123",
      "field": "Email",
      "message": "Invalid email format",
      "raw_value": "not-an-email"
    },
    {
      "row_id": "usr_456",
      "field": "LastName",
      "message": "Required field is null",
      "raw_value": null
    }
  ],
  "total_errors": 336,
  "page": 1,
  "per_page": 100
}

Retrying Failed Runs

If a run fails due to a transient issue (e.g., temporary network outage, destination API downtime), you can retry it:

1. Navigate to the failed run’s detail page
2. Click Retry Run
3. The sync re-executes using the current model data (not a replay of the failed run’s data)

Via the API:

curl -X POST https://your-workspace.signalsmith.dev/api/v1/syncs/{sync_id}/trigger \
  -H "Authorization: Bearer $API_TOKEN"

Note: A retry triggers a new full sync run. It does not selectively retry only the failed rows from the previous run.

Best Practices

• Monitor error rates — A consistent error rate above 1% indicates a systematic issue that should be investigated
• Watch duration trends — If run duration is increasing, optimize the model query or check warehouse performance
• Set up failure alerts — Enable notifications for failed runs so you can respond quickly
• Review errors after the first run — The initial sync often surfaces data quality and mapping issues
• Use the API for automation — Build monitoring dashboards or trigger alerts based on run metrics

Next Steps

• Troubleshoot common errors
• Configure scheduling for optimal cadence
• Review sync modes to understand record handling