---
title: "Create a dashboard widget"
method: POST
path: "/api/v1/public/widgets"
tags: ["Widgets"]
---

# Create a dashboard widget

`POST /api/v1/public/widgets`

## Request

- Base URL: `https://app.traceroot.ai`
- URL: `https://app.traceroot.ai/api/v1/public/widgets`
- Auth: HTTP bearer

Create a widget on a dashboard the authenticated user can write to.

Requires MEMBER role or higher in the project's workspace (the write
service decides). Strict create — never idempotent, ``created`` is always
``true`` on success.

Args:
    request (Request): Incoming request (rate-limit plumbing).
    response (Response): Outgoing response (rate-limit plumbing).
    auth (AccountStampedAuth): Account-scope user auth (session token or
        CLI access JWT); its resolved ``user_id`` becomes the actor.
    payload (CreateWidgetRequest): The widget to create.
    _live (None): Write-path liveness gate (blocks a revoked JWT session).

Returns:
    CreateWidgetResponse: The created widget.

## Request body

- CreateWidgetRequest: Body for creating a widget on a dashboard. Unlike the other create bodies, ``spec`` is deep-validated here: it is a structured contract the agent/CLI must compose (a wrong shape only surfaces at render time otherwise), and the union below is what generated tool schemas show the model.
  - `dashboard_id` string, required
  - `display_config` object, nullable
  - `project_id` string, required
  - `spec` union, required: The widget's content. For type "query": a chart spec (view/filters/metric/breakdown/display). For type "trace_feed": a trace-list feed spec (predicate filters + row limit).
    - object: Chart spec over the "spans" view; the enums below are the complete field vocabulary for this view.
      - `breakdown` 'name' | 'span_kind' | 'error_type' | 'model_name' | 'environment' | 'null', nullable
      - `display` object, required: Controls how the query result is rendered on the dashboard.
        - `type` 'line' | 'area' | 'bar' | 'pie' | 'number' | 'table' | 'histogram', required
      - `filters` object[]
        - `field` 'name' | 'span_kind' | 'status' | 'error_type' | 'model_name' | 'environment' | 'is_root' | 'duration_ms' | 'cost' | 'input_tokens' | 'output_tokens' | 'cache_read_tokens' | 'cache_write_tokens' | 'total_tokens' | 'metadata', required
        - `key` string
        - `op` '=' | 'contains' | 'in' | '>' | '>=' | '<' | '<=', required
        - `value` union, required
          - string
          - number
          - string[]
      - `metric` object, required: The measure and aggregation function that define the widget's y-axis.
        - `agg` 'count' | 'sum' | 'avg' | 'min' | 'max' | 'p50' | 'p75' | 'p90' | 'p95' | 'p99' | 'uniq', required
        - `measure` 'duration_ms' | 'cost' | 'input_tokens' | 'output_tokens' | 'cache_read_tokens' | 'cache_write_tokens' | 'total_tokens' | 'tokens_per_second' | 'trace_id' | 'count', required
      - `view` 'spans', required
    - object: Chart spec over the "traces" view; the enums below are the complete field vocabulary for this view.
      - `breakdown` 'name' | 'user_id' | 'session_id' | 'environment' | 'null', nullable
      - `display` object, required: Controls how the query result is rendered on the dashboard.
        - `type` 'line' | 'area' | 'bar' | 'pie' | 'number' | 'table' | 'histogram', required
      - `filters` object[]
        - `field` 'name' | 'user_id' | 'session_id' | 'environment' | 'duration_ms' | 'cost' | 'input_tokens' | 'output_tokens' | 'cache_read_tokens' | 'cache_write_tokens' | 'total_tokens' | 'error_count', required
        - `key` string
        - `op` '=' | 'contains' | 'in' | '>' | '>=' | '<' | '<=', required
        - `value` union, required
          - string
          - number
          - string[]
      - `metric` object, required: The measure and aggregation function that define the widget's y-axis.
        - `agg` 'count' | 'sum' | 'avg' | 'min' | 'max' | 'p50' | 'p75' | 'p90' | 'p95' | 'p99' | 'uniq', required
        - `measure` 'duration_ms' | 'cost' | 'input_tokens' | 'output_tokens' | 'cache_read_tokens' | 'cache_write_tokens' | 'total_tokens' | 'count' | 'error_count', required
      - `view` 'traces', required
    - TraceFeedSpec: Spec for a ``trace_feed`` widget: a filtered live list of recent traces. Mirrors the trace-list predicate wire format (canonical shape: what ``isValidPredicate`` in frontend/ui/src/features/filters/predicate.ts accepts and the dashboard seed produces). ``limit`` carries the trace-list page-size bound; it defaults to 10 rows in the renderer when omitted.
      - `filters` union[]
        - union
          - TraceFeedInPredicate: Membership predicate: the field's value is one of the listed strings.
            - `field` string, required
            - `key` string
            - `op` 'in', required
            - `value` string[], required
          - TraceFeedNumericPredicate: Numeric comparison predicate (equality or ordering) on a finite number.
            - `field` string, required
            - `key` string
            - `op` 'eq' | 'gt' | 'gte' | 'lt' | 'lte', required
            - `value` number, required
          - TraceFeedTextPredicate: Text predicate: exact match or substring containment.
            - `field` string, required
            - `key` string
            - `op` 'eq' | 'contains', required
            - `value` string, required
      - `limit` integer
  - `title` string, required
  - `type` string, required

## Response `200`

Successful Response

- CreateWidgetResponse: The created widget (widget creation is strict, never idempotent).
  - `created` boolean, required
  - `dashboard_id` string, required
  - `id` string, required
  - `title` string, required
  - `type` string, required

## Other responses

- `400`: Invalid request
- `401`: Authentication failed or session revoked
- `403`: Insufficient role or wrong credential kind
- `404`: Not found
- `422`: Validation Error
- `503`: Write service unavailable

---

[API](https://skmtc.dev/traceroot/apis/traceroot-public-api.md) - [All operations](https://skmtc.dev/traceroot/apis/traceroot-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/traceroot/apis/traceroot-public-api/revisions/ce6aef96c0d6?raw)