---
title: "Toggle auto-tune on/off for a job's recommendation"
method: PATCH
path: "/api/v1/databricks/jobs/{job_id}/auto-tune/toggle"
tags: ["DATABRICKS", "Databricks", "Databricks Jobs"]
---

# Toggle auto-tune on/off for a job's recommendation

`PATCH /api/v1/databricks/jobs/{job_id}/auto-tune/toggle`

Enable or disable auto-tune for a recommendation.

Three flows behind one endpoint (v2.5 §15):

1. **Enable** — write APPLY_REQUESTED + flip config to enabled.
   Worker picks up async and calls Databricks.
2. **Disable when never applied** — fast-path. Write APPLY_REQUESTED
   (mode=disable) + flip the per-role cfg rows to disabled. No
   Databricks call needed.
3. **Disable when previously APPLIED** — sync rollback.
   BE preflight → optionally cancel active runs (with ``force=true``)
   → POST /api/2.2/jobs/update with attributes.from of the most
   recent APPLIED → write APPLIED audit row + update config in one
   Postgres tx. On Databricks failure: NO audit row, surface error.

## Path parameters

- `job_id` string, required

## Query parameters

- `instance_id` integer, required — Tenant instance ID (workspace) the job runs in
- `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.
- `task_key` string — Task key when toggling a per-task recommendation. Empty string for job-level recommendations (default).
- `force` boolean — Only meaningful for sync rollback (disable on an applied rec). When the job has active runs, force=true cancels them before reverting the cluster config. Defaults to false; the BE returns rollback.needs_confirmation=true and the FE shows an interstitial.
- `navigationSource` string, nullable

## Headers

- `x-tenant` string, required

## Request body

- ToggleAutoTuneRequest — Request body for ``PATCH /databricks/jobs/{id}/auto-tune/toggle``.
  - `enabled` boolean, required — Desired auto-tune state for the recommendation.
  - `scope` 'all_tasks' | 'specific_tasks', nullable — Optional whole-job cascade. 'all_tasks' cascade-writes the toggle to every (entity_id, task_key) row under this job. 'specific_tasks' enables the recs whose ``task_key`` appears in ``enabled_task_keys`` and DISABLES every other rec on the job — the config row converges to the exact set the user chose. When omitted, the toggle behaves per-task (legacy behavior — only the (job_id, task_key) row from the URL/query is mutated).
  - `enabled_task_keys` string[], nullable — Required (and must be non-empty) when ``scope='specific_tasks'``. Rejected for any other scope. The list of task_keys the user has chosen to enable; every other rec on the job is disabled.

## Response `200`

Successful Response

- ToggleAutoTuneResponse — Response body for the toggle endpoint. Returns the resolved ``auto_tune_mode`` so the FE can re-render the toggle position from the response without a second round-trip (though the FE still invalidates and refetches the list query so the full row state stays consistent).
  - `auto_tune_mode` string, nullable
  - `audit_event_id` integer, nullable
  - `entity_name` string, nullable
  - `preflight` ToggleAutoTunePreflight — Surfaced to the FE so it can render an actionable error inline. When ``blocked=False`` the toggle pipeline ran. When ``blocked=True`` no DB writes happened and ``actionable_message`` should be shown to the user verbatim (e.g. "ask your workspace admin to add r5.xlarge to the policy allowlist").
    - `blocked` boolean
    - `reason` string, nullable
    - `actionable_message` string, nullable
  - `rollback` RollbackInfo — Surfaced on the toggle response when the user disables an APPLIED recommendation (sync rollback path, v2.5 §15). - ``performed=True`` → the cluster was reverted and audit/config were updated. The toggle is now OFF. - ``needs_confirmation=True`` → the BE detected active runs on the job. No DB writes happened. The FE should show an interstitial ("kill {N} running runs and roll back?"); on confirm, re-call the endpoint with ``force=true``.
    - `performed` boolean
    - `needs_confirmation` boolean
    - `active_run_ids` integer[], nullable
    - `reason` string, nullable
  - `partial_failures` CascadePartialFailure[], nullable — Populated only on cascade calls (``scope=all_tasks`` or ``scope=specific_tasks``) when one or more per-task applies raised. ``None`` for single-task toggles or fully-successful cascades. Empty list is never returned — None means no failures occurred.
    - `task_key` string, required — The recommendation's ``task_key`` that failed to apply.
    - `error` string, required — Stringified exception message. The cascade catches all exceptions to keep the loop going; the original type is lost.

## Other responses

- `403` — Not authorized
- `404` — No recommendation found for this job
- `422` — Validation Error

---

[API](https://skmtc.dev/myaltimate/apis/fastapi.md) · [All operations](https://skmtc.dev/myaltimate/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/myaltimate/fastapi/revisions/fcb62c79da95/schema)