> ## 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.

# List Alerts

> Retrieves alerts for the authenticated team (paginated). Results are capped at `limit` (default and maximum 1000). When more records exist than are returned, `meta.total` exceeds `data.length`; clients with large collections must page with `limit`/`offset` to retrieve them all.



## OpenAPI

````yaml https://raw.githubusercontent.com/hyperdxio/hyperdx/refs/heads/main/packages/api/openapi.json get /api/v2/alerts
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://<host>:<port>)
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/alerts:
    get:
      tags:
        - Alerts
      summary: List Alerts
      description: >-
        Retrieves alerts for the authenticated team (paginated). Results are
        capped at `limit` (default and maximum 1000). When more records exist
        than are returned, `meta.total` exceeds `data.length`; clients with
        large collections must page with `limit`/`offset` to retrieve them all.
      operationId: listAlerts
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
          description: Maximum number of alerts to return.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of alerts to skip before returning results.
      responses:
        '200':
          description: Successfully retrieved alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsListResponse'
              examples:
                alertsList:
                  summary: List of alerts
                  value:
                    data:
                      - id: 65f5e4a3b9e77c001a123456
                        threshold: 100
                        interval: 15m
                        thresholdType: above
                        source: tile
                        state: OK
                        channel:
                          type: webhook
                          webhookId: 65f5e4a3b9e77c001a789012
                        teamId: 65f5e4a3b9e77c001a345678
                        tileId: 65f5e4a3b9e77c001a901234
                        dashboardId: 65f5e4a3b9e77c001a567890
                        createdAt: '2023-01-01T00:00:00.000Z'
                        updatedAt: '2023-01-01T00:00:00.000Z'
                    meta:
                      total: 1
                      limit: 1000
                      offset: 0
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Unauthorized access. API key is missing or invalid.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AlertsListResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          type: array
          description: List of alert objects.
          items:
            $ref: '#/components/schemas/AlertResponse'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
          description: Pagination metadata for this result page.
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: 'NOT_FOUND: Alert not found'
    AlertResponse:
      allOf:
        - $ref: '#/components/schemas/Alert'
        - type: object
          properties:
            id:
              type: string
              description: Unique alert identifier.
              example: 65f5e4a3b9e77c001a123456
            state:
              $ref: '#/components/schemas/AlertState'
              description: Current alert state.
              example: ALERT
            teamId:
              type: string
              description: Team identifier.
              example: 65f5e4a3b9e77c001a345678
            silenced:
              $ref: '#/components/schemas/AlertSilenced'
              description: Silencing metadata.
              nullable: true
            executionErrors:
              type: array
              nullable: true
              description: Errors recorded during the most recent alert execution, if any.
              items:
                $ref: '#/components/schemas/AlertExecutionError'
            createdAt:
              type: string
              nullable: true
              format: date-time
              description: Creation timestamp.
              example: '2023-01-01T00:00:00.000Z'
            updatedAt:
              type: string
              nullable: true
              format: date-time
              description: Last update timestamp.
              example: '2023-01-01T00:00:00.000Z'
    PaginationMeta:
      type: object
      required:
        - total
        - limit
        - offset
      properties:
        total:
          type: integer
          description: Total number of items matching the query, ignoring pagination.
          example: 142
        limit:
          type: integer
          description: Maximum number of items returned in this page.
          example: 50
        offset:
          type: integer
          description: Number of items skipped before this page.
          example: 100
    Alert:
      type: object
      properties:
        dashboardId:
          type: string
          description: Dashboard ID for tile-based alerts.
          nullable: true
          example: 65f5e4a3b9e77c001a567890
        tileId:
          type: string
          description: >-
            Tile ID for tile-based alerts. Must be a line, stacked bar, or
            number type tile.
          nullable: true
          example: 65f5e4a3b9e77c001a901234
        savedSearchId:
          type: string
          description: Saved search ID for saved_search alerts.
          nullable: true
          example: 65f5e4a3b9e77c001a345678
        groupBy:
          type: string
          description: Group-by key for saved search alerts.
          nullable: true
          example: ServiceName
        chartConfig:
          $ref: '#/components/schemas/AlertChartConfig'
          description: >
            Chart configuration for inline alerts. Required when source is
            "inline" and rejected otherwise. Returned on single-alert responses
            (GET by ID, POST, PUT); the list endpoint omits it.
        threshold:
          type: number
          description: >-
            Threshold value for triggering the alert. For between and
            not_between threshold types, this is the lower bound.
          example: 100
        thresholdMax:
          type: number
          nullable: true
          description: >-
            Upper bound for between and not_between threshold types. Required
            when thresholdType is between or not_between, must be >= threshold.
          example: 500
        interval:
          $ref: '#/components/schemas/AlertInterval'
          description: Evaluation interval for the alert.
          example: 1h
        scheduleOffsetMinutes:
          type: integer
          minimum: 0
          description: >-
            Offset from the interval boundary in minutes. For example, 2 with a
            5m interval evaluates windows at :02, :07, :12, etc. (UTC).
          nullable: true
          example: 2
        scheduleStartAt:
          type: string
          format: date-time
          description: >-
            Absolute UTC start time anchor. Alert windows start from this
            timestamp and repeat every interval.
          nullable: true
          example: '2026-02-08T10:00:00.000Z'
        source:
          $ref: '#/components/schemas/AlertSource'
          description: Alert source type (tile-based or saved search).
          example: tile
        thresholdType:
          $ref: '#/components/schemas/AlertThresholdType'
          description: Threshold comparison direction.
          example: above
        channel:
          $ref: '#/components/schemas/AlertChannel'
          description: >-
            First notification channel, mirrored from "channels" for
            pre-multi-channel clients.
        channels:
          $ref: '#/components/schemas/AlertChannels'
          description: >-
            All notification channels to trigger when the alert fires or
            resolves.
        name:
          type: string
          description: Human-friendly alert name.
          nullable: true
          example: Test Alert
        message:
          type: string
          description: Alert message template.
          nullable: true
          example: Test Alert Message
        note:
          type: string
          description: Freeform note for the alert. Supports markdown formatting.
          nullable: true
          minLength: 1
          maxLength: 4096
          example: >-
            Threshold raised from 50 to 100 on 2026-01-15. See
            [runbook](https://wiki.example.com/runbook).
        numConsecutiveWindows:
          type: integer
          minimum: 1
          nullable: true
          description: >-
            Fire the alert only after its condition has been met for this many
            consecutive evaluation windows. While the condition is met but fewer
            than this many consecutive windows have violated, the alert is in
            the PENDING state.
          example: 3
    AlertState:
      type: string
      enum:
        - ALERT
        - OK
        - INSUFFICIENT_DATA
        - DISABLED
        - PENDING
      description: Current alert state.
    AlertSilenced:
      type: object
      description: Silencing metadata.
      properties:
        by:
          type: string
          description: User ID who silenced the alert.
          nullable: true
          example: 65f5e4a3b9e77c001a234567
        at:
          type: string
          description: Silence start timestamp.
          format: date-time
          example: '2026-03-19T08:00:00.000Z'
        until:
          type: string
          description: Silence end timestamp.
          format: date-time
          example: '2026-03-20T08:00:00.000Z'
    AlertExecutionError:
      type: object
      description: An error recorded during a recent alert execution.
      required:
        - timestamp
        - type
        - message
      properties:
        timestamp:
          type: string
          format: date-time
          description: When the error occurred.
          example: '2026-04-17T12:00:00.000Z'
        type:
          $ref: '#/components/schemas/AlertErrorType'
          description: Category of the error.
          example: QUERY_ERROR
        message:
          type: string
          description: Human-readable error message.
          example: Query timed out after 30s
    AlertChartConfig:
      description: >
        The chart configuration an inline alert evaluates, in the same dialect
        as dashboard tile configs plus the alert-only fields in
        AlertChartConfigOverlay. Only the display types the alert evaluator
        supports are accepted: line, stacked_bar, and number, in both builder
        and Raw SQL (configType "sql") variants. Raw SQL templates must
        reference the evaluation window via the time-filter and interval macros
        (e.g. $__timeFilter and $__timeInterval), and the referenced
        source/connection must belong to the team.
      oneOf:
        - $ref: '#/components/schemas/AlertLineChartConfig'
        - $ref: '#/components/schemas/AlertBarChartConfig'
        - $ref: '#/components/schemas/AlertNumberChartConfig'
    AlertInterval:
      type: string
      enum:
        - 1m
        - 5m
        - 15m
        - 30m
        - 1h
        - 6h
        - 12h
        - 1d
      description: Evaluation interval.
    AlertSource:
      type: string
      enum:
        - saved_search
        - tile
        - inline
      description: >
        Alert source type. "saved_search" alerts monitor a saved search, "tile"
        alerts monitor a dashboard tile, and "inline" alerts carry their own
        chart configuration (see AlertChartConfig) without requiring a saved
        search or dashboard.
    AlertThresholdType:
      type: string
      enum:
        - above
        - below
        - above_exclusive
        - below_or_equal
        - equal
        - not_equal
        - between
        - not_between
      description: Threshold comparison direction.
    AlertChannel:
      oneOf:
        - $ref: '#/components/schemas/AlertChannelWebhook'
      discriminator:
        propertyName: type
    AlertChannels:
      type: array
      description: >
        Notification channels to trigger when the alert fires or resolves.
        Between 1 and 10 channels; duplicates are rejected.
      minItems: 1
      maxItems: 10
      items:
        $ref: '#/components/schemas/AlertChannel'
    AlertErrorType:
      type: string
      enum:
        - QUERY_ERROR
        - QUERY_TIMEOUT
        - WEBHOOK_ERROR
        - INVALID_ALERT
        - UNKNOWN
      description: Category of error recorded during alert execution.
    AlertLineChartConfig:
      allOf:
        - $ref: '#/components/schemas/LineChartConfig'
        - $ref: '#/components/schemas/AlertChartConfigOverlay'
    AlertBarChartConfig:
      allOf:
        - $ref: '#/components/schemas/BarChartConfig'
        - $ref: '#/components/schemas/AlertChartConfigOverlay'
    AlertNumberChartConfig:
      allOf:
        - $ref: '#/components/schemas/NumberChartConfig'
        - $ref: '#/components/schemas/AlertChartConfigOverlay'
    AlertChannelWebhook:
      type: object
      required:
        - type
        - webhookId
      properties:
        type:
          $ref: '#/components/schemas/AlertChannelType'
          description: Channel type. Must be "webhook" for webhook alerts.
        webhookId:
          type: string
          description: Webhook destination ID.
          example: 65f5e4a3b9e77c001a789012
    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'
    AlertChartConfigOverlay:
      type: object
      description: >
        Fields an alert's chart config carries on top of the dashboard tile
        config dialect. Unlike a tile (whose name lives on the tile, not its
        config), an inline alert's config is standalone.
      properties:
        name:
          type: string
          description: >
            Display name for the alert query. Used in notification titles and as
            an alert-name fallback when the alert itself has no name.
          example: Error Rate Query
        where:
          type: string
          maxLength: 10000
          description: >
            Chart-level filter applied on top of every select item's own "where"
            (combined via AND). Builder variants only; rejected on Raw SQL
            variants (filter inside the sqlTemplate instead).
          example: ServiceName:api
        whereLanguage:
          $ref: '#/components/schemas/QueryLanguage'
          description: Language of the chart-level "where" filter.
    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'
    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'
    AlertChannelType:
      type: string
      enum:
        - webhook
      description: Channel type.
    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
        seriesLimit:
          type: integer
          minimum: 0
          description: >
            Maximum number of series rendered (top-N by value). Omit to use the
            default render cap, set 0 for unlimited, or a positive N to keep the
            top N series.
          example: 5
        formulas:
          type: array
          maxItems: 10
          description: >
            Derived series computed from the select items via letter-ref
            arithmetic ("A" = select[0], "B" = select[1], ...). Metric, log, and
            trace sources only. Cannot be combined with asRatio.
          items:
            $ref: '#/components/schemas/Formula'
        showOperandSeries:
          type: boolean
          description: >
            Only meaningful with formulas. When false, only the formula series
            are returned; the raw operand series are hidden.
          default: true
    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
    QueryLanguage:
      type: string
      enum:
        - sql
        - lucene
      description: Query language for the where clause.
    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.
        seriesLimit:
          type: integer
          minimum: 0
          description: >-
            Maximum number of series rendered (top-N by value). Omit to use the
            default render cap, set 0 for unlimited, or a positive N to keep the
            top N series.
          example: 5
        formulas:
          type: array
          maxItems: 10
          description: >
            Derived series computed from the select items via letter-ref
            arithmetic ("A" = select[0], "B" = select[1], ...). Metric, log, and
            trace sources only. Cannot be combined with asRatio.
          items:
            $ref: '#/components/schemas/Formula'
        showOperandSeries:
          type: boolean
          description: >
            Only meaningful with formulas. When false, only the formula series
            are returned; the raw operand series are hidden.
          default: true
    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
    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: 20
          description: >
            Exactly one aggregated value to display as a single number — unless
            "formulas" is set, in which case the select items are the formula's
            operands and the (single) formula value is displayed instead.
          items:
            $ref: '#/components/schemas/SelectItem'
        formulas:
          type: array
          maxItems: 1
          description: >
            A single derived value computed from the select items via letter-ref
            arithmetic ("A" = select[0], "B" = select[1], ...). Metric, log, and
            trace sources only. Number tiles display the formula value and
            always hide the operand series.
          items:
            $ref: '#/components/schemas/Formula'
        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.
            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'
    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.
    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
    Formula:
      type: object
      required:
        - expression
      description: >
        A derived series computed from the chart's select items via a letter-ref
        arithmetic expression (metric, log, and trace sources only). "A" refers
        to select[0], "B" to select[1], and so on. The grammar supports + - * /,
        parentheses, and numeric constants; expressions are parsed and
        validated, never passed through as raw SQL. Division by zero or a
        missing operand yields NULL (rendered as a gap).
      properties:
        expression:
          type: string
          maxLength: 1024
          description: >
            Arithmetic expression over the select items by position, e.g. "A /
            (A + B) * 100" for a success-rate percentage.
          example: A / (A + B) * 100
        alias:
          type: string
          description: >
            Display label for the formula series in chart legends and column
            headers. Falls back to the raw expression text when unset.
          example: Success rate %
        numberFormat:
          $ref: '#/components/schemas/NumberFormat'
          description: |
            Per-series number formatting options for the formula series.
    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.
    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.
    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.
    QuantileLevel:
      type: number
      enum:
        - 0.5
        - 0.9
        - 0.95
        - 0.99
      description: Percentile level; only valid when aggFn is "quantile".
    MetricDataType:
      type: string
      enum:
        - sum
        - gauge
        - histogram
        - summary
        - exponential histogram
      description: Metric data type, only for metrics data sources.
    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).
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````