Skip to main content

Run a checkpoint on a schedule

Goal​

You'll attach a cron schedule to a checkpoint so PLACEHOLDER Cloud runs it automatically — every weekday at 6 AM, hourly, daily at midnight, whatever cadence your data lands on.

Schedule CRUD and the cron worker job are shipped. Per-tenant timezones shipped in FEATURE-30; see Per-tenant timezones below.

Prereqs​

  • A checkpoint that runs successfully when you click Run now.
  • Workspace editor role or higher.

Steps​

  1. Open the checkpoint detail page.

  2. Click "Add schedule". A small form opens.

  3. Enter a cron expression. Standard 5-field cron — minute, hour, day-of-month, month, day-of-week. Examples:

    CadenceCron
    Every weekday at 06:00 (configured tz)0 6 * * MON-FRI
    Every hour on the hour0 * * * *
    Every 15 minutes*/15 * * * *
    Daily at midnight0 0 * * *

    The form shows a humanised preview as you type.

  4. Pick a timezone. The picker defaults to your browser's IANA zone. Either select from the curated list (~30 common zones) or paste any IANA name — America/New_York, Europe/Paris, Asia/Kolkata, etc. The cron expression is evaluated against this zone.

  5. Toggle Enabled on.

  6. Save. PLACEHOLDER Cloud writes a ScheduledRun row. A worker cron job runs every minute, finds schedules whose next_run_at <= now(), enqueues the checkpoint, and advances next_run_at per the cron expression interpreted in the configured timezone.

Verify​

  • The schedule appears on the checkpoint detail page with its next-run time.
  • After the next scheduled minute, a fresh ValidationResult row appears under the checkpoint's results list with the calendar icon next to it (distinguishes scheduled from manual runs).

Per-tenant timezones​

Each ScheduledRun row carries an IANA timezone (default UTC). The worker evaluates the cron expression against that zone, so 0 9 * * MON-FRI in America/New_York fires at 09:00 New-York wall-clock all year — 13:00 UTC during EDT, 14:00 UTC during EST. No twice-yearly retuning.

Picking a zone. The schedule form's timezone picker offers ~30 common IANA zones in its dropdown, and accepts any IANA name typed in directly. Unknown zones are rejected with a 400 at create/update time, so a typo like Americas/New_York is caught before it ever reaches the worker.

Display. The schedules list shows the next-run-at twice — once relative to your viewing browser ("in 2 hours"), and once in the configured zone's wall-clock with a UTC±HH:MM offset badge. A US-East operator looking at a Tokyo schedule sees both renderings side by side.

DST edge case. A cron expression whose fire-time falls in the missing or duplicate hour during a DST transition follows croniter's behaviour: the missing hour is skipped, the duplicate hour fires once. If your business logic depends on the missing/duplicate slot specifically, write two cron lines around it. (Follow-up tracking is in FEATURE-30's out-of-scope note.)

Editing a schedule​

From the Schedules list, each row has an Edit (pencil) action that opens a form pre-populated with the schedule's current cron expression and timezone. Change either and Save changes — the schedule is updated in place (PATCH /schedules/{id}), keeping its id, run history, and checkpoint association. No more delete-and-recreate to fix a cron typo or move to a different zone. Editing requires the same role as pause/resume (workspace editor or higher).

Run now feedback​

The per-row Run now action enqueues the checkpoint immediately and returns 202 Accepted. The list shows a confirmation banner with a link to the Results page, where the queued run appears once the worker picks it up.

Disable vs. delete​

  • Edit changes the cadence (cron / timezone) without losing the row.
  • Disable keeps the row, just stops enqueueing. Re-enable later.
  • Delete removes the schedule entirely.

In-flight runs already in RunQueue continue regardless — the schedule only governs new enqueues.

Backfilling history​

For a one-off "validate the last 30 daily partitions of this asset", you want a backfill, not a schedule. Use POST /api/v1/.../checkpoints/{id}/run-subset with a body of {"batch_definition_ids": [...]} — one batch definition per partition slice you want re-validated. Shipped in FEATURE-37; see Checkpoints for the surrounding lifecycle and Batch definitions for how to define the slices.