> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Validate Dashboard > 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. ## OpenAPI ````yaml https://raw.githubusercontent.com/hyperdxio/hyperdx/refs/heads/main/packages/api/openapi.json post /api/v2/dashboards/validate openapi: 3.0.0 info: title: HyperDX External API description: API for managing HyperDX alerts and dashboards version: 2.0.0 servers: - url: / description: Your HyperDX instance (http://:) security: - BearerAuth: [] tags: - name: Dashboards description: Endpoints for managing dashboards and their visualizations - name: Alerts description: Endpoints for managing monitoring alerts - name: Charts description: Endpoints for querying chart data - name: Connections description: Endpoints for managing ClickHouse connections - name: Sources description: Endpoints for managing data sources - name: Webhooks description: Endpoints for managing webhooks - name: Search description: Endpoints for querying raw data from log and trace sources paths: /api/v2/dashboards/validate: post: tags: - Dashboards summary: Validate Dashboard description: | 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. operationId: validateDashboard requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDashboardRequest' responses: '200': description: | Validation result. HTTP 200 is always returned for valid **and** invalid bodies — a non-200 response means the request itself failed (auth, server error, etc.). content: application/json: schema: type: object required: - valid - errors - normalized properties: valid: type: boolean description: True when the body passes all validation rules. errors: type: array description: Validation errors. Empty when valid is true. items: type: object required: - path - message properties: path: type: string description: >- Dot-separated field path, or empty string for top-level errors. message: type: string description: Human-readable error description. normalized: type: object nullable: true description: | The parsed dashboard body with defaults applied (no persistence, so no server-assigned tile IDs). Populated when valid is true, null when valid is false. examples: valid: summary: Valid dashboard body value: valid: true errors: [] normalized: name: My Dashboard tiles: [] invalid: summary: Invalid dashboard body value: valid: false errors: - path: name message: Required normalized: null '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: message: Unauthorized access. API key is missing or invalid. components: schemas: CreateDashboardRequest: type: object required: - name - tiles properties: name: type: string maxLength: 1024 description: Dashboard name. example: New Dashboard tiles: type: array description: List of tiles/charts to include in the dashboard. maxItems: 500 items: $ref: '#/components/schemas/TileInput' tags: type: array description: Tags for organizing and filtering dashboards. items: type: string maxLength: 32 maxItems: 50 example: - development filters: type: array description: >- Dashboard filter keys to add to the dashboard and apply across all tiles items: $ref: '#/components/schemas/FilterInput' savedQuery: type: string nullable: true description: Optional default dashboard query to persist on the dashboard. example: service.name = 'api' savedQueryLanguage: $ref: '#/components/schemas/QueryLanguage' nullable: true description: Query language used by savedQuery. default: lucene example: sql savedFilterValues: type: array description: >- Optional default dashboard filter values to persist on the dashboard. items: $ref: '#/components/schemas/SavedFilterValue' containers: type: array description: >- Optional grouping containers. Each tile may join a container via tile.containerId, and a tab inside it via tile.tabId. maxItems: 50 items: $ref: '#/components/schemas/DashboardContainer' Error: type: object properties: message: type: string description: Human-readable error message. example: 'NOT_FOUND: Alert not found' TileInput: description: > Input / request format when creating or updating tiles. The id field is optional: on create it is ignored (the server always assigns a new ID); on update, a matching id is used to identify the existing tile to preserve. Tiles whose id does not match an existing tile are assigned a new generated ID. allOf: - $ref: '#/components/schemas/TileBase' - type: object properties: id: type: string maxLength: 36 description: Optional tile ID. Omit to generate a new ID. example: 65f5e4a3b9e77c001a901234 asRatio: type: boolean description: >- Display two series as a ratio (series[0] / series[1]). Only applicable when providing "series". Deprecated in favor of "config.asRatio". example: false deprecated: true series: type: array minItems: 1 description: >- Data series to display in this tile (all must be the same type). Deprecated; use "config" instead. deprecated: true items: $ref: '#/components/schemas/DashboardChartSeries' FilterInput: type: object description: Dashboard filter key that can be added to a dashboard required: - type - name - expression - sourceId properties: type: type: string enum: - QUERY_EXPRESSION description: Filter type. Must be "QUERY_EXPRESSION". example: QUERY_EXPRESSION name: type: string minLength: 1 description: Display name for the dashboard filter key example: Environment expression: type: string minLength: 1 description: Key expression used when applying this dashboard filter key example: environment sourceId: type: string description: Source ID this dashboard filter key applies to example: 65f5e4a3b9e77c001a111111 sourceMetricType: type: string enum: - sum - gauge - histogram - summary - exponential histogram description: Metric type when source is metrics example: gauge where: type: string description: >- Optional WHERE condition to scope which rows this filter key reads values from example: ServiceName:api whereLanguage: type: string enum: - sql - lucene description: Language of the where condition default: sql example: lucene appliesToSourceIds: type: array items: type: string description: > 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). example: - 65f5e4a3b9e77c001a111111 QueryLanguage: type: string enum: - sql - lucene description: Query language for the where clause. SavedFilterValue: type: object required: - condition properties: type: type: string enum: - sql default: sql description: Filter type. Currently only "sql" is supported. example: sql condition: type: string description: >- SQL filter condition. For example use expressions in the form "column IN ('value')". example: ServiceName IN ('hdx-oss-dev-api') DashboardContainer: type: object description: >- A grouping container for tiles on a dashboard. Tiles join a container via containerId. required: - id - title - collapsed properties: id: type: string minLength: 1 maxLength: 256 description: Unique identifier for the container within the dashboard. example: service-health title: type: string minLength: 1 maxLength: 256 description: Display title for the container. example: Service Health collapsed: type: boolean description: Persisted default collapse state. Per-viewer state lives in the URL. example: false collapsible: type: boolean description: Whether the user can collapse the group. default: true example: true bordered: type: boolean description: Whether to show a visual border around the group. default: true example: true tabs: type: array description: >- Optional tabs. 2+ entries renders a tab bar; 0-1 entries renders a plain group header. Tiles join a tab via tabId. maxItems: 20 items: $ref: '#/components/schemas/DashboardContainerTab' TileBase: type: object description: Common fields shared by tile input and output required: - name - x - 'y' - w - h properties: name: type: string description: Display name for the tile example: Error Rate x: type: integer minimum: 0 maximum: 23 description: Horizontal position in the grid (0-based) example: 0 'y': type: integer minimum: 0 description: Vertical position in the grid (0-based) example: 0 w: type: integer minimum: 1 maximum: 24 description: Width in grid units example: 6 h: type: integer minimum: 1 description: Height in grid units example: 3 config: $ref: '#/components/schemas/TileConfig' description: >- Chart configuration for the tile. The displayType field determines which variant is used. Replaces the deprecated "series" and "asRatio" fields. containerId: type: string minLength: 1 maxLength: 256 description: >- References a DashboardContainer by id. Tiles without containerId render in the default ungrouped area. example: service-health tabId: type: string minLength: 1 maxLength: 256 description: >- 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 DashboardChartSeries: oneOf: - $ref: '#/components/schemas/TimeChartSeries' - $ref: '#/components/schemas/TableChartSeries' - $ref: '#/components/schemas/NumberChartSeries' - $ref: '#/components/schemas/SearchChartSeries' - $ref: '#/components/schemas/MarkdownChartSeries' discriminator: propertyName: type mapping: time: $ref: '#/components/schemas/TimeChartSeries' table: $ref: '#/components/schemas/TableChartSeries' number: $ref: '#/components/schemas/NumberChartSeries' search: $ref: '#/components/schemas/SearchChartSeries' markdown: $ref: '#/components/schemas/MarkdownChartSeries' DashboardContainerTab: type: object description: A single tab inside a dashboard container. Tiles join a tab via tabId. required: - id - title properties: id: type: string minLength: 1 maxLength: 256 description: Unique identifier for the tab within its container. example: errors title: type: string minLength: 1 maxLength: 256 description: Display title for the tab. example: Errors TileConfig: description: > Tile chart configuration. displayType is the primary discriminant and determines which variant group applies. For displayTypes that support both builder and Raw SQL modes (line, stacked_bar, table, number, pie, bar), configType is the secondary discriminant: omit it for the builder variant or set it to "sql" for the Raw SQL variant. The heatmap, search, event_patterns, and markdown displayTypes only have a builder variant. oneOf: - $ref: '#/components/schemas/LineChartConfig' - $ref: '#/components/schemas/BarChartConfig' - $ref: '#/components/schemas/TableChartConfig' - $ref: '#/components/schemas/NumberChartConfig' - $ref: '#/components/schemas/PieChartConfig' - $ref: '#/components/schemas/CategoricalBarChartConfig' - $ref: '#/components/schemas/HeatmapChartConfig' - $ref: '#/components/schemas/SearchChartConfig' - $ref: '#/components/schemas/EventPatternsChartConfig' - $ref: '#/components/schemas/MarkdownChartConfig' discriminator: propertyName: displayType mapping: line: $ref: '#/components/schemas/LineChartConfig' stacked_bar: $ref: '#/components/schemas/BarChartConfig' table: $ref: '#/components/schemas/TableChartConfig' number: $ref: '#/components/schemas/NumberChartConfig' pie: $ref: '#/components/schemas/PieChartConfig' bar: $ref: '#/components/schemas/CategoricalBarChartConfig' heatmap: $ref: '#/components/schemas/HeatmapChartConfig' search: $ref: '#/components/schemas/SearchChartConfig' event_patterns: $ref: '#/components/schemas/EventPatternsChartConfig' markdown: $ref: '#/components/schemas/MarkdownChartConfig' TimeChartSeries: type: object required: - type - sourceId - aggFn - where - whereLanguage - groupBy properties: type: type: string enum: - time description: Series type discriminator. Must be "time" for time-series charts. example: time sourceId: type: string description: ID of the data source to query example: 65f5e4a3b9e77c001a567890 aggFn: $ref: '#/components/schemas/AggregationFunction' description: Aggregation function to apply to the field or metric value example: count level: type: number minimum: 0 maximum: 1 description: Percentile level for quantile aggregations (e.g., 0.95 for p95) example: 0.95 field: type: string description: >- Column or expression to aggregate (required for most aggregation functions except count) example: duration alias: type: string description: Display name for the series in the chart example: Request Duration where: type: string description: Filter query for the data (syntax depends on whereLanguage) example: service:api whereLanguage: $ref: '#/components/schemas/QueryLanguage' description: Query language for the where clause example: lucene groupBy: type: array items: type: string maxItems: 10 description: Fields to group results by (creates separate series for each group) example: - host numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. metricDataType: $ref: '#/components/schemas/MetricDataType' description: Metric data type, only for metrics data sources. example: sum metricName: type: string description: Metric name for metrics data sources example: http.server.duration displayType: $ref: '#/components/schemas/TimeSeriesDisplayType' description: Visual representation type for the time series example: line TableChartSeries: type: object required: - type - sourceId - aggFn - where - whereLanguage - groupBy properties: type: type: string enum: - table description: Series type discriminator. Must be "table" for table charts. example: table sourceId: type: string description: ID of the data source to query example: 65f5e4a3b9e77c001a567890 aggFn: $ref: '#/components/schemas/AggregationFunction' description: Aggregation function to apply to the field or metric value example: count level: type: number minimum: 0 maximum: 1 description: Percentile level for quantile aggregations (e.g., 0.95 for p95) example: 0.95 field: type: string description: >- Column or expression to aggregate (required for most aggregation functions except count) example: duration alias: type: string description: Display name for the series example: Total Count where: type: string description: Filter query for the data (syntax depends on whereLanguage) example: level:error whereLanguage: $ref: '#/components/schemas/QueryLanguage' description: Query language for the where clause example: lucene groupBy: type: array items: type: string maxItems: 10 description: Fields to group results by (creates separate rows for each group) example: - errorType sortOrder: $ref: '#/components/schemas/SortOrder' description: Sort order for table rows example: desc numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. metricDataType: $ref: '#/components/schemas/MetricDataType' description: Metric data type, only for metrics data sources. example: sum metricName: type: string description: Metric name for metrics data sources example: http.server.duration NumberChartSeries: type: object required: - type - sourceId - aggFn - where - whereLanguage properties: type: type: string enum: - number description: >- Series type discriminator. Must be "number" for single-value number charts. example: number sourceId: type: string description: ID of the data source to query example: 65f5e4a3b9e77c001a567890 aggFn: $ref: '#/components/schemas/AggregationFunction' description: Aggregation function to apply to the field or metric value example: count level: type: number minimum: 0 maximum: 1 description: Percentile level for quantile aggregations (e.g., 0.95 for p95) example: 0.95 field: type: string description: >- Column or expression to aggregate (required for most aggregation functions except count) example: duration alias: type: string description: Display name for the series in the chart example: Total Requests where: type: string description: Filter query for the data (syntax depends on whereLanguage) example: service:api whereLanguage: $ref: '#/components/schemas/QueryLanguage' description: Query language for the where clause example: lucene numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. metricDataType: $ref: '#/components/schemas/MetricDataType' description: Metric data type, only for metrics data sources. example: sum metricName: type: string description: Metric name for metrics data sources. example: http.server.duration SearchChartSeries: type: object required: - type - sourceId - fields - where - whereLanguage properties: type: type: string enum: - search description: >- Series type discriminator. Must be "search" for search/log viewer charts. example: search sourceId: type: string description: ID of the data source to query example: 65f5e4a3b9e77c001a567890 fields: type: array items: type: string description: List of field names to display in the search results table example: - timestamp - level - message where: type: string description: Filter query for the data (syntax depends on whereLanguage) example: level:error whereLanguage: $ref: '#/components/schemas/QueryLanguage' description: Query language for the where clause example: lucene MarkdownChartSeries: type: object required: - type - content properties: type: type: string enum: - markdown description: >- Series type discriminator. Must be "markdown" for markdown text widgets. example: markdown content: type: string description: Markdown content to render inside the widget. example: |- # Dashboard Title This is a markdown widget. maxLength: 100000 LineChartConfig: description: > Line chart. Omit configType for the builder variant (requires sourceId and select). Set configType to "sql" for the Raw SQL variant (requires connectionId and sqlTemplate). oneOf: - $ref: '#/components/schemas/LineBuilderChartConfig' - $ref: '#/components/schemas/LineRawSqlChartConfig' discriminator: propertyName: configType mapping: sql: $ref: '#/components/schemas/LineRawSqlChartConfig' BarChartConfig: description: > Stacked-bar chart. Omit configType for the builder variant (requires sourceId and select). Set configType to "sql" for the Raw SQL variant (requires connectionId and sqlTemplate). oneOf: - $ref: '#/components/schemas/BarBuilderChartConfig' - $ref: '#/components/schemas/BarRawSqlChartConfig' discriminator: propertyName: configType mapping: sql: $ref: '#/components/schemas/BarRawSqlChartConfig' TableChartConfig: description: > Table chart. Omit configType for the builder variant (requires sourceId and select). Set configType to "sql" for the Raw SQL variant (requires connectionId and sqlTemplate). oneOf: - $ref: '#/components/schemas/TableBuilderChartConfig' - $ref: '#/components/schemas/TableRawSqlChartConfig' discriminator: propertyName: configType mapping: sql: $ref: '#/components/schemas/TableRawSqlChartConfig' NumberChartConfig: description: > Single big-number chart. Omit configType for the builder variant (requires sourceId and select). Set configType to "sql" for the Raw SQL variant (requires connectionId and sqlTemplate). oneOf: - $ref: '#/components/schemas/NumberBuilderChartConfig' - $ref: '#/components/schemas/NumberRawSqlChartConfig' discriminator: propertyName: configType mapping: sql: $ref: '#/components/schemas/NumberRawSqlChartConfig' PieChartConfig: description: > Pie chart. Omit configType for the builder variant (requires sourceId and select). Set configType to "sql" for the Raw SQL variant (requires connectionId and sqlTemplate). oneOf: - $ref: '#/components/schemas/PieBuilderChartConfig' - $ref: '#/components/schemas/PieRawSqlChartConfig' discriminator: propertyName: configType mapping: sql: $ref: '#/components/schemas/PieRawSqlChartConfig' CategoricalBarChartConfig: description: > Categorical bar chart (one bar per group value; not a time series). Omit configType for the builder variant (requires sourceId and select). Set configType to "sql" for the Raw SQL variant (requires connectionId and sqlTemplate). oneOf: - $ref: '#/components/schemas/CategoricalBarBuilderChartConfig' - $ref: '#/components/schemas/CategoricalBarRawSqlChartConfig' discriminator: propertyName: configType mapping: sql: $ref: '#/components/schemas/CategoricalBarRawSqlChartConfig' HeatmapChartConfig: type: object required: - displayType - sourceId - select description: > Builder configuration for a heatmap tile. Heatmap is builder-only (no Raw SQL variant) and currently supports trace sources. The row-level filter lives at the chart-config level (where / whereLanguage), matching the HeatmapSeriesEditor in the UI. properties: displayType: type: string enum: - heatmap description: Display type discriminator. Must be "heatmap" for heatmap tiles. example: heatmap sourceId: type: string description: ID of the data source to query. example: 65f5e4a3b9e77c001a111111 select: type: array minItems: 1 maxItems: 1 description: Exactly one heatmap select item. items: $ref: '#/components/schemas/HeatmapSelectItem' where: type: string maxLength: 10000 description: Row-level filter (syntax depends on whereLanguage). default: '' example: ServiceName = 'api' whereLanguage: $ref: '#/components/schemas/QueryLanguage' description: Query language for the where clause. default: lucene numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. SearchChartConfig: type: object required: - displayType - sourceId - select - whereLanguage description: Configuration for a raw-event search / log viewer tile. properties: displayType: type: string enum: - search description: >- Display type discriminator. Must be "search" for search/log viewer tiles. example: search sourceId: type: string description: ID of the data source to query. example: 65f5e4a3b9e77c001a111111 select: type: string maxLength: 10000 description: Comma-separated list of expressions to display. example: timestamp, level, message where: type: string maxLength: 10000 description: Filter condition for the search (syntax depends on whereLanguage). default: '' example: level:error whereLanguage: $ref: '#/components/schemas/QueryLanguage' description: Query language for the where clause. EventPatternsChartConfig: type: object required: - displayType - sourceId description: >- Configuration for an event pattern mining tile. Clusters log or trace events by recurring message shapes. properties: displayType: type: string enum: - event_patterns description: >- Display type discriminator. Must be "event_patterns" for pattern mining tiles. example: event_patterns sourceId: type: string description: ID of the data source to mine patterns from. example: 65f5e4a3b9e77c001a111111 select: type: string maxLength: 10000 description: >- Column or expression to mine patterns from. Leave empty to use the source default (Body for logs, SpanName for traces). default: '' example: Body where: type: string maxLength: 10000 description: >- Filter condition for the pattern mining query (syntax depends on whereLanguage). default: '' example: level:error whereLanguage: $ref: '#/components/schemas/QueryLanguage' description: Query language for the where clause. MarkdownChartConfig: type: object required: - displayType description: Configuration for a freeform Markdown text tile. properties: displayType: type: string enum: - markdown description: >- Display type discriminator. Must be "markdown" for markdown text tiles. example: markdown markdown: type: string maxLength: 50000 description: Markdown content to render inside the tile. example: |- # Dashboard Title This is a markdown widget. AggregationFunction: type: string enum: - avg - count - count_distinct - last_value - max - min - quantile - sum - any - none description: Aggregation function to apply to the field or metric value. NumberFormat: type: object properties: output: $ref: '#/components/schemas/NumberFormatOutput' description: Output format applied to the number. example: number mantissa: type: integer description: Number of decimal places. example: 2 thousandSeparated: type: boolean description: Whether to use thousand separators. example: true average: type: boolean description: Whether to show as average. example: false decimalBytes: type: boolean description: Use decimal bytes (1000) vs binary bytes (1024). example: false factor: type: number description: Multiplication factor. example: 1 currencySymbol: type: string description: Currency symbol for currency format. example: $ numericUnit: type: string enum: - bytes_iec - bytes_si - bits_iec - bits_si - kibibytes - kilobytes - mebibytes - megabytes - gibibytes - gigabytes - tebibytes - terabytes - pebibytes - petabytes - packets_sec - bytes_sec_iec - bytes_sec_si - bits_sec_iec - bits_sec_si - kibibytes_sec - kibibits_sec - kilobytes_sec - kilobits_sec - mebibytes_sec - mebibits_sec - megabytes_sec - megabits_sec - gibibytes_sec - gibibits_sec - gigabytes_sec - gigabits_sec - tebibytes_sec - tebibits_sec - terabytes_sec - terabits_sec - pebibytes_sec - pebibits_sec - petabytes_sec - petabits_sec - cps - ops - rps - reads_sec - wps - iops - cpm - opm - rpm_reads - wpm description: Numeric unit for data, data rate, or throughput formats. example: bytes_iec unit: type: string description: Custom unit label. example: ms MetricDataType: type: string enum: - sum - gauge - histogram - summary - exponential histogram description: Metric data type, only for metrics data sources. TimeSeriesDisplayType: type: string enum: - stacked_bar - line description: Visual representation type for the time series. SortOrder: type: string enum: - desc - asc description: Sort order for table rows. LineBuilderChartConfig: type: object required: - displayType - sourceId - select description: Builder configuration for a line time-series chart. properties: displayType: type: string enum: - line description: Display type discriminator. Must be "line" for line charts. example: line sourceId: type: string description: ID of the data source to query. example: 65f5e4a3b9e77c001a111111 select: type: array minItems: 1 maxItems: 20 description: > One or more aggregated values to plot. When asRatio is true, exactly two select items are required. items: $ref: '#/components/schemas/SelectItem' groupBy: type: string description: >- Field expression to group results by (creates separate lines per group value). example: host maxLength: 10000 asRatio: type: boolean description: >- Plot select[0] / select[1] as a ratio. Requires exactly two select items. default: false alignDateRangeToGranularity: type: boolean description: Expand date range boundaries to the query granularity interval. default: true fillNulls: type: boolean description: Fill missing time buckets with zero instead of leaving gaps. default: true fitYAxisToData: type: boolean description: > Set the y-axis lower bound to the minimum of the displayed data instead of zero, making small fluctuations between series easier to see. default: false numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. compareToPreviousPeriod: type: boolean description: Overlay the equivalent previous time period for comparison. default: false LineRawSqlChartConfig: description: Raw SQL configuration for a line time-series chart. allOf: - $ref: '#/components/schemas/RawSqlChartConfigBase' - type: object required: - displayType properties: displayType: type: string enum: - line description: Display as a line time-series chart. example: line compareToPreviousPeriod: type: boolean description: Overlay the equivalent previous time period for comparison. default: false fillNulls: type: boolean description: Fill missing time buckets with zero instead of leaving gaps. default: true alignDateRangeToGranularity: type: boolean description: Expand date range boundaries to the query granularity interval. default: true fitYAxisToData: type: boolean description: > Set the y-axis lower bound to the minimum of the displayed data instead of zero, making small fluctuations between series easier to see. default: false BarBuilderChartConfig: type: object required: - displayType - sourceId - select description: Builder configuration for a stacked-bar time-series chart. properties: displayType: type: string enum: - stacked_bar description: >- Display type discriminator. Must be "stacked_bar" for stacked-bar charts. example: stacked_bar sourceId: type: string description: ID of the data source to query. example: 65f5e4a3b9e77c001a111111 select: type: array minItems: 1 maxItems: 20 description: > One or more aggregated values to plot. When asRatio is true, exactly two select items are required. items: $ref: '#/components/schemas/SelectItem' groupBy: type: string description: >- Field expression to group results by (creates separate bars segments per group value). example: service maxLength: 10000 asRatio: type: boolean description: >- Plot select[0] / select[1] as a ratio. Requires exactly two select items. default: false alignDateRangeToGranularity: type: boolean description: Align the date range boundaries to the query granularity interval. default: true fillNulls: type: boolean description: Fill missing time buckets with zero instead of leaving gaps. default: true numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. BarRawSqlChartConfig: description: Raw SQL configuration for a stacked-bar time-series chart. allOf: - $ref: '#/components/schemas/RawSqlChartConfigBase' - type: object required: - displayType properties: displayType: type: string enum: - stacked_bar description: Display as a stacked-bar time-series chart. example: stacked_bar fillNulls: type: boolean description: Fill missing time buckets with zero instead of leaving gaps. default: true alignDateRangeToGranularity: type: boolean description: Expand date range boundaries to the query granularity interval. default: true TableBuilderChartConfig: type: object required: - displayType - sourceId - select description: Builder configuration for a table aggregation chart. properties: displayType: type: string enum: - table description: Display type discriminator. Must be "table" for table charts. example: table sourceId: type: string description: ID of the data source to query. example: 65f5e4a3b9e77c001a111111 select: type: array minItems: 1 maxItems: 20 description: > One or more aggregated values to display as table columns. When asRatio is true, exactly two select items are required. items: $ref: '#/components/schemas/SelectItem' groupBy: type: string maxLength: 10000 description: Field expression to group results by (one row per group value). example: service having: type: string maxLength: 10000 description: Post-aggregation SQL HAVING condition. example: count > 100 orderBy: type: string maxLength: 10000 description: SQL ORDER BY expression for sorting table rows. example: count DESC asRatio: type: boolean description: >- Display select[0] / select[1] as a ratio. Requires exactly two select items. example: false numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. groupByColumnsOnLeft: type: boolean description: > When true, render Group By columns to the left of series columns in the table. Defaults to false (Group By columns on the right). default: false example: false onClick: $ref: '#/components/schemas/OnClick' description: Optional link-out configuration applied when a user clicks a row. TableRawSqlChartConfig: description: Raw SQL configuration for a table chart. allOf: - $ref: '#/components/schemas/RawSqlChartConfigBase' - type: object required: - displayType properties: displayType: type: string enum: - table description: Display as a table chart. example: table onClick: $ref: '#/components/schemas/OnClick' description: >- Optional link-out configuration applied when a user clicks a row. NumberBuilderChartConfig: type: object required: - displayType - sourceId - select description: Builder configuration for a single big-number chart. properties: displayType: type: string enum: - number description: >- Display type discriminator. Must be "number" for single big-number charts. example: number sourceId: type: string description: ID of the data source to query. example: 65f5e4a3b9e77c001a111111 select: type: array minItems: 1 maxItems: 1 description: Exactly one aggregated value to display as a single number. items: $ref: '#/components/schemas/SelectItem' numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. color: $ref: '#/components/schemas/ChartPaletteToken' description: Optional static color applied to the displayed number. colorRules: type: array maxItems: 10 description: > Ordered conditional color rules evaluated against the displayed value (last match wins). Falls back to color, then the default text color when no rule matches. items: $ref: '#/components/schemas/NumberTileColorCondition' backgroundChart: $ref: '#/components/schemas/BackgroundChart' description: | Optional background trend sparkline drawn behind the value. NumberRawSqlChartConfig: description: Raw SQL configuration for a single big-number chart. allOf: - $ref: '#/components/schemas/RawSqlChartConfigBase' - type: object required: - displayType properties: displayType: type: string enum: - number description: Display as a single big-number chart. example: number color: $ref: '#/components/schemas/ChartPaletteToken' description: > Optional static color applied to the displayed number. Raw SQL number tiles do not support conditional colorRules. PieBuilderChartConfig: type: object required: - displayType - sourceId - select description: >- Builder configuration for a pie chart tile. Each slice represents one group value. properties: displayType: type: string enum: - pie description: Display type discriminator. Must be "pie" for pie charts. example: pie sourceId: type: string description: ID of the data source to query. example: 65f5e4a3b9e77c001a111111 select: type: array minItems: 1 maxItems: 1 description: Exactly one aggregated value used to size each pie slice. items: $ref: '#/components/schemas/SelectItem' groupBy: type: string maxLength: 10000 description: Field expression to group results by (one slice per group value). example: service orderBy: type: string maxLength: 10000 description: > Optional custom SQL ORDER BY expression (raw SQL). Overrides the default value-descending ordering and, when combined with "limit", controls which slices are kept. example: '"Count" DESC' numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. limit: type: integer minimum: 1 description: > Maximum number of slices (SQL LIMIT). Without a custom "orderBy" the query keeps the groups with the largest aggregated values; with an "orderBy" it keeps the first slices in that order. Omit to fetch all groups. example: 10 PieRawSqlChartConfig: description: Raw SQL configuration for a pie chart. allOf: - $ref: '#/components/schemas/RawSqlChartConfigBase' - type: object required: - displayType properties: displayType: type: string enum: - pie description: Display as a pie chart. example: pie CategoricalBarBuilderChartConfig: type: object required: - displayType - sourceId - select description: > Builder configuration for a categorical bar chart tile. Each bar represents one group value. Distinct from stacked_bar, which is a time-series chart. properties: displayType: type: string enum: - bar description: >- Display type discriminator. Must be "bar" for categorical bar charts. example: bar sourceId: type: string description: ID of the data source to query. example: 65f5e4a3b9e77c001a111111 select: type: array minItems: 1 maxItems: 1 description: Exactly one aggregated value used to size each bar. items: $ref: '#/components/schemas/SelectItem' groupBy: type: string maxLength: 10000 description: Field expression to group results by (one bar per group value). example: service orderBy: type: string maxLength: 10000 description: > Optional custom SQL ORDER BY expression (raw SQL). Overrides the default value-descending ordering and, when combined with "limit", controls which bars are kept. example: '"Count" DESC' numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. limit: type: integer minimum: 1 description: > Maximum number of bars (SQL LIMIT). Without a custom "orderBy" the query keeps the groups with the largest aggregated values; with an "orderBy" it keeps the first bars in that order. Omit to fetch all groups. example: 10 CategoricalBarRawSqlChartConfig: description: Raw SQL configuration for a categorical bar chart. allOf: - $ref: '#/components/schemas/RawSqlChartConfigBase' - type: object required: - displayType properties: displayType: type: string enum: - bar description: Display as a categorical bar chart. example: bar HeatmapSelectItem: type: object required: - valueExpression description: > Single select item for a heatmap tile. The value being bucketed is provided in valueExpression and the count contributing to each bucket in countExpression. The heatmap-specific fields (countExpression, heatmapScaleType) are persisted on the select item, not the chart config. The chart-level discriminator is the HeatmapChartConfig's `displayType: "heatmap"`; no aggregation function or alias is exposed on this select item because the heatmap aggregation function is fixed internally and the HeatmapSeriesEditor does not render an alias input. properties: valueExpression: type: string minLength: 1 maxLength: 10000 description: >- SQL expression for the value being bucketed on the y-axis. Must be non-empty. example: Duration countExpression: type: string maxLength: 10000 description: > SQL expression for the count contributing to each bucket. Defaults to "count()" in the editor when omitted. example: count() heatmapScaleType: type: string enum: - log - linear description: Scale type used to bucket values on the y-axis. example: log NumberFormatOutput: type: string enum: - currency - percent - byte - time - number - data_rate - throughput - duration description: >- Output format type (currency, percent, byte, time, number, data_rate, throughput, duration). SelectItem: type: object required: - aggFn description: > A single aggregated value to compute. The valueExpression must be omitted when aggFn is "count", and required for all other functions. The level field may only be used with aggFn "quantile". properties: aggFn: $ref: '#/components/schemas/AggregationFunction' description: > Aggregation function to apply. "count" does not require a valueExpression; "quantile" requires a level field indicating the desired percentile (e.g., 0.95). example: count valueExpression: type: string maxLength: 10000 description: > Expression for the column or value to aggregate. Must be omitted when aggFn is "count"; required for all other aggFn values. example: Duration alias: type: string maxLength: 10000 description: Display alias for this select item in chart legends. example: Request Duration level: $ref: '#/components/schemas/QuantileLevel' description: Percentile level; only valid when aggFn is "quantile". where: type: string maxLength: 10000 description: SQL or Lucene filter condition applied before aggregation. default: '' example: service:api whereLanguage: $ref: '#/components/schemas/QueryLanguage' description: Query language for the where clause. metricName: type: string description: >- Name of the metric to aggregate; only applicable when the source is a metrics source. example: http.server.duration metricType: $ref: '#/components/schemas/MetricDataType' description: Metric type; only applicable when the source is a metrics source. periodAggFn: type: string enum: - delta description: >- Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period). example: delta numberFormat: $ref: '#/components/schemas/NumberFormat' description: > Per-series number formatting options. When set, takes precedence over the chart-level numberFormat for this select item only. RawSqlChartConfigBase: type: object required: - configType - connectionId - sqlTemplate description: >- Shared fields for Raw SQL chart configs. Set configType to "sql" and provide connectionId + sqlTemplate instead of sourceId + select. properties: configType: type: string enum: - sql description: Must be "sql" to use the Raw SQL chart config variant. example: sql connectionId: type: string description: ID of the ClickHouse connection to execute the query against. example: 65f5e4a3b9e77c001a567890 sqlTemplate: type: string maxLength: 100000 description: SQL query template to execute. Supports HyperDX template variables. example: >- SELECT count() FROM otel_logs WHERE timestamp > now() - INTERVAL 1 HOUR sourceId: type: string description: >- Optional ID of the data source associated with this Raw SQL chart. Used for applying dashboard filters. example: 65f5e4a3b9e77c001a567890 numberFormat: $ref: '#/components/schemas/NumberFormat' description: Number formatting options for displayed values. OnClick: description: > Link-out configuration applied when a user clicks a row of a table tile. Only table tiles (builder or raw SQL) currently support onClick. When target.mode is "id", the referenced source (type=search) or dashboard (type=dashboard) must already exist for the team. oneOf: - $ref: '#/components/schemas/OnClickSearch' - $ref: '#/components/schemas/OnClickDashboard' - $ref: '#/components/schemas/OnClickExternal' discriminator: propertyName: type mapping: search: $ref: '#/components/schemas/OnClickSearch' dashboard: $ref: '#/components/schemas/OnClickDashboard' external: $ref: '#/components/schemas/OnClickExternal' ChartPaletteToken: type: string enum: - chart-blue - chart-orange - chart-red - chart-cyan - chart-green - chart-pink - chart-purple - chart-light-blue - chart-brown - chart-gray - chart-success - chart-warning - chart-error description: > Palette token used to color a number tile. Tokens reflow across light and dark themes, so raw hex values are not accepted. example: chart-red NumberTileColorCondition: description: > A single conditional color rule for a number tile. Rules are evaluated in order and the last matching rule wins. When no rule matches, the static color applies, then the default text color. The number-tile editor surfaces numeric and equality operators only. oneOf: - $ref: '#/components/schemas/NumericColorCondition' - $ref: '#/components/schemas/BetweenColorCondition' - $ref: '#/components/schemas/EqualityColorCondition' discriminator: propertyName: operator mapping: gt: $ref: '#/components/schemas/NumericColorCondition' gte: $ref: '#/components/schemas/NumericColorCondition' lt: $ref: '#/components/schemas/NumericColorCondition' lte: $ref: '#/components/schemas/NumericColorCondition' between: $ref: '#/components/schemas/BetweenColorCondition' eq: $ref: '#/components/schemas/EqualityColorCondition' neq: $ref: '#/components/schemas/EqualityColorCondition' BackgroundChart: type: object required: - type description: > Optional background trend sparkline drawn behind a number tile's value, derived from a time-bucketed version of the tile's query. Builder number tiles only (raw SQL number tiles have no time dimension to bucket). properties: type: type: string enum: - line - area description: Sparkline shape. example: line color: $ref: '#/components/schemas/ChartPaletteToken' description: > Optional palette-token override for the sparkline. When unset the sparkline inherits the tile's static color. QuantileLevel: type: number enum: - 0.5 - 0.9 - 0.95 - 0.99 description: Percentile level; only valid when aggFn is "quantile". OnClickSearch: type: object required: - type - target description: Link-out that navigates to the HyperDX search view. properties: type: type: string enum: - search description: >- OnClick variant discriminator. Must be "search" for search link-outs. example: search target: $ref: '#/components/schemas/OnClickTarget' description: The source to navigate to. whereTemplate: type: string description: Optional WHERE clause template applied to the destination search. example: ServiceName = '{{ServiceName}}' whereLanguage: $ref: '#/components/schemas/QueryLanguage' description: Language of the rendered whereTemplate. filters: type: array description: >- Optional dashboard filter templates rendered against the clicked row. items: $ref: '#/components/schemas/OnClickFilterTemplate' OnClickDashboard: type: object required: - type - target description: Link-out that navigates to a HyperDX dashboard. properties: type: type: string enum: - dashboard description: >- OnClick variant discriminator. Must be "dashboard" for dashboard link-outs. example: dashboard target: $ref: '#/components/schemas/OnClickTarget' description: The dashboard to navigate to. whereTemplate: type: string description: Optional WHERE clause template applied to the destination dashboard. example: ServiceName = '{{ServiceName}}' whereLanguage: $ref: '#/components/schemas/QueryLanguage' description: Language of the rendered whereTemplate. filters: type: array description: >- Optional dashboard filter templates rendered against the clicked row. items: $ref: '#/components/schemas/OnClickFilterTemplate' OnClickExternal: type: object required: - type - urlTemplate description: > Link-out that navigates to an arbitrary external URL (e.g. a Grafana or Langfuse dashboard). The rendered URL must be an absolute http(s) URL. properties: type: type: string enum: - external description: >- OnClick variant discriminator. Must be "external" for external link-outs. example: external urlTemplate: type: string minLength: 1 description: > Handlebars template rendered against the clicked row; supports `{{column}}` variables. The rendered value must be an absolute http(s) URL. example: https://example.com/d/abc?var-service={{ServiceName}} NumericColorCondition: type: object required: - operator - value - color description: Color rule comparing the displayed value against a single numeric bound. properties: operator: type: string enum: - gt - gte - lt - lte description: Numeric comparison operator. example: gt value: type: number description: > Numeric bound the displayed value is compared against. Only finite numbers are accepted (Infinity and NaN are rejected). example: 100 color: $ref: '#/components/schemas/ChartPaletteToken' description: Color applied when the rule matches. label: type: string maxLength: 40 description: Optional label describing the rule. example: High BetweenColorCondition: type: object required: - operator - value - color description: >- Color rule matching when the displayed value falls within an inclusive range. properties: operator: type: string enum: - between description: Range comparison operator. example: between value: type: array minItems: 2 maxItems: 2 items: type: number description: | Inclusive [min, max] range. Both bounds must be finite numbers. example: - 100 - 500 color: $ref: '#/components/schemas/ChartPaletteToken' description: Color applied when the rule matches. label: type: string maxLength: 40 description: Optional label describing the rule. example: Warning EqualityColorCondition: type: object required: - operator - value - color description: >- Color rule matching when the displayed value equals (eq) or does not equal (neq) a number or string. properties: operator: type: string enum: - eq - neq description: Equality comparison operator. example: eq value: oneOf: - type: number - type: string maxLength: 200 description: > A finite number, or a string up to 200 characters, to compare for equality. example: OK color: $ref: '#/components/schemas/ChartPaletteToken' description: Color applied when the rule matches. label: type: string maxLength: 40 description: Optional label describing the rule. example: Healthy OnClickTarget: description: > Identifies the source (for type=search) or dashboard (for type=dashboard) to link out to. Set mode to "id" to resolve a concrete ID, or "template" to resolve by rendered name at click time. oneOf: - type: object required: - mode - id properties: mode: type: string enum: - id description: Target is a single dashboard or log/trace source example: id id: type: string description: >- ID of the target source (for search) or dashboard (for dashboard). example: 65f5e4a3b9e77c001a567890 - type: object required: - mode - template properties: mode: type: string enum: - template description: Target is matched by name against the template. example: template template: type: string minLength: 1 description: > Name template rendered against the clicked row; supports `{{column}}` variables. example: '{{ServiceName}}' discriminator: propertyName: mode OnClickFilterTemplate: type: object description: > A templated filter applied to the link-out destination. The rendered template value is combined with the expression as `expression IN (...)` on the destination search or dashboard. Multiple templates sharing the same expression are merged into a single IN clause. required: - kind - expression - template properties: kind: type: string enum: - expressionTemplate description: >- Filter template kind. Currently only "expressionTemplate" is supported. example: expressionTemplate expression: type: string minLength: 1 description: >- The column/expression to filter the destination by (e.g. "ServiceName"). example: ServiceName template: type: string minLength: 1 description: > Value template rendered against the clicked row; supports row column variables in `{{column}}` form (e.g. `{{ServiceName}}`). example: '{{ServiceName}}' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key ````