---
title: "Add a dashboard widget"
method: POST
path: "/api/v1/query/dashboards/{dashboardId}/widgets"
tags: ["query"]
---

# Add a dashboard widget

`POST /api/v1/query/dashboards/{dashboardId}/widgets`

## Request

- Base URL: `https://api.trigger.dev`
- URL: `https://api.trigger.dev/api/v1/query/dashboards/{dashboardId}/widgets`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/docs/api/v1/query/dashboards/:dashboardId/widgets/post.ts> (a function with typed inputs; its response is checked against the schema)

Add a widget to a custom dashboard. Without a position it is placed full width at the bottom.

## Request body

- object
  - `id` string: Omit to generate one. Letters, numbers, `_` and `-`, unique within the dashboard.
  - `title` string, required
  - `query` string: A TRQL query. Required unless the display type is `title`.
  - `display` union, required: How the widget renders its query results.
    - object
      - `type` 'table', required
      - `prettyFormatting` boolean
      - `sorting` object[]
        - `id` string
        - `desc` boolean
    - object
      - `type` 'chart', required
      - `chartType` 'bar' | 'line', required
      - `xAxisColumn` string, nullable, required
      - `yAxisColumns` string[], required
      - `groupByColumn` string, nullable, required
      - `stacked` boolean, required
      - `sortByColumn` string, nullable, required
      - `sortDirection` 'asc' | 'desc', required
      - `aggregation` 'sum' | 'avg' | 'count' | 'min' | 'max', required
      - `seriesColors` object
    - object
      - `type` 'bignumber', required
      - `column` string, required
      - `aggregation` 'sum' | 'avg' | 'count' | 'min' | 'max' | 'first' | 'last', required
      - `sortDirection` 'asc' | 'desc'
      - `abbreviate` boolean
      - `prefix` string
      - `suffix` string
    - object
      - `type` 'title', required
  - `fillGaps` boolean: Fill empty time buckets, carrying gauges forward and zero-filling counters.
  - `position` DashboardWidgetPosition: A position on the dashboard's 12-column grid.
    - `x` integer, required
    - `y` integer, required
    - `w` integer, required
    - `h` integer, required
  - `revision` string: The `revision` from the dashboard you last read. Send it to reject the write with a 409 if someone else changed the dashboard in the meantime.

## Response `201`

Widget added

- object
  - `widgetId` string
  - `dashboard` DashboardObject
    - `id` string: The dashboard id, starting with `dashboard_`
    - `title` string
    - `description` string
    - `revision` string: The `revision` from the dashboard you last read. Send it to reject the write with a 409 if someone else changed the dashboard in the meantime.
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `widgets` object[]: Widgets in grid order, top to bottom then left to right.
      - `id` string
      - `title` string
      - `query` string
      - `display` union: How the widget renders its query results.
        - object
          - `type` 'table', required
          - `prettyFormatting` boolean
          - `sorting` object[]
            - `id` string
            - `desc` boolean
        - object
          - `type` 'chart', required
          - `chartType` 'bar' | 'line', required
          - `xAxisColumn` string, nullable, required
          - `yAxisColumns` string[], required
          - `groupByColumn` string, nullable, required
          - `stacked` boolean, required
          - `sortByColumn` string, nullable, required
          - `sortDirection` 'asc' | 'desc', required
          - `aggregation` 'sum' | 'avg' | 'count' | 'min' | 'max', required
          - `seriesColors` object
        - object
          - `type` 'bignumber', required
          - `column` string, required
          - `aggregation` 'sum' | 'avg' | 'count' | 'min' | 'max' | 'first' | 'last', required
          - `sortDirection` 'asc' | 'desc'
          - `abbreviate` boolean
          - `prefix` string
          - `suffix` string
        - object
          - `type` 'title', required
      - `fillGaps` boolean
      - `position` DashboardWidgetPosition: A position on the dashboard's 12-column grid.
        - `x` integer, required
        - `y` integer, required
        - `w` integer, required
        - `h` integer, required

## Other responses

- `400`: Invalid widget, for example an invalid query
- `403`: The widget limit for your plan was reached
- `404`: Dashboard not found
- `409`: A widget with this id already exists, or the dashboard changed since `revision` was read

## Changes

- **2026-10-17** `15d1c9c9899c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v1/query/dashboards/:dashboardId/widgets/post.md)

---

[API](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api.md) - [All operations](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/revisions/441161111493?raw)