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

# Get context-aware columns for a datasource

> Returns available columns for a datasource based on the intent and current query context. For filters/groupBy/measurements intents, returns all eligible columns. For orderBy intent, returns columns based on current groupBy and measurements context.



## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/avido/openapi.documented.yml post /v0/reporting/datasources/{id}/columns
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/datasources/{id}/columns:
    post:
      tags:
        - Reports
      summary: Get context-aware columns for a datasource
      description: >-
        Returns available columns for a datasource based on the intent and
        current query context. For filters/groupBy/measurements intents, returns
        all eligible columns. For orderBy intent, returns columns based on
        current groupBy and measurements context.
      operationId: getContextAwareColumns
      parameters:
        - in: path
          name: id
          schema:
            $ref: '#/components/schemas/ReportingQueryDatasource'
            description: Datasource name
            example: task
          required: true
          description: Datasource name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportingColumnsRequest'
            examples:
              filtersIntent:
                summary: Get filterable columns
                value:
                  intent: filters
              groupByIntent:
                summary: Get groupable columns
                value:
                  intent: groupBy
              measurementsIntent:
                summary: Get measurable columns
                value:
                  intent: measurements
              orderByWithGroupBy:
                summary: Get sortable columns for grouped query
                value:
                  intent: orderBy
                  groupBy:
                    - column: status
                      type: string
                    - column: createdAt
                      type: date
                      dateTrunc: month
                  measurements:
                    - type: count
                    - type: avg
                      column: score
                      alias: average_score
              orderByNonGrouped:
                summary: Get sortable columns for non-grouped query
                value:
                  intent: orderBy
      responses:
        '201':
          description: Successfully retrieved context-aware columns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportingContextAwareColumnsResponse'
              examples:
                filtersResponse:
                  summary: Filterable columns for eval datasource
                  value:
                    data:
                      datasource: eval
                      intent: filters
                      columns:
                        - id: id
                          name: Evaluation ID
                          type: string
                        - id: createdAt
                          name: Created Date
                          type: date
                        - id: status
                          name: Status
                          type: string
                        - id: score
                          name: Score
                          type: number
                        - id: passed
                          name: Passed
                          type: boolean
                measurementsResponse:
                  summary: Measurable columns for eval datasource
                  value:
                    data:
                      datasource: eval
                      intent: measurements
                      columns:
                        - id: score
                          name: Score
                          type: number
                        - id: passed
                          name: Passed
                          type: boolean
                orderByGroupedResponse:
                  summary: Sortable columns for grouped query
                  value:
                    data:
                      datasource: eval
                      intent: orderBy
                      columns:
                        - id: createdAt
                          name: Created Date
                          type: date
                        - id: status
                          name: Status
                          type: string
                        - id: count
                          name: Count
                          type: number
                        - id: average_score
                          name: Average Score
                          type: number
        '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:
    ReportingQueryDatasource:
      type: string
      enum:
        - task
        - test
        - eval
        - topic
        - tag
        - human_annotation
    ReportingColumnsRequest:
      type: object
      properties:
        intent:
          $ref: '#/components/schemas/ReportingColumnsIntentSchema'
          description: Intent for which columns are needed
          example: filters
        filters:
          description: Current filters applied (used for context when intent is orderBy)
          type: array
          items:
            $ref: '#/components/schemas/ReportingQueryFilter'
        groupBy:
          description: >-
            Current groupBy clauses (required when intent is orderBy to
            determine available sort columns)
          type: array
          items:
            $ref: '#/components/schemas/ReportingQueryGroupBy'
        measurements:
          description: >-
            Current measurements (required when intent is orderBy to include
            measurement aliases as sortable columns)
          type: array
          items:
            $ref: '#/components/schemas/Measurement'
      required:
        - intent
      additionalProperties: false
      title: ReportingColumnsRequest
      description: Request for context-aware column retrieval based on query intent
    ReportingContextAwareColumnsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            datasource:
              $ref: '#/components/schemas/ReportingQueryDatasource'
            intent:
              $ref: '#/components/schemas/ReportingColumnsIntentSchema'
            columns:
              type: array
              items:
                $ref: '#/components/schemas/ReportingColumnMetadataOutput'
              description: Available columns based on the intent and current query context
          required:
            - datasource
            - intent
            - columns
          additionalProperties: false
      required:
        - data
      additionalProperties: false
      title: ReportingContextAwareColumnsResponse
      description: Response containing context-aware columns for the specified intent
    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.
    ReportingColumnsIntentSchema:
      type: string
      enum:
        - filters
        - groupBy
        - measurements
        - orderBy
      description: >-
        Intent for which columns are being requested: filters (all filterable
        columns), groupBy (groupable columns), measurements (columns available
        for aggregation), orderBy (columns that can be used for sorting based on
        current query context)
    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
    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.
    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'
    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

````