Query Ad-hoc Widget Data

POSThttps://api.confident-ai.com/v1/widgets/query

Computes widget data from a widget definition supplied inline, without creating a dashboard or saving a widget. Returns the same data shape as the dashboard widget query. Scoped to the project of the API key. At most 20 lines and a topK.limit of 100 are allowed, and an explicit query range may not exceed 366 days.

POST/v1/widgets/query

curl -X POST "https://api.confident-ai.com/v1/widgets/query" \
  -H "Content-Type: application/json" \
  -d '{
  "widget": {
    "name": "Trace Count",
    "type": "LINE",
    "unit": "COUNT",
    "mode": "TIME_SERIES",
    "lines": [
      {
        "name": "Count",
        "dataModel": "TRACE",
        "aggregation": "COUNT"
      }
    ]
  },
  "startTime": "2024-01-01T00:00:00.000Z",
  "endTime": "2024-01-31T23:59:59.999Z",
  "granularity": "day"
}'

200

{
  "success": true,
  "data": {
    "type": "LINE",
    "mode": "TIME_SERIES",
    "kind": "TIME_SERIES",
    "unit": "COUNT",
    "xAxis": {
      "type": "time"
    },
    "series": [
      {
        "key": "Count",
        "name": "Count",
        "color": "BLUE",
        "lineId": "line-0",
        "points": [
          {
            "x": "2024-01-01T00:00:00.000Z",
            "y": 42
          }
        ]
      }
    ]
  },
  "deprecated": false
}

Request body

widgetobjectRequired
The widget configuration to compute data for.
Show 12 propertiesHide 12 properties
- 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.
    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
startTimestring
ISO 8601 start time for the query range. Must be provided with endTime.
endTimestring
ISO 8601 end time for the query range. Must be provided with startTime.
granularityenum
Optional bucket granularity override for the query.
Show 5 enum valuesHide 5 enum values
- thirty_minutes
- hour
- day
- week
- month

Response

The computed data for the supplied widget.

successboolean
Indicates if the request was successful.
dataobject
The computed widget data.
Show 9 propertiesHide 9 properties
- typeenum
  The widget's visualization (display) type, echoed from the request.
  Show 6 enum valuesHide 6 enum values
  - LINE
  - AREA
  - BAR
  - STACKED_BAR
  - TABLE
  - BIG_NUMBER
- modeenum
  The widget's aggregation mode, echoed from the request. Branch on kind rather than mode when reading the response.
  Show 2 enum valuesHide 2 enum values
  - TIME_SERIES
  - DIMENSION_SERIES
- kindenum
  The shape of the data in this response, and the field to branch on when reading it. TIME_SERIES and DIMENSION populate series (with xAxis.type time and category respectively); BIG_NUMBER populates values; TABLE populates columns and rows.
  Show 4 enum valuesHide 4 enum values
  - TIME_SERIES
  - DIMENSION
  - BIG_NUMBER
  - TABLE
- unitenum
  Unit for the returned values, when applicable.
  Show 6 enum valuesHide 6 enum values
  - COUNT
  - PERCENT
  - SCORE
  - SECONDS
  - USD
  - MILLISECONDS
- xAxisobject
  Present for TIME_SERIES and DIMENSION data.
  Show 1 propertyHide 1 property
  - typeenum
    Axis type for the returned data.
    Show 2 enum valuesHide 2 enum values
    time
    category
- serieslist of objects
  Present for TIME_SERIES and DIMENSION data.
  Show 5 propertiesHide 5 properties
  - keystring
    Stable key that uniquely identifies this series within the result. Use it to correlate series across queries or as a render key.
  - namestring
    Display name for the series.
  - colorstring
    Display color for the series.
  - lineIdstring
    The line id that produced this series, when applicable.
  - pointslist of objects
    Points in this series.
    Show 2 propertiesHide 2 properties
    xstring
    Time bucket start or category label.
    ynumber
    Numeric value for the series at this point, or null when no data is available.
- valueslist of objects
  Present for BIG_NUMBER data.
  Show 5 propertiesHide 5 properties
  - keystring
    Stable key that uniquely identifies this value within the result.
  - namestring
    Display name for the value.
  - colorstring
    Display color for the value.
  - lineIdstring
    The line id that produced this value, when applicable.
  - valuenumber
    Scalar value, or null when no data is available.
- columnslist of objects
  Column definitions for TABLE data. The first column is the dimension (key dimension); the remaining columns are one per line, keyed by the line's name.
  Show 2 propertiesHide 2 properties
  - keystring
    Stable column key. Read each row's value for this column as row[key].
  - labelstring
    Display label for the column.
- rowslist of objects
  Present for TABLE data.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI