> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avidoai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query reporting data

> Queries reporting data from specified datasources with optional filters and groupBy clauses. Supports aggregation and date truncation for time-based grouping.



## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/avido/openapi.documented.yml post /v0/reporting/query
openapi: 3.1.1
info:
  title: Avido API
  description: >-
    Avido's API for LLM usage events, tool calls, trace management, webhook
    validation, and more. See each endpoint's request/response schema for
    details.
  version: 0.1.0
  contact:
    name: Avido Support
    email: support@avidoai.com
    url: https://avidoai.com/support
servers:
  - url: https://api.avidoai.com
    description: Production API
security:
  - ApiKey: []
    ApplicationId: []
paths:
  /v0/reporting/query:
    post:
      tags:
        - Reports
      summary: Query reporting data
      description: >-
        Queries reporting data from specified datasources with optional filters
        and groupBy clauses. Supports aggregation and date truncation for
        time-based grouping.
      operationId: queryReportingData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportingQueryRequest'
            examples:
              taskDatasource:
                summary: Query task datasource
                value:
                  datasource: task
              taskWithFilters:
                summary: Query tasks with filters
                value:
                  datasource: task
                  filters:
                    - column: type
                      operator: eq
                      value:
                        - STATIC
                    - column: topicId
                      operator: eq
                      value:
                        - 123e4567-e89b-12d3-a456-426614174000
                        - 456e7890-e89b-12d3-a456-426614174001
              testWithStatusFilter:
                summary: Query tests excluding failed status
                value:
                  datasource: test
                  filters:
                    - column: status
                      operator: neq
                      value:
                        - FAILED
              evalDatasource:
                summary: Query eval datasource
                value:
                  datasource: eval
              groupByString:
                summary: Group tasks by type
                value:
                  datasource: task
                  groupBy:
                    - column: type
                      type: string
              groupByDateMonth:
                summary: Group tests by month
                value:
                  datasource: test
                  groupBy:
                    - column: createdAt
                      type: date
                      dateTrunc: month
              groupByMultiple:
                summary: Group by status and day
                value:
                  datasource: test
                  groupBy:
                    - column: status
                      type: string
                    - column: createdAt
                      type: date
                      dateTrunc: day
              filtersAndGroupBy:
                summary: Filter and group tasks
                value:
                  datasource: task
                  filters:
                    - column: type
                      operator: eq
                      value:
                        - STATIC
                        - NORMAL
                  groupBy:
                    - column: type
                      type: string
              measurementsWithCount:
                summary: Group with count measurement
                value:
                  datasource: eval
                  groupBy:
                    - column: status
                      type: string
                  measurements:
                    - type: count
              measurementsWithAverage:
                summary: Group with average score
                value:
                  datasource: eval
                  groupBy:
                    - column: status
                      type: string
                  measurements:
                    - type: count
                    - type: avg
                      column: score
                      alias: average_score
              measurementsMultiple:
                summary: Group with multiple measurements
                value:
                  datasource: eval
                  groupBy:
                    - column: passed
                      type: boolean
                  measurements:
                    - type: count
                    - type: avg
                      column: score
                    - type: min
                      column: score
                    - type: max
                      column: score
              confidenceGroupBy:
                summary: Group tasks by confidence level
                value:
                  datasource: task
                  groupBy:
                    - column: confidenceLevel
                      type: string
                  measurements:
                    - type: count
                    - type: avg
                      column: confidenceHalfWidth
                      alias: avgConfidenceHalfWidth
              stabilityMeasurements:
                summary: Measure task stability metrics
                value:
                  datasource: task
                  groupBy:
                    - column: stabilityLevel
                      type: string
                  measurements:
                    - type: count
                    - type: avg
                      column: stability
                      alias: avgStability
                    - type: avg
                      column: isHighStability
                      alias: pctHighStability
              customOrderBy:
                summary: Custom ordering by measurement
                value:
                  datasource: eval
                  groupBy:
                    - column: status
                      type: string
                  measurements:
                    - type: count
                    - type: avg
                      column: score
                  orderBy:
                    - column: avg_score
                      direction: desc
              multipleOrderBy:
                summary: Order by multiple columns
                value:
                  datasource: test
                  groupBy:
                    - column: status
                      type: string
                    - column: createdAt
                      type: date
                      dateTrunc: day
                  orderBy:
                    - column: createdAt
                      direction: desc
                    - column: status
                      direction: asc
      responses:
        '200':
          description: Successfully queried reporting data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportingQueryResponse'
              examples:
                nonGroupedQuery:
                  summary: Non-grouped query result (raw data)
                  value:
                    data:
                      datasource: task
                      columns:
                        - id: id
                          name: Task ID
                          type: string
                        - id: orgId
                          name: Organization ID
                          type: string
                        - id: title
                          name: Title
                          type: string
                        - id: type
                          name: Task Type
                          type: string
                        - id: topicId
                          name: Topic
                          type: string
                        - id: createdAt
                          name: Created Date
                          type: date
                      results:
                        - id: 123e4567-e89b-12d3-a456-426614174000
                          orgId: org_123456
                          title: Example Task
                          type: STATIC
                          topicId:
                            id: topic-uuid-123
                            name: Authentication
                          createdAt: '2024-01-05T12:34:56.789Z'
                      visualization:
                        compatibleCharts:
                          - table
                        recommendedChart: table
                        fieldMapping:
                          measures: []
                    pagination:
                      skip: 0
                      limit: 25
                      total: 1
                      totalPages: 1
                groupedByDate:
                  summary: Grouped query with date dimension
                  value:
                    data:
                      datasource: eval
                      columns:
                        - id: createdAt
                          name: Created Date
                          type: date
                        - id: count
                          name: Count
                          type: number
                        - id: avg_score
                          name: Average Score
                          type: number
                      results:
                        - createdAt: '2024-01-01T00:00:00Z'
                          count: 42
                          avg_score: 0.85
                        - createdAt: '2024-02-01T00:00:00Z'
                          count: 38
                          avg_score: 0.89
                      visualization:
                        compatibleCharts:
                          - line
                          - table
                        recommendedChart: line
                        fieldMapping:
                          dimension:
                            field: createdAt
                            type: date
                            dateTrunc: month
                            from: '2024-01-01T00:00:00Z'
                            to: '2024-02-28T23:59:59Z'
                          measures:
                            - field: count
                              label: Count
                              aggregation: count
                            - field: avg_score
                              label: Average Score
                              aggregation: avg
                    pagination:
                      skip: 0
                      limit: 25
                      total: 2
                      totalPages: 1
                groupedByCategory:
                  summary: Grouped query with category dimension
                  value:
                    data:
                      datasource: task
                      columns:
                        - id: type
                          name: Task Type
                          type: string
                        - id: count
                          name: Count
                          type: number
                      results:
                        - type: STATIC
                          count: 25
                        - type: NORMAL
                          count: 17
                      visualization:
                        compatibleCharts:
                          - table
                        recommendedChart: table
                        fieldMapping:
                          dimension:
                            field: type
                            type: string
                          measures:
                            - field: count
                              label: Count
                              aggregation: count
                    pagination:
                      skip: 0
                      limit: 25
                      total: 2
                      totalPages: 1
        '400':
          description: bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ReportingQueryRequest:
      type: object
      properties:
        skip:
          description: Number of items to skip before starting to collect the result set.
          example: 0
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        limit:
          description: Number of items to include in the result set.
          example: 25
          type: integer
          minimum: 1
          maximum: 100
        datasource:
          $ref: '#/components/schemas/ReportingQueryDatasource'
          description: Datasource to query
          example: task
        timezone:
          type: string
          description: >-
            IANA timezone identifier for date filter resolution (e.g.,
            'America/New_York', 'Europe/London', 'UTC')
          example: America/New_York
        filters:
          description: >-
            Optional filters to apply to the query. Each filter must specify a
            type (string/number/boolean/date) that matches the column type.
          example:
            - type: string
              column: type
              operator: eq
              value:
                - STATIC
          type: array
          items:
            $ref: '#/components/schemas/ReportingQueryFilter'
        groupBy:
          description: >-
            Optional group by clauses for aggregating results. For date columns,
            dateTrunc is required.
          example:
            - column: type
              type: string
            - column: createdAt
              type: date
              dateTrunc: month
          type: array
          items:
            $ref: '#/components/schemas/ReportingQueryGroupBy'
        measurements:
          description: >-
            Optional measurements/aggregations to compute when using groupBy.
            Defaults to count if not specified. Use avg/sum/min/max for numeric
            or boolean columns.
          example:
            - type: count
            - type: avg
              column: score
          type: array
          items:
            $ref: '#/components/schemas/Measurement'
        orderBy:
          description: >-
            Optional ordering specification. If not specified, defaults to
            ordering by all groupBy columns (with createdAt priority) then
            measurements. For non-groupBy queries, defaults to createdAt DESC,
            id DESC.
          example:
            - column: createdAt
              direction: desc
            - column: count
              direction: asc
          type: array
          items:
            type: object
            properties:
              column:
                type: string
                description: >-
                  Column name to order by (must be a groupBy column or
                  measurement alias)
                example: createdAt
              direction:
                type: string
                enum:
                  - asc
                  - desc
                description: Sort order direction (ascending or descending).
                example: desc
            required:
              - column
              - direction
            title: ReportingQueryOrderBy
            description: >-
              Order by specification for sorting results. Column must be in the
              SELECT clause (groupBy column or measurement).
        includeArchived:
          description: >-
            When true, includes archived entities (tasks, topics, tags) in the
            query results. Defaults to false, which filters out archived data.
          example: false
          type: boolean
      required:
        - datasource
        - timezone
      additionalProperties: false
      title: ReportingQueryRequest
      description: Request body for querying reporting data
    ReportingQueryResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            datasource:
              $ref: '#/components/schemas/ReportingQueryDatasource'
            columns:
              type: array
              items:
                $ref: '#/components/schemas/ReportingColumnMetadataOutput'
              description: >-
                Column metadata describing the structure of the results. For
                non-groupBy queries, includes all datasource columns. For
                groupBy queries, includes groupBy columns and measurement
                columns.
            results:
              type: array
              items:
                $ref: '#/components/schemas/ReportingQueryResultOutput'
            visualization:
              $ref: '#/components/schemas/VisualizationMetadataOutput'
              description: >-
                Visualization metadata describing compatible chart types and
                field mappings for rendering
          required:
            - datasource
            - columns
            - results
            - visualization
          additionalProperties: false
        pagination:
          type: object
          properties:
            skip:
              type: integer
              minimum: 0
              maximum: 9007199254740991
              description: Number of items skipped.
              example: 0
            limit:
              type: integer
              minimum: 1
              maximum: 9007199254740991
              description: Number of items per page.
              example: 25
            total:
              type: integer
              minimum: 0
              maximum: 9007199254740991
              description: Total number of items available.
              example: 100
            totalPages:
              type: integer
              minimum: 0
              maximum: 9007199254740991
              description: Total number of pages available.
              example: 4
            totalCount:
              description: >-
                Total number of items without filters applied. Used to
                distinguish between truly empty results and empty filtered
                results.
              example: 100
              type: integer
              minimum: 0
              maximum: 9007199254740991
          required:
            - skip
            - limit
            - total
            - totalPages
          additionalProperties: false
          title: PaginationResponse
          description: Pagination metadata returned in a paginated response.
      required:
        - data
        - pagination
      additionalProperties: false
      title: ReportingQueryResponse
      description: >-
        Successful response from reporting query with column metadata and
        visualization hints
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message explaining the error.
          example: Resource not found
      required:
        - message
      additionalProperties: false
      title: ErrorResponse
      description: Standard error format for failed API operations.
    ValidationErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message indicating what went wrong.
          example: Invalid request data
        issues:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              path:
                type: array
                items:
                  type: string
            required:
              - code
              - message
              - path
            additionalProperties: false
          description: Array of detailed validation error objects.
          example:
            - code: invalid_string
              message: Invalid UUID
              path:
                - id
      required:
        - message
        - issues
      additionalProperties: false
      title: ValidationErrorResponse
      description: Details about validation errors in incoming requests.
    ReportingQueryDatasource:
      type: string
      enum:
        - task
        - test
        - eval
        - topic
        - tag
        - human_annotation
    ReportingQueryFilter:
      oneOf:
        - $ref: '#/components/schemas/ReportingQueryStringFilter'
        - $ref: '#/components/schemas/ReportingQueryNumberFilter'
        - $ref: '#/components/schemas/ReportingQueryBooleanFilter'
        - $ref: '#/components/schemas/ReportingQueryDateFilter'
      title: ReportingQueryFilter
      description: >-
        Filter for reporting queries. Type must match the column type in the
        datasource.
      type: object
      discriminator:
        propertyName: type
        mapping:
          string:
            $ref: '#/components/schemas/ReportingQueryStringFilter'
          number:
            $ref: '#/components/schemas/ReportingQueryNumberFilter'
          boolean:
            $ref: '#/components/schemas/ReportingQueryBooleanFilter'
          date:
            $ref: '#/components/schemas/ReportingQueryDateFilter'
    ReportingQueryGroupBy:
      oneOf:
        - type: object
          properties:
            column:
              type: string
              description: Column name to group by (must be whitelisted for datasource)
              example: type
            type:
              type: string
              enum:
                - string
                - number
                - boolean
              description: Column type for non-date columns
              example: string
          required:
            - column
            - type
          title: ReportingQueryGroupByBase
          description: Group by specification for non-date columns
        - type: object
          properties:
            column:
              type: string
              description: >-
                Date column name to group by (must be whitelisted for
                datasource)
              example: createdAt
            type:
              type: string
              const: date
              description: Column type for date columns
              example: date
            dateTrunc:
              $ref: '#/components/schemas/ReportingQueryDateTrunc'
              description: Required date truncation granularity for date columns
              example: month
          required:
            - column
            - type
            - dateTrunc
          title: ReportingQueryGroupByDate
          description: Group by specification for date columns with required truncation
      title: ReportingQueryGroupBy
      description: >-
        Group by specification with discriminated union on type field. Date
        columns require dateTrunc parameter.
      type: object
    Measurement:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/MeasurementType'
          description: Type of measurement to perform
          example: avg
        column:
          description: Column to measure (required for avg/sum/min/max, not used for count)
          example: score
          type: string
        alias:
          description: >-
            Optional alias for the measurement in results (defaults to
            type_column or 'count')
          example: average_score
          type: string
      required:
        - type
      title: Measurement
      description: >-
        Measurement/aggregation specification for GROUP BY queries. Count
        measures all records, while avg/sum/min/max measure specific
        numeric/boolean columns.
    ReportingColumnMetadataOutput:
      type: object
      properties:
        id:
          type: string
          description: Column identifier
          example: id
        name:
          type: string
          description: Column name
          example: Evaluation ID
        type:
          type: string
          enum:
            - string
            - number
            - date
            - boolean
          description: Column data type
          example: string
      required:
        - id
        - name
        - type
      additionalProperties: false
      title: ReportingColumnMetadata
      description: Metadata about a column in a datasource
    ReportingQueryResultOutput:
      type: object
      propertyNames:
        type: string
      additionalProperties:
        anyOf:
          - $ref: '#/components/schemas/ReportingColumnValueOutput'
          - type: 'null'
      description: >-
        Record from the queried datasource. All columns return objects with {id,
        name} structure. For primitive values, both id and name contain the same
        value. For relations (e.g., topicId, taskId, definitionId), id contains
        the UUID and name contains the human-readable label.
      example:
        id:
          id: 123e4567-e89b-12d3-a456-426614174000
          name: 123e4567-e89b-12d3-a456-426614174000
        orgId:
          id: org_123456
          name: org_123456
        title:
          id: Example Task
          name: Example Task
        createdAt:
          id: '2024-01-05T12:34:56.789Z'
          name: '2024-01-05T12:34:56.789Z'
        topicId:
          id: topic-uuid-123
          name: Authentication
    VisualizationMetadataOutput:
      type: object
      properties:
        compatibleCharts:
          type: array
          items:
            $ref: '#/components/schemas/ChartType'
          description: >-
            Chart types that are compatible with the query structure and can
            display the data
          example:
            - line
            - table
        recommendedChart:
          $ref: '#/components/schemas/ChartType'
          description: >-
            Recommended default chart type based on query structure (e.g., line
            for time-series, table for categories)
          example: line
        fieldMapping:
          $ref: '#/components/schemas/VisualizationFieldMappingOutput'
          description: >-
            Field mapping describing which fields to use for dimensions (x-axis)
            and measures (y-axis)
      required:
        - compatibleCharts
        - recommendedChart
        - fieldMapping
      additionalProperties: false
      title: VisualizationMetadata
      description: >-
        Metadata describing how to visualize the query results, including
        compatible chart types and field mappings
    ReportingQueryStringFilter:
      type: object
      properties:
        type:
          type: string
          const: string
          description: Filter type for string columns
        column:
          type: string
          description: Column name to filter on (must be a string column in the datasource)
          example: type
        operator:
          type: string
          enum:
            - eq
            - neq
          description: Filter operator for string values
          example: eq
        value:
          minItems: 1
          type: array
          items:
            type: string
          description: Array of string values to filter by
          example:
            - STATIC
            - NORMAL
      required:
        - type
        - column
        - operator
        - value
      title: ReportingQueryStringFilter
      description: Filter for string columns using eq/neq operators
    ReportingQueryNumberFilter:
      type: object
      properties:
        type:
          type: string
          const: number
          description: Filter type for numeric columns
        column:
          type: string
          description: >-
            Column name to filter on (must be a numeric column in the
            datasource)
          example: score
        operator:
          type: string
          enum:
            - eq
            - neq
            - lt
            - gt
            - lte
            - gte
          description: Filter operator for numeric values
          example: gte
        value:
          minItems: 1
          type: array
          items:
            type: number
          description: >-
            Array of numeric values to filter by (for comparison operators, only
            first value is used)
          example:
            - 0.8
      required:
        - type
        - column
        - operator
        - value
      title: ReportingQueryNumberFilter
      description: Filter for numeric columns using eq/neq/lt/gt/lte/gte operators
    ReportingQueryBooleanFilter:
      type: object
      properties:
        type:
          type: string
          const: boolean
          description: Filter type for boolean columns
        column:
          type: string
          description: >-
            Column name to filter on (must be a boolean column in the
            datasource)
          example: passed
        operator:
          type: string
          enum:
            - eq
          description: Filter operator for boolean values
          example: eq
        value:
          type: boolean
          description: Boolean value to filter by
          example: true
      required:
        - type
        - column
        - operator
        - value
      title: ReportingQueryBooleanFilter
      description: Filter for boolean columns using eq operator with single value
    ReportingQueryDateFilter:
      type: object
      properties:
        type:
          type: string
          const: date
          description: Filter type for date columns
        column:
          type: string
          description: Column name to filter on (must be a date column in the datasource)
          example: createdAt
        dateFilter:
          $ref: '#/components/schemas/DateFilter'
          description: >-
            Date filter supporting absolute ranges, presets, and relative
            windows
      required:
        - type
        - column
        - dateFilter
      title: ReportingQueryDateFilter
      description: Filter for date columns using date filter (range/preset/relative)
    ReportingQueryDateTrunc:
      type: string
      enum:
        - year
        - month
        - week
        - day
        - hour
      description: >-
        Date truncation granularity for grouping date columns using PostgreSQL
        date_trunc
    MeasurementType:
      type: string
      enum:
        - count
        - avg
        - sum
        - min
        - max
      description: >-
        Type of measurement/aggregation to perform. count works on all columns,
        while avg/sum/min/max require numeric or boolean columns.
    ReportingColumnValueOutput:
      type: object
      properties:
        id:
          type: string
          description: Value identifier
          example: PENDING
        name:
          type: string
          description: Human-readable value name
          example: PENDING
      required:
        - id
        - name
      additionalProperties: false
      title: ReportingColumnValue
      description: >-
        A distinct value from a datasource column with id and display name. Can
        be null for optional fields.
    ChartType:
      type: string
      enum:
        - line
        - table
      description: Available chart types for visualization
    VisualizationFieldMappingOutput:
      type: object
      properties:
        dimension:
          $ref: '#/components/schemas/DimensionOutput'
          description: >-
            Dimension field (x-axis). Present for grouped queries, omitted for
            non-grouped queries.
        measures:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: Column name for y-axis value/measure
                example: count
              label:
                type: string
                description: Human-readable label for this measure
                example: Total Count
              aggregation:
                $ref: '#/components/schemas/MeasurementType'
                description: Aggregation function used for this measure
                example: count
            required:
              - field
              - label
            additionalProperties: false
          description: >-
            Measure fields (y-axis values). Contains measurement columns from
            the query.
        series:
          description: >-
            Series definitions for multi-line charts. Present when there are
            secondary groupBy fields beyond the primary dimension (e.g., topicId
            when grouping by createdAt and topicId). Each series represents a
            separate line in the chart.
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: >-
                  Secondary groupBy field that defines separate lines/series in
                  line charts
                example: topicId
              values:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      anyOf:
                        - type: string
                        - type: number
                        - type: boolean
                        - type: 'null'
                      description: Unique identifier value for this series
                      example: 550e8400-e29b-41d4-a716-446655440000
                    name:
                      anyOf:
                        - type: string
                        - type: number
                        - type: boolean
                        - type: 'null'
                      description: >-
                        Display name for this series (resolved from related
                        table if applicable)
                      example: Product Features
                  required:
                    - id
                    - name
                  additionalProperties: false
                description: >-
                  List of unique values for this series field, with id and
                  resolved display name
            required:
              - field
              - values
            additionalProperties: false
      required:
        - measures
      additionalProperties: false
      title: VisualizationFieldMapping
      description: Maps query result fields to visualization dimensions and measures
    DateFilter:
      oneOf:
        - $ref: '#/components/schemas/DateFilterRange'
        - $ref: '#/components/schemas/DateFilterPreset'
        - $ref: '#/components/schemas/DateFilterRelative'
      title: DateFilter
      description: >-
        Date filter supporting absolute ranges, presets (thisQuarter,
        last30Days), and relative windows (last N days/weeks/months)
      type: object
      discriminator:
        propertyName: type
        mapping:
          range:
            $ref: '#/components/schemas/DateFilterRange'
          preset:
            $ref: '#/components/schemas/DateFilterPreset'
          relative:
            $ref: '#/components/schemas/DateFilterRelative'
    DimensionOutput:
      oneOf:
        - type: object
          properties:
            field:
              type: string
              description: Column name for x-axis/dimension
              example: type
            type:
              type: string
              enum:
                - string
                - number
                - boolean
              description: Data type of the dimension field
              example: string
          required:
            - field
            - type
          additionalProperties: false
          title: DimensionBase
          description: >-
            Dimension specification for non-date columns (string, number,
            boolean)
        - type: object
          properties:
            field:
              type: string
              description: Date column name for x-axis/dimension
              example: createdAt
            type:
              type: string
              const: date
              description: Data type indicating a date dimension
              example: date
            dateTrunc:
              $ref: '#/components/schemas/ReportingQueryDateTrunc'
              description: >-
                Date truncation level for grouping (year, month, week, day,
                hour)
              example: month
            from:
              description: >-
                Start date for date range (ISO 8601 format). Derived from date
                filter or query results.
              example: '2024-01-01T00:00:00Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            to:
              description: >-
                End date for date range (ISO 8601 format). Derived from date
                filter or query results.
              example: '2024-12-31T23:59:59Z'
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          required:
            - field
            - type
            - dateTrunc
          additionalProperties: false
          title: DimensionDate
          description: >-
            Dimension specification for date columns with truncation and date
            range
      title: Dimension
      description: >-
        Dimension field (x-axis) with discriminated union on type. Date
        dimensions include dateTrunc and optional from/to range.
      type: object
    DateFilterRange:
      type: object
      properties:
        type:
          type: string
          const: range
          description: Absolute date range with explicit boundaries
        from:
          description: Inclusive start boundary (ISO8601). Omit for open-ended range.
          example: '2025-01-01T00:00:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        to:
          description: Exclusive end boundary (ISO8601). Omit for open-ended range.
          example: '2025-02-01T00:00:00Z'
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - type
      title: DateFilterRange
      description: >-
        Absolute date range with optional from/to boundaries. from is inclusive,
        to is exclusive.
    DateFilterPreset:
      type: object
      properties:
        type:
          type: string
          const: preset
          description: Preset date range using common shortcuts
        preset:
          $ref: '#/components/schemas/DateFilterPresetValue'
      required:
        - type
        - preset
      title: DateFilterPreset
      description: >-
        Preset date range that expands to concrete dates at query time (e.g.,
        thisQuarter, last30Days)
    DateFilterRelative:
      type: object
      properties:
        type:
          type: string
          const: relative
          description: Relative date range using offsets from now
        unit:
          $ref: '#/components/schemas/DateFilterUnit'
        from:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: >-
            Starting offset (units ago from now). 0 = now. Must be < to.
            Defaults to 0.
          example: 0
        to:
          type: integer
          minimum: 1
          maximum: 9007199254740991
          description: Ending offset (units ago from now). Must be > from. Defaults to 1.
          example: 14
      required:
        - type
        - unit
        - from
        - to
      title: DateFilterRelative
      description: >-
        Relative date range using bounded offsets from now (e.g., last 14 days,
        2-6 weeks ago)
    DateFilterPresetValue:
      type: string
      enum:
        - today
        - yesterday
        - last_7_days
        - last_30_days
        - last_90_days
        - last_12_months
        - this_week
        - last_week
        - this_month
        - last_month
        - this_quarter
        - last_quarter
        - this_year
        - last_year
      description: Preset date range that expands to concrete dates at query time
      example: last_30_days
    DateFilterUnit:
      type: string
      enum:
        - day
        - week
        - month
        - quarter
        - year
      description: Time unit for relative date ranges (day, week, month, quarter, year)
      example: day
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your unique Avido API key
    ApplicationId:
      type: apiKey
      in: header
      name: x-application-id
      description: Your unique Avido Application ID

````