Set up docs MCP/v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards/{clickStackDashboardId}This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future.
ClickStack: Updates an existing dashboard. Concurrency: This endpoint does not support optimistic concurrency control. Concurrent PUT requests for the same dashboard may silently overwrite each other, which can leave orphan tile-to-container references on layout-shape edits. Clients should serialize edits to a given dashboard.
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
Full list of tiles for the dashboard. Existing tiles are matched by ID; tiles with an ID that does not match an existing tile will be assigned a new generated ID.
11 properties
- configoptionalClickStackLineChartConfigorClickStackBarChartConfigorClickStackTableChartConfigorClickStackNumberChartConfigorClickStackPieChartConfigorClickStackCategoricalBarChartConfigorClickStackHeatmapChartConfigorClickStackSearchChartConfigorClickStackEventPatternsChartConfigorClickStackMarkdownChartConfig
10 variants
One of the following:
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.
Example: "Duration" - countExpressionoptionalstring
SQL expression for the count contributing to each bucket. Defaults to "count()" in the editor when omitted.
Example: "count()" - heatmapScaleTypeoptionallogorlinear
Scale type used to bucket values on the y-axis.
Example: "log"
- whereoptionalstring
Row-level filter (syntax depends on whereLanguage).
Example: "ServiceName = 'api'" - whereLanguageoptionalsqlorlucene
Query language for the where clause.
- 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"
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"
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.
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:
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_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)
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"
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"
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.
Example: "# Dashboard Title\n\nThis is a markdown widget."
- filtersoptionalarray ofobject{ … }
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.
12 properties
- 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"] - 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"
Optional default dashboard filter values to persist on the dashboard.
2 variants
One of the following:
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"
3 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
Example: ["hdx-oss-dev-api"]
Response
200
Successful response
- resultoptionalobject{ … }
9 properties
- tilesoptionalarray ofobject{ … }
List of tiles/charts in the dashboard
9 properties
- configoptionalClickStackLineChartConfigorClickStackBarChartConfigorClickStackTableChartConfigorClickStackNumberChartConfigorClickStackPieChartConfigorClickStackCategoricalBarChartConfigorClickStackHeatmapChartConfigorClickStackSearchChartConfigorClickStackEventPatternsChartConfigorClickStackMarkdownChartConfig
10 variants
One of the following:
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.
Example: "Duration" - countExpressionoptionalstring
SQL expression for the count contributing to each bucket. Defaults to "count()" in the editor when omitted.
Example: "count()" - heatmapScaleTypeoptionallogorlinear
Scale type used to bucket values on the y-axis.
Example: "log"
- whereoptionalstring
Row-level filter (syntax depends on whereLanguage).
Example: "ServiceName = 'api'" - whereLanguageoptionalsqlorlucene
Query language for the where clause.
- 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"
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"
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.
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."
- filtersoptionalarray ofobject{ … }
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.
12 properties
- 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"] - 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"
Optional default dashboard filter values restored when loading the dashboard.
2 variants
One of the following:
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"
3 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
Example: ["hdx-oss-dev-api"]
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.