History

The history endpoints provide access to durable records stored in Postgres. While the Jobs endpoints expose the operational jobs table, the history endpoints query the long-lived job_history, job_action_history, and health_snapshots tables that retain data for 90+ days.

---

List job history

GET /jobs/history

Returns completed job records from Postgres, ordered newest first. These records persist long after the operational jobs table rows have been pruned, making this the go-to endpoint for auditing past maintenance runs.

Query parameters

Parameter	Type	Default	Description
table	string	—	Filter by table in database.table_name format.
status	string	—	Filter by status: completed, failed, cancelled, etc.
limit	int	100	Maximum rows to return (capped at 500).

Response — 200 OK

[
  {
    "job_id": "a1b2c3d4e5f678901234567890abcdef",
    "database": "analytics",
    "table_name": "page_views",
    "actions": ["rewrite_data_files", "expire_snapshots"],
    "status": "completed",
    "submitted_at": "2026-04-24T10:00:00.000000+00:00",
    "completed_at": "2026-04-24T10:05:30.000000+00:00"
  }
]

Status codes

Code	Meaning
200	Success.
422	Invalid table format (must contain a . separator).
503	Postgres unavailable.

Example

# Recent history for a specific table
curl "https://snowpack-api.internal/jobs/history?table=analytics.page_views&limit=20"

# All failed jobs
curl "https://snowpack-api.internal/jobs/history?status=failed"

---

Health snapshot history

GET /jobs/history/health

Returns health snapshot records from Postgres, ordered newest first. Each snapshot captures a point-in-time health assessment of a table — file statistics, snapshot counts, recommended actions, and maintenance status.

Health snapshots are written by two sources:

1. The live health endpoint, which persists every successful analysis.
2. The background health-sync worker, which periodically refreshes snapshots for tables in configured databases.

Query parameters

Parameter	Type	Default	Description
table	string	—	Filter by table in database.table_name format.
limit	int	100	Maximum rows to return (capped at 500).

Response — 200 OK

[
  {
    "database": "analytics",
    "table_name": "page_views",
    "snapshot_count": 34,
    "small_file_count": 87,
    "needs_maintenance": true,
    "health_status": "Degraded",
    "captured_at": "2026-04-25T14:32:00.000000+00:00"
  }
]

Status codes

Code	Meaning
200	Success.
422	Invalid table format (must contain a . separator).
503	Postgres unavailable.

Example

curl "https://snowpack-api.internal/jobs/history/health?table=analytics.page_views&limit=50"

---

Prune history

POST /jobs/history/prune

Deletes job history and health snapshot records older than the specified retention window. Use this for manual retention cleanup; the default retention period is 90 days.

Query parameters

Parameter	Type	Default	Description
retention_days	int	90	Delete records older than this many days. Minimum is 1.

Response — 200 OK

{
  "deleted": 142
}

Field	Type	Description
deleted	int	Total number of records removed across all tables.

Status codes

Code	Meaning
200	Prune completed.
422	retention_days is less than 1.
503	Postgres unavailable.

Example

# Prune records older than 90 days (default)
curl -X POST https://snowpack-api.internal/jobs/history/prune

# Prune records older than 30 days
curl -X POST "https://snowpack-api.internal/jobs/history/prune?retention_days=30"