Dashboards API

Project dashboards let you build persistent, shareable views over normalized telemetry. Each dashboard is a collection of widgets that query traces, spans, logs, metrics, or conver

View as Markdown Open the plain-text version of this page.

When To Use It#

Use the Dashboards API when you want to:

create or update dashboards programmatically;
embed dashboard definitions in project configuration;
run ad-hoc widget queries outside the Workbench.

For interactive exploration, use the Workbench Dashboards view.

Dashboard Definition#

A dashboard contains a list of widgets. Each widget specifies a data source, visualization type, time range, and query. The exact shape is validated by the dashboard normalizer in @provon/observability/dashboards.

Common widget types include metric charts, trace lists, conversation tables, and value cards. Time ranges can be absolute or relative, for example last_24h or last_7d.

List Dashboards#

curl "$PROVON_API_URL/projects/$PROJECT_ID/dashboards" \
  -H "Authorization: Bearer $PROVON_API_KEY"

Create A Dashboard#

curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/dashboards" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gateway health",
    "description": "Request volume, errors, and latency",
    "widgets": [
      {
        "id": "requests",
        "type": "metric_chart",
        "title": "Gateway requests",
        "source": "traces",
        "timeRange": "last_24h",
        "query": { ... }
      }
    ]
  }'

Get, Update, And Delete#

# Get
curl "$PROVON_API_URL/projects/$PROJECT_ID/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $PROVON_API_KEY"

# Update
curl -X PATCH "$PROVON_API_URL/projects/$PROJECT_ID/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated name", "widgets": [ ... ]}'

# Delete
curl -X DELETE "$PROVON_API_URL/projects/$PROJECT_ID/dashboards/$DASHBOARD_ID" \
  -H "Authorization: Bearer $PROVON_API_KEY"

Set The Default Dashboard#

curl -X PUT "$PROVON_API_URL/projects/$PROJECT_ID/default-dashboard" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dashboardId": "<dashboard-id>"}'

The default dashboard is shown first when a project opens the Dashboards view.

Run a dashboard query and stream results:

curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/dashboard-queries" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "widgets": [
      {
        "id": "requests",
        "type": "metric_chart",
        "source": "traces",
        "timeRange": "last_24h",
        "query": { ... }
      }
    ]
  }'

The response is a Server-Sent Events stream (text/event-stream). Up to 24 widgets can be requested and up to 3 are executed concurrently.

Stream Events#

Event	Purpose
`init`	Sent once with `totalWidgets` and `maxConcurrency`.
`progress`	Sent when a widget completes, with `completedWidgets`, `totalWidgets`, `percent`, and `durationMs`.
`widget_data`	Sent once per widget with `widgetId`, `status` (`success` or `error`), `rows`, optional `trend`, and `durationMs`.
`complete`	Sent once at the end with `success`, `durationMs`, and `completedWidgets`.
`error`	Sent on stream processing failure.

Example stream:

event: init
data: {"totalWidgets":2,"maxConcurrency":3}

event: widget_data
data: {"widgetId":"requests","status":"success","rows":[...],"trend":null,"durationMs":120}

event: progress
data: {"completedWidgets":1,"totalWidgets":2,"percent":50,"durationMs":120}

event: widget_data
data: {"widgetId":"errors","status":"error","error":"...","rows":[],"durationMs":45}

event: progress
data: {"completedWidgets":2,"totalWidgets":2,"percent":100,"durationMs":165}

event: complete
data: {"success":true,"durationMs":165,"completedWidgets":2}

The client should read events until the stream closes and handle error events as failures.

Capability Requirements#

The project API key needs:

workspace:read or project:read to list and get dashboards;
workspace:write or project:update to create, update, delete, and set the default dashboard;
telemetry:read or project:data:read to execute dashboard queries.

Limitations#

Dashboard definitions are project-scoped; sharing across projects requires copying the definition.
Widget query syntax is validated by the telemetry backend and may differ slightly between DuckDB and Cloudflare R2 SQL deployments.
The API does not render charts; it returns the query result data and metadata that the Workbench visualizes.