Orchestrator

The orchestrator is a Kubernetes CronJob that runs on a configurable schedule. Each run discovers opted-in tables (via the snowpack.maintenance_enabled table property and the database allowlist), evaluates their health against configured thresholds, and submits maintenance jobs through the API for tables that need work. It respects per-table cadence overrides to avoid maintaining tables more frequently than their owners intend.

These endpoints record and expose orchestrator run metadata so operators can monitor scheduling behavior without digging through pod logs.

---

Record an orchestrator run

POST /orchestrator/runs

Records a completed orchestrator run. This endpoint is called by the CronJob container at the end of each execution cycle, regardless of whether the run succeeded or failed.

Request body

{
  "started_at": "2026-04-25T14:00:00.000000+00:00",
  "completed_at": "2026-04-25T14:02:45.000000+00:00",
  "status": "completed",
  "tables_assessed": 247,
  "tables_skipped": 180,
  "tables_healthy": 42,
  "jobs_submitted": 25,
  "jobs_completed": 24,
  "jobs_failed": 1,
  "dry_run": false,
  "error": null
}

Field	Type	Required	Default	Description
started_at	string	Yes	—	ISO 8601 timestamp when the run started.
completed_at	string	Yes	—	ISO 8601 timestamp when the run finished.
status	string	Yes	—	Run outcome: completed, failed, partial, etc.
tables_assessed	int	No	0	Number of tables evaluated for health.
tables_skipped	int	No	0	Tables skipped (cadence not due, not opted in, etc.).
tables_healthy	int	No	0	Tables that passed all health thresholds.
jobs_submitted	int	No	0	Maintenance jobs submitted during this run.
jobs_completed	int	No	0	Jobs that completed successfully during this run.
jobs_failed	int	No	0	Jobs that failed during this run.
dry_run	boolean	No	false	Whether the run was a dry run (no actual jobs submitted).
error	string|null	No	null	Error message if the run itself failed.

Response --- 201 Created

Returns the stored run record, including a server-assigned id.

{
  "id": 42,
  "started_at": "2026-04-25T14:00:00.000000+00:00",
  "completed_at": "2026-04-25T14:02:45.000000+00:00",
  "status": "completed",
  "tables_assessed": 247,
  "tables_skipped": 180,
  "tables_healthy": 42,
  "jobs_submitted": 25,
  "jobs_completed": 24,
  "jobs_failed": 1,
  "dry_run": false,
  "error": null
}

Status codes

Code	Meaning
201	Run recorded.
422	Invalid request body.
503	Postgres unavailable.

Example

curl -X POST https://snowpack-api.internal/orchestrator/runs \
  -H "Content-Type: application/json" \
  -d '{
    "started_at": "2026-04-25T14:00:00+00:00",
    "completed_at": "2026-04-25T14:02:45+00:00",
    "status": "completed",
    "tables_assessed": 247,
    "jobs_submitted": 25,
    "jobs_completed": 24,
    "jobs_failed": 1
  }'

---

List orchestrator runs

GET /orchestrator/runs

Returns recent orchestrator runs, newest first. Use this to verify the CronJob is firing on schedule and to review run-over-run trends in table assessments and job outcomes.

Query parameters

Parameter	Type	Default	Description
limit	int	20	Maximum runs to return (capped at 100).

Response --- 200 OK

[
  {
    "id": 42,
    "started_at": "2026-04-25T14:00:00.000000+00:00",
    "completed_at": "2026-04-25T14:02:45.000000+00:00",
    "status": "completed",
    "tables_assessed": 247,
    "tables_skipped": 180,
    "tables_healthy": 42,
    "jobs_submitted": 25,
    "jobs_completed": 24,
    "jobs_failed": 1,
    "dry_run": false,
    "error": null
  },
  {
    "id": 41,
    "started_at": "2026-04-25T08:00:00.000000+00:00",
    "completed_at": "2026-04-25T08:03:12.000000+00:00",
    "status": "completed",
    "tables_assessed": 245,
    "tables_skipped": 178,
    "tables_healthy": 44,
    "jobs_submitted": 23,
    "jobs_completed": 23,
    "jobs_failed": 0,
    "dry_run": false,
    "error": null
  }
]

Status codes

Code	Meaning
200	Success.
503	Postgres unavailable.

Example

# Last 20 runs (default)
curl https://snowpack-api.internal/orchestrator/runs

# Last 5 runs
curl "https://snowpack-api.internal/orchestrator/runs?limit=5"