---
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
    - `config` union — Tile chart configuration. The displayType field determines which variant is used.
      - LineChartConfig — Configuration for a line time-series chart.
        - `displayType` 'line', required
        - `sourceId` string, required — ID of the data source to query.
        - `select` SelectItem[], required — One or more aggregated values to plot. When asRatio is true, exactly two select items are required.
          - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
          - `valueExpression` string — Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values.
          - `alias` string — Display alias for this select item in chart legends.
          - `level` 0.5 | 0.9 | 0.95 | 0.99 — Percentile level; only valid when aggFn is "quantile".
          - `where` string — SQL or Lucene filter condition applied before aggregation.
          - `whereLanguage` 'sql' | 'lucene' — Query language for the where clause.
          - `metricName` string — Name of the metric to aggregate; only applicable when the source is a metrics source.
          - `metricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
          - `periodAggFn` 'delta' — Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).
        - `groupBy` string — Field expression to group results by (creates separate lines per group value).
        - `asRatio` boolean — Plot select[0] / select[1] as a ratio. Requires exactly two select items.
        - `alignDateRangeToGranularity` boolean — Expand date range boundaries to the query granularity interval.
        - `fillNulls` boolean — Fill missing time buckets with zero instead of leaving gaps.
        - `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.
        - `compareToPreviousPeriod` boolean — Overlay the equivalent previous time period for comparison.
      - BarChartConfig — Configuration for a stacked-bar time-series chart.
        - `displayType` 'stacked_bar', required
        - `sourceId` string, required — ID of the data source to query.
        - `select` SelectItem[], required — One or more aggregated values to plot. When asRatio is true, exactly two select items are required.
          - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
          - `valueExpression` string — Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values.
          - `alias` string — Display alias for this select item in chart legends.
          - `level` 0.5 | 0.9 | 0.95 | 0.99 — Percentile level; only valid when aggFn is "quantile".
          - `where` string — SQL or Lucene filter condition applied before aggregation.
          - `whereLanguage` 'sql' | 'lucene' — Query language for the where clause.
          - `metricName` string — Name of the metric to aggregate; only applicable when the source is a metrics source.
          - `metricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
          - `periodAggFn` 'delta' — Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).
        - `groupBy` string — Field expression to group results by (creates separate bars segments per group value).
        - `asRatio` boolean — Plot select[0] / select[1] as a ratio. Requires exactly two select items.
        - `alignDateRangeToGranularity` boolean — Align the date range boundaries to the query granularity interval.
        - `fillNulls` boolean — Fill missing time buckets with zero instead of leaving gaps.
        - `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.
      - TableChartConfig — Configuration for a table aggregation chart.
        - `displayType` 'table', required
        - `sourceId` string, required — ID of the data source to query.
        - `select` SelectItem[], required — One or more aggregated values to display as table columns. When asRatio is true, exactly two select items are required.
          - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
          - `valueExpression` string — Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values.
          - `alias` string — Display alias for this select item in chart legends.
          - `level` 0.5 | 0.9 | 0.95 | 0.99 — Percentile level; only valid when aggFn is "quantile".
          - `where` string — SQL or Lucene filter condition applied before aggregation.
          - `whereLanguage` 'sql' | 'lucene' — Query language for the where clause.
          - `metricName` string — Name of the metric to aggregate; only applicable when the source is a metrics source.
          - `metricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
          - `periodAggFn` 'delta' — Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).
        - `groupBy` string — Field expression to group results by (one row per group value).
        - `having` string — Post-aggregation SQL HAVING condition.
        - `orderBy` string — SQL ORDER BY expression for sorting table rows.
        - `asRatio` boolean — Display select[0] / select[1] as a ratio. Requires exactly two select items.
        - `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.
      - NumberChartConfig — Configuration for a single big-number chart.
        - `displayType` 'number', required
        - `sourceId` string, required — ID of the data source to query.
        - `select` SelectItem[], required — Exactly one aggregated value to display as a single number.
          - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
          - `valueExpression` string — Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values.
          - `alias` string — Display alias for this select item in chart legends.
          - `level` 0.5 | 0.9 | 0.95 | 0.99 — Percentile level; only valid when aggFn is "quantile".
          - `where` string — SQL or Lucene filter condition applied before aggregation.
          - `whereLanguage` 'sql' | 'lucene' — Query language for the where clause.
          - `metricName` string — Name of the metric to aggregate; only applicable when the source is a metrics source.
          - `metricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
          - `periodAggFn` 'delta' — Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).
        - `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.
      - PieChartConfig — Configuration for a pie chart tile. Each slice represents one group value.
        - `displayType` 'pie', required
        - `sourceId` string, required — ID of the data source to query.
        - `select` SelectItem[], required — Exactly one aggregated value used to size each pie slice.
          - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
          - `valueExpression` string — Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values.
          - `alias` string — Display alias for this select item in chart legends.
          - `level` 0.5 | 0.9 | 0.95 | 0.99 — Percentile level; only valid when aggFn is "quantile".
          - `where` string — SQL or Lucene filter condition applied before aggregation.
          - `whereLanguage` 'sql' | 'lucene' — Query language for the where clause.
          - `metricName` string — Name of the metric to aggregate; only applicable when the source is a metrics source.
          - `metricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
          - `periodAggFn` 'delta' — Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).
        - `groupBy` string — Field expression to group results by (one slice per group value).
        - `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.
      - SearchChartConfig — Configuration for a raw-event search / log viewer tile.
        - `displayType` 'search', required
        - `sourceId` string, required — ID of the data source to query.
        - `select` string, required — Comma-separated list of expressions to display.
        - `where` string — Filter condition for the search (syntax depends on whereLanguage).
        - `whereLanguage` 'sql' | 'lucene', required — Query language for the where clause.
      - MarkdownChartConfig — Configuration for a freeform Markdown text tile.
        - `displayType` 'markdown', required
        - `markdown` string — Markdown content to render inside the tile.
    - `id` string — Optional tile ID. Omit to generate a new ID.
    - `asRatio` boolean — Display two series as a ratio (series[0] / series[1]). Only applicable when providing "series". Deprecated in favor of "config.asRatio".
    - `series` DashboardChartSeries[] — Data series to display in this tile (all must be the same type). Deprecated; use "config" instead.
      - 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
  - `savedQuery` string, nullable — Optional default dashboard query to persist on the dashboard.
  - `savedQueryLanguage` 'sql' | 'lucene' — Query language for the where clause.
  - `savedFilterValues` SavedFilterValue[] — Optional default dashboard filter values to persist on the dashboard.
    - `type` 'sql'
    - `condition` string, required — SQL filter condition. For example use expressions in the form "column IN ('value')".

## Response `200`

Successfully created dashboard

- DashboardResponseEnvelope
  - `data` DashboardResponse — Dashboard with tiles and configuration
    - `id` string — Dashboard ID
    - `name` string — Dashboard name
    - `tiles` TileOutput[] — 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
      - `config` union — Tile chart configuration. The displayType field determines which variant is used.
        - LineChartConfig — Configuration for a line time-series chart.
          - `displayType` 'line', required
          - `sourceId` string, required — ID of the data source to query.
          - `select` SelectItem[], required — One or more aggregated values to plot. When asRatio is true, exactly two select items are required.
            - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
            - `valueExpression` string — Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values.
            - `alias` string — Display alias for this select item in chart legends.
            - `level` 0.5 | 0.9 | 0.95 | 0.99 — Percentile level; only valid when aggFn is "quantile".
            - `where` string — SQL or Lucene filter condition applied before aggregation.
            - `whereLanguage` 'sql' | 'lucene' — Query language for the where clause.
            - `metricName` string — Name of the metric to aggregate; only applicable when the source is a metrics source.
            - `metricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
            - `periodAggFn` 'delta' — Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).
          - `groupBy` string — Field expression to group results by (creates separate lines per group value).
          - `asRatio` boolean — Plot select[0] / select[1] as a ratio. Requires exactly two select items.
          - `alignDateRangeToGranularity` boolean — Expand date range boundaries to the query granularity interval.
          - `fillNulls` boolean — Fill missing time buckets with zero instead of leaving gaps.
          - `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.
          - `compareToPreviousPeriod` boolean — Overlay the equivalent previous time period for comparison.
        - BarChartConfig — Configuration for a stacked-bar time-series chart.
          - `displayType` 'stacked_bar', required
          - `sourceId` string, required — ID of the data source to query.
          - `select` SelectItem[], required — One or more aggregated values to plot. When asRatio is true, exactly two select items are required.
            - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
            - `valueExpression` string — Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values.
            - `alias` string — Display alias for this select item in chart legends.
            - `level` 0.5 | 0.9 | 0.95 | 0.99 — Percentile level; only valid when aggFn is "quantile".
            - `where` string — SQL or Lucene filter condition applied before aggregation.
            - `whereLanguage` 'sql' | 'lucene' — Query language for the where clause.
            - `metricName` string — Name of the metric to aggregate; only applicable when the source is a metrics source.
            - `metricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
            - `periodAggFn` 'delta' — Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).
          - `groupBy` string — Field expression to group results by (creates separate bars segments per group value).
          - `asRatio` boolean — Plot select[0] / select[1] as a ratio. Requires exactly two select items.
          - `alignDateRangeToGranularity` boolean — Align the date range boundaries to the query granularity interval.
          - `fillNulls` boolean — Fill missing time buckets with zero instead of leaving gaps.
          - `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.
        - TableChartConfig — Configuration for a table aggregation chart.
          - `displayType` 'table', required
          - `sourceId` string, required — ID of the data source to query.
          - `select` SelectItem[], required — One or more aggregated values to display as table columns. When asRatio is true, exactly two select items are required.
            - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
            - `valueExpression` string — Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values.
            - `alias` string — Display alias for this select item in chart legends.
            - `level` 0.5 | 0.9 | 0.95 | 0.99 — Percentile level; only valid when aggFn is "quantile".
            - `where` string — SQL or Lucene filter condition applied before aggregation.
            - `whereLanguage` 'sql' | 'lucene' — Query language for the where clause.
            - `metricName` string — Name of the metric to aggregate; only applicable when the source is a metrics source.
            - `metricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
            - `periodAggFn` 'delta' — Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).
          - `groupBy` string — Field expression to group results by (one row per group value).
          - `having` string — Post-aggregation SQL HAVING condition.
          - `orderBy` string — SQL ORDER BY expression for sorting table rows.
          - `asRatio` boolean — Display select[0] / select[1] as a ratio. Requires exactly two select items.
          - `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.
        - NumberChartConfig — Configuration for a single big-number chart.
          - `displayType` 'number', required
          - `sourceId` string, required — ID of the data source to query.
          - `select` SelectItem[], required — Exactly one aggregated value to display as a single number.
            - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
            - `valueExpression` string — Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values.
            - `alias` string — Display alias for this select item in chart legends.
            - `level` 0.5 | 0.9 | 0.95 | 0.99 — Percentile level; only valid when aggFn is "quantile".
            - `where` string — SQL or Lucene filter condition applied before aggregation.
            - `whereLanguage` 'sql' | 'lucene' — Query language for the where clause.
            - `metricName` string — Name of the metric to aggregate; only applicable when the source is a metrics source.
            - `metricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
            - `periodAggFn` 'delta' — Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).
          - `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.
        - PieChartConfig — Configuration for a pie chart tile. Each slice represents one group value.
          - `displayType` 'pie', required
          - `sourceId` string, required — ID of the data source to query.
          - `select` SelectItem[], required — Exactly one aggregated value used to size each pie slice.
            - `aggFn` 'avg' | 'count' | 'count_distinct' | 'last_value' | 'max' | 'min' | 'quantile' | 'sum' | 'any' | 'none', required — Aggregation function to apply to the field or metric value.
            - `valueExpression` string — Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values.
            - `alias` string — Display alias for this select item in chart legends.
            - `level` 0.5 | 0.9 | 0.95 | 0.99 — Percentile level; only valid when aggFn is "quantile".
            - `where` string — SQL or Lucene filter condition applied before aggregation.
            - `whereLanguage` 'sql' | 'lucene' — Query language for the where clause.
            - `metricName` string — Name of the metric to aggregate; only applicable when the source is a metrics source.
            - `metricType` 'sum' | 'gauge' | 'histogram' | 'summary' | 'exponential histogram' — Metric data type for metrics data sources.
            - `periodAggFn` 'delta' — Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).
          - `groupBy` string — Field expression to group results by (one slice per group value).
          - `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.
        - SearchChartConfig — Configuration for a raw-event search / log viewer tile.
          - `displayType` 'search', required
          - `sourceId` string, required — ID of the data source to query.
          - `select` string, required — Comma-separated list of expressions to display.
          - `where` string — Filter condition for the search (syntax depends on whereLanguage).
          - `whereLanguage` 'sql' | 'lucene', required — Query language for the where clause.
        - MarkdownChartConfig — Configuration for a freeform Markdown text tile.
          - `displayType` 'markdown', required
          - `markdown` string — Markdown content to render inside the tile.
      - `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
    - `savedQuery` string, nullable — Optional default dashboard query restored when loading the dashboard.
    - `savedQueryLanguage` 'sql' | 'lucene' — Query language for the where clause.
    - `savedFilterValues` SavedFilterValue[] — Optional default dashboard filter values restored when loading the dashboard.
      - `type` 'sql'
      - `condition` string, required — SQL filter condition. For example use expressions in the form "column IN ('value')".

## Other responses

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

## Changes

- **2026-03-04** `5dd37daf8c9f` — 6 info
  - added the new optional request property `savedFilterValues`
  - added the new optional request property `savedQuery`
  - added the new optional request property `savedQueryLanguage`
  - added the optional property `data/allOf[#/components/schemas/Dashboard]/savedFilterValues` to the response with the `200` status
  - …2 more
- **2026-02-23** `1a98071f39d8` — 1 breaking, 3 info
  - added `#/components/schemas/PieChartConfig` to the `data/allOf[#/components/schemas/Dashboard]/tiles/items/allOf[#/components/schemas/TileBase]/config` response property `oneOf` list for the response status `200`
  - added `pie` discriminator mapping keys to the `tiles/items/allOf[#/components/schemas/TileBase]/config` request property
  - added `#/components/schemas/PieChartConfig` to the `tiles/items/allOf[#/components/schemas/TileBase]/config` request property `oneOf` list
  - added `pie` discriminator mapping keys to the `data/allOf[#/components/schemas/Dashboard]/tiles/items/allOf[#/components/schemas/TileBase]/config` response property for the response status `200`
- **2026-02-20** `13cad9d7c34c` — 2 breaking, 7 warning, 2 info
  - added `#/components/schemas/TileBase, subschema #2` to the `tiles/items/` request property `allOf` list
  - the `tiles/items/` request property type/format changed from `object`/`` to ``/``
  - removed the request property `tiles/items/asRatio`
  - removed the request property `tiles/items/h`
  - …7 more
- …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/5dd37daf8c9f/schema)