Create Dashboard

POST/api/v2/dashboards

Creates a new dashboard

Authorizations

AuthorizationBearer API Keyheaderrequired
`Authorization: Bearer <token>`

Request bodyJSON

namestringrequired
Dashboard name.

maxLength: 1024
Example: "New Dashboard"
tilesarray ofunknownrequired
List of tiles/charts to include in the dashboard.
11 properties
- namestringrequired
  Display name for the tile
  
  Example: "Error Rate"
- xintegerrequired
  Horizontal position in the grid (0-based)
  
  maximum: 23, minimum: 0
  Example: 0
- yintegerrequired
  Vertical position in the grid (0-based)
  
  minimum: 0
  Example: 0
- wintegerrequired
  Width in grid units
  
  maximum: 24, minimum: 1
  Example: 6
- hintegerrequired
  Height in grid units
  
  minimum: 1
  Example: 3
- configoptionalLineChartConfigorBarChartConfigorTableChartConfigorNumberChartConfigorPieChartConfigorCategoricalBarChartConfigorHeatmapChartConfigorSearchChartConfigorEventPatternsChartConfigorMarkdownChartConfig
  Chart configuration for the tile. The displayType field determines which variant is used. Replaces the deprecated "series" and "asRatio" fields.
  
  10 variants
  One of the following:
  LineChartConfigline
  BarChartConfigstacked_bar
  TableChartConfigtable
  NumberChartConfignumber
  PieChartConfigpie
  CategoricalBarChartConfigbar
  HeatmapChartConfigheatmap
  View HeatmapChartConfig schema →
  6 properties
  displayTypeheatmaprequired
  Display type discriminator. Must be "heatmap" for heatmap tiles.
  
  Example: "heatmap"
  sourceIdstringrequired
  ID of the data source to query.
  
  Example: "65f5e4a3b9e77c001a111111"
  selectarray ofobjectrequired
  Exactly one heatmap select item.
  
  3 properties
  valueExpressionstringrequired
  SQL expression for the value being bucketed on the y-axis. Must be non-empty.
  
  maxLength: 10000, minLength: 1
  Example: "Duration"
  countExpressionoptionalstring
  SQL expression for the count contributing to each bucket. Defaults to "count()" in the editor when omitted.
  
  maxLength: 10000
  Example: "count()"
  heatmapScaleTypeoptionallogorlinear
  Scale type used to bucket values on the y-axis.
  
  Example: "log"
  whereoptionalstring
  Row-level filter (syntax depends on whereLanguage).
  
  maxLength: 10000
  Default: "" · Example: "ServiceName = 'api'"
  whereLanguageoptionalsqlorlucene
  Query language for the where clause.
  
  Default: "lucene"
  numberFormatoptionalobject
  Number formatting options for displayed values.
  
  9 properties
  outputoptionalcurrencyorpercentorbyteortimeornumberordata_rate+2 more
  Output format applied to the number.
  
  Example: "number"
  mantissaoptionalinteger
  Number of decimal places.
  
  Example: 2
  thousandSeparatedoptionalboolean
  Whether to use thousand separators.
  
  Example: true
  averageoptionalboolean
  Whether to show as average.
  
  Example: false
  decimalBytesoptionalboolean
  Use decimal bytes (1000) vs binary bytes (1024).
  
  Example: false
  factoroptionalnumber
  Multiplication factor.
  
  Example: 1
  currencySymboloptionalstring
  Currency symbol for currency format.
  
  Example: "$"
  numericUnitoptionalbytes_iecorbytes_siorbits_iecorbits_siorkibibytesorkilobytes+43 more
  Numeric unit for data, data rate, or throughput formats.
  
  Example: "bytes_iec"
  unitoptionalstring
  Custom unit label.
  
  Example: "ms"
  SearchChartConfigsearch
  View SearchChartConfig schema →
  5 properties
  displayTypesearchrequired
  Display type discriminator. Must be "search" for search/log viewer tiles.
  
  Example: "search"
  sourceIdstringrequired
  ID of the data source to query.
  
  Example: "65f5e4a3b9e77c001a111111"
  selectstringrequired
  Comma-separated list of expressions to display.
  
  maxLength: 10000
  Example: "timestamp, level, message"
  whereLanguagesqlorlucenerequired
  Query language for the where clause.
  
  whereoptionalstring
  Filter condition for the search (syntax depends on whereLanguage).
  
  maxLength: 10000
  Default: "" · Example: "level:error"
  EventPatternsChartConfigevent_patterns
  View EventPatternsChartConfig schema →
  5 properties
  displayTypeevent_patternsrequired
  Display type discriminator. Must be "event_patterns" for pattern mining tiles.
  
  Example: "event_patterns"
  sourceIdstringrequired
  ID of the data source to mine patterns from.
  
  Example: "65f5e4a3b9e77c001a111111"
  selectoptionalstring
  Column or expression to mine patterns from. Leave empty to use the source default (Body for logs, SpanName for traces).
  
  maxLength: 10000
  Default: "" · Example: "Body"
  whereoptionalstring
  Filter condition for the pattern mining query (syntax depends on whereLanguage).
  
  maxLength: 10000
  Default: "" · Example: "level:error"
  whereLanguageoptionalsqlorlucene
  Query language for the where clause.
  
  MarkdownChartConfigmarkdown
  View MarkdownChartConfig schema →
  2 properties
  displayTypemarkdownrequired
  Display type discriminator. Must be "markdown" for markdown text tiles.
  
  Example: "markdown"
  markdownoptionalstring
  Markdown content to render inside the tile.
  
  maxLength: 50000
  Example: "# Dashboard Title\n\nThis is a markdown widget."
- containerIdoptionalstring
  References a DashboardContainer by id. Tiles without containerId render in the default ungrouped area.
  
  maxLength: 256, minLength: 1
  Example: "service-health"
- tabIdoptionalstring
  References a tab inside the tile's container by id. Requires containerId to be set, and the container to declare a matching tab.
  
  maxLength: 256, minLength: 1
  Example: "errors"
- idoptionalstring
  Optional tile ID. Omit to generate a new ID.
  
  maxLength: 36
  Example: "65f5e4a3b9e77c001a901234"
- asRatiodeprecatedboolean
  Display two series as a ratio (series[0] / series[1]). Only applicable when providing "series". Deprecated in favor of "config.asRatio".
  
  Example: false
- seriesdeprecatedarray ofTimeChartSeriesorTableChartSeriesorNumberChartSeriesorSearchChartSeriesorMarkdownChartSeries
  Data series to display in this tile (all must be the same type). Deprecated; use "config" instead.
  
  5 variants
  One of the following:
  TimeChartSeriestime
  View TimeChartSeries schema →
  13 properties
  typetimerequired
  Series type discriminator. Must be "time" for time-series charts.
  
  Example: "time"
  sourceIdstringrequired
  ID of the data source to query
  
  Example: "65f5e4a3b9e77c001a567890"
  aggFnavgorcountorcount_distinctorlast_valueormaxormin+4 morerequired
  Aggregation function to apply to the field or metric value
  
  Example: "count"
  wherestringrequired
  Filter query for the data (syntax depends on whereLanguage)
  
  Example: "service:api"
  whereLanguagesqlorlucenerequired
  Query language for the where clause
  
  Example: "lucene"
  groupByarray ofstringrequired
  Fields to group results by (creates separate series for each group)
  
  Example: ["host"]
  leveloptionalnumber
  Percentile level for quantile aggregations (e.g., 0.95 for p95)
  
  maximum: 1, minimum: 0
  Example: 0.95
  fieldoptionalstring
  Column or expression to aggregate (required for most aggregation functions except count)
  
  Example: "duration"
  aliasoptionalstring
  Display name for the series in the chart
  
  Example: "Request Duration"
  numberFormatoptionalobject
  Number formatting options for displayed values.
  
  9 properties
  outputoptionalcurrencyorpercentorbyteortimeornumberordata_rate+2 more
  Output format applied to the number.
  
  Example: "number"
  mantissaoptionalinteger
  Number of decimal places.
  
  Example: 2
  thousandSeparatedoptionalboolean
  Whether to use thousand separators.
  
  Example: true
  averageoptionalboolean
  Whether to show as average.
  
  Example: false
  decimalBytesoptionalboolean
  Use decimal bytes (1000) vs binary bytes (1024).
  
  Example: false
  factoroptionalnumber
  Multiplication factor.
  
  Example: 1
  currencySymboloptionalstring
  Currency symbol for currency format.
  
  Example: "$"
  numericUnitoptionalbytes_iecorbytes_siorbits_iecorbits_siorkibibytesorkilobytes+43 more
  Numeric unit for data, data rate, or throughput formats.
  
  Example: "bytes_iec"
  unitoptionalstring
  Custom unit label.
  
  Example: "ms"
  metricDataTypeoptionalsumorgaugeorhistogramorsummaryorexponential histogram
  Metric data type, only for metrics data sources.
  
  Example: "sum"
  metricNameoptionalstring
  Metric name for metrics data sources
  
  Example: "http.server.duration"
  displayTypeoptionalstacked_barorline
  Visual representation type for the time series
  
  Example: "line"
  TableChartSeriestable
  View TableChartSeries schema →
  13 properties
  typetablerequired
  Series type discriminator. Must be "table" for table charts.
  
  Example: "table"
  sourceIdstringrequired
  ID of the data source to query
  
  Example: "65f5e4a3b9e77c001a567890"
  aggFnavgorcountorcount_distinctorlast_valueormaxormin+4 morerequired
  Aggregation function to apply to the field or metric value
  
  Example: "count"
  wherestringrequired
  Filter query for the data (syntax depends on whereLanguage)
  
  Example: "level:error"
  whereLanguagesqlorlucenerequired
  Query language for the where clause
  
  Example: "lucene"
  groupByarray ofstringrequired
  Fields to group results by (creates separate rows for each group)
  
  Example: ["errorType"]
  leveloptionalnumber
  Percentile level for quantile aggregations (e.g., 0.95 for p95)
  
  maximum: 1, minimum: 0
  Example: 0.95
  fieldoptionalstring
  Column or expression to aggregate (required for most aggregation functions except count)
  
  Example: "duration"
  aliasoptionalstring
  Display name for the series
  
  Example: "Total Count"
  sortOrderoptionaldescorasc
  Sort order for table rows
  
  Example: "desc"
  numberFormatoptionalobject
  Number formatting options for displayed values.
  
  9 properties
  outputoptionalcurrencyorpercentorbyteortimeornumberordata_rate+2 more
  Output format applied to the number.
  
  Example: "number"
  mantissaoptionalinteger
  Number of decimal places.
  
  Example: 2
  thousandSeparatedoptionalboolean
  Whether to use thousand separators.
  
  Example: true
  averageoptionalboolean
  Whether to show as average.
  
  Example: false
  decimalBytesoptionalboolean
  Use decimal bytes (1000) vs binary bytes (1024).
  
  Example: false
  factoroptionalnumber
  Multiplication factor.
  
  Example: 1
  currencySymboloptionalstring
  Currency symbol for currency format.
  
  Example: "$"
  numericUnitoptionalbytes_iecorbytes_siorbits_iecorbits_siorkibibytesorkilobytes+43 more
  Numeric unit for data, data rate, or throughput formats.
  
  Example: "bytes_iec"
  unitoptionalstring
  Custom unit label.
  
  Example: "ms"
  metricDataTypeoptionalsumorgaugeorhistogramorsummaryorexponential histogram
  Metric data type, only for metrics data sources.
  
  Example: "sum"
  metricNameoptionalstring
  Metric name for metrics data sources
  
  Example: "http.server.duration"
  NumberChartSeriesnumber
  View NumberChartSeries schema →
  11 properties
  typenumberrequired
  Series type discriminator. Must be "number" for single-value number charts.
  
  Example: "number"
  sourceIdstringrequired
  ID of the data source to query
  
  Example: "65f5e4a3b9e77c001a567890"
  aggFnavgorcountorcount_distinctorlast_valueormaxormin+4 morerequired
  Aggregation function to apply to the field or metric value
  
  Example: "count"
  wherestringrequired
  Filter query for the data (syntax depends on whereLanguage)
  
  Example: "service:api"
  whereLanguagesqlorlucenerequired
  Query language for the where clause
  
  Example: "lucene"
  leveloptionalnumber
  Percentile level for quantile aggregations (e.g., 0.95 for p95)
  
  maximum: 1, minimum: 0
  Example: 0.95
  fieldoptionalstring
  Column or expression to aggregate (required for most aggregation functions except count)
  
  Example: "duration"
  aliasoptionalstring
  Display name for the series in the chart
  
  Example: "Total Requests"
  numberFormatoptionalobject
  Number formatting options for displayed values.
  
  9 properties
  outputoptionalcurrencyorpercentorbyteortimeornumberordata_rate+2 more
  Output format applied to the number.
  
  Example: "number"
  mantissaoptionalinteger
  Number of decimal places.
  
  Example: 2
  thousandSeparatedoptionalboolean
  Whether to use thousand separators.
  
  Example: true
  averageoptionalboolean
  Whether to show as average.
  
  Example: false
  decimalBytesoptionalboolean
  Use decimal bytes (1000) vs binary bytes (1024).
  
  Example: false
  factoroptionalnumber
  Multiplication factor.
  
  Example: 1
  currencySymboloptionalstring
  Currency symbol for currency format.
  
  Example: "$"
  numericUnitoptionalbytes_iecorbytes_siorbits_iecorbits_siorkibibytesorkilobytes+43 more
  Numeric unit for data, data rate, or throughput formats.
  
  Example: "bytes_iec"
  unitoptionalstring
  Custom unit label.
  
  Example: "ms"
  metricDataTypeoptionalsumorgaugeorhistogramorsummaryorexponential histogram
  Metric data type, only for metrics data sources.
  
  Example: "sum"
  metricNameoptionalstring
  Metric name for metrics data sources.
  
  Example: "http.server.duration"
  SearchChartSeriessearch
  View SearchChartSeries schema →
  5 properties
  typesearchrequired
  Series type discriminator. Must be "search" for search/log viewer charts.
  
  Example: "search"
  sourceIdstringrequired
  ID of the data source to query
  
  Example: "65f5e4a3b9e77c001a567890"
  fieldsarray ofstringrequired
  List of field names to display in the search results table
  
  Example: ["timestamp","level","message"]
  wherestringrequired
  Filter query for the data (syntax depends on whereLanguage)
  
  Example: "level:error"
  whereLanguagesqlorlucenerequired
  Query language for the where clause
  
  Example: "lucene"
  MarkdownChartSeriesmarkdown
  View MarkdownChartSeries schema →
  2 properties
  typemarkdownrequired
  Series type discriminator. Must be "markdown" for markdown text widgets.
  
  Example: "markdown"
  contentstringrequired
  Markdown content to render inside the widget.
  
  maxLength: 100000
  Example: "# Dashboard Title\n\nThis is a markdown widget."
tagsoptionalarray ofstring
Tags for organizing and filtering dashboards.

maxLength: 32
Example: ["development"]
filtersoptionalarray ofQueryExpressionFilterInputorStaticListFilterInputorPrometheusLabelFilterInput
Dropdown filters added to the dashboard. Each one broadcasts its selected value as a condition, acts as a variable which can be referenced in tile queries, or both.
3 variants
One of the following:
QueryExpressionFilterInputQUERY_EXPRESSION
View QueryExpressionFilterInput schema →
13 properties
typeQUERY_EXPRESSIONrequired
Filter type discriminator. Must be "QUERY_EXPRESSION".

Example: "QUERY_EXPRESSION"
namestringrequired
Display name for the dashboard filter key

minLength: 1
Example: "Environment"
expressionstringrequired
SQL expression used when querying values for this filter, and when applying this dashboard filter to tiles.

minLength: 1
Example: "environment"
sourceIdstringrequired
Source ID this dashboard filter key applies to

Example: "65f5e4a3b9e77c001a111111"
sourceMetricTypeoptionalsumorgaugeorhistogramorsummaryorexponential histogram
Metric type when source is metrics

Example: "gauge"
whereoptionalstring
Optional WHERE condition to scope which rows this filter key reads values from

Example: "ServiceName:api"
whereLanguageoptionalsqlorlucene
Language of the where condition

Default: "sql" · Example: "lucene"
appliesToSourceIdsoptionalarray ofstring
Optional list of source IDs this filter applies to. Omit or provide an empty array to apply the filter to ALL tiles regardless of source. A non-empty array restricts the filter to only tiles whose source ID is in the list; tiles using other sources are not affected by the selected filter value(s). Scopes the broadcast condition only, so a non-empty array is rejected when isBroadcastEnabled is false, and is omitted from responses for such a filter.

Example: ["65f5e4a3b9e77c001a111111"]
isBroadcastEnabledoptionalboolean
Whether the selected value is applied as a filter condition on every builder tile this filter applies to (see appliesToSourceIds), and every raw sql tile using the $__filters macro. Omitting the field means enabled.

Default: true · Example: false
isVariableEnabledoptionalboolean
Whether the selected value is exposed to tile queries as a dashboard variable named by variableName. Tiles may reference it as $variableName or using the (preferred) $__filter($<variableName>) and $__conditionalAll(<condition>, $<variableName>) macros.

Default: false · Example: true
variableNameoptionalstring
Token tiles reference this filter's selected value by, as $variableName. Must start with a letter and may contain only letters, numbers, and underscores. Defaults to the display name with whitespace replaced by underscores and remaining illegal characters removed, so a variable-enabled filter whose name derives nothing usable must send this field explicitly. Variable names must be unique across a dashboard's variable-enabled filters. Names the variable only, so the field is rejected when isVariableEnabled is not true, and is omitted from responses for such a filter.

maxLength: 64, pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
Example: "environment"
minSelectionsoptional0or1
Minimum number of values that must be selected before tiles load. Set to 1 to make the filter required. Only 0 and 1 are accepted. Omit the field (or send 0) for the default optional behavior.

Default: 0 · Example: 1
isGlobalRequirementoptionalboolean
Widens a required filter's block to every tile on the dashboard. False (the default) blocks only the tiles that read the filter: those referencing its variableName, and those its broadcast applies to. Ignored unless minSelections is 1.

Default: false · Example: true
StaticListFilterInputSTATIC_LIST
View StaticListFilterInput schema →
8 properties
typeSTATIC_LISTrequired
Discriminator. Must be "STATIC_LIST".

Example: "STATIC_LIST"
namestringrequired
Display name for the dashboard filter key

minLength: 1
Example: "Environment"
optionsarray ofstringrequired
The values this filter's dropdown offers. Must be non-empty and free of duplicates.

maxLength: 10000, minLength: 1
Example: ["prod","staging","dev"]
isBroadcastEnabledoptionalfalse
Must be false — there is no expression to broadcast. Omit it and it is false.

Default: false · Example: false
isVariableEnabledoptionaltrue
Must be true if provided, and is true when omitted. Tiles reference the selection as $variableName, or with the $__filter(<expression>, $<variableName>) and $__conditionalAll(<condition>, $<variableName>) macros. The one-argument $__filter($<variableName>) form renders the filter's own expression, which this kind of filter does not have, so it reports that the expression must be passed explicitly.

Default: true · Example: true
variableNameoptionalstring
Token tiles reference this filter's selected value by, as $variableName. Must start with a letter and may contain only letters, numbers, and underscores. Defaults to the display name with whitespace replaced by underscores and remaining illegal characters removed, so a variable-enabled filter whose name derives nothing usable must send this field explicitly. Variable names must be unique across a dashboard's variable-enabled filters. Names the variable only, so the field is rejected when isVariableEnabled is not true, and is omitted from responses for such a filter.

maxLength: 64, pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
Example: "environment"
minSelectionsoptional0or1
Minimum number of values that must be selected before tiles load. Set to 1 to make the filter required. Only 0 and 1 are accepted. Omit the field (or send 0) for the default optional behavior.

Default: 0 · Example: 1
isGlobalRequirementoptionalboolean
Widens a required filter's block to every tile on the dashboard. False (the default) blocks only the tiles that read the filter: those referencing its variableName, and those its broadcast applies to. Ignored unless minSelections is 1.

Default: false · Example: true
PrometheusLabelFilterInputPROMETHEUS_LABEL
View PrometheusLabelFilterInput schema →
10 properties
typePROMETHEUS_LABELrequired
Discriminator. Must be "PROMETHEUS_LABEL".

Example: "PROMETHEUS_LABEL"
namestringrequired
Display name for the dashboard filter

minLength: 1
Example: "Pod"
sourceIdstringrequired
Id of the PromQL source the label values are read from.

Example: "65f5e4a3b9e77c001a123456"
labelstringrequired
Label whose values populate the dropdown. Use "name" to list metric names.

maxLength: 1024, minLength: 1
Example: "pod"
matchoptionalstring
Optional Prometheus series selector narrowing which series the label values are read from.

minLength: 1
Example: "up{job=\"api\"}"
isBroadcastEnabledoptionalfalse
Must be false or omitted.

Default: false · Example: false
isVariableEnabledoptionaltrue
Must be true if provided, and is true when omitted. Tiles reference the selection as $variableName.

Default: true · Example: true
variableNameoptionalstring
Token that tiles reference this filter's selected value by, as $variableName. Must start with a letter and may contain only letters, numbers, and underscores. Defaults to the display name with whitespace replaced by underscores and remaining illegal characters removed. Variable names must be unique across a dashboard's variable-enabled filters.

maxLength: 64, pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
Example: "pod"
minSelectionsoptional0or1
Minimum number of values that must be selected before tiles load. Set to 1 to make the filter required. Only 0 and 1 are accepted. Omit the field (or send 0) for the default optional behavior.

Default: 0 · Example: 1
isGlobalRequirementoptionalboolean
Widens a required filter's block to every tile on the dashboard. False (the default) blocks only the tiles that read the filter: those referencing its variableName, and those its broadcast applies to. Ignored unless minSelections is 1.

Default: false · Example: true
savedQueryoptionalstringor null
Optional default dashboard query to persist on the dashboard.

Example: "service.name = 'api'"
savedQueryLanguageoptionalsqlorluceneor null
Query language used by savedQuery.

Default: "lucene" · Example: "sql"
savedFilterValuesoptionalarray ofSqlSavedFilterValueorVariableSavedFilterValue
Optional default dashboard filter values to persist on the dashboard.
2 variants
One of the following:
SqlSavedFilterValue
View SqlSavedFilterValue schema →
2 properties
conditionstringrequired
SQL filter condition. For example use expressions in the form "column IN ('value')".

maxLength: 10000
Example: "ServiceName IN ('hdx-oss-dev-api')"
typeoptionalsql
Filter type.

Default: "sql" · Example: "sql"
VariableSavedFilterValue
View VariableSavedFilterValue schema →
3 properties
typevariablerequired
Filter type.

Example: "variable"
namestringrequired
The variableName of the dashboard variable this selection belongs to. Only allowed for variable-enabled filters.

maxLength: 1024, minLength: 1
Example: "service"
valuesarray ofstringrequired
Selected values

maxLength: 10000
Example: ["hdx-oss-dev-api"]
containersoptionalarray ofobject
Optional grouping containers. Each tile may join a container via tile.containerId, and a tab inside it via tile.tabId.
6 properties
- idstringrequired
  Unique identifier for the container within the dashboard.
  
  maxLength: 256, minLength: 1
  Example: "service-health"
- titlestringrequired
  Display title for the container.
  
  maxLength: 256, minLength: 1
  Example: "Service Health"
- collapsedbooleanrequired
  Persisted default collapse state. Per-viewer state lives in the URL.
  
  Example: false
- collapsibleoptionalboolean
  Whether the user can collapse the group.
  
  Default: true · Example: true
- borderedoptionalboolean
  Whether to show a visual border around the group.
  
  Default: true · Example: true
- tabsoptionalarray ofobject
  Optional tabs. 2+ entries renders a tab bar; 0-1 entries renders a plain group header. Tiles join a tab via tabId.
  
  2 properties
  idstringrequired
  Unique identifier for the tab within its container.
  
  maxLength: 256, minLength: 1
  Example: "errors"
  titlestringrequired
  Display title for the tab.
  
  maxLength: 256, minLength: 1
  Example: "Errors"

Response

JSON

200

Successfully created dashboard

JSON

dataoptionalobject
The dashboard object.
9 properties
- idoptionalstring
  Dashboard ID
  
  Example: "65f5e4a3b9e77c001a567890"
- nameoptionalstring
  Dashboard name
  
  maxLength: 1024
  Example: "Service Overview"
- tilesoptionalarray ofunknown
  List of tiles/charts in the dashboard
  
  9 properties
  namestringrequired
  Display name for the tile
  
  Example: "Error Rate"
  xintegerrequired
  Horizontal position in the grid (0-based)
  
  maximum: 23, minimum: 0
  Example: 0
  yintegerrequired
  Vertical position in the grid (0-based)
  
  minimum: 0
  Example: 0
  wintegerrequired
  Width in grid units
  
  maximum: 24, minimum: 1
  Example: 6
  hintegerrequired
  Height in grid units
  
  minimum: 1
  Example: 3
  idstringrequired
  Unique tile ID assigned by the server.
  
  maxLength: 36
  Example: "65f5e4a3b9e77c001a901234"
  configoptionalLineChartConfigorBarChartConfigorTableChartConfigorNumberChartConfigorPieChartConfigorCategoricalBarChartConfigorHeatmapChartConfigorSearchChartConfigorEventPatternsChartConfigorMarkdownChartConfig
  Chart configuration for the tile. The displayType field determines which variant is used. Replaces the deprecated "series" and "asRatio" fields.
  
  10 variants
  One of the following:
  LineChartConfigline
  BarChartConfigstacked_bar
  TableChartConfigtable
  NumberChartConfignumber
  PieChartConfigpie
  CategoricalBarChartConfigbar
  HeatmapChartConfigheatmap
  View HeatmapChartConfig schema →
  6 properties
  displayTypeheatmaprequired
  Display type discriminator. Must be "heatmap" for heatmap tiles.
  
  Example: "heatmap"
  sourceIdstringrequired
  ID of the data source to query.
  
  Example: "65f5e4a3b9e77c001a111111"
  selectarray ofobjectrequired
  Exactly one heatmap select item.
  
  3 properties
  valueExpressionstringrequired
  SQL expression for the value being bucketed on the y-axis. Must be non-empty.
  
  maxLength: 10000, minLength: 1
  Example: "Duration"
  countExpressionoptionalstring
  SQL expression for the count contributing to each bucket. Defaults to "count()" in the editor when omitted.
  
  maxLength: 10000
  Example: "count()"
  heatmapScaleTypeoptionallogorlinear
  Scale type used to bucket values on the y-axis.
  
  Example: "log"
  whereoptionalstring
  Row-level filter (syntax depends on whereLanguage).
  
  maxLength: 10000
  Default: "" · Example: "ServiceName = 'api'"
  whereLanguageoptionalsqlorlucene
  Query language for the where clause.
  
  Default: "lucene"
  numberFormatoptionalobject
  Number formatting options for displayed values.
  
  9 properties
  outputoptionalcurrencyorpercentorbyteortimeornumberordata_rate+2 more
  Output format applied to the number.
  
  Example: "number"
  mantissaoptionalinteger
  Number of decimal places.
  
  Example: 2
  thousandSeparatedoptionalboolean
  Whether to use thousand separators.
  
  Example: true
  averageoptionalboolean
  Whether to show as average.
  
  Example: false
  decimalBytesoptionalboolean
  Use decimal bytes (1000) vs binary bytes (1024).
  
  Example: false
  factoroptionalnumber
  Multiplication factor.
  
  Example: 1
  currencySymboloptionalstring
  Currency symbol for currency format.
  
  Example: "$"
  numericUnitoptionalbytes_iecorbytes_siorbits_iecorbits_siorkibibytesorkilobytes+43 more
  Numeric unit for data, data rate, or throughput formats.
  
  Example: "bytes_iec"
  unitoptionalstring
  Custom unit label.
  
  Example: "ms"
  SearchChartConfigsearch
  View SearchChartConfig schema →
  5 properties
  displayTypesearchrequired
  Display type discriminator. Must be "search" for search/log viewer tiles.
  
  Example: "search"
  sourceIdstringrequired
  ID of the data source to query.
  
  Example: "65f5e4a3b9e77c001a111111"
  selectstringrequired
  Comma-separated list of expressions to display.
  
  maxLength: 10000
  Example: "timestamp, level, message"
  whereLanguagesqlorlucenerequired
  Query language for the where clause.
  
  whereoptionalstring
  Filter condition for the search (syntax depends on whereLanguage).
  
  maxLength: 10000
  Default: "" · Example: "level:error"
  EventPatternsChartConfigevent_patterns
  View EventPatternsChartConfig schema →
  5 properties
  displayTypeevent_patternsrequired
  Display type discriminator. Must be "event_patterns" for pattern mining tiles.
  
  Example: "event_patterns"
  sourceIdstringrequired
  ID of the data source to mine patterns from.
  
  Example: "65f5e4a3b9e77c001a111111"
  selectoptionalstring
  Column or expression to mine patterns from. Leave empty to use the source default (Body for logs, SpanName for traces).
  
  maxLength: 10000
  Default: "" · Example: "Body"
  whereoptionalstring
  Filter condition for the pattern mining query (syntax depends on whereLanguage).
  
  maxLength: 10000
  Default: "" · Example: "level:error"
  whereLanguageoptionalsqlorlucene
  Query language for the where clause.
  
  MarkdownChartConfigmarkdown
  View MarkdownChartConfig schema →
  2 properties
  displayTypemarkdownrequired
  Display type discriminator. Must be "markdown" for markdown text tiles.
  
  Example: "markdown"
  markdownoptionalstring
  Markdown content to render inside the tile.
  
  maxLength: 50000
  Example: "# Dashboard Title\n\nThis is a markdown widget."
  containerIdoptionalstring
  References a DashboardContainer by id. Tiles without containerId render in the default ungrouped area.
  
  maxLength: 256, minLength: 1
  Example: "service-health"
  tabIdoptionalstring
  References a tab inside the tile's container by id. Requires containerId to be set, and the container to declare a matching tab.
  
  maxLength: 256, minLength: 1
  Example: "errors"
- tagsoptionalarray ofstring
  Tags for organizing and filtering dashboards
  
  maxLength: 32
  Example: ["production","monitoring"]
- filtersoptionalarray ofQueryExpressionFilterInputorStaticListFilterInputorPrometheusLabelFilterInput
  Dropdown filters added to the dashboard. Each one broadcasts its selected value as a condition, acts as a variable which can be referenced in tile queries, or both.
  
  3 variants
  One of the following:
  QueryExpressionFilterInputQUERY_EXPRESSION
  View QueryExpressionFilterInput schema →
  13 properties
  typeQUERY_EXPRESSIONrequired
  Filter type discriminator. Must be "QUERY_EXPRESSION".
  
  Example: "QUERY_EXPRESSION"
  namestringrequired
  Display name for the dashboard filter key
  
  minLength: 1
  Example: "Environment"
  expressionstringrequired
  SQL expression used when querying values for this filter, and when applying this dashboard filter to tiles.
  
  minLength: 1
  Example: "environment"
  sourceIdstringrequired
  Source ID this dashboard filter key applies to
  
  Example: "65f5e4a3b9e77c001a111111"
  sourceMetricTypeoptionalsumorgaugeorhistogramorsummaryorexponential histogram
  Metric type when source is metrics
  
  Example: "gauge"
  whereoptionalstring
  Optional WHERE condition to scope which rows this filter key reads values from
  
  Example: "ServiceName:api"
  whereLanguageoptionalsqlorlucene
  Language of the where condition
  
  Default: "sql" · Example: "lucene"
  appliesToSourceIdsoptionalarray ofstring
  Optional list of source IDs this filter applies to. Omit or provide an empty array to apply the filter to ALL tiles regardless of source. A non-empty array restricts the filter to only tiles whose source ID is in the list; tiles using other sources are not affected by the selected filter value(s). Scopes the broadcast condition only, so a non-empty array is rejected when isBroadcastEnabled is false, and is omitted from responses for such a filter.
  
  Example: ["65f5e4a3b9e77c001a111111"]
  isBroadcastEnabledoptionalboolean
  Whether the selected value is applied as a filter condition on every builder tile this filter applies to (see appliesToSourceIds), and every raw sql tile using the $__filters macro. Omitting the field means enabled.
  
  Default: true · Example: false
  isVariableEnabledoptionalboolean
  Whether the selected value is exposed to tile queries as a dashboard variable named by variableName. Tiles may reference it as $variableName or using the (preferred) $__filter($<variableName>) and $__conditionalAll(<condition>, $<variableName>) macros.
  
  Default: false · Example: true
  variableNameoptionalstring
  Token tiles reference this filter's selected value by, as $variableName. Must start with a letter and may contain only letters, numbers, and underscores. Defaults to the display name with whitespace replaced by underscores and remaining illegal characters removed, so a variable-enabled filter whose name derives nothing usable must send this field explicitly. Variable names must be unique across a dashboard's variable-enabled filters. Names the variable only, so the field is rejected when isVariableEnabled is not true, and is omitted from responses for such a filter.
  
  maxLength: 64, pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
  Example: "environment"
  minSelectionsoptional0or1
  Minimum number of values that must be selected before tiles load. Set to 1 to make the filter required. Only 0 and 1 are accepted. Omit the field (or send 0) for the default optional behavior.
  
  Default: 0 · Example: 1
  isGlobalRequirementoptionalboolean
  Widens a required filter's block to every tile on the dashboard. False (the default) blocks only the tiles that read the filter: those referencing its variableName, and those its broadcast applies to. Ignored unless minSelections is 1.
  
  Default: false · Example: true
  StaticListFilterInputSTATIC_LIST
  View StaticListFilterInput schema →
  8 properties
  typeSTATIC_LISTrequired
  Discriminator. Must be "STATIC_LIST".
  
  Example: "STATIC_LIST"
  namestringrequired
  Display name for the dashboard filter key
  
  minLength: 1
  Example: "Environment"
  optionsarray ofstringrequired
  The values this filter's dropdown offers. Must be non-empty and free of duplicates.
  
  maxLength: 10000, minLength: 1
  Example: ["prod","staging","dev"]
  isBroadcastEnabledoptionalfalse
  Must be false — there is no expression to broadcast. Omit it and it is false.
  
  Default: false · Example: false
  isVariableEnabledoptionaltrue
  Must be true if provided, and is true when omitted. Tiles reference the selection as $variableName, or with the $__filter(<expression>, $<variableName>) and $__conditionalAll(<condition>, $<variableName>) macros. The one-argument $__filter($<variableName>) form renders the filter's own expression, which this kind of filter does not have, so it reports that the expression must be passed explicitly.
  
  Default: true · Example: true
  variableNameoptionalstring
  Token tiles reference this filter's selected value by, as $variableName. Must start with a letter and may contain only letters, numbers, and underscores. Defaults to the display name with whitespace replaced by underscores and remaining illegal characters removed, so a variable-enabled filter whose name derives nothing usable must send this field explicitly. Variable names must be unique across a dashboard's variable-enabled filters. Names the variable only, so the field is rejected when isVariableEnabled is not true, and is omitted from responses for such a filter.
  
  maxLength: 64, pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
  Example: "environment"
  minSelectionsoptional0or1
  Minimum number of values that must be selected before tiles load. Set to 1 to make the filter required. Only 0 and 1 are accepted. Omit the field (or send 0) for the default optional behavior.
  
  Default: 0 · Example: 1
  isGlobalRequirementoptionalboolean
  Widens a required filter's block to every tile on the dashboard. False (the default) blocks only the tiles that read the filter: those referencing its variableName, and those its broadcast applies to. Ignored unless minSelections is 1.
  
  Default: false · Example: true
  PrometheusLabelFilterInputPROMETHEUS_LABEL
  View PrometheusLabelFilterInput schema →
  10 properties
  typePROMETHEUS_LABELrequired
  Discriminator. Must be "PROMETHEUS_LABEL".
  
  Example: "PROMETHEUS_LABEL"
  namestringrequired
  Display name for the dashboard filter
  
  minLength: 1
  Example: "Pod"
  sourceIdstringrequired
  Id of the PromQL source the label values are read from.
  
  Example: "65f5e4a3b9e77c001a123456"
  labelstringrequired
  Label whose values populate the dropdown. Use "name" to list metric names.
  
  maxLength: 1024, minLength: 1
  Example: "pod"
  matchoptionalstring
  Optional Prometheus series selector narrowing which series the label values are read from.
  
  minLength: 1
  Example: "up{job=\"api\"}"
  isBroadcastEnabledoptionalfalse
  Must be false or omitted.
  
  Default: false · Example: false
  isVariableEnabledoptionaltrue
  Must be true if provided, and is true when omitted. Tiles reference the selection as $variableName.
  
  Default: true · Example: true
  variableNameoptionalstring
  Token that tiles reference this filter's selected value by, as $variableName. Must start with a letter and may contain only letters, numbers, and underscores. Defaults to the display name with whitespace replaced by underscores and remaining illegal characters removed. Variable names must be unique across a dashboard's variable-enabled filters.
  
  maxLength: 64, pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
  Example: "pod"
  minSelectionsoptional0or1
  Minimum number of values that must be selected before tiles load. Set to 1 to make the filter required. Only 0 and 1 are accepted. Omit the field (or send 0) for the default optional behavior.
  
  Default: 0 · Example: 1
  isGlobalRequirementoptionalboolean
  Widens a required filter's block to every tile on the dashboard. False (the default) blocks only the tiles that read the filter: those referencing its variableName, and those its broadcast applies to. Ignored unless minSelections is 1.
  
  Default: false · Example: true
- savedQueryoptionalstringor null
  Optional default dashboard query restored when loading the dashboard.
  
  Example: "service.name = 'api'"
- savedQueryLanguageoptionalsqlorluceneor null
  Query language used by savedQuery.
  
  Default: "lucene" · Example: "sql"
- savedFilterValuesoptionalarray ofSqlSavedFilterValueorVariableSavedFilterValue
  Optional default dashboard filter values restored when loading the dashboard.
  
  2 variants
  One of the following:
  SqlSavedFilterValue
  View SqlSavedFilterValue schema →
  2 properties
  conditionstringrequired
  SQL filter condition. For example use expressions in the form "column IN ('value')".
  
  maxLength: 10000
  Example: "ServiceName IN ('hdx-oss-dev-api')"
  typeoptionalsql
  Filter type.
  
  Default: "sql" · Example: "sql"
  VariableSavedFilterValue
  View VariableSavedFilterValue schema →
  3 properties
  typevariablerequired
  Filter type.
  
  Example: "variable"
  namestringrequired
  The variableName of the dashboard variable this selection belongs to. Only allowed for variable-enabled filters.
  
  maxLength: 1024, minLength: 1
  Example: "service"
  valuesarray ofstringrequired
  Selected values
  
  maxLength: 10000
  Example: ["hdx-oss-dev-api"]
- containersoptionalarray ofobject
  Optional grouping containers. Each tile may join a container via tile.containerId, and a tab inside it via tile.tabId.
  
  6 properties
  idstringrequired
  Unique identifier for the container within the dashboard.
  
  maxLength: 256, minLength: 1
  Example: "service-health"
  titlestringrequired
  Display title for the container.
  
  maxLength: 256, minLength: 1
  Example: "Service Health"
  collapsedbooleanrequired
  Persisted default collapse state. Per-viewer state lives in the URL.
  
  Example: false
  collapsibleoptionalboolean
  Whether the user can collapse the group.
  
  Default: true · Example: true
  borderedoptionalboolean
  Whether to show a visual border around the group.
  
  Default: true · Example: true
  tabsoptionalarray ofobject
  Optional tabs. 2+ entries renders a tab bar; 0-1 entries renders a plain group header. Tiles join a tab via tabId.
  
  2 properties
  idstringrequired
  Unique identifier for the tab within its container.
  
  maxLength: 256, minLength: 1
  Example: "errors"
  titlestringrequired
  Display title for the tab.
  
  maxLength: 256, minLength: 1
  Example: "Errors"

Create Dashboard

curl --request POST \
  --url /api/v2/dashboards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "API Monitoring Dashboard",
  "tiles": [
    {
      "name": "API Request Volume",
      "x": 0,
      "y": 0,
      "w": 6,
      "h": 3,
      "config": {
        "displayType": "line",
        "sourceId": "65f5e4a3b9e77c001a111111",
        "select": [
          {
            "aggFn": "count",
            "where": "service:api"
          }
        ]
      }
    }
  ],
  "tags": [
    "api",
    "monitoring"
  ],
  "filters": [
    {
      "type": "QUERY_EXPRESSION",
      "name": "Environment",
      "expression": "environment",
      "sourceId": "65f5e4a3b9e77c001a111111"
    }
  ]
}
'

const url = '/api/v2/dashboards';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    name: 'API Monitoring Dashboard',
    tiles: [
      {
        name: 'API Request Volume',
        x: 0,
        y: 0,
        w: 6,
        h: 3,
        config: {
          displayType: 'line',
          sourceId: '65f5e4a3b9e77c001a111111',
          select: [{aggFn: 'count', where: 'service:api'}]
        }
      }
    ],
    tags: ['api', 'monitoring'],
    filters: [
      {
        type: 'QUERY_EXPRESSION',
        name: 'Environment',
        expression: 'environment',
        sourceId: '65f5e4a3b9e77c001a111111'
      }
    ]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "/api/v2/dashboards"

payload = {
    "name": "API Monitoring Dashboard",
    "tiles": [
        {
            "name": "API Request Volume",
            "x": 0,
            "y": 0,
            "w": 6,
            "h": 3,
            "config": {
                "displayType": "line",
                "sourceId": "65f5e4a3b9e77c001a111111",
                "select": [
                    {
                        "aggFn": "count",
                        "where": "service:api"
                    }
                ]
            }
        }
    ],
    "tags": ["api", "monitoring"],
    "filters": [
        {
            "type": "QUERY_EXPRESSION",
            "name": "Environment",
            "expression": "environment",
            "sourceId": "65f5e4a3b9e77c001a111111"
        }
    ]
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "data": {
    "id": "65f5e4a3b9e77c001a567890",
    "name": "API Monitoring Dashboard",
    "tiles": [
      {
        "id": "65f5e4a3b9e77c001a901234",
        "name": "API Request Volume",
        "x": 0,
        "y": 0,
        "w": 6,
        "h": 3,
        "config": {
          "displayType": "line",
          "sourceId": "65f5e4a3b9e77c001a111111",
          "select": [
            {
              "aggFn": "count",
              "where": "service:api"
            }
          ]
        }
      }
    ],
    "tags": [
      "api",
      "monitoring"
    ],
    "filters": [
      {
        "id": "65f5e4a3b9e77c001a301004",
        "type": "QUERY_EXPRESSION",
        "name": "Environment",
        "expression": "environment",
        "sourceId": "65f5e4a3b9e77c001a111111"
      }
    ]
  }
}

{
  "message": "Could not find the following source IDs: 68fa86308aa879b977aa6af6"
}

{
  "message": "Unauthorized access. API key is missing or invalid."
}

{
  "message": "Dashboard validation failed: name is required"
}

Authorizations

Request bodyJSON

Response

200

400

401

500