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, job_actions, and table health assessment 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"

---

Health assessment history

GET /jobs/history/health

Returns split health assessment payloads from Postgres, ordered newest first. Each assessment captures health status and issues for a point-in-time table status snapshot. It does not include maintenance policy fields or recommended actions; use /tables/{database}/{table}/maintenance/recommendation for action intent.

Health assessments are written by two sources:

1. The live health endpoint, which persists every successful assessment.
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

[
  {
    "table": {
      "database": "analytics",
      "table_name": "page_views",
      "location": "s3://lakehouse/analytics/page_views",
      "format_version": 2
    },
    "assessed_at": "2026-04-25T14:32:01+00:00",
    "status_collected_at": "2026-04-25T14:32:00+00:00",
    "health_status": "Warning",
    "issues": [
      {
        "code": "small_files",
        "severity": "warning",
        "message": "Table has 87 files below the small-file threshold.",
        "evidence": {
          "small_file_count": 87,
          "small_file_pct": 6.78
        }
      }
    ],
    "collection": {
      "source": "cached",
      "stale": false,
      "warnings": []
    },
    "error": null
  }
]

Status codes

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

Example

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

---

Prune history

POST /jobs/history/prune

Deletes job history, legacy health snapshots, split table status snapshots, split table health assessments, 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"