Skip to main content
POST
Run Widget Query

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

project_id
string | null

Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project.

Body

application/json

Envelope that pairs a WidgetSpec with the time window to answer it for.

The window is either a range preset (the site picker's ids — how the agent and the CLI describe one) or explicit start_time/end_time (how the dashboard page and the card previews do). Neither means the site's default window; both, or one bound alone, is rejected. The rules live in rest.services.date_presets.resolve_window so every query surface applies the same ones.

spec
WidgetSpec · object
required

Full declarative specification of a single dashboard widget.

Mirrors the canonical zod WidgetSpecSchema (frontend/ui/src/features/dashboards/types.ts); the frontend widget-spec-parity test guards the two against structural drift.

bucket_seconds
integer | null
Required range: 1 <= x <= 86400
end_time
string<date-time> | null
range
enum<string> | null

A preset window ending now, by the site picker's id. Give this or explicit start_time/end_time; neither means the site's 24-hour default.

Available options:
30m,
1h,
3h,
6h,
1d,
7d,
14d,
30d,
60d,
90d
start_time
string<date-time> | null

Response

Successful Response

Query result returned to the frontend; meta carries display hints (e.g. granularity for time-series displays).

columns
string[]
required
rows
any[][]
required
window
QueryWindow · object
required

The window a query was actually answered for.

range is the preset id the caller gave (or the default's, when they gave nothing) and None for explicit bounds. clamped is True when the plan's retention pulled start_time forward — the honest reason a caller's window and the answered one differ.

meta
Meta · object