Dashboards as code

A dashboard definition is a JSON file that lists the widgets of a dashboard and their queries. You keep the file in your repository, review changes to it like code, and apply it to a project.

Write a definition

Save the definition as a JSON file, for example dashboards/service-latency.json:

dashboards/service-latency.json

{
  "kind": "dashboard_definition",
  "version": "dashboard-definition/v1",
  "definition_id": "service-latency",
  "name": "Service latency",
  "description": "Request latency and volume for the api service.",
  "widgets": [
    {
      "widget_id": "request-latency",
      "title": "Request latency",
      "chart_type": "line",
      "position": { "x": 0, "y": 0, "w": 6, "h": 4 },
      "query": {
        "source": "traces",
        "aggregation": "p95",
        "metric_name": "GET /api/checkout",
        "service_name": "api",
        "time_range": "24h"
      }
    },
    {
      "widget_id": "error-logs",
      "title": "Error logs by service",
      "chart_type": "bar",
      "position": { "x": 6, "y": 0, "w": 6, "h": 4 },
      "query": {
        "source": "logs",
        "aggregation": "count",
        "group_by": "service",
        "q": "level:error",
        "time_range": "24h"
      }
    }
  ]
}

Keep widget_id values stable. They let Squasher update the same widgets when you apply the file again.

Apply the definition

With the CLI, after you sign in with squasher login:

squasher dashboards apply --project "$SQUASHER_PROJECT_ID" dashboards/service-latency.json

To update a dashboard that already exists, add --dashboard-id <dashboard_id>. With the API, send the definition in a definition field. Add dashboard_id next to it to update an existing dashboard.

curl https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/dashboards/apply \
  -H "x-squasher-key: $SQUASHER_API_KEY" \
  -H "content-type: application/json" \
  -d "{\"definition\": $(cat dashboards/service-latency.json)}"

The API returns 201 when it creates a dashboard and 200 when it updates one. The key needs the project:write scope. The ingest key from the Setup page does not have it. See API keys and Dashboards API.

Definition reference

Field	Values
`chart_type`	`line`, `bar`, `area`, `pie`, or `table`.
`position`	`x` and `y` from 0, and `w` and `h` from 1, in grid units.
`query.aggregation`	`count`, `avg`, `p50`, `p90`, `p95`, `p99`, or `sum`.
`query.time_range`	For example `5m`, `24h`, or `7d`.
`query.metric_type`	For `metrics`: `gauge`, `sum`, `hist`, or `exponential_histogram`.
`query.group_by`	A field to split the series by. For `logs` and `errors`: `service`, `level`, `environment`, `release`, `source`, `platform`, `browser`, or `os`. Events without a value for the field are in the `(none)` group.
`query.filters`	A list of `{ "field", "operator", "value" }`. The operator is `eq` or `neq`.
`query.q`	A search query. Only for the `logs` and `errors` sources.
`category`	Optional. The group a template is listed under: `application`, `runtime`, `database`, `infrastructure`, `edge`, `ai`, or `web`.
`requires`	Optional. The data the dashboard needs: `signals`, `metric_prefixes`, and span `attributes` (`key`, optional `values`). Used for readiness checks.

Source	What it queries
`metrics`	OpenTelemetry metrics. Set `metric_name` and `metric_type`.
`logs`	Logs from SDKs, log drains, and OpenTelemetry.
`traces`	Span counts and durations. Set `metric_name` to a span name, or omit it for every span. Filter or group by `service`, `status_code`, `span_kind`, or a span attribute.
`errors`	Issues and their events.
`vitals`	Web Vitals from the browser SDK.
`fixes`	Auto-fix runs.
`ai`	AI observations from your app.
`ingestion`	The delay and health of data delivery to Squasher.

Start from a template

List the built-in templates and whether your project has the data each one needs, preview one with your data, then create a dashboard from it:

squasher dashboards templates --project "$SQUASHER_PROJECT_ID"
squasher dashboards templates --project "$SQUASHER_PROJECT_ID" --preview service-health --time-range 24h
squasher dashboards from-template --project "$SQUASHER_PROJECT_ID" --template-id service-health

In the dashboard, select Dashboards, then the Templates tab. Templates are grouped by Ready and Needs setup. Select a template to see its widgets with your data, then select Create dashboard. A template that needs setup shows what to send and a link to the setup guide.

Test a query before you apply it

Run one widget query from the CLI to check the result:

squasher dashboards query --project "$SQUASHER_PROJECT_ID" \
  --source logs --aggregation count --group-by level --time-range 24h

squasher dashboards inspect-query takes the same flags and returns a summary of the result that is easier to read.

See the dashboard

Select Dashboards in the sidebar, under Telemetry, and open the dashboard. Choose a time range, an Environment, and a Service at the top. To change the layout by hand, select Edit layout. To add a widget, select Add widget. Changes that you make in the dashboard are not written back to your file. Apply the file again to restore its version.

Get started

Guides

Dashboards as code

Write a definition

Apply the definition

Definition reference

Valid widget query sources

Start from a template

Test a query before you apply it

See the dashboard

Next steps

Explore

MCP

​Write a definition

​Apply the definition

​Definition reference

​Valid widget query sources

​Start from a template

​Test a query before you apply it

​See the dashboard

​Next steps

Explore

MCP

Write a definition

Apply the definition

Definition reference

Valid widget query sources

Start from a template

Test a query before you apply it

See the dashboard

Next steps