---
title: "Enable or disable auto-tune for a SQL warehouse"
method: POST
path: "/api/v1/databricks/warehouses/{warehouse_id}/auto-tune/toggle"
tags: ["DATABRICKS", "Databricks", "Databricks Warehouses"]
---

# Enable or disable auto-tune for a SQL warehouse

`POST /api/v1/databricks/warehouses/{warehouse_id}/auto-tune/toggle`

Enable or disable auto-tune for a serverless SQL warehouse.

Applies inline and synchronously — unlike the job-cluster toggle, a
warehouse ``/edit`` drains gracefully, so there is no async worker
hand-off. See ``app.service.databricks.auto_tune.warehouse_toggle``
for the full enable/disable flow (recommendation resolution,
write-once baseline capture, and the audit trail written).

## Path parameters

- `warehouse_id` string, required

## Headers

- `x-tenant` string, required

## Request body

- WarehouseAutoTuneToggleRequest — Request body for ``POST /databricks/warehouses/{id}/auto-tune/toggle``.
  - `enabled` boolean, required — Desired auto-tune state for the warehouse.
  - `instance_id` integer, required — Tenant instance ID (workspace) the warehouse runs in.
  - `workspace_id` string, required — Required Databricks workspace_id. Scopes credential resolution to the correct workspace on multi-workspace tenants (defends against cross-workspace warehouse_id collisions) AND is the join key the ingestion cost-savings mart (``mrt_auto_tune_cost_savings``) uses to attribute realized savings on ``(workspace_id, entity_id)``. An empty or mismatched value silently drops all ``actual`` savings for this warehouse.
  - `backoff_configuration` WarehouseAutoTuneBackoffConfiguration — User-configured backoff thresholds for the 7-day post-apply monitor. Mirrors Snowflake's ``BackoffConfiguration`` shape (percentages, not raw ratios) but adds bounds validation Snowflake's never had — a threshold below 110% would trigger backoff on ordinary noise, and an absurdly high one (past 1000%) defeats the monitor's purpose entirely. Both default to 150 (allow up to 1.5x the baseline before treating it as a regression).
    - `max_latency_percentage` number — Backoff triggers when live p95 latency exceeds this percentage of the pre-apply baseline for the sustained-breach window.
    - `max_queue_time_percentage` number — Backoff triggers when live p95 queue time (cold-start + at-capacity) exceeds this percentage of the pre-apply baseline.
    - `trigger_action` string, nullable — What a sustained backoff breach does — the cluster drawer's two choices, one for the whole warehouse: 'rollback' (step back to the last config that ran clean; the default) or 'revert_to_original' (restore the pre-Auto-Tune config). Not validated as an enum on purpose: an operator may store one of the pod's finer internal actions directly, and the monitor's target resolver falls back to the frozen original for any value without a branch.
  - `rec_type` 'resize' | 'auto_terminate' — Which axis this toggle targets. Defaults to auto_terminate so every existing caller is unaffected — this is NOT a master toggle that flips both axes (contrast the all-purpose-cluster path's rec_type=None semantics).

## Response `200`

Successful Response

- WarehouseAutoTuneToggleResponse — Response body for the warehouse toggle endpoint.
  - `auto_tune_mode` 'enabled' | 'disabled', required
  - `applied` boolean — True iff this call actually mutated the live warehouse.
  - `auto_stop_mins_from` integer, nullable
  - `auto_stop_mins_to` integer, nullable
  - `blocked` boolean — True iff the requested action could not proceed (see reason).
  - `reason` string, nullable
  - `audit_event_ids` integer[]

## Other responses

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

## Changes

- **2026-09-02** `fcb62c79da95` — 2 info
  - added the new optional request property `backoff_configuration/anyOf[subschema #1: WarehouseAutoTuneBackoffConfiguration]/trigger_action`
  - added the new optional request property `rec_type`

[Change history](https://skmtc.dev/myaltimate/apis/fastapi/changes/api/v1/databricks/warehouses/:warehouse_id/auto-tune/toggle/post.md)

---

[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/b8f442483dc9/schema)