---
title: "Create Dashboard"
method: POST
path: "/api/v2/dashboards"
tags: ["Dashboards"]
---

# Create Dashboard

`POST /api/v2/dashboards`

Creates a new dashboard

## Request body

- CreateDashboardRequest
  - `name` string, required
  - `tiles` TileInput[], required
    - `name` string, required — Display name for the tile
    - `x` integer, required — Horizontal position in the grid (0-based)
    - `y` integer, required — Vertical position in the grid (0-based)
    - `w` integer, required — Width in grid units
    - `h` integer, required — Height in grid units
    - `asRatio` boolean — Display two series as a ratio (series[0] / series[1])
    - `series` DashboardChartSeries[], required — Data series to display in this tile (all must be the same type)
      - union
        - TimeChartSeries
          - `type` 'time', required
          - `sourceId` string, required — ID of the data source to query
          - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
          - `level` number — Percentile level for quantile aggregations (e.g., 0.95 for p95)
          - `field` string — Field/property name to aggregate (required for most aggregation functions except count)
          - `alias` string — Display name for the series in the chart
          - `where` string, required — Filter query for the data (syntax depends on whereLanguage)
          - `whereLanguage` 'sql' | 'lucene', required — Query language for the where clause.
          - `groupBy` string[], required — Fields to group results by (creates separate series for each group)
          - `numberFormat` NumberFormat
            - `output` 'currency' | 'percent' | 'byte' | 'time' | 'number' — Output format type (currency, percent, byte, time, number).
            - `mantissa` integer — Number of decimal places.
            - `thousandSeparated` boolean — Whether to use thousand separators.
            - `average` boolean — Whether to show as average.
            - `decimalBytes` boolean — Use decimal bytes (1000) vs binary bytes (1024).
            - `factor` number — Multiplication factor.
            - `currencySymbol` string — Currency symbol for currency format.
            - `unit` string — Custom unit label.
          - `metricDataType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
          - `metricName` string — Metric name for metrics data sources
          - `displayType` 'stacked_bar' | 'line' — Visual representation type for the time series.
        - TableChartSeries
          - `type` 'table', required
          - `sourceId` string, required — ID of the data source to query
          - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
          - `level` number — Percentile level for quantile aggregations (e.g., 0.95 for p95)
          - `field` string
          - `alias` string
          - `where` string, required
          - `whereLanguage` 'sql' | 'lucene', required — Query language for the where clause.
          - `groupBy` string[], required
          - `sortOrder` 'desc' | 'asc' — Sort order for table rows.
          - `numberFormat` NumberFormat
            - `output` 'currency' | 'percent' | 'byte' | 'time' | 'number' — Output format type (currency, percent, byte, time, number).
            - `mantissa` integer — Number of decimal places.
            - `thousandSeparated` boolean — Whether to use thousand separators.
            - `average` boolean — Whether to show as average.
            - `decimalBytes` boolean — Use decimal bytes (1000) vs binary bytes (1024).
            - `factor` number — Multiplication factor.
            - `currencySymbol` string — Currency symbol for currency format.
            - `unit` string — Custom unit label.
          - `metricDataType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
          - `metricName` string — Metric name for metrics data sources
        - NumberChartSeries
          - `type` 'number', required
          - `sourceId` string, required — ID of the data source to query
          - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
          - `level` number — Percentile level for quantile aggregations (e.g., 0.95 for p95)
          - `field` string
          - `alias` string
          - `where` string, required
          - `whereLanguage` 'sql' | 'lucene', required — Query language for the where clause.
          - `numberFormat` NumberFormat
            - `output` 'currency' | 'percent' | 'byte' | 'time' | 'number' — Output format type (currency, percent, byte, time, number).
            - `mantissa` integer — Number of decimal places.
            - `thousandSeparated` boolean — Whether to use thousand separators.
            - `average` boolean — Whether to show as average.
            - `decimalBytes` boolean — Use decimal bytes (1000) vs binary bytes (1024).
            - `factor` number — Multiplication factor.
            - `currencySymbol` string — Currency symbol for currency format.
            - `unit` string — Custom unit label.
          - `metricDataType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
          - `metricName` string
        - SearchChartSeries
          - `type` 'search', required
          - `sourceId` string, required — ID of the data source to query
          - `fields` string[], required — List of field names to display in the search results table
          - `where` string, required — Filter query for the data (syntax depends on whereLanguage)
          - `whereLanguage` 'sql' | 'lucene', required — Query language for the where clause.
        - MarkdownChartSeries
          - `type` 'markdown', required
          - `content` string, required
  - `tags` string[]
  - `filters` FilterInput[] — Dashboard filter keys to add to the dashboard and apply across all tiles
    - `type` 'QUERY_EXPRESSION', required
    - `name` string, required — Display name for the dashboard filter key
    - `expression` string, required — Key expression used when applying this dashboard filter key
    - `sourceId` string, required — Source ID this dashboard filter key applies to
    - `sourceMetricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric type when source is metrics

## Response `200`

Successfully created dashboard

- DashboardResponseEnvelope
  - `data` DashboardResponse — Dashboard with tiles and configuration
    - `id` string — Dashboard ID
    - `name` string — Dashboard name
    - `tiles` Tile[] — List of tiles/charts in the dashboard
      - `name` string, required — Display name for the tile
      - `x` integer, required — Horizontal position in the grid (0-based)
      - `y` integer, required — Vertical position in the grid (0-based)
      - `w` integer, required — Width in grid units
      - `h` integer, required — Height in grid units
      - `asRatio` boolean — Display two series as a ratio (series[0] / series[1])
      - `series` DashboardChartSeries[], required — Data series to display in this tile (all must be the same type)
        - union
          - TimeChartSeries
            - `type` 'time', required
            - `sourceId` string, required — ID of the data source to query
            - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
            - `level` number — Percentile level for quantile aggregations (e.g., 0.95 for p95)
            - `field` string — Field/property name to aggregate (required for most aggregation functions except count)
            - `alias` string — Display name for the series in the chart
            - `where` string, required — Filter query for the data (syntax depends on whereLanguage)
            - `whereLanguage` 'sql' | 'lucene', required — Query language for the where clause.
            - `groupBy` string[], required — Fields to group results by (creates separate series for each group)
            - `numberFormat` NumberFormat
              - …
            - `metricDataType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
            - `metricName` string — Metric name for metrics data sources
            - `displayType` 'stacked_bar' | 'line' — Visual representation type for the time series.
          - TableChartSeries
            - `type` 'table', required
            - `sourceId` string, required — ID of the data source to query
            - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
            - `level` number — Percentile level for quantile aggregations (e.g., 0.95 for p95)
            - `field` string
            - `alias` string
            - `where` string, required
            - `whereLanguage` 'sql' | 'lucene', required — Query language for the where clause.
            - `groupBy` string[], required
            - `sortOrder` 'desc' | 'asc' — Sort order for table rows.
            - `numberFormat` NumberFormat
              - …
            - `metricDataType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
            - `metricName` string — Metric name for metrics data sources
          - NumberChartSeries
            - `type` 'number', required
            - `sourceId` string, required — ID of the data source to query
            - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
            - `level` number — Percentile level for quantile aggregations (e.g., 0.95 for p95)
            - `field` string
            - `alias` string
            - `where` string, required
            - `whereLanguage` 'sql' | 'lucene', required — Query language for the where clause.
            - `numberFormat` NumberFormat
              - …
            - `metricDataType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
            - `metricName` string
          - SearchChartSeries
            - `type` 'search', required
            - `sourceId` string, required — ID of the data source to query
            - `fields` string[], required — List of field names to display in the search results table
            - `where` string, required — Filter query for the data (syntax depends on whereLanguage)
            - `whereLanguage` 'sql' | 'lucene', required — Query language for the where clause.
          - MarkdownChartSeries
            - `type` 'markdown', required
            - `content` string, required
      - `id` string, required
    - `tags` string[] — Tags for organizing and filtering dashboards
    - `filters` Filter[] — Dashboard filter keys added to the dashboard and applied to all tiles
      - `type` 'QUERY_EXPRESSION', required
      - `name` string, required — Display name for the dashboard filter key
      - `expression` string, required — Key expression used when applying this dashboard filter key
      - `sourceId` string, required — Source ID this dashboard filter key applies to
      - `sourceMetricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric type when source is metrics
      - `id` string, required — Unique dashboard filter key ID

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `500` — Server error or validation failure

## Changes

- **2026-02-19** `defc8c0a5046` — 4 breaking, 4 info
  - the request property `tiles/items/series/items/oneOf[#/components/schemas/NumberChartSeries]/whereLanguage` became required
  - the request property `tiles/items/series/items/oneOf[#/components/schemas/SearchChartSeries]/whereLanguage` became required
  - the request property `tiles/items/series/items/oneOf[#/components/schemas/TableChartSeries]/whereLanguage` became required
  - the request property `tiles/items/series/items/oneOf[#/components/schemas/TimeChartSeries]/whereLanguage` became required
  - …4 more
- **2026-02-12** `ca7f63e15766` — 2 info
  - added the new optional request property `filters`
  - added the optional property `data/allOf[#/components/schemas/Dashboard]/filters` to the response with the `200` status
- **2026-02-11** `50f295ac37bd` — 3 breaking
  - the `tiles/items/series/items/oneOf[#/components/schemas/NumberChartSeries]/numberFormat/mantissa` request property type/format changed from `number`/`` to `integer`/``
  - the `tiles/items/series/items/oneOf[#/components/schemas/TableChartSeries]/numberFormat/mantissa` request property type/format changed from `number`/`` to `integer`/``
  - the `tiles/items/series/items/oneOf[#/components/schemas/TimeChartSeries]/numberFormat/mantissa` request property type/format changed from `number`/`` to `integer`/``
- …earlier changes not shown

[Full history](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api/changes/api/v2/dashboards/post.md)

---

[API](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api.md) · [All operations](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hyperdxio/hyperdx-external-api/revisions/defc8c0a5046/schema)