Sign in

v54

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-21125231416.4 KB
Dashboards

Create Widget

Adds a widget configuration to a dashboard and returns the id of the created widget. Use the dashboard detail endpoint for its full configuration, or a query endpoint for computed widget data.

post/v1/dashboards/{dashboardId}/widgets

Path parameters

dashboardIdstring required

The id of the dashboard.

Request body

namestring required

The widget's name.

descriptionstring nullable

An optional description of the widget.

type'LINE' | 'AREA' | 'BAR' | 'STACKED_BAR' | 'TABLE' | 'BIG_NUMBER'

The visualization type of a widget.

unit'COUNT' | 'PERCENT' | 'SCORE' | 'SECONDS' | 'USD' | 'MILLISECONDS'

The unit a widget's values are measured in.

mode'TIME_SERIES' | 'DIMENSION_SERIES'

How a widget aggregates its lines. TIME_SERIES plots each configured line over time; DIMENSION_SERIES takes a single metric and splits it into one series per value of the widget's dimension. This is the widget's saved configuration — it does not by itself describe the shape of a query response (use kind on the query result for that).

bucketMode'SERIES' | 'RANGE'

How a widget's data is bucketed over the query time range. SERIES splits the range into one bucket per granularity interval (a time series); RANGE aggregates the whole range into a single bucket (one total, as used by BIG_NUMBER widgets). Defaults to SERIES when omitted.

dimension'project' | 'trace_name' | 'span_name' | 'model' | 'type' | 'thread_id' | 'test_case_id' | 'test_run_id' | 'end_user' | 'source' | 'annotator' | 'name' | 'error' | 'prompt_alias' | 'tag' | 'label' | 'evaluation_model' | 'prompt_version' | 'prompt_label' | 'prompt_commit_hash' | 'metadata' | 'classifier'

The dimension a widget breaks down by when mode is DIMENSION_SERIES.

startTimestring date-time nullable

The start of the widget's custom time range, if set.

endTimestring date-time nullable

The end of the widget's custom time range, if set.

Example request

{
  "lines": [
    {
      "extraQueryParams": {
        "metricMetadataKey": "tokenCount"
      }
    }
  ]
}

Response

The id of the created widget.

successboolean required

Indicates if the request was successful.

deprecatedboolean required

Indicates if this endpoint is deprecated.