Set up docs MCP/api/v2/dashboards/validateValidates a dashboard body against the same schema and tile rules used by POST /api/v2/dashboards. The dashboard is never persisted. Use this endpoint at plan time (e.g. from a Terraform provider) to check that a dashboard configuration is valid before applying it.
Authorizations
Request bodyJSON
- tilesarray ofunknown{ … }required
List of tiles/charts to include in the dashboard.
11 properties
- 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
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 ofobject{ … }required
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: 1Example: "Duration" - countExpressionoptionalstring
SQL expression for the count contributing to each bucket. Defaults to "count()" in the editor when omitted.
maxLength: 10000Example: "count()" - heatmapScaleTypeoptionallogorlinear
Scale type used to bucket values on the y-axis.
Example: "log"
- whereoptionalstring
Row-level filter (syntax depends on whereLanguage).
maxLength: 10000Default: "" · 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"
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: 10000Example: "timestamp, level, message" - whereLanguagesqlorlucenerequired
Query language for the where clause.
- whereoptionalstring
Filter condition for the search (syntax depends on whereLanguage).
maxLength: 10000Default: "" · Example: "level:error"
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: 10000Default: "" · Example: "Body" - whereoptionalstring
Filter condition for the pattern mining query (syntax depends on whereLanguage).
maxLength: 10000Default: "" · Example: "level:error" - whereLanguageoptionalsqlorlucene
Query language for the where clause.
2 properties
- displayTypemarkdownrequired
Display type discriminator. Must be "markdown" for markdown text tiles.
Example: "markdown" - markdownoptionalstring
Markdown content to render inside the tile.
maxLength: 50000Example: "# Dashboard Title\n\nThis is a markdown widget."
- 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:
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: 0Example: 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"
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: 0Example: 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"
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: 0Example: 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"
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"
2 properties
- typemarkdownrequired
Series type discriminator. Must be "markdown" for markdown text widgets.
Example: "markdown" - contentstringrequired
Markdown content to render inside the widget.
maxLength: 100000Example: "# Dashboard Title\n\nThis is a markdown widget."
- 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:
13 properties
- typeQUERY_EXPRESSIONrequired
Filter type discriminator. Must be "QUERY_EXPRESSION".
Example: "QUERY_EXPRESSION" - namestringrequired
Display name for the dashboard filter key
minLength: 1Example: "Environment" - expressionstringrequired
SQL expression used when querying values for this filter, and when applying this dashboard filter to tiles.
minLength: 1Example: "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
$variableNameor 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
8 properties
- typeSTATIC_LISTrequired
Discriminator. Must be "STATIC_LIST".
Example: "STATIC_LIST" - namestringrequired
Display name for the dashboard filter key
minLength: 1Example: "Environment" - optionsarray ofstringrequired
The values this filter's dropdown offers. Must be non-empty and free of duplicates.
maxLength: 10000, minLength: 1Example: ["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
10 properties
- typePROMETHEUS_LABELrequired
Discriminator. Must be "PROMETHEUS_LABEL".
Example: "PROMETHEUS_LABEL" - namestringrequired
Display name for the dashboard filter
minLength: 1Example: "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: 1Example: "pod" - matchoptionalstring
Optional Prometheus series selector narrowing which series the label values are read from.
minLength: 1Example: "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
Optional default dashboard filter values to persist on the dashboard.
2 variants
One of the following:
- SqlSavedFilterValue{ … }
2 properties
- conditionstringrequired
SQL filter condition. For example use expressions in the form "column IN ('value')".
maxLength: 10000Example: "ServiceName IN ('hdx-oss-dev-api')" - typeoptionalsql
Filter type.
Default: "sql" · Example: "sql"
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: 1Example: "service" - valuesarray ofstringrequired
Selected values
maxLength: 10000Example: ["hdx-oss-dev-api"]
Response
200
Validation result. HTTP 200 is always returned for valid and invalid bodies — a non-200 response means the request itself failed (auth, server error, etc.).