---
title: "Get time-bucketed query metrics timeline for a warehouse"
method: GET
path: "/api/v1/databricks/warehouses/{warehouse_id}/query-metrics-timeline"
tags: ["DATABRICKS", "Databricks", "Databricks Warehouses"]
---

# Get time-bucketed query metrics timeline for a warehouse

`GET /api/v1/databricks/warehouses/{warehouse_id}/query-metrics-timeline`

Get the time-bucketed metrics timeline powering the SQL warehouse
Monitoring page's stacked charts (latency, queueing, scan size, cache
hit rate, spill).

Hybrid-sourced: historical buckets come from the ClickHouse mirror,
and the fresh tail the mirror hasn't ingested yet (up to ~24h) is
read live from Databricks system tables via the Statement Execution
API against the tenant's ingestion SQL warehouse — this will
auto-start that warehouse if it is currently suspended. A live-tail
failure degrades to a ClickHouse-only response rather than erroring.

The lookback window is capped at ``MAX_MONITORING_LOOKBACK_DAYS`` days
regardless of what's requested — ``end_date`` is clamped to today and
``start_date`` is clamped to ``end_date - MAX_MONITORING_LOOKBACK_DAYS``
(silently, not a 400; the frontend's date-range picker clamps to the
same bound).

## Path parameters

- `warehouse_id` string, required

## Query parameters

- `start_date` string, date, required — Start date
- `end_date` string, date — End date
- `granularity` string — Time granularity: 'hour' or 'day'
- `instance_id` integer, nullable — Databricks instance id
- `navigationSource` string, nullable

## Headers

- `x-tenant` string, required

## Response `200`

Successful Response

- WarehouseQueryMetricsTimelineResponse — Response for the SQL warehouse Monitoring page's metrics timeline. ``ch_data_through`` is the observed ClickHouse-mirror freshness cutover used to route the query-history source between ClickHouse and a live Databricks-system-tables tail (``None`` if that mirror has never ingested a row for this tenant). ``live_tail_used`` is true if the query-metrics source actually pulled rows from the live tail for this response. Additive fields — the frontend schema tolerates extra optional keys.
  - `warehouse_id` string, required
  - `granularity` string, required
  - `timeline` WarehouseQueryMetricsTimelinePoint[]
    - `bucket_start` string, required
    - `query_count` integer
    - `latency_p50_ms` number, nullable
    - `latency_p95_ms` number, nullable
    - `exec_time_avg_ms` number, nullable
    - `exec_time_p90_ms` number, nullable
    - `queue_cold_start_p95_ms` number, nullable
    - `queue_at_capacity_p95_ms` number, nullable
    - `bytes_scanned` number, nullable
    - `result_cache_hit_pct` number, nullable
    - `disk_cache_hit_pct` number, nullable
    - `spilled_query_count` integer
    - `spilled_bytes` number, nullable
  - `ch_data_through` string, nullable
  - `live_tail_used` boolean

## Other responses

- `403` — Not authorized
- `404` — No ClickHouse database configured
- `422` — Validation Error

---

[API](https://skmtc.net/myaltimate/apis/fastapi.md) · [All operations](https://skmtc.net/myaltimate/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/myaltimate/fastapi/versions/dbf2c969464f/schema)