Dashboards API

A dashboard is a set of widgets that chart the telemetry of a project. Use this API to read dashboards, run their queries, and keep dashboard definitions in code.

List dashboards

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

GET https://api.squasher.ai/v1/projects/{project_id}/dashboards/{dashboard_id}

Returns the dashboard summary plus:

layout
widgets

List templates

GET https://api.squasher.ai/v1/projects/{project_id}/dashboard-templates

Returns the built-in templates. Each template has:

category: application, runtime, database, infrastructure, edge, ai, or web.
requires: the data the template needs. signals (traces, logs, metrics, errors, vitals, ai), metric_prefixes (for example system. or k8s.), and attributes (a span attribute such as db.system.name, with optional values).
readiness: whether this project has that data.

`readiness.status`	Meaning
`ready`	Every requirement had data in the last 24 hours.
`no_recent_data`	Every requirement had data in the last 7 days, but not all in the last 24 hours.
`needs_setup`	One or more requirements had no data in the last 7 days.

readiness.missing lists each requirement without recent data, with a hint that says what to send and a docs_url. The check is cached for about two minutes per project. If the check cannot run, the templates are returned without readiness. Add ?readiness=false to skip the check. The library includes service health (requests, errors, and latency from traces), HTTP endpoints, database client, PostgreSQL, Redis, Node.js, JVM, and Go runtimes, host metrics, Docker containers, Kubernetes workloads, Railway services, AI agents, web traffic, and log patterns. The metric templates use OpenTelemetry semantic convention names.

Preview a template

GET https://api.squasher.ai/v1/projects/{project_id}/dashboard-templates/{template_id}/preview

Runs every widget of the template for the project without saving a dashboard. The response has the same per-widget status, summary, and data as a dashboard snapshot.

Query parameter	Description
`time_range`	Range for every widget, such as `1h`, `24h`, or `7d`. At most `7d`.
`environment`	Optional environment filter.
`service_name`	Optional service filter for metrics widgets.

Without time_range, each widget uses its own range, capped at 7 days. A preview runs at most 16 widgets. When the project stores a metric with another instrument type than the template (for example a gauge instead of an up/down counter), the preview and a dashboard created from the template read the stored type. A range over 7 days returns 400; an unknown template returns 404.

Create from template

POST https://api.squasher.ai/v1/projects/{project_id}/dashboards/from-template

Request body:

{
  "template_id": "internal-metrics-average",
  "name": "My internal metrics board"
}

Execute a dashboard query

POST https://api.squasher.ai/v1/projects/{project_id}/dashboard-query

Example metrics query body:

{
  "source": "metrics",
  "aggregation": "avg",
  "metric_name": "http.server.request.duration",
  "metric_type": "hist",
  "service_name": "api",
  "time_range": "24h"
}

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

{
  "source": "traces",
  "aggregation": "p95",
  "metric_name": "http.server.handler",
  "group_by": "service",
  "time_range": "1h"
}

Example logs query body with Squasher search syntax:

{
  "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 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 cached rows and force-refresh cooldown are shared across API replicas with a small in-process warm layer for per-replica single-flight on concurrent misses. Send Cache-Control: no-cache to force a fresh execution without changing the JSON query body.

Capture a dashboard snapshot

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

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 only the raw chart points. Example log query body:

{
  "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

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:

{
  "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.request.duration",
          "metric_type": "hist",
          "service_name": "api",
          "time_range": "24h"
        }
      }
    ]
  }
}

Update an existing dashboard by adding dashboard_id:

{
  "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 templates for templates with readiness, and squasher dashboards templates --preview <template_id> --time-range 24h for a preview
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:

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.previewTemplate, dashboards.executeQuery, dashboards.inspectQuery, or dashboards.apply.

Start here

Resources

List dashboards

Get one dashboard

List templates

Preview a template

Create from template

Execute a dashboard query

Capture a dashboard snapshot

Inspect a dashboard query

Apply a dashboard definition

CLI and MCP parity

Agent handoff

​List dashboards

​Get one dashboard

​List templates

​Preview a template

​Create from template

​Execute a dashboard query

​Capture a dashboard snapshot

​Inspect a dashboard query

​Apply a dashboard definition

​CLI and MCP parity

​Agent handoff

​Related docs

List dashboards

Get one dashboard

List templates

Preview a template

Create from template

Execute a dashboard query

Capture a dashboard snapshot

Inspect a dashboard query

Apply a dashboard definition

CLI and MCP parity

Agent handoff

Related docs