Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

ClickStack: Get Dashboard

Beta
GET/v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards/{clickStackDashboardId}
API playground

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

Path parameters

  • organizationIdstringrequired

    ID of the organization that owns the service.

    format: uuid
  • serviceIdstringrequired

    ID of the ClickStack service.

    format: uuid
  • clickStackDashboardIdstringrequired

    ClickStack Dashboard ID

Response

JSON

200

Successful response

JSON
  • statusoptionalnumber

    HTTP status code.

    Example: 200
  • requestIdoptionalstring

    Unique id assigned to every request. UUIDv4

    format: uuid
  • resultoptionalobject
    9 properties
    • idoptionalstring

      Dashboard ID

      Example: "65f5e4a3b9e77c001a567890"
    • nameoptionalstring

      Dashboard name

      Example: "Service Overview"
    • tilesoptionalarray ofobject

      List of tiles/charts in the dashboard

      10 properties
      • namestringrequired

        Display name for the tile

        Example: "Error Rate"
      • xintegerrequired

        Horizontal position in the grid (0-based)

        Example: 0
      • yintegerrequired

        Vertical position in the grid (0-based)

        Example: 0
      • wintegerrequired

        Width in grid units

        Example: 6
      • hintegerrequired

        Height in grid units

        Example: 3
      • idstringrequired

        Unique tile ID assigned by the server.

        Example: "65f5e4a3b9e77c001a901234"
      • 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."
      • containerIdoptionalstring

        References a DashboardContainer by id. Tiles without containerId render in the default ungrouped area.

        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.

        Example: "errors"
      • descriptionoptionalstring

        Short explanation of the tile, shown as a tooltip next to its name.

        Example: "Share of API requests that returned a 5xx response."
    • tagsoptionalarray ofstring

      Tags for organizing and filtering dashboards

      Example: ["production","monitoring"]
    • 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 $variableName or 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 $__sourceTable or $__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
    • savedQueryoptionalstring | null

      Optional default dashboard query restored when loading the dashboard.

      Example: "service.name = 'api'"
    • savedQueryLanguageoptionalsqlorlucene

      Query language used by savedQuery.

      Example: "sql"
    • 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
    • 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.

        Example: "service-health"
      • titlestringrequired

        Display title for the container.

        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.

        Example: true
      • borderedoptionalboolean

        Whether to show a visual border around the group.

        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.

          Example: "errors"
        • titlestringrequired

          Display title for the tab.

          Example: "Errors"