Scheduling

Scheduling determines when and how often a sync runs. SignalSmith supports interval-based schedules for regular cadences, cron expressions for precise timing, and manual-only mode for on-demand execution.

Schedule Types

Interval-Based

The simplest scheduling option. Choose a fixed interval, and SignalSmith runs the sync at that frequency.

How it works: After each sync run completes, SignalSmith schedules the next run at the current time plus the interval. If a run takes longer than the interval, the next run starts immediately after the previous one finishes (runs never overlap).

Cron-Based

For precise timing control, use a cron expression. Cron scheduling lets you specify exact times, days of the week, and days of the month.

Cron Syntax

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, 0 = Sunday)
│ │ │ │ │
* * * * *

Common Cron Expressions

Cron Special Characters

Timezone

All cron expressions are evaluated in the workspace’s configured timezone. The default timezone is UTC. To change the timezone:

1. Go to Settings > Workspace
2. Set the Timezone to your preferred timezone
3. All cron schedules in the workspace will use this timezone

Manual Only

No automatic schedule is set. The sync only runs when you explicitly trigger it via the UI or API.

When to use manual mode:

• One-time data migrations
• Ad-hoc data pushes
• Testing and development
• Syncs that should only run in response to external events

Triggering a manual run:

In the UI:

1. Navigate to the sync detail page
2. Click Run Now

Via the API:

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

Schedule Configuration

Using the UI

When creating or editing a sync, the schedule step presents:

1. Schedule type — Choose between Interval, Cron, or Manual
2. Interval selector — (If interval) Choose from predefined intervals
3. Cron expression — (If cron) Enter a cron expression
4. Preview — Shows the next 5 scheduled run times based on your configuration

Using the API

# Interval schedule
{
  "schedule": {
    "type": "interval",
    "interval_minutes": 60
  }
}
 
# Cron schedule
{
  "schedule": {
    "type": "cron",
    "cron_expression": "0 9 * * 1-5"
  }
}
 
# Manual only
{
  "schedule": {
    "type": "manual"
  }
}

Run Behavior

Concurrency

Sync runs for the same sync never overlap. If a scheduled run time arrives while the previous run is still executing, the new run is queued and starts immediately after the previous run completes.

Missed Runs

If a sync is paused and then resumed, missed scheduled runs are not retroactively executed. The sync resumes from the next upcoming scheduled time.

Run Duration

The total run duration depends on:

• Query execution time in the warehouse
• Number of records to process
• Destination API rate limits and latency
• Network conditions

For large syncs (100,000+ rows), consider scheduling during off-peak hours to avoid warehouse contention and destination API throttling.

Failure Handling

If a sync run fails:

1. The failure is recorded in the run history
2. The sync remains active — the next scheduled run proceeds as normal
3. If multiple consecutive runs fail, SignalSmith sends an alert to workspace administrators
4. After a configurable number of consecutive failures, the sync may be automatically paused

Best Practices

Choosing the Right Frequency

Consider these factors when setting a schedule:

Staggering Syncs

If you have multiple syncs running against the same source, stagger their schedules to avoid overloading the warehouse:

# Instead of all at the top of the hour:
Sync A: 0 * * * *    (every hour at :00)
Sync B: 0 * * * *    (every hour at :00)  ← concurrent load
Sync C: 0 * * * *    (every hour at :00)  ← concurrent load

# Stagger by 10 minutes:
Sync A: 0 * * * *    (every hour at :00)
Sync B: 10 * * * *   (every hour at :10)
Sync C: 20 * * * *   (every hour at :20)

Monitoring Schedule Health

Keep an eye on:

• Run duration trends — If runs are getting slower, the dataset may be growing and the query needs optimization
• Overlapping runs — If runs frequently overlap (next run queued because previous is still running), increase the interval or optimize the query
• Failure rates — A sudden increase in failures may indicate a destination API issue or credential expiration

Next Steps

• Create a sync with a schedule
• Monitor sync runs to track execution history
• Troubleshoot issues with scheduling and runs