---
title: "Create a dashboard"
method: POST
path: "/api/v1/query/dashboards"
tags: ["query"]
---

# Create a dashboard

`POST /api/v1/query/dashboards`

## Request

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

Create a custom dashboard, optionally with its widgets. Every widget query is checked against the queryable tables before it is saved. Creating more dashboards than your plan allows returns a 403.

## Request body

- object
  - `title` string, required
  - `description` string
  - `widgets` DashboardWidgetInput[]: Widgets without a position are stacked full width below the positioned ones, in order.
    - `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

## Response `201`

Dashboard created

- 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 request, for example an invalid widget query
- `401`: Unauthorized - API key is missing or invalid
- `403`: The dashboard or widget limit for your plan was reached, or the credentials cannot write dashboards

## 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/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)