Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

ClickStack: Validate Dashboard

Beta
View as MarkdownEdit this pageReport an issueSet up docs MCP
POST/v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards/validate

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

ClickStack: Validates a dashboard body against the same schema and tile rules used by POST /api/v2/dashboards. The dashboard is never persisted. Use this endpoint at plan time (e.g. from a Terraform provider) to check that a dashboard configuration is valid before applying it.

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.

    11 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
    • configoptionalClickStackLineChartConfigorClickStackBarChartConfigorClickStackTableChartConfigorClickStackNumberChartConfigorClickStackPieChartConfigorClickStackCategoricalBarChartConfigorClickStackHeatmapChartConfigorClickStackSearchChartConfigorClickStackEventPatternsChartConfigorClickStackMarkdownChartConfig
      10 variants

      One of the following:

      • ClickStackLineChartConfig
      • ClickStackBarChartConfig
      • ClickStackTableChartConfig
      • ClickStackNumberChartConfig
      • ClickStackPieChartConfig
      • ClickStackCategoricalBarChartConfig
      • ClickStackHeatmapChartConfig
        View ClickStackHeatmapChartConfig schema →
        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 ofobjectrequired

          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"
      • ClickStackSearchChartConfig
        View ClickStackSearchChartConfig schema →
        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
        View ClickStackEventPatternsChartConfig schema →
        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
        View ClickStackMarkdownChartConfig schema →
        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"
    • 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
        View ClickStackTimeChartSeries schema →
        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"
      • ClickStackTableChartSeries
        View ClickStackTableChartSeries schema →
        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
        View ClickStackNumberChartSeries schema →
        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
        View ClickStackSearchChartSeries schema →
        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
        View ClickStackMarkdownChartSeries schema →
        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 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.

    11 properties
    • typeQUERY_EXPRESSIONrequired

      Filter type. 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"
  • 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:

  • 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
    3 properties
    • validbooleanrequired

      True when the body passes all validation rules.

    • errorsarray ofobjectrequired

      Validation errors. Empty when valid is true.

      2 properties
      • pathstringrequired

        Dot-separated field path, or empty string for top-level errors.

        Example: "tiles.0.config"
      • messagestringrequired

        Human-readable error description.

        Example: "Required"
    • normalizedClickStackValidateDashboardResponseNormalizedornullrequired
      2 variants

      One of the following:

Navigation