---
title: "Edit a dashboard widget"
method: PATCH
path: "/api/v1/public/widgets/{widget_id}"
tags: ["Widgets"]
---

# Edit a dashboard widget

`PATCH /api/v1/public/widgets/{widget_id}`

## Request

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

Edit a widget's title, spec, or display config.

Requires MEMBER role or higher in the project's workspace (the write
service decides). A sent ``spec`` replaces the whole spec and is checked
against the widget's stored type by the service; ``type`` is immutable.

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.
    widget_id (str): The widget to edit.
    payload (UpdateWidgetRequest): The project and the fields to change.
    _live (None): Write-path liveness gate (blocks a revoked JWT session).

Returns:
    UpdateWidgetResponse: The updated widget and the changed fields.

Raises:
    HTTPException: The write service's 400/403/404 verbatim, or a 503
        when its response is ambiguous.

## Path parameters

- `widget_id` string, required

## Request body

- UpdateWidgetRequest: Body for editing a widget; ``type`` and ``dashboard_id`` are immutable.
  - `display_config` object, nullable: Replaces the whole display config; null resets it to {}
  - `project_id` string, required
  - `spec` union: Replaces the whole spec, in the dialect of the widget's stored type. 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

## Response `200`

Successful Response

- UpdateWidgetResponse: The updated widget.
  - `changed` string[], required
  - `updated` boolean, required
  - `widget` WidgetRow, required: A widget as the write service returns it.
    - `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)