/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: Retrieves a specific dashboard by ID
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
Response
200
Successful response
- resultoptionalobject{ … }
9 properties
- tilesoptionalarray ofobject{ … }
List of tiles/charts in the dashboard
10 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."
- filtersoptionalarray ofClickStackQueryExpressionFilterorClickStackStaticListFilterorClickStackPrometheusLabelFilterorClickStackSourceFilterorClickStackSqlQueryFilter
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:
- ClickStackQueryExpressionFilter{ … }
15 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" - idstringrequired
Unique dashboard filter key ID
- 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
- ClickStackStaticListFilter{ … }
10 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"] - idstringrequired
Unique dashboard filter key ID
- 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
- ClickStackPrometheusLabelFilter{ … }
12 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" - idstringrequired
Unique dashboard filter key ID
- 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
- ClickStackSourceFilter{ … }
12 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" - idstringrequired
Unique dashboard filter key ID
- 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
- ClickStackSqlQueryFilter{ … }
11 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" - idstringrequired
Unique dashboard filter key ID
- 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 restored when loading 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
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.