Dashboards as Code

Use dashboards as code when you want a repeatable, reviewable way to create metric dashboards from scripts, repos, or agent workflows. The same definition shape works across:

the Dashboards API
the Squasher CLI
the hosted MCP server

Dashboard workflow

The dashboard library is for saved views with one clear operating purpose. Start from a focused template or a blank dashboard. A dashboard opens in view mode; select Edit dashboard before you rename it, add or duplicate widgets, or move and resize the grid. The time range plus supported environment and service filters apply to all widgets and stay in the URL. Relative ranges can auto-refresh. Absolute from and to ranges keep a fixed evidence window and disable auto-refresh. Use Share only when live widget data can be visible to anyone with the link; disabling sharing revokes that link. From the dashboard library, Use with agent provides Prompt, CLI, REST API, MCP, and JSON views of one versioned handoff. The dashboard handoff is read-only: it lists the supported definition read and snapshot operations, copies no credentials or raw widget telemetry, and asks the agent to propose a change instead of applying one.

Definition format

Dashboard definitions are versioned JSON manifests. Every widget’s query.source field must be one of:

Source	What it queries
`metrics`	OTLP metrics (gauge, sum, histogram, exponential histogram)
`logs`	Structured logs ingested via SDK or drains
`traces`	OTLP spans — aggregate `duration_ms` by span name across `count`, `avg`, `p50`, `p90`, `p95`, `p99`. Use `metric_name` for the span name.
`errors`	Error groups + occurrences
`vitals`	Web vitals (LCP, INP, CLS, etc.)
`fixes`	Hosted fix-run activity
`ai`	AI agent observations
`ingestion`	Ingestion latency and delivery health

traces is the right choice when the underlying service already records the span (via the Squasher edge SDK or any OTLP client) and you don’t want to also emit a duplicate duration metric. Span attributes are queryable via group_by and filters (service, status, or any custom span attribute name).

{
  "kind": "dashboard_definition",
  "version": "dashboard-definition/v1",
  "definition_id": "service-latency",
  "name": "Service Latency",
  "description": "Track request latency and volume for one service.",
  "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"
      }
    },
    {
      "widget_id": "request-volume",
      "title": "Request volume",
      "chart_type": "bar",
      "position": { "x": 6, "y": 0, "w": 6, "h": 4 },
      "query": {
        "source": "metrics",
        "aggregation": "sum",
        "metric_name": "http.server.request.count",
        "metric_type": "sum",
        "service_name": "api",
        "time_range": "24h"
      }
    }
  ]
}

API

Apply a definition in one request:

curl https://api.squasher.ai/v1/projects/{project_id}/dashboards/apply \
  -H "x-squasher-key: sq_pk_your_key_here" \
  -H "content-type: application/json" \
  -d @dashboard-apply.json

Example request body:

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

If you want to update an existing dashboard instead of creating a new one, include dashboard_id beside definition.

CLI

List dashboards:

squasher dashboards list --project YOUR_PROJECT_ID

List templates:

squasher dashboards templates --project YOUR_PROJECT_ID

Create from a template:

squasher dashboards from-template \
  --project YOUR_PROJECT_ID \
  --template-id internal-metrics-average

Execute a dashboard query directly:

squasher dashboards query \
  --project YOUR_PROJECT_ID \
  --source metrics \
  --aggregation avg \
  --time-range 24h \
  --metric-name http.server.duration \
  --metric-type hist \
  --service-name api

Use --from and --to for absolute query windows:

squasher dashboards query \
  --project YOUR_PROJECT_ID \
  --source logs \
  --aggregation count \
  --time-range 5m \
  --from 2026-04-01T00:00:00.000Z \
  --to 2026-04-01T00:05:00.000Z

Filter log/error dashboard queries with search syntax:

squasher dashboards query \
  --project YOUR_PROJECT_ID \
  --source logs \
  --aggregation count \
  --group-by level \
  --time-range 24h \
  --q 'service_name:api "database timeout"'

Apply a definition from a file:

squasher dashboards apply --project YOUR_PROJECT_ID ./dashboard-definition.json

To update an existing dashboard in place:

squasher dashboards apply \
  --project YOUR_PROJECT_ID \
  --dashboard-id DASHBOARD_ID \
  ./dashboard-definition.json

MCP

The hosted MCP server exposes the same workflows through Code Mode. Agents should call search for the operation they need, then execute the generated squasher.request(...) example. Useful searches:

search("dashboards.list")
search("dashboards.listTemplates")
search("dashboards.executeQuery")
search("dashboards.inspectQuery")
search("dashboards.apply")

Example prompt:

Apply the dashboard definition in this JSON to project 550e8400-e29b-41d4-a716-446655440000 and return the created dashboard.

Agent handoff

Use this prompt when asking an agent to create or update dashboards:

Create a Squasher dashboard definition for project <project_id>. Use the documented dashboard-definition/v1 shape, keep widget ids stable, use supported query sources only, validate with the Dashboards API or CLI, and ask before applying it to the project.

The manifest format also powers Squasher’s built-in operational dashboard templates, so the same apply surface works for custom dashboards instead of a UI-only flow.

Get Started

SDKs

Integrations

Migrations

Cloud Log Drains

Features

API Reference

Dashboards as Code

Dashboard workflow

Definition format

Valid widget query sources

API

CLI

MCP

Agent handoff

​Dashboard workflow

​Definition format

​Valid widget query sources

​API

​CLI

​MCP

​Agent handoff

​Related docs

Dashboard workflow

Definition format

Valid widget query sources

API

CLI

MCP

Agent handoff

Related docs