---
title: "Paginated Auto Tune audit history for a job"
method: GET
path: "/api/v1/databricks/jobs/{job_id}/auto-tune/history"
tags: ["DATABRICKS", "Databricks", "Databricks Jobs"]
---

# Paginated Auto Tune audit history for a job

`GET /api/v1/databricks/jobs/{job_id}/auto-tune/history`

## Request

- Base URL: `https://api.myaltimate.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.myaltimate.com/api/v1/databricks/jobs/{job_id}/auto-tune/history`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Read-only audit history for the Auto Tune tab.

Returns the most-recent events first. Each row carries
``event_message`` composed server-side from event_type + mode + actor
+ payload via ``DBX_AUTO_TUNE_EVENT_UI_MAPPING`` so the FE renders
one string verbatim.

User resolution is manual (PR #5070 hasn't merged): we batch-load
``altimate_users`` rows for displayed rows and any request rows used
for APPLIED provenance. A separate lightweight MUTATION_STARTED query
follows exact request links without exposing those markers in history.

## Path parameters

- `job_id` string, required

## Query parameters

- `instance_id` integer, required: Tenant instance ID (workspace) the job runs in
- `event_types` string, nullable: Comma-separated list of event_type values to include. Empty/omitted defaults to the 5 customer-relevant states (APPLY_REQUESTED, APPLIED, REVERTED, BACKOFF, FAILED). Pass explicit values (e.g. MUTATION_STARTED, CANCELLED) to escape the default for internal/debug use.
- `period` integer, nullable: Look-back window in days. Excludes audit rows whose ``change_timestamp`` is older than now - period days.
- `workspace_id` string, nullable: Optional Databricks workspace_id to scope queries to a specific workspace within the tenant's Databricks account. Defends against cross-workspace job_id collisions. When None, falls back to (instance_id, entity_id) lookup.
- `page` integer: Page number (1-indexed)
- `page_size` integer: Items per page

## Headers

- `x-tenant` string, required

## Response `200`

Successful Response

- AutoTuneHistoryResponse: Paginated response wrapper for the Auto Tune history endpoint. Matches the existing Databricks response convention (``total_count`` / ``page`` / ``page_size`` / ``total_pages``) rather than ``fastapi_pagination.Page[T]`` — none of the other Databricks endpoints in this router use the latter. Shared by the job-cluster history endpoint and the all-purpose-cluster history endpoint (``cluster_auto_tune_api.py``). Both populate ``reason_detail`` from stored audit evidence; a row with nothing to explain carries ``reason_detail=None`` and the FE falls back to ``actionable_message`` / ``reason``.
  - `items` AutoTuneHistoryEvent[], required
    - `event_id` integer, required
    - `event_type` string, required
    - `mode` string, nullable
    - `change_timestamp` string, date-time, required
    - `task_key` string, nullable
    - `recommendation_from` string, nullable
    - `recommendation_to` string, nullable
    - `change_summary` string, nullable
    - `recommendation_from_workers` string, nullable
    - `recommendation_to_workers` string, nullable
    - `recommendation_from_worker_instance` string, nullable
    - `recommendation_to_worker_instance` string, nullable
    - `recommendation_from_driver_instance` string, nullable
    - `recommendation_to_driver_instance` string, nullable
    - `changed_by` integer, nullable
    - `changed_by_name` string, nullable
    - `actionable_message` string, nullable
    - `reason` string, nullable
    - `event_message` string
    - `reason_detail` string, nullable
    - `rec_type` string, nullable
  - `total_count` integer
  - `page` integer
  - `page_size` integer
  - `total_pages` integer

## Other responses

- `403`: Not authorized
- `422`: Validation Error

## Changes

- **2026-09-02** `fcb62c79da95`: 2 info
  - added the optional property `items/items/change_summary` to the response with the `200` status
  - added the optional property `items/items/rec_type` to the response with the `200` status

[Operation history](https://skmtc.dev/myaltimate/apis/fastapi/changes/api/v1/databricks/jobs/:job_id/auto-tune/history/get.md)

---

[API](https://skmtc.dev/myaltimate/apis/fastapi.md) - [All operations](https://skmtc.dev/myaltimate/apis/fastapi/llms.txt) - [OpenAPI document](https://skmtc.dev/myaltimate/apis/fastapi/revisions/c123c3b831f8?raw)