Update Widget

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

Replaces a widget's configuration and returns it. This is a full replacement: every field you leave out is cleared, apart from layout and lines, which keep what is stored until you send them. Sending lines replaces the widget's lines outright, so the returned lines have new ids.

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

curl -X PUT "https://api.confident-ai.com/v2/dashboards/{dashboardId}/widgets/{widgetId}" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Trace volume",
  "description": "Traces served per day across production.",
  "type": "LINE",
  "unit": "COUNT",
  "mode": "TIME_SERIES",
  "bucketMode": "SERIES",
  "dimension": "model",
  "topK": {
    "limit": 10,
    "orderBy": "p90_latency",
    "direction": "desc"
  },
  "startTime": "2025-01-01T00:00:00.000Z",
  "endTime": "2025-01-31T23:59:59.999Z",
  "layout": {
    "x": 0,
    "y": 0,
    "w": 6,
    "h": 2
  },
  "lines": [
    {
      "name": "Traces",
      "color": "BLUE",
      "dataModel": "TRACE",
      "aggregation": "COUNT",
      "filters": {
        "operator": "AND",
        "groups": [
          {
            "operator": "AND",
            "filters": [
              {
                "category": "User Id",
                "condition": "Is less than",
                "value": "string",
                "key": "string"
              }
            ]
          }
        ]
      },
      "extraQueryParams": {
        "metricMetadataKey": "tokenCount"
      }
    }
  ]
}'

200

{
  "success": true,
  "data": {
    "id": "<WIDGET-ID>",
    "name": "Trace volume",
    "description": "Traces served per day across production.",
    "type": "LINE",
    "unit": "COUNT",
    "mode": "TIME_SERIES",
    "bucketMode": "SERIES",
    "dimension": "project",
    "topK": {
      "limit": 10,
      "orderBy": "p90_latency",
      "direction": "desc"
    },
    "startTime": null,
    "endTime": null,
    "layout": {
      "x": 0,
      "y": 0,
      "w": 6,
      "h": 2
    },
    "lines": [
      {
        "id": "<LINE-ID>",
        "name": "Traces",
        "color": "AMBER",
        "dataModel": "TRACE",
        "aggregation": "AVG_COST",
        "filters": {
          "operator": "AND",
          "groups": [
            {
              "operator": "AND",
              "filters": [
                {
                  "category": "User Id",
                  "condition": "Is less than",
                  "value": "string",
                  "key": "string"
                }
              ]
            }
          ]
        },
        "extraQueryParams": {}
      }
    ]
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

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

Request body

namestringRequired
The name shown as the widget's title.
descriptionstring | null
What the widget shows. Send null to leave it unset.
typeenum | null
The visualization a widget is drawn as. It is how the widget is displayed and does not by itself decide the shape of a query response — a TABLE widget returns tabular data whatever its mode is.
Show 7 enum valuesHide 7 enum values
- LINE
- AREA
- BAR
- STACKED_BAR
- GROUPED_BAR
- TABLE
- BIG_NUMBER
unitenum | null
The unit a widget's values are measured in.
Show 6 enum valuesHide 6 enum values
- COUNT
- PERCENT
- SCORE
- SECONDS
- USD
- MILLISECONDS
modeenum | null
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 — the shape of a query response is given by kind on the result.
Show 2 enum valuesHide 2 enum values
- TIME_SERIES
- DIMENSION_SERIES
bucketModeenum | null
How a widget's data is bucketed over the query time range. SERIES splits the range into one bucket per granularity interval; RANGE aggregates the whole range into a single bucket, as a BIG_NUMBER widget wants. Defaults to SERIES.
Show 2 enum valuesHide 2 enum values
- SERIES
- RANGE
dimensionenum | null
The property a widget breaks its data down by, one series or table row per distinct value.
Show 26 enum valuesHide 26 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
- hyperparameter
- classifier
- polarity
- classifier_label
- version
topKobject | null
Caps a dimension breakdown at the most interesting values, so a dimension with thousands of values still plots.
Show 3 propertiesHide 3 properties
- limitinteger
  The number of series or rows to keep, taking the highest or lowest by orderBy. Defaults to 10.
- orderByenum | enum
  The metric or column the dimension values are ranked by. Defaults to count.
  Show 2 variantsHide 2 variants
  - enum
    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
    pass_count
    avg_score
    stddev_score
    median_score
    avg_rating
    score_histogram
  - OR
  - enum
    Show 3 enum valuesHide 3 enum values
    created_at
    start_time
    dimension
- directionenum
  Whether to keep the highest ranked values or the lowest. Defaults to desc.
  Show 2 enum valuesHide 2 enum values
  - asc
  - desc
startTimestring | null
The start of the widget's own time range, as an ISO 8601 datetime. Send null to let the query decide the range.
endTimestring | null
The end of the widget's own time range, as an ISO 8601 datetime. Send null to let the query decide the range.
layoutobject | null
A widget's position and size on the dashboard's 12-column grid. Omit it when creating a widget and Confident AI packs it into the first free space.
Show 4 propertiesHide 4 properties
- xnumberRequired
  The widget's left edge, as a column index on the 12-column grid.
- ynumberRequired
  The widget's top edge, as a row index on the grid.
- wnumberRequired
  The widget's width in grid columns.
- hnumberRequired
  The widget's height in grid rows.
linesarray | null
The series the widget plots.
Show 6 propertiesHide 6 properties
- namestringRequired
  The name the line is labelled with in the legend.
- colorenum | null
  The colour a line is drawn in, from the Confident AI palette. A line you create without one is assigned the next colour in the palette.
  Show 10 enum valuesHide 10 enum values
  - AMBER
  - VIOLET
  - EMERALD
  - BLUE
  - PINK
  - CYAN
  - ROSE
  - LIME
  - TEAL
  - ORANGE
- dataModelenum | null
  The entity a widget line aggregates over. It decides which aggregations, filters and extraQueryParams the line accepts.
  Show 12 enum valuesHide 12 enum values
  - TRACE
  - SPAN
  - LLM_SPAN
  - AGENT_SPAN
  - RETRIEVER_SPAN
  - TOOL_SPAN
  - CUSTOM_SPAN
  - THREAD
  - END_USER
  - METRIC_DATA
  - ANNOTATION
  - CLASSIFICATION
- aggregationenum | null
  The aggregation a line computes, given as its token. Which tokens apply depends on the line's dataModel — AVG_RATING belongs to ANNOTATION lines, TOTAL_TOKENS to span lines — and a token that does not apply to the line's data model is rejected with the list of the ones that do.
  Show 26 enum valuesHide 26 enum values
  - AVG_COST
  - AVG_COST_PER_USER
  - AVG_LATENCY
  - AVG_RATING
  - AVG_SCORE
  - COUNT
  - ERROR_COUNT
  - ERROR_RATE
  - FAILURE_RATE
  - INPUT_COST
  - INPUT_TOKENS
  - MEDIAN_SCORE
  - NEW_USERS
  - OUTPUT_COST
  - OUTPUT_TOKENS
  - P50_LATENCY
  - P90_LATENCY
  - P99_LATENCY
  - PASS_RATE
  - RETENTION
  - TOTAL_COST
  - TOTAL_TOKENS
  - UNIQUE_END_USERS
  - UNIQUE_METADATA_VALUES
  - UNIQUE_THREADS
  - UNIQUE_USERS
- filtersobject | null
  A set of filter groups combined by a top-level operator. Each group combines its filter rows by its own operator, and each row matches one property, such as Name or User Id, against a value with a condition such as Is or Contains.
  Show 2 propertiesHide 2 properties
  - operatorenumRequired
    Show 2 enum valuesHide 2 enum values
    AND
    OR
  - groupslist of objectsRequired
    Show 2 propertiesHide 2 properties
    operatorenumRequired
    Show 2 enum valuesHide 2 enum values
    AND
    OR
    filterslist of objectsRequired
    Show 4 propertiesHide 4 properties
    categoryenumRequired
    Show 80 enum valuesHide 80 enum values
    User Id
    Thread Id
    Trace Uuid
    Trace Name
    Trace Version
    Trace Status
    Trace Tags
    Trace
    Span Uuid
    Name
    Span Name
    Span Type
    Span Status
    Metrics Status
    Error Status
    Name
    Model
    Provider
    Integration
    Embedder
    Chunk Size
    Top-K
    Hyperparameter
    Dataset
    Dataset Name
    Test Run ID
    Identifier
    Test File
    Status
    Official
    Evals Mode
    Tests Passed
    Tests Failed
    Pass Rate
    Fail Rate
    Star Rating
    Thumbs Rating
    Explanation
    Expected Output
    Expected Outcome
    Annotator
    End User
    Annotation Type
    Annotation Name
    Criteria
    Annotation Date
    Metric Score
    Metric Status
    Name
    Metadata
    Classifier
    Metric
    Metric Name
    Trace Count
    Test Case ID
    Requested review from
    Assigned to
    Tags
    Labels
    Tools Called
    Finalized
    Golden ID
    Ingestion Task
    Latency
    Environment
    Review flag
    Vulnerability
    Vulnerability Type
    Attack Method
    Risk Category
    Framework
    Assessment ID
    Prompt Alias
    Prompt Version
    Prompt Label
    Prompt Commit Hash
    Prompt
    Annotations
    Status Code
    Actor Type
    conditionenum | enum | enum | enum | enum | enum | enum | enum | enum | enumRequired
    Show 10 variantsHide 10 variants
    enum
    Show 6 enum valuesHide 6 enum values
    Is less than
    Is equal or less than
    Is greater than
    Is equal or greater than
    Is equal to
    Does not equal
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Has
    Has not
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Is
    Is not
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Is one of
    Is not one of
    OR
    enum
    Show 4 enum valuesHide 4 enum values
    Is
    Is not
    Is empty
    Is not empty
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Contains
    Does not contain
    OR
    enum
    Show 3 enum valuesHide 3 enum values
    Contains
    Contains only
    Does not contain
    OR
    enum
    Show 4 enum valuesHide 4 enum values
    Has decreased by more than
    Has decreased by less than
    Has increased by more than
    Has increased by less than
    OR
    enum
    Show 1 enum valueHide 1 enum value
    Has changed from
    OR
    enum
    Show 1 enum valueHide 1 enum value
    Is between
    valuestring | number | list of stringsRequired
    Show 3 variantsHide 3 variants
    string
    OR
    number
    OR
    list of strings
    keystring
- extraQueryParamsobject | null
  Advanced per-line query parameters, whose recognised keys depend on the line's dataModel. spanType restricts a SPAN line to one span type; metricMetadataKey names the metadata field a span, trace or thread line aggregates; category and metricName pick out the metric a METRIC_DATA line reads; dataType and source say which annotations an ANNOTATION line counts. Unrecognised keys are ignored, and most lines send none of these.

Response

Update Widget succeeded.

successboolean
Indicates if the request was successful.
dataobject
One chart on a dashboard, with the configuration a query computes it from.
Show 13 propertiesHide 13 properties
- idstring
  The id of the widget, generated by Confident AI.
- namestring
  The name shown as the widget's title.
- descriptionstring | null
  What the widget shows, or null when it has no description.
- typeenum | null
  The visualization a widget is drawn as. It is how the widget is displayed and does not by itself decide the shape of a query response — a TABLE widget returns tabular data whatever its mode is.
  Show 7 enum valuesHide 7 enum values
  - LINE
  - AREA
  - BAR
  - STACKED_BAR
  - GROUPED_BAR
  - TABLE
  - BIG_NUMBER
- unitenum | null
  The unit a widget's values are measured in.
  Show 6 enum valuesHide 6 enum values
  - COUNT
  - PERCENT
  - SCORE
  - SECONDS
  - USD
  - MILLISECONDS
- modeenum | null
  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 — the shape of a query response is given by kind on the result.
  Show 2 enum valuesHide 2 enum values
  - TIME_SERIES
  - DIMENSION_SERIES
- bucketModeenum | null
  How a widget's data is bucketed over the query time range. SERIES splits the range into one bucket per granularity interval; RANGE aggregates the whole range into a single bucket, as a BIG_NUMBER widget wants. Defaults to SERIES.
  Show 2 enum valuesHide 2 enum values
  - SERIES
  - RANGE
- dimensionenum | null
  The property a widget breaks its data down by, one series or table row per distinct value.
  Show 26 enum valuesHide 26 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
  - hyperparameter
  - classifier
  - polarity
  - classifier_label
  - version
- topKobject | null
  Caps a dimension breakdown at the most interesting values, so a dimension with thousands of values still plots.
  Show 3 propertiesHide 3 properties
  - limitinteger
    The number of series or rows to keep, taking the highest or lowest by orderBy. Defaults to 10.
  - orderByenum | enum
    The metric or column the dimension values are ranked by. Defaults to count.
    Show 2 variantsHide 2 variants
    enum
    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
    pass_count
    avg_score
    stddev_score
    median_score
    avg_rating
    score_histogram
    OR
    enum
    Show 3 enum valuesHide 3 enum values
    created_at
    start_time
    dimension
  - directionenum
    Whether to keep the highest ranked values or the lowest. Defaults to desc.
    Show 2 enum valuesHide 2 enum values
    asc
    desc
- startTimestring | null
  The start of the widget's own time range, or null when it has none.
- endTimestring | null
  The end of the widget's own time range, or null when it has none.
- layoutobject | null
  A widget's position and size on the dashboard's 12-column grid. Omit it when creating a widget and Confident AI packs it into the first free space.
  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 the widget plots.
  Show 7 propertiesHide 7 properties
  - idstring
    The id of the line, generated by Confident AI.
  - namestring
    The name the line is labelled with in the legend.
  - colorenum
    The colour a line is drawn in, from the Confident AI palette. A line you create without one is assigned the next colour in the palette.
    Show 10 enum valuesHide 10 enum values
    AMBER
    VIOLET
    EMERALD
    BLUE
    PINK
    CYAN
    ROSE
    LIME
    TEAL
    ORANGE
  - dataModelenum | null
    The entity a widget line aggregates over. It decides which aggregations, filters and extraQueryParams the line accepts.
    Show 12 enum valuesHide 12 enum values
    TRACE
    SPAN
    LLM_SPAN
    AGENT_SPAN
    RETRIEVER_SPAN
    TOOL_SPAN
    CUSTOM_SPAN
    THREAD
    END_USER
    METRIC_DATA
    ANNOTATION
    CLASSIFICATION
  - aggregationenum | null
    The aggregation a line computes, given as its token. Which tokens apply depends on the line's dataModel — AVG_RATING belongs to ANNOTATION lines, TOTAL_TOKENS to span lines — and a token that does not apply to the line's data model is rejected with the list of the ones that do.
    Show 26 enum valuesHide 26 enum values
    AVG_COST
    AVG_COST_PER_USER
    AVG_LATENCY
    AVG_RATING
    AVG_SCORE
    COUNT
    ERROR_COUNT
    ERROR_RATE
    FAILURE_RATE
    INPUT_COST
    INPUT_TOKENS
    MEDIAN_SCORE
    NEW_USERS
    OUTPUT_COST
    OUTPUT_TOKENS
    P50_LATENCY
    P90_LATENCY
    P99_LATENCY
    PASS_RATE
    RETENTION
    TOTAL_COST
    TOTAL_TOKENS
    UNIQUE_END_USERS
    UNIQUE_METADATA_VALUES
    UNIQUE_THREADS
    UNIQUE_USERS
  - filtersobject | null
    A set of filter groups combined by a top-level operator. Each group combines its filter rows by its own operator, and each row matches one property, such as Name or User Id, against a value with a condition such as Is or Contains.
    Show 2 propertiesHide 2 properties
    operatorenum
    Show 2 enum valuesHide 2 enum values
    AND
    OR
    groupslist of objects
    Show 2 propertiesHide 2 properties
    operatorenum
    Show 2 enum valuesHide 2 enum values
    AND
    OR
    filterslist of objects
    Show 4 propertiesHide 4 properties
    categoryenum
    Show 80 enum valuesHide 80 enum values
    User Id
    Thread Id
    Trace Uuid
    Trace Name
    Trace Version
    Trace Status
    Trace Tags
    Trace
    Span Uuid
    Name
    Span Name
    Span Type
    Span Status
    Metrics Status
    Error Status
    Name
    Model
    Provider
    Integration
    Embedder
    Chunk Size
    Top-K
    Hyperparameter
    Dataset
    Dataset Name
    Test Run ID
    Identifier
    Test File
    Status
    Official
    Evals Mode
    Tests Passed
    Tests Failed
    Pass Rate
    Fail Rate
    Star Rating
    Thumbs Rating
    Explanation
    Expected Output
    Expected Outcome
    Annotator
    End User
    Annotation Type
    Annotation Name
    Criteria
    Annotation Date
    Metric Score
    Metric Status
    Name
    Metadata
    Classifier
    Metric
    Metric Name
    Trace Count
    Test Case ID
    Requested review from
    Assigned to
    Tags
    Labels
    Tools Called
    Finalized
    Golden ID
    Ingestion Task
    Latency
    Environment
    Review flag
    Vulnerability
    Vulnerability Type
    Attack Method
    Risk Category
    Framework
    Assessment ID
    Prompt Alias
    Prompt Version
    Prompt Label
    Prompt Commit Hash
    Prompt
    Annotations
    Status Code
    Actor Type
    conditionenum | enum | enum | enum | enum | enum | enum | enum | enum | enum
    valuestring | number | list of strings
    keystring
  - extraQueryParamsobject | null
    Advanced per-line query parameters, whose recognised keys depend on the line's dataModel. spanType restricts a SPAN line to one span type; metricMetadataKey names the metadata field a span, trace or thread line aggregates; category and metricName pick out the metric a METRIC_DATA line reads; dataType and source say which annotations an ANNOTATION line counts. Unrecognised keys are ignored, and most lines send none of these.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI