> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboards API

> List dashboards, create from templates, execute widget queries, inspect query breakdowns, and apply versioned dashboard definitions.

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

## List dashboards

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/dashboards
```

Returns dashboard summaries with:

* `id`
* `name`
* `description`
* `sharing_enabled`
* `sharing_token`
* `created_at`
* `updated_at`

## Get one dashboard

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/dashboards/{dashboard_id}
```

Returns the dashboard summary plus:

* `layout`
* `widgets`

## List templates

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/dashboard-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

```text theme={null}
POST https://api.squasher.ai/v1/projects/{project_id}/dashboards/from-template
```

Request body:

```json theme={null}
{
  "template_id": "internal-metrics-average",
  "name": "My internal metrics board"
}
```

## Execute a dashboard query

```text theme={null}
POST https://api.squasher.ai/v1/projects/{project_id}/dashboard-query
```

Example metrics query body:

```json theme={null}
{
  "source": "metrics",
  "aggregation": "avg",
  "metric_name": "http.server.duration",
  "metric_type": "hist",
  "service_name": "api",
  "time_range": "24h"
}
```

Example traces query body (aggregates `duration_ms` over the span name):

```json theme={null}
{
  "source": "traces",
  "aggregation": "p95",
  "metric_name": "http.server.handler",
  "group_by": "service",
  "time_range": "1h"
}
```

Example logs query body with Squasher search syntax:

```json theme={null}
{
  "source": "logs",
  "aggregation": "count",
  "group_by": "level",
  "q": "service_name:api \"database timeout\"",
  "time_range": "24h"
}
```

Valid `source` values: `metrics`, `logs`, `traces`, `errors`, `vitals`, `fixes`, `ai`, `ingestion`. See [Dashboards as Code](/features/dashboards-as-code#valid-widget-query-sources) 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

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/dashboards/{dashboard_id}/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

```text theme={null}
POST https://api.squasher.ai/v1/projects/{project_id}/dashboard-query/insight
```

Use this when you want the breakdown an operator would actually read, not just the raw chart points.

Example log query body:

```json theme={null}
{
  "source": "logs",
  "aggregation": "count",
  "group_by": "level",
  "time_range": "24h",
  "filters": [{ "field": "service", "value": "web" }]
}
```

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

```text theme={null}
POST https://api.squasher.ai/v1/projects/{project_id}/dashboards/apply
```

Use this endpoint when you want one request to create or update a dashboard from a manifest file.

Create a dashboard:

```json theme={null}
{
  "definition": {
    "kind": "dashboard_definition",
    "version": "dashboard-definition/v1",
    "definition_id": "service-latency",
    "name": "Service Latency",
    "widgets": [
      {
        "widget_id": "request-latency",
        "title": "Request latency",
        "chart_type": "line",
        "position": { "x": 0, "y": 0, "w": 6, "h": 4 },
        "query": {
          "source": "metrics",
          "aggregation": "avg",
          "metric_name": "http.server.duration",
          "metric_type": "hist",
          "service_name": "api",
          "time_range": "24h"
        }
      }
    ]
  }
}
```

Update an existing dashboard by adding `dashboard_id`:

```json theme={null}
{
  "dashboard_id": "660e8400-e29b-41d4-a716-446655440001",
  "definition": {
    "kind": "dashboard_definition",
    "version": "dashboard-definition/v1",
    "definition_id": "service-latency",
    "name": "Service Latency",
    "widgets": []
  }
}
```

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:

```text theme={null}
Inspect or create a Squasher dashboard for project <project_id>. Start with dashboard templates and existing dashboards, use inspect-query for explanations, keep definition ids and widget ids stable, and ask before applying or deleting anything.
```

For MCP, search for `dashboards.list`, `dashboards.listTemplates`, `dashboards.executeQuery`, `dashboards.inspectQuery`, or `dashboards.apply`.

## Related docs

* [Dashboards as Code](/features/dashboards-as-code)
* [Metrics API](/api-reference/metrics)