Skip to main content
Use the Dashboards API to inspect dashboards, create dashboards from templates, run widget queries, and apply versioned dashboard definitions from code.

​
List dashboards

Returns dashboard summaries with:
  • id
  • name
  • description
  • sharing_enabled
  • sharing_token
  • created_at
  • updated_at

​
Get one dashboard

Returns the dashboard summary plus:
  • layout
  • widgets

​
List templates

This includes built-in starter dashboard templates for common operational views. Notable starter templates now include operator-oriented boards such as API Operator Overview and Web Runtime Operator, which bias toward high-signal latency, error, release, and log-group views instead of raw metric catalog coverage.

​
Create from template

Request body:

​
Execute a dashboard query

Example metrics query body:
Example traces query body (aggregates duration_ms over the span name):
Example logs query body with Squasher search syntax:
Valid source values: metrics, logs, traces, errors, vitals, fixes, ai, ingestion. See Dashboards as Code for what each one queries. Use optional q only with logs and errors queries. It accepts the same fielded search syntax as event search. Use time_range for relative windows such as 5m, 1h, 24h, or 7d. For an absolute window, include both from and to as ISO 8601 timestamps; those timestamps override the relative time_range during execution while keeping the query shape compatible with saved widgets. The response includes:
  • aggregation
  • from
  • to
  • granularity
  • data
  • cache - freshness metadata with status, cached_at, expires_at, age_ms, ttl_ms, next_allowed_refresh_at, and refresh_mode
Dashboard query responses are cached by query shape, project, data region, and resolved time window. The cache is shared across API replicas with a small in-process warm layer. Send Cache-Control: no-cache to force a fresh execution without changing the JSON query body.

​
Capture a dashboard snapshot

This returns every widget query result in one response for dashboards and agents that need to inspect a whole board without N separate requests. Use Cache-Control: no-cache to force-refresh the widget queries. The response includes cache_summary, and each widget result includes the same cache metadata as dashboard-query.

​
Inspect a dashboard query

Use this when you want the breakdown an operator would actually read, not just the raw chart points. Example log query body:
The response includes:
  • highlights - compact takeaways from the widget data
  • latest_points - the latest bucket, trimmed to the most relevant groups
  • peak_points - the highest points in the selected window
  • top_groups - total, latest, and peak values per group
  • nonzero_point_count
  • total_points

​
Apply a dashboard definition

Use this endpoint when you want one request to create or update a dashboard from a manifest file. Create a dashboard:
Update an existing dashboard by adding dashboard_id:
Malformed definitions return a 422 response with a human-readable error message.

​
CLI and MCP parity

The same workflows are also exposed through:
  • squasher dashboards ... in the CLI
  • squasher dashboards snapshot --refresh for a forced dashboard snapshot
  • squasher dashboards inspect-query for operator-friendly widget breakdowns
  • the hosted MCP search and execute Code Mode tools for dashboard list, template, query, inspect, and apply operations

​
Agent handoff

Use dashboard APIs when an agent needs a repeatable query or a versioned dashboard definition:
For MCP, search for dashboards.list, dashboards.listTemplates, dashboards.executeQuery, dashboards.inspectQuery, or dashboards.apply.