> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-update-reference-docs-60.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GenAI Spans Query

> Query agent spans, either as raw rows or grouped aggregates.



## OpenAPI

````yaml weave/reference/service-api/openapi.json POST /agents/spans/query
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /agents/spans/query:
    post:
      tags:
        - Agents
      summary: Genai Spans Query
      description: Query agent spans, either as raw rows or grouped aggregates.
      operationId: genai_spans_query_agents_spans_query_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentSpansQueryReq'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSpansQueryRes'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AgentSpansQueryReq:
      properties:
        project_id:
          type: string
          title: Project Id
        query:
          anyOf:
            - $ref: '#/components/schemas/Query'
            - type: 'null'
        group_by:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentGroupByRef'
              type: array
            - type: 'null'
          title: Group By
        measures:
          items:
            $ref: '#/components/schemas/AgentSpanMeasureSpec'
          type: array
          title: Measures
        group_filters:
          items:
            $ref: '#/components/schemas/AgentSpanGroupFilter'
          type: array
          title: Group Filters
        group_distributions:
          items:
            $ref: '#/components/schemas/AgentSpanGroupDistributionSpec'
          type: array
          maxItems: 20
          title: Group Distributions
        custom_attr_columns:
          items:
            $ref: '#/components/schemas/AgentSpanValueRef'
          type: array
          title: Custom Attr Columns
        include_details:
          type: boolean
          title: Include Details
          default: false
        include_costs:
          type: boolean
          title: Include Costs
          default: false
        sort_by:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentSortBy'
              type: array
            - type: 'null'
          title: Sort By
        limit:
          type: integer
          maximum: 10000
          minimum: 0
          title: Limit
          default: 100
        offset:
          type: integer
          minimum: 0
          title: Offset
          default: 0
        started_after:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started After
        started_before:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started Before
        signal_filters:
          anyOf:
            - $ref: '#/components/schemas/AgentSignalFilter'
            - type: 'null'
      type: object
      required:
        - project_id
      title: AgentSpansQueryReq
      description: |-
        Request to query agent spans for a project.

        When `group_by` is empty (or omitted), returns raw span rows in the
        response's `spans` field. When `group_by` is non-empty, returns
        aggregate group rows in the response's `groups` field.
    AgentSpansQueryRes:
      properties:
        spans:
          items:
            $ref: '#/components/schemas/AgentSpanSchema'
          type: array
          title: Spans
        groups:
          items:
            $ref: '#/components/schemas/AgentSpanGroupRow'
          type: array
          title: Groups
        total_count:
          type: integer
          title: Total Count
          default: 0
      type: object
      required:
        - spans
        - groups
        - total_count
      title: AgentSpansQueryRes
      description: |-
        Response from a spans query.

        Exactly one of `spans` or `groups` will be populated, based on
        whether the request specified `group_by`.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Query:
      properties:
        $expr:
          anyOf:
            - $ref: '#/components/schemas/AndOperation'
            - $ref: '#/components/schemas/OrOperation'
            - $ref: '#/components/schemas/NotOperation'
            - $ref: '#/components/schemas/EqOperation'
            - $ref: '#/components/schemas/GtOperation'
            - $ref: '#/components/schemas/LtOperation'
            - $ref: '#/components/schemas/GteOperation'
            - $ref: '#/components/schemas/LteOperation'
            - $ref: '#/components/schemas/InOperation'
            - $ref: '#/components/schemas/ContainsOperation'
          title: $Expr
      additionalProperties: false
      type: object
      required:
        - $expr
      title: Query
    AgentGroupByRef:
      properties:
        source:
          type: string
          enum:
            - field
            - column
            - custom_attrs_string
            - custom_attrs_int
            - custom_attrs_float
            - custom_attrs_bool
          title: Source
          default: field
        key:
          type: string
          title: Key
        alias:
          anyOf:
            - type: string
            - type: 'null'
          title: Alias
      type: object
      required:
        - key
      title: AgentGroupByRef
      description: >-
        Reference to a field or map-key that spans should be grouped by.


        `source="field"` targets a semantic span field (`agent.name`) or direct

        span column (`agent_name`), allowlisted server-side. `source="column"`
        is

        accepted for existing callers.

        The other sources target keys inside the typed custom attribute Map
        columns,

        which accept arbitrary user-defined keys.
    AgentSpanMeasureSpec:
      properties:
        alias:
          type: string
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
          title: Alias
        aggregation:
          type: string
          enum:
            - sum
            - avg
            - min
            - max
            - count
            - count_distinct
            - count_true
            - count_false
          title: Aggregation
        value:
          anyOf:
            - $ref: '#/components/schemas/AgentSpanValueRef'
            - type: 'null'
        value_type:
          anyOf:
            - type: string
              enum:
                - datetime
                - number
                - boolean
                - string
            - type: 'null'
          title: Value Type
        filter:
          anyOf:
            - $ref: '#/components/schemas/Query'
            - type: 'null'
      type: object
      required:
        - alias
        - aggregation
      title: AgentSpanMeasureSpec
      description: One aggregate measure computed over spans in a group or bucket.
    AgentSpanGroupFilter:
      properties:
        group_by:
          items:
            $ref: '#/components/schemas/AgentGroupByRef'
          type: array
          title: Group By
        measure:
          $ref: '#/components/schemas/AgentSpanMeasureSpec'
        min:
          anyOf:
            - type: number
            - type: string
              format: date-time
            - type: 'null'
          title: Min
        max:
          anyOf:
            - type: number
            - type: string
              format: date-time
            - type: 'null'
          title: Max
      type: object
      required:
        - measure
      title: AgentSpanGroupFilter
      description: Range filter over one grouped span measure.
    AgentSpanGroupDistributionSpec:
      properties:
        alias:
          type: string
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
          title: Alias
        value:
          $ref: '#/components/schemas/AgentSpanValueRef'
        bins:
          type: integer
          maximum: 50
          minimum: 1
          title: Bins
          default: 12
        top_n:
          type: integer
          maximum: 20
          minimum: 1
          title: Top N
          default: 5
      type: object
      required:
        - alias
        - value
      title: AgentSpanGroupDistributionSpec
      description: One custom attribute distribution to compute per returned span group.
    AgentSpanValueRef:
      properties:
        source:
          type: string
          enum:
            - field
            - derived
            - custom_attrs_string
            - custom_attrs_int
            - custom_attrs_float
            - custom_attrs_bool
          title: Source
          default: field
        key:
          type: string
          title: Key
      type: object
      required:
        - key
      title: AgentSpanValueRef
      description: Reference to a span field or typed custom attribute map value.
    AgentSortBy:
      properties:
        field:
          type: string
          title: Field
        direction:
          type: string
          enum:
            - asc
            - desc
          title: Direction
          default: desc
      type: object
      required:
        - field
      title: AgentSortBy
      description: Sort specification for agent query endpoints.
    AgentSignalFilter:
      properties:
        tags:
          items:
            type: string
          type: array
          title: Tags
        ratings:
          items:
            $ref: '#/components/schemas/RatingCondition'
          type: array
          title: Ratings
      type: object
      title: AgentSignalFilter
    AgentSpanSchema:
      properties:
        project_id:
          type: string
          title: Project Id
        trace_id:
          type: string
          title: Trace Id
        span_id:
          type: string
          title: Span Id
        parent_span_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Span Id
        span_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Span Name
        span_kind:
          anyOf:
            - type: string
              enum:
                - UNSPECIFIED
                - INTERNAL
                - SERVER
                - CLIENT
                - PRODUCER
                - CONSUMER
            - type: 'null'
          title: Span Kind
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
        status_code:
          anyOf:
            - type: string
              enum:
                - UNSET
                - OK
                - ERROR
            - type: 'null'
          title: Status Code
        status_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Message
        operation_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation Name
        provider_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider Name
        agent_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Name
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
        agent_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Description
        agent_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Version
        eval_run_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Eval Run Id
        eval_predict_and_score_call_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Eval Predict And Score Call Id
        eval_kind:
          anyOf:
            - type: string
            - type: 'null'
          title: Eval Kind
        eval_row_digest:
          anyOf:
            - type: string
            - type: 'null'
          title: Eval Row Digest
        eval_example_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Eval Example Id
        eval_trial_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Eval Trial Index
        eval_evaluation_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Eval Evaluation Name
        parent_call_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Call Id
        parent_call_trace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Call Trace Id
        request_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Model
        response_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Response Model
        response_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Response Id
        input_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Input Tokens
        output_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Output Tokens
        reasoning_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Reasoning Tokens
        cache_creation_input_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Cache Creation Input Tokens
        cache_read_input_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Cache Read Input Tokens
        input_cost_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Input Cost Usd
        output_cost_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Output Cost Usd
        cache_read_cost_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Cache Read Cost Usd
        cache_creation_cost_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Cache Creation Cost Usd
        total_cost_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Total Cost Usd
        reasoning_content:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning Content
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Id
        conversation_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Name
        tool_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Name
        tool_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Type
        tool_call_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Call Id
        tool_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Description
        tool_definitions:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Definitions
        finish_reasons:
          items:
            type: string
          type: array
          title: Finish Reasons
        error_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Type
        request_temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Request Temperature
        request_max_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Request Max Tokens
        request_top_p:
          anyOf:
            - type: number
            - type: 'null'
          title: Request Top P
        request_frequency_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Request Frequency Penalty
        request_presence_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Request Presence Penalty
        request_seed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Request Seed
        request_stop_sequences:
          items:
            type: string
          type: array
          title: Request Stop Sequences
        request_choice_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Request Choice Count
        output_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Type
        input_messages:
          items:
            $ref: '#/components/schemas/NormalizedMessage'
          type: array
          title: Input Messages
        output_messages:
          items:
            $ref: '#/components/schemas/NormalizedMessage'
          type: array
          title: Output Messages
        system_instructions:
          items:
            type: string
          type: array
          title: System Instructions
        tool_call_arguments:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Call Arguments
        tool_call_result:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Call Result
        compaction_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Compaction Summary
        compaction_items_before:
          anyOf:
            - type: integer
            - type: 'null'
          title: Compaction Items Before
        compaction_items_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Compaction Items After
        content_refs:
          items:
            type: string
          type: array
          title: Content Refs
        artifact_refs:
          items:
            type: string
          type: array
          title: Artifact Refs
        object_refs:
          items:
            type: string
          type: array
          title: Object Refs
        custom_attrs_string:
          additionalProperties:
            type: string
          type: object
          title: Custom Attrs String
        custom_attrs_int:
          additionalProperties:
            type: integer
          type: object
          title: Custom Attrs Int
        custom_attrs_float:
          additionalProperties:
            type: number
          type: object
          title: Custom Attrs Float
        custom_attrs_bool:
          additionalProperties:
            type: boolean
          type: object
          title: Custom Attrs Bool
        server_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Server Address
        server_port:
          anyOf:
            - type: integer
            - type: 'null'
          title: Server Port
        wb_user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Wb User Id
        wb_run_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Wb Run Id
        wb_run_step:
          anyOf:
            - type: integer
            - type: 'null'
          title: Wb Run Step
        wb_run_step_end:
          anyOf:
            - type: integer
            - type: 'null'
          title: Wb Run Step End
        raw_span_dump:
          anyOf:
            - type: string
            - type: 'null'
          title: Raw Span Dump
      type: object
      required:
        - project_id
        - trace_id
        - span_id
        - parent_span_id
        - span_name
        - span_kind
        - started_at
        - ended_at
        - status_code
        - status_message
        - operation_name
        - provider_name
        - agent_name
        - agent_id
        - agent_description
        - agent_version
        - eval_run_id
        - eval_predict_and_score_call_id
        - eval_kind
        - eval_row_digest
        - eval_example_id
        - eval_trial_index
        - eval_evaluation_name
        - parent_call_id
        - parent_call_trace_id
        - request_model
        - response_model
        - response_id
        - input_tokens
        - output_tokens
        - reasoning_tokens
        - cache_creation_input_tokens
        - cache_read_input_tokens
        - input_cost_usd
        - output_cost_usd
        - cache_read_cost_usd
        - cache_creation_cost_usd
        - total_cost_usd
        - reasoning_content
        - conversation_id
        - conversation_name
        - tool_name
        - tool_type
        - tool_call_id
        - tool_description
        - tool_definitions
        - finish_reasons
        - error_type
        - request_temperature
        - request_max_tokens
        - request_top_p
        - request_frequency_penalty
        - request_presence_penalty
        - request_seed
        - request_stop_sequences
        - request_choice_count
        - output_type
        - input_messages
        - output_messages
        - system_instructions
        - tool_call_arguments
        - tool_call_result
        - compaction_summary
        - compaction_items_before
        - compaction_items_after
        - content_refs
        - artifact_refs
        - object_refs
        - custom_attrs_string
        - custom_attrs_int
        - custom_attrs_float
        - custom_attrs_bool
        - server_address
        - server_port
        - wb_user_id
        - wb_run_id
        - wb_run_step
        - wb_run_step_end
        - raw_span_dump
      title: AgentSpanSchema
      description: A normalized agent span returned by query APIs.
    AgentSpanGroupRow:
      properties:
        group_keys:
          additionalProperties:
            anyOf:
              - type: string
              - type: integer
              - type: number
              - type: boolean
              - type: 'null'
          type: object
          title: Group Keys
        span_count:
          type: integer
          title: Span Count
          default: 0
        invocation_count:
          type: integer
          title: Invocation Count
          default: 0
        conversation_count:
          type: integer
          title: Conversation Count
          default: 0
        total_input_tokens:
          type: integer
          title: Total Input Tokens
          default: 0
        total_cache_creation_input_tokens:
          type: integer
          title: Total Cache Creation Input Tokens
          default: 0
        total_cache_read_input_tokens:
          type: integer
          title: Total Cache Read Input Tokens
          default: 0
        total_output_tokens:
          type: integer
          title: Total Output Tokens
          default: 0
        total_reasoning_tokens:
          type: integer
          title: Total Reasoning Tokens
          default: 0
        total_duration_ms:
          type: integer
          title: Total Duration Ms
          default: 0
        error_count:
          type: integer
          title: Error Count
          default: 0
        total_cost_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Total Cost Usd
        total_input_cost_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Total Input Cost Usd
        total_output_cost_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Total Output Cost Usd
        agent_names:
          items:
            type: string
          type: array
          title: Agent Names
        agent_versions:
          items:
            type: string
          type: array
          title: Agent Versions
        provider_names:
          items:
            type: string
          type: array
          title: Provider Names
        request_models:
          items:
            type: string
          type: array
          title: Request Models
        conversation_names:
          items:
            type: string
          type: array
          title: Conversation Names
        first_seen:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: First Seen
        last_seen:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Seen
        first_message:
          anyOf:
            - $ref: '#/components/schemas/AgentConversationMessagePreview'
            - type: 'null'
        last_message:
          anyOf:
            - $ref: '#/components/schemas/AgentConversationMessagePreview'
            - type: 'null'
        metrics:
          additionalProperties:
            anyOf:
              - type: string
                format: date-time
              - type: string
              - type: integer
              - type: number
              - type: boolean
              - type: 'null'
          type: object
          title: Metrics
        distributions:
          additionalProperties:
            $ref: '#/components/schemas/AgentSpanGroupDistributionItem'
          type: object
          title: Distributions
      type: object
      required:
        - group_keys
        - span_count
        - invocation_count
        - conversation_count
        - total_input_tokens
        - total_cache_creation_input_tokens
        - total_cache_read_input_tokens
        - total_output_tokens
        - total_reasoning_tokens
        - total_duration_ms
        - error_count
        - total_cost_usd
        - total_input_cost_usd
        - total_output_cost_usd
        - agent_names
        - agent_versions
        - provider_names
        - request_models
        - conversation_names
        - first_seen
        - last_seen
        - first_message
        - last_message
        - metrics
        - distributions
      title: AgentSpanGroupRow
      description: |-
        A single row in a grouped spans query response.

        `group_keys` maps each group_by ref's alias to its value for this row.
        The remaining fields are a fixed aggregate bundle computed per group.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AndOperation:
      properties:
        $and:
          items:
            anyOf:
              - $ref: '#/components/schemas/LiteralOperation'
              - $ref: '#/components/schemas/GetFieldOperator'
              - $ref: '#/components/schemas/ConvertOperation'
              - $ref: '#/components/schemas/SizeOperation'
              - $ref: '#/components/schemas/AndOperation'
              - $ref: '#/components/schemas/OrOperation'
              - $ref: '#/components/schemas/NotOperation'
              - $ref: '#/components/schemas/EqOperation'
              - $ref: '#/components/schemas/GtOperation'
              - $ref: '#/components/schemas/LtOperation'
              - $ref: '#/components/schemas/GteOperation'
              - $ref: '#/components/schemas/LteOperation'
              - $ref: '#/components/schemas/InOperation'
              - $ref: '#/components/schemas/ContainsOperation'
          type: array
          title: $And
      type: object
      required:
        - $and
      title: AndOperation
      description: |-
        Logical AND. All conditions must evaluate to true.

        Example:
            ```
            {
                "$and": [
                    {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]},
                    {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]}
                ]
            }
            ```
    OrOperation:
      properties:
        $or:
          items:
            anyOf:
              - $ref: '#/components/schemas/LiteralOperation'
              - $ref: '#/components/schemas/GetFieldOperator'
              - $ref: '#/components/schemas/ConvertOperation'
              - $ref: '#/components/schemas/SizeOperation'
              - $ref: '#/components/schemas/AndOperation'
              - $ref: '#/components/schemas/OrOperation'
              - $ref: '#/components/schemas/NotOperation'
              - $ref: '#/components/schemas/EqOperation'
              - $ref: '#/components/schemas/GtOperation'
              - $ref: '#/components/schemas/LtOperation'
              - $ref: '#/components/schemas/GteOperation'
              - $ref: '#/components/schemas/LteOperation'
              - $ref: '#/components/schemas/InOperation'
              - $ref: '#/components/schemas/ContainsOperation'
          type: array
          title: $Or
      type: object
      required:
        - $or
      title: OrOperation
      description: |-
        Logical OR. At least one condition must be true.

        Example:
            ```
            {
                "$or": [
                    {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]},
                    {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]}
                ]
            }
            ```
    NotOperation:
      properties:
        $not:
          prefixItems:
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
          type: array
          maxItems: 1
          minItems: 1
          title: $Not
      type: object
      required:
        - $not
      title: NotOperation
      description: |-
        Logical NOT. Inverts the condition.

        Example:
            ```
            {
                "$not": [
                    {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]}
                ]
            }
            ```
    EqOperation:
      properties:
        $eq:
          prefixItems:
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
          type: array
          maxItems: 2
          minItems: 2
          title: $Eq
      type: object
      required:
        - $eq
      title: EqOperation
      description: |-
        Equality check between two operands.

        Example:
            ```
            {
                "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]
            }
            ```
    GtOperation:
      properties:
        $gt:
          prefixItems:
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
          type: array
          maxItems: 2
          minItems: 2
          title: $Gt
      type: object
      required:
        - $gt
      title: GtOperation
      description: |-
        Greater than comparison.

        Example:
            ```
            {
                "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}]
            }
            ```
    LtOperation:
      properties:
        $lt:
          prefixItems:
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
          type: array
          maxItems: 2
          minItems: 2
          title: $Lt
      type: object
      required:
        - $lt
      title: LtOperation
      description: |-
        Less than comparison.

        Example:
            ```
            {
                "$lt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}]
            }
            ```
    GteOperation:
      properties:
        $gte:
          prefixItems:
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
          type: array
          maxItems: 2
          minItems: 2
          title: $Gte
      type: object
      required:
        - $gte
      title: GteOperation
      description: |-
        Greater than or equal comparison.

        Example:
            ```
            {
                "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}]
            }
            ```
    LteOperation:
      properties:
        $lte:
          prefixItems:
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
          type: array
          maxItems: 2
          minItems: 2
          title: $Lte
      type: object
      required:
        - $lte
      title: LteOperation
      description: |-
        Less than or equal comparison.

        Example:
            ```
            {
                "$lte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}]
            }
            ```
    InOperation:
      properties:
        $in:
          prefixItems:
            - anyOf:
                - $ref: '#/components/schemas/LiteralOperation'
                - $ref: '#/components/schemas/GetFieldOperator'
                - $ref: '#/components/schemas/ConvertOperation'
                - $ref: '#/components/schemas/SizeOperation'
                - $ref: '#/components/schemas/AndOperation'
                - $ref: '#/components/schemas/OrOperation'
                - $ref: '#/components/schemas/NotOperation'
                - $ref: '#/components/schemas/EqOperation'
                - $ref: '#/components/schemas/GtOperation'
                - $ref: '#/components/schemas/LtOperation'
                - $ref: '#/components/schemas/GteOperation'
                - $ref: '#/components/schemas/LteOperation'
                - $ref: '#/components/schemas/InOperation'
                - $ref: '#/components/schemas/ContainsOperation'
            - items:
                anyOf:
                  - $ref: '#/components/schemas/LiteralOperation'
                  - $ref: '#/components/schemas/GetFieldOperator'
                  - $ref: '#/components/schemas/ConvertOperation'
                  - $ref: '#/components/schemas/SizeOperation'
                  - $ref: '#/components/schemas/AndOperation'
                  - $ref: '#/components/schemas/OrOperation'
                  - $ref: '#/components/schemas/NotOperation'
                  - $ref: '#/components/schemas/EqOperation'
                  - $ref: '#/components/schemas/GtOperation'
                  - $ref: '#/components/schemas/LtOperation'
                  - $ref: '#/components/schemas/GteOperation'
                  - $ref: '#/components/schemas/LteOperation'
                  - $ref: '#/components/schemas/InOperation'
                  - $ref: '#/components/schemas/ContainsOperation'
              type: array
          type: array
          maxItems: 2
          minItems: 2
          title: $In
      type: object
      required:
        - $in
      title: InOperation
      description: >-
        Membership check.


        Returns true if the left operand is in the list provided as the second
        operand.


        Example:
            ```
            {
                "$in": [
                    {"$getField": "op_name"},
                    [{"$literal": "predict"}, {"$literal": "generate"}]
                ]
            }
            ```
    ContainsOperation:
      properties:
        $contains:
          $ref: '#/components/schemas/ContainsSpec'
      type: object
      required:
        - $contains
      title: ContainsOperation
      description: |-
        Case-insensitive substring match.

        Not part of MongoDB. Weave-specific addition.

        Example:
            ```
            {
                "$contains": {
                    "input": {"$getField": "display_name"},
                    "substr": {"$literal": "llm"},
                    "case_insensitive": true
                }
            }
            ```
    RatingCondition:
      properties:
        scorer_key:
          type: string
          title: Scorer Key
        op:
          type: string
          enum:
            - gte
            - gt
            - lte
            - lt
            - eq
          title: Op
        value:
          type: number
          title: Value
      type: object
      required:
        - scorer_key
        - op
        - value
      title: RatingCondition
    NormalizedMessage:
      properties:
        role:
          type: string
          title: Role
          default: ''
        content:
          type: string
          title: Content
        finish_reason:
          type: string
          title: Finish Reason
          default: ''
      type: object
      required:
        - role
        - content
        - finish_reason
      title: NormalizedMessage
      description: >-
        A single message normalized from any provider format.


        Maps to ClickHouse ``Tuple(role String, content String, finish_reason
        String)``.


        - role: message role (user, assistant, tool, system)

        - content: plain text for simple messages, or JSON-serialized parts
          array for multimodal/structured messages
        - finish_reason: per-message finish reason (output messages only)


        Serialization JSON Schema marks defaulted fields required. In the public

        OpenAPI document this class appears only as an AgentSpanSchema message

        element. Ingest validation is unchanged.
    AgentConversationMessagePreview:
      properties:
        role:
          type: string
          enum:
            - user_message
            - assistant_message
          title: Role
        text:
          type: string
          title: Text
          default: ''
      type: object
      required:
        - role
        - text
      title: AgentConversationMessagePreview
      description: |-
        A truncated first/last message snippet for a grouped conversation row.

        `role` is the chat-timeline message type (e.g. "user_message",
        "assistant_message") so clients can style it consistently with the full
        chat view; `text` is the trimmed, length-capped preview content.
    AgentSpanGroupDistributionItem:
      properties:
        alias:
          type: string
          title: Alias
        source:
          type: string
          enum:
            - custom_attrs_string
            - custom_attrs_int
            - custom_attrs_float
            - custom_attrs_bool
          title: Source
        key:
          type: string
          title: Key
        value_type:
          type: string
          enum:
            - string
            - int
            - float
            - bool
          title: Value Type
        total_count:
          type: integer
          title: Total Count
          default: 0
        present_count:
          type: integer
          title: Present Count
          default: 0
        missing_count:
          type: integer
          title: Missing Count
          default: 0
        other_count:
          type: integer
          title: Other Count
          default: 0
        bins:
          items:
            $ref: '#/components/schemas/AgentSpanGroupDistributionBin'
          type: array
          title: Bins
        values:
          items:
            $ref: '#/components/schemas/AgentSpanGroupDistributionValue'
          type: array
          title: Values
      type: object
      required:
        - alias
        - source
        - key
        - value_type
        - total_count
        - present_count
        - missing_count
        - other_count
        - bins
        - values
      title: AgentSpanGroupDistributionItem
      description: Distribution data for one span-group/custom-attribute pair.
    LiteralOperation:
      properties:
        $literal:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - additionalProperties:
                $ref: '#/components/schemas/LiteralOperation'
              type: object
            - items:
                $ref: '#/components/schemas/LiteralOperation'
              type: array
            - type: 'null'
          title: $Literal
      type: object
      required:
        - $literal
      title: LiteralOperation
      description: |-
        Represents a constant value in the query language.

        This can be any standard JSON-serializable value.

        Example:
            ```
            {"$literal": "predict"}
            ```
    GetFieldOperator:
      properties:
        $getField:
          type: string
          title: $Getfield
      type: object
      required:
        - $getField
      title: GetFieldOperator
      description: |-
        Access a field on the traced call.

        Supports dot notation for nested access, e.g. `summary.usage.tokens`.

        Only works on fields present in the `CallSchema`, including:
        - Top-level fields like `op_name`, `trace_id`, `started_at`
        - Nested fields like `inputs.input_name`, `summary.usage.tokens`, etc.

        Example:
            ```
            {"$getField": "op_name"}
            ```
    ConvertOperation:
      properties:
        $convert:
          $ref: '#/components/schemas/ConvertSpec'
      type: object
      required:
        - $convert
      title: ConvertOperation
      description: >-
        Convert the input value to a specific type (e.g., `int`, `bool`,
        `string`).


        Example:
            ```
            {
                "$convert": {
                    "input": {"$getField": "inputs.value"},
                    "to": "int"
                }
            }
            ```
    SizeOperation:
      properties:
        $size:
          anyOf:
            - $ref: '#/components/schemas/LiteralOperation'
            - $ref: '#/components/schemas/GetFieldOperator'
            - $ref: '#/components/schemas/ConvertOperation'
            - $ref: '#/components/schemas/SizeOperation'
            - $ref: '#/components/schemas/AndOperation'
            - $ref: '#/components/schemas/OrOperation'
            - $ref: '#/components/schemas/NotOperation'
            - $ref: '#/components/schemas/EqOperation'
            - $ref: '#/components/schemas/GtOperation'
            - $ref: '#/components/schemas/LtOperation'
            - $ref: '#/components/schemas/GteOperation'
            - $ref: '#/components/schemas/LteOperation'
            - $ref: '#/components/schemas/InOperation'
            - $ref: '#/components/schemas/ContainsOperation'
          title: $Size
      type: object
      required:
        - $size
      title: SizeOperation
      description: |-
        Return the number of elements in a collection or characters in a string.

        Example:
            ```
            {"$size": {"$getField": "scorer_tags"}}
            ```
    ContainsSpec:
      properties:
        input:
          anyOf:
            - $ref: '#/components/schemas/LiteralOperation'
            - $ref: '#/components/schemas/GetFieldOperator'
            - $ref: '#/components/schemas/ConvertOperation'
            - $ref: '#/components/schemas/SizeOperation'
            - $ref: '#/components/schemas/AndOperation'
            - $ref: '#/components/schemas/OrOperation'
            - $ref: '#/components/schemas/NotOperation'
            - $ref: '#/components/schemas/EqOperation'
            - $ref: '#/components/schemas/GtOperation'
            - $ref: '#/components/schemas/LtOperation'
            - $ref: '#/components/schemas/GteOperation'
            - $ref: '#/components/schemas/LteOperation'
            - $ref: '#/components/schemas/InOperation'
            - $ref: '#/components/schemas/ContainsOperation'
          title: Input
        substr:
          anyOf:
            - $ref: '#/components/schemas/LiteralOperation'
            - $ref: '#/components/schemas/GetFieldOperator'
            - $ref: '#/components/schemas/ConvertOperation'
            - $ref: '#/components/schemas/SizeOperation'
            - $ref: '#/components/schemas/AndOperation'
            - $ref: '#/components/schemas/OrOperation'
            - $ref: '#/components/schemas/NotOperation'
            - $ref: '#/components/schemas/EqOperation'
            - $ref: '#/components/schemas/GtOperation'
            - $ref: '#/components/schemas/LtOperation'
            - $ref: '#/components/schemas/GteOperation'
            - $ref: '#/components/schemas/LteOperation'
            - $ref: '#/components/schemas/InOperation'
            - $ref: '#/components/schemas/ContainsOperation'
          title: Substr
        case_insensitive:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Case Insensitive
          default: false
      type: object
      required:
        - input
        - substr
      title: ContainsSpec
      description: |-
        Specification for the `$contains` operation.

        - `input`: The string to search.
        - `substr`: The substring to search for.
        - `case_insensitive`: If true, match is case-insensitive.
    AgentSpanGroupDistributionBin:
      properties:
        index:
          type: integer
          title: Index
        min:
          type: number
          title: Min
        max:
          type: number
          title: Max
        count:
          type: integer
          title: Count
      type: object
      required:
        - index
        - min
        - max
        - count
      title: AgentSpanGroupDistributionBin
      description: One numeric histogram bin for a custom attribute in a span group.
    AgentSpanGroupDistributionValue:
      properties:
        value:
          type: string
          title: Value
        count:
          type: integer
          title: Count
      type: object
      required:
        - value
        - count
      title: AgentSpanGroupDistributionValue
      description: One categorical custom attribute value count in a span group.
    ConvertSpec:
      properties:
        input:
          anyOf:
            - $ref: '#/components/schemas/LiteralOperation'
            - $ref: '#/components/schemas/GetFieldOperator'
            - $ref: '#/components/schemas/ConvertOperation'
            - $ref: '#/components/schemas/SizeOperation'
            - $ref: '#/components/schemas/AndOperation'
            - $ref: '#/components/schemas/OrOperation'
            - $ref: '#/components/schemas/NotOperation'
            - $ref: '#/components/schemas/EqOperation'
            - $ref: '#/components/schemas/GtOperation'
            - $ref: '#/components/schemas/LtOperation'
            - $ref: '#/components/schemas/GteOperation'
            - $ref: '#/components/schemas/LteOperation'
            - $ref: '#/components/schemas/InOperation'
            - $ref: '#/components/schemas/ContainsOperation'
          title: Input
        to:
          type: string
          enum:
            - double
            - string
            - int
            - bool
            - exists
          title: To
      type: object
      required:
        - input
        - to
      title: ConvertSpec
      description: |-
        Specifies conversion details for `$convert`.

        - `input`: The operand to convert.
        - `to`: The type to convert to.

````