Update Widget

PUThttps://api.confident-ai.com/v1/dashboards/{dashboardId}/widgets/{widgetId}

Updates a widget configuration and returns the id of the updated widget. Provided fields replace its configuration, omitted scalar fields are cleared, and lines replace the existing lines when provided.

PUT/v1/dashboards/{dashboardId}/widgets/{widgetId}

curl -X PUT "https://api.confident-ai.com/v1/dashboards/{dashboardId}/widgets/{widgetId}" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Trace Count",
  "type": "BAR",
  "unit": "COUNT",
  "mode": "TIME_SERIES",
  "lines": [
    {
      "name": "Count",
      "dataModel": "TRACE",
      "aggregation": "COUNT"
    }
  ]
}'

200

{
  "success": true,
  "data": {
    "id": "WIDGET-ID"
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

dashboardIdstringRequired
The id of the dashboard.
widgetIdstringRequired
The id of the widget.

Request body

namestringRequired
The widget's name.
descriptionstring
An optional description of the widget.
typeenum
The visualization type of a widget.
Show 6 enum valuesHide 6 enum values
- LINE
- AREA
- BAR
- STACKED_BAR
- TABLE
- BIG_NUMBER
unitenum
The unit a widget's values are measured in.
Show 6 enum valuesHide 6 enum values
- COUNT
- PERCENT
- SCORE
- SECONDS
- USD
- MILLISECONDS
modeenum
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).
Show 2 enum valuesHide 2 enum values
- TIME_SERIES
- DIMENSION_SERIES
bucketModeenum
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.
Show 2 enum valuesHide 2 enum values
- SERIES
- RANGE
dimensionenum
The dimension a widget breaks down by when mode is DIMENSION_SERIES.
Show 22 enum valuesHide 22 enum values
- 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
topKobject
Limits a dimension breakdown to the top K series.
Show 3 propertiesHide 3 properties
- limitinteger
  Maximum number of series to return. Defaults to 10.
- orderByenum
  The metric or column to order topK results by.
  Show 28 enum valuesHide 28 enum values
  - count
  - avg_latency
  - p50_latency
  - p90_latency
  - p99_latency
  - error_rate
  - pass_rate
  - failure_rate
  - input_cost
  - output_cost
  - total_cost
  - avg_cost
  - input_tokens
  - output_tokens
  - total_tokens
  - count_distinct_endUserId
  - count_distinct_threadId
  - count_distinct_model
  - count_distinct_projectId
  - count_distinct_error
  - count_distinct_metadata
  - error_count
  - avg_score
  - stddev_score
  - avg_rating
  - created_at
  - start_time
  - dimension
- directionenum
  The sort direction for topK results.
  Show 2 enum valuesHide 2 enum values
  - asc
  - desc
startTimestring
The start of the widget's custom time range, if set.
endTimestring
The end of the widget's custom time range, if set.
layoutobject
A widget's position on the dashboard grid.
Show 4 propertiesHide 4 properties
- xnumber
  The widget's left edge as a column index on the 12-column grid.
- ynumber
  The widget's top edge as a row index on the grid.
- wnumber
  The widget's width in grid columns.
- hnumber
  The widget's height in grid rows.
lineslist of objects
The series to show in the widget.
Show 6 propertiesHide 6 properties
- namestringRequired
  The line's name.
- colorenum
  The color of a line. If omitted or unrecognized, a color is auto-assigned from the palette.
  Show 10 enum valuesHide 10 enum values
  - AMBER
  - VIOLET
  - EMERALD
  - BLUE
  - PINK
  - CYAN
  - ROSE
  - LIME
  - TEAL
  - ORANGE
- dataModelenum
  The entity a line aggregates over.
  Show 11 enum valuesHide 11 enum values
  - TRACE
  - SPAN
  - LLM_SPAN
  - AGENT_SPAN
  - RETRIEVER_SPAN
  - TOOL_SPAN
  - CUSTOM_SPAN
  - THREAD
  - END_USER
  - METRIC_DATA
  - ANNOTATION
- aggregationenum
  The aggregation applied to a line. The set of valid values depends on the line's dataModel.
  Show 25 enum valuesHide 25 enum values
  - COUNT
  - ERROR_RATE
  - PASS_RATE
  - UNIQUE_END_USERS
  - UNIQUE_THREADS
  - UNIQUE_USERS
  - UNIQUE_METADATA_VALUES
  - AVG_LATENCY
  - P50_LATENCY
  - P90_LATENCY
  - P99_LATENCY
  - TOTAL_COST
  - AVG_COST
  - INPUT_COST
  - OUTPUT_COST
  - AVG_COST_PER_USER
  - INPUT_TOKENS
  - OUTPUT_TOKENS
  - TOTAL_TOKENS
  - ERROR_COUNT
  - NEW_USERS
  - RETENTION
  - AVG_SCORE
  - FAILURE_RATE
  - AVG_RATING
- filtersobject
  A set of filter groups combined by a top-level operator.
  Show 2 propertiesHide 2 properties
  - operatorenumRequired
    How filters or groups are combined.
    Show 2 enum valuesHide 2 enum values
    AND
    OR
  - groupslist of objectsRequired
    The filter groups.
    Show 2 propertiesHide 2 properties
    operatorenumRequired
    How filters or groups are combined.
    Show 2 enum valuesHide 2 enum values
    AND
    OR
    filterslist of objectsRequired
    The filter rows in this group.
    Show 4 propertiesHide 4 properties
    categorystringRequired
    The property a filter row matches on (e.g. "Name", "User Id", "Model", "Metadata"). The set of valid values depends on the line's dataModel.
    conditionenumRequired
    The comparison a filter row applies. Valid conditions depend on the category.
    Show 18 enum valuesHide 18 enum values
    Is
    Is not
    Is equal to
    Does not equal
    Is less than
    Is equal or less than
    Is greater than
    Is equal or greater than
    Has
    Has not
    Contains
    Contains only
    Does not contain
    Has increased by more than
    Has increased by less than
    Has decreased by more than
    Has decreased by less than
    Has changed from
    valuestring | number | list of stringsRequired
    The value to match against.
    Show 3 variantsHide 3 variants
    string
    OR
    number
    OR
    list of strings
    keystring
    The property key. Auto-populated from category when omitted; required for Metadata, Metric, and Classifier filters.
- extraQueryParamsobject
  Advanced, per-line query parameters. Which keys take effect depends on the line's dataModel, and unrecognized keys are ignored. All values are strings. Most lines leave this null.
  Show 6 propertiesHide 6 properties
  - spanTypeenum
    For a SPAN line, restricts aggregation to a single span type. Not needed for the typed span models (LLM_SPAN, AGENT_SPAN, RETRIEVER_SPAN, TOOL_SPAN, CUSTOM_SPAN), which already imply their span type.
    Show 5 enum valuesHide 5 enum values
    LLM
    AGENT
    RETRIEVER
    TOOL
    CUSTOM
  - metricMetadataKeystring
    For span (SPAN, LLM_SPAN, AGENT_SPAN, RETRIEVER_SPAN, TOOL_SPAN, CUSTOM_SPAN), TRACE, and THREAD lines, the metadata field key whose numeric value is aggregated.
  - categoryenum
    For a METRIC_DATA line, the entity category the metric is attached to.
    Show 11 enum valuesHide 11 enum values
    SINGLE_TURN
    MULTI_TURN
    TEST_RUN
    TRACE
    SPAN
    LLM_SPAN
    AGENT_SPAN
    RETRIEVER_SPAN
    TOOL_SPAN
    CUSTOM_SPAN
    THREAD
  - metricNamestring
    For a METRIC_DATA line, the name of the metric to aggregate.
  - dataTypeenum
    For an ANNOTATION line, which annotated entity type to aggregate over.
    Show 3 enum valuesHide 3 enum values
    Traces
    Spans
    Threads
  - sourceenum
    For an ANNOTATION line, whether to aggregate annotations left by end users or by reviewers.
    Show 2 enum valuesHide 2 enum values
    User
    Reviewer

Response

The id of the updated widget.

successboolean
Indicates if the request was successful.
dataobject
The id of the affected dashboard or widget.
Show 1 propertyHide 1 property
- idstring
  The id of the affected dashboard or widget.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI