Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs

ClickStack: Create Dashboard

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

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future.

ClickStack: Creates a new dashboard

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

Request bodyJSON

  • namestringrequired

    Dashboard name.

    Example: "New Dashboard"
  • tilesarray ofobjectrequired

    List of tiles/charts to include in the dashboard.

    12 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
    • 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."
    • idoptionalstring

      Optional tile ID. Omit to generate a new ID.

      Example: "65f5e4a3b9e77c001a901234"
    • asRatiodeprecatedboolean

      Display two series as a ratio (series[0] / series[1]). Only applicable when providing "series". Deprecated in favor of "config.asRatio".

      Example: false
    • 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."
  • tagsoptionalarray ofstring

    Tags for organizing and filtering dashboards.

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

    Optional default dashboard query to persist on the dashboard.

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

    Query language used by savedQuery.

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

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"