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 jobs and job_actions 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": ["expire_snapshots", "rewrite_data_files"],
    "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://icepack-api.internal/jobs/history?table=analytics.page_views&limit=20"

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

---

Prune history

POST /jobs/history/prune

Deletes job history, legacy health snapshots, and orchestrator run 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://icepack-api.internal/jobs/history/prune

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