Schedules API

A schedule captures a snapshot of a project at a fixed interval. Fires happen on the server, so they run whether or not anyone has the app open.

Scheduling requires Platinum or Enterprise, plus a writer role (owner, admin, editor or data_fabricator) on the project.

Create

curl -s "$SEEDQL_API/api/schedules" -X POST \
  -H "Authorization: Bearer $SEEDQL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "…",
    "name": "nightly backup",
    "interval_minutes": 1440
  }'

{
  "id": "7c4a…",
  "project_id": "…",
  "name": "nightly backup",
  "kind": "snapshot",
  "interval_minutes": 1440,
  "enabled": true,
  "next_run_at": "2026-07-29T02:00:00",
  "last_run_at": null
}

Minimum interval is 15 minutes; maximum is 30 days.

Manage

GET    /api/schedules?org_id=…        # list
PATCH  /api/schedules/{id}            # name, interval_minutes, enabled
DELETE /api/schedules/{id}
POST   /api/schedules/{id}/run        # fire now
GET    /api/schedules/{id}/runs       # recent history

Changing interval_minutes re-anchors the next fire from now, so a shortened cadence takes effect immediately rather than after the old interval elapses. Re-enabling a paused schedule likewise schedules a full interval out, instead of firing instantly because its next_run_at sat in the past.

POST /{id}/run does not advance next_run_at. An ad-hoc capture should not postpone the scheduled one.

Run history

[
  { "status": "ok",      "detail": "snapshot captured", "snapshot_id": "…", "created_at": "…" },
  { "status": "skipped", "detail": "no schema captured yet: run an introspection or take a first snapshot", "snapshot_id": null, "created_at": "…" }
]

Status	Meaning
ok	A snapshot was captured; snapshot_id points to it
skipped	Nothing to capture, or the tier no longer permits scheduling
error	The capture failed; detail says why

The last 20 runs per schedule are kept.

Behaviour worth knowing

Overdue schedules fire once. After downtime, a schedule that missed forty intervals fires a single time and re-anchors. Firing per missed interval would dump a burst of snapshots, which is not what a backup cadence should do.

A lapsed tier stops fires, not the schedule. Entitlement is re-checked at every fire against the creator's current tier. Downgrade and fires record skipped: tier; upgrade again and the same schedule resumes. The configuration survives a payment gap.

Nothing to capture is not an error. A project with no schema yet records skipped with a reason.

Monitoring across the org

curl -s "$SEEDQL_API/api/schedule-runs?org_id=$ORG&status=error&limit=50" \
  -H "Authorization: Bearer $SEEDQL_KEY"

One request covering every schedule, rather than walking each one.