/v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards/validateThis endpoint is in beta. API contract is stable, and no breaking changes are expected in the future.
ClickStack: Validates 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.
Permission
The API key must have the control-plane:service:manage-clickstack-api permission.
Authorizations
- AuthorizationstringheaderrequiredUse key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi
Path parameters
Request bodyJSON
- tilesarray ofobject{ … }required
List of tiles/charts to include in the dashboard.
12 properties
- configoptionalClickStackLineChartConfigorClickStackBarChartConfigorClickStackStackedLineChartConfigorClickStackTableChartConfigorClickStackNumberChartConfigorClickStackPieChartConfigorClickStackCategoricalBarChartConfigorClickStackHeatmapChartConfigorClickStackSearchChartConfigorClickStackEventPatternsChartConfigorClickStackMarkdownChartConfig
11 variants
One of the following:
- ClickStackLineChartConfig
- ClickStackBarChartConfig
- ClickStackStackedLineChartConfig
- ClickStackTableChartConfig
- ClickStackNumberChartConfig
- ClickStackPieChartConfig
- ClickStackCategoricalBarChartConfig
- ClickStackHeatmapChartConfig
- ClickStackSearchChartConfig{ … }
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.
Example: "timestamp, level, message" - whereLanguagesqlorlucenerequired
Query language for the where clause.
- whereoptionalstring
Filter condition for the search (syntax depends on whereLanguage).
Example: "level:error"
- ClickStackEventPatternsChartConfig{ … }
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).
Example: "Body" - whereoptionalstring
Filter condition for the pattern mining query (syntax depends on whereLanguage).
Example: "level:error" - whereLanguageoptionalsqlorlucene
Query language for the where clause.
- ClickStackMarkdownChartConfig{ … }
2 properties
- displayTypemarkdownrequired
Display type discriminator. Must be "markdown" for markdown text tiles.
Example: "markdown" - markdownoptionalstring
Markdown content to render inside the tile.
Example: "# Dashboard Title\n\nThis is a markdown widget."
- seriesdeprecatedarray ofClickStackTimeChartSeriesorClickStackTableChartSeriesorClickStackNumberChartSeriesorClickStackSearchChartSeriesorClickStackMarkdownChartSeries
Data series to display in this tile (all must be the same type). Deprecated; use "config" instead.
5 variants
One of the following:
- ClickStackTimeChartSeries{ … }
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)
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{ … }
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_barorstacked_lineorline
Visual representation type for the time series
Example: "line"
- ClickStackTableChartSeries{ … }
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)
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{ … }
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"
- ClickStackNumberChartSeries{ … }
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)
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{ … }
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"
- ClickStackSearchChartSeries{ … }
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"
- ClickStackMarkdownChartSeries{ … }
2 properties
- typemarkdownrequired
Series type discriminator. Must be "markdown" for markdown text widgets.
Example: "markdown" - contentstringrequired
Markdown content to render inside the widget.
Example: "# Dashboard Title\n\nThis is a markdown widget."
- filtersoptionalarray ofClickStackQueryExpressionFilterInputorClickStackStaticListFilterInputorClickStackPrometheusLabelFilterInputorClickStackSourceFilterInputorClickStackSqlQueryFilterInput
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.
5 variants
One of the following:
- ClickStackQueryExpressionFilterInput{ … }
14 properties
- typeQUERY_EXPRESSIONrequired
Filter type discriminator. Must be "QUERY_EXPRESSION".
Example: "QUERY_EXPRESSION" - namestringrequired
Display name for the dashboard filter key
Example: "Environment" - expressionstringrequired
SQL expression used when querying values for this filter, and when applying this dashboard filter to tiles.
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
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.
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.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.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.
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.
Example: true - maxSelectionsoptional1
Maximum number of values that can be selected at once. Set to 1 to make the filter single-select. Omit the field for the default multi-select behavior.
Example: 1
- ClickStackStaticListFilterInput{ … }
9 properties
- typeSTATIC_LISTrequired
Discriminator. Must be "STATIC_LIST".
Example: "STATIC_LIST" - namestringrequired
Display name for the dashboard filter key
Example: "Environment" - optionsarray ofstringrequired
The values this filter's dropdown offers. Must be non-empty and free of duplicates.
Example: ["prod","staging","dev"] - isBroadcastEnabledoptionalboolean
Must be false — there is no expression to broadcast. Omit it and it is false. Allowed values: false.
Example: false - isVariableEnabledoptionalboolean
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. Allowed values: 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.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.
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.
Example: true - maxSelectionsoptional1
Maximum number of values that can be selected at once. Set to 1 to make the filter single-select. Omit the field for the default multi-select behavior.
Example: 1
- ClickStackPrometheusLabelFilterInput{ … }
11 properties
- typePROMETHEUS_LABELrequired
Discriminator. Must be "PROMETHEUS_LABEL".
Example: "PROMETHEUS_LABEL" - namestringrequired
Display name for the dashboard filter
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.
Example: "pod" - matchoptionalstring
Optional Prometheus series selector narrowing which series the label values are read from.
Example: "up{job=\"api\"}" - isBroadcastEnabledoptionalboolean
Must be false or omitted. Allowed values: false.
Example: false - isVariableEnabledoptionalboolean
Must be true if provided, and is true when omitted. Tiles reference the selection as
$variableName. Allowed values: 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.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.
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.
Example: true - maxSelectionsoptional1
Maximum number of values that can be selected at once. Set to 1 to make the filter single-select. Omit the field for the default multi-select behavior.
Example: 1
- ClickStackSourceFilterInput{ … }
11 properties
- typeSOURCE_FILTERrequired
Discriminator. Must be "SOURCE_FILTER".
Example: "SOURCE_FILTER" - namestringrequired
Display name for the dashboard filter
Example: "Cluster" - sourceIdstringrequired
Id of the source whose filterSettings declares this column. Read filterSettings from GET /api/v2/sources to see which columns a source declares.
Example: "65f5e4a3b9e77c001a111111" - expressionstringrequired
Column this filter selects values for. Must match one of the source's filterSettings.columns[].name values, and is the expression the selection is broadcast on.
Example: "cluster" - variableNamestringrequired
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.Example: "cluster" - appliesToSourceIdsoptionalarray ofstring
Optional list of source IDs this filter broadcasts to. Omit or provide an empty array to apply the selection to ALL tiles regardless of source; a non-empty array restricts it to tiles whose source ID is in the list.
Example: ["65f5e4a3b9e77c001a111111"] - isBroadcastEnabledoptionalboolean
Must be true if provided, and is true when omitted — a source filter should always broadcast to at least its own source. Allowed values: true.
Example: true - isVariableEnabledoptionalboolean
Must be true if provided, and is true when omitted. Tiles reference the selection as
$variableName. Allowed values: true.Example: true - 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.
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.
Example: true - maxSelectionsoptional1
Maximum number of values that can be selected at once. Set to 1 to make the filter single-select. Omit the field for the default multi-select behavior.
Example: 1
- ClickStackSqlQueryFilterInput{ … }
10 properties
- typeSQL_QUERYrequired
Discriminator. Must be "SQL_QUERY".
Example: "SQL_QUERY" - namestringrequired
Display name for the dashboard filter
Example: "Environment" - connectionIdstringrequired
ID of the ClickHouse connection the query runs on.
Example: "65f5e4a3b9e77c001a567890" - sqlTemplatestringrequired
Query whose first column populates the dropdown. May use the time macros and other filters' variables, but not
$__sourceTableor$__filters, since the filter has no source.Example: "SELECT DISTINCT env FROM default.envs ORDER BY env" - isBroadcastEnabledoptionalboolean
Must be false or omitted. Allowed values: false.
Example: false - isVariableEnabledoptionalboolean
Must be true if provided, and is true when omitted. Tiles reference the selection as
$variableName. Allowed values: true.Example: true - variableNameoptionalstring
Token that tiles reference this filter's selected value by, as
$variableName. Defaults to the display name with whitespace replaced by underscores and remaining illegal characters removed. Must be unique across a dashboard's variable-enabled filters.Example: "env" - minSelectionsoptional0or1
Set to 1 to make the filter required.
Example: 1 - isGlobalRequirementoptionalboolean
Widens a required filter's block to every tile on the dashboard. Ignored unless minSelections is 1.
Example: true - maxSelectionsoptional1
Set to 1 to make the filter single-select.
Example: 1
- savedFilterValuesoptionalarray ofClickStackSqlSavedFilterValueorClickStackVariableSavedFilterValue
Optional default dashboard filter values to persist on the dashboard.
2 variants
One of the following:
- ClickStackSqlSavedFilterValue{ … }
2 properties
- conditionstringrequired
SQL filter condition. For example use expressions in the form "column IN ('value')".
Example: "ServiceName IN ('hdx-oss-dev-api')" - typeoptionalsql
Filter type.
Example: "sql"
- ClickStackVariableSavedFilterValue{ … }
4 properties
- typevariablerequired
Filter type.
Example: "variable" - namestringrequired
The variableName of the dashboard variable this selection belongs to. Only allowed for variable-enabled filters.
Example: "service" - valuesarray ofstringrequired
Selected values. Ignored when "all" is true.
Example: ["hdx-oss-dev-api"] - alloptionalboolean
Set to true to select every available value rather than a fixed list, which only SOURCE_FILTER filters offer (and only for columns their source declares with allowAll). Send an empty "values" alongside it. Allowed values: true.
Example: true
Response
200
Successful response
400
The request cannot be processed due to a client error. Please verify your request parameters and try again.
500
An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.