ArthurAI Spans API

openapi: 3.1.0
info:
  title: Arthur GenAI Engine Agent Discovery Spans API
  version: 2.1.688
tags:
- name: Spans
paths:
  /v1/traces/query:
    get:
      tags:
      - Spans
      summary: Query Traces
      description: Query traces with comprehensive filtering. Returns traces containing spans that match the filters, not just the spans themselves.
      operationId: query_spans_v1_traces_query_get
      deprecated: true
      security:
      - API Key: []
      parameters:
      - name: sort_by
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/TraceSortBy'
          description: Column to sort results by.
          default: start_time
        description: Column to sort results by.
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PaginationSortMethod'
          description: Sort the results (asc/desc)
          default: desc
        description: Sort the results (asc/desc)
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          description: Page size. Default is 10. Must be greater than 0 and less than 5000.
          default: 10
          title: Page Size
        description: Page size. Default is 10. Must be greater than 0 and less than 5000.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: Page number
          default: 0
          title: Page
        description: Page number
      - name: task_ids
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
          minItems: 1
          description: Task IDs to filter on. At least one is required.
          title: Task Ids
        description: Task IDs to filter on. At least one is required.
      - name: trace_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Trace IDs to filter on. Optional.
          title: Trace Ids
        description: Trace IDs to filter on. Optional.
      - name: start_time
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Inclusive start date in ISO8601 string format. Use local time (not UTC).
          title: Start Time
        description: Inclusive start date in ISO8601 string format. Use local time (not UTC).
      - name: end_time
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Exclusive end date in ISO8601 string format. Use local time (not UTC).
          title: End Time
        description: Exclusive end date in ISO8601 string format. Use local time (not UTC).
      - name: tool_name
        in: query
        required: false
        schema:
          type: string
          description: Return only results with this tool name.
          title: Tool Name
        description: Return only results with this tool name.
      - name: span_types
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: 'Span types to filter on. Optional. Valid values: AGENT, CHAIN, EMBEDDING, EVALUATOR, GUARDRAIL, LLM, PROMPT, RERANKER, RETRIEVER, TOOL, UNKNOWN'
          title: Span Types
        description: 'Span types to filter on. Optional. Valid values: AGENT, CHAIN, EMBEDDING, EVALUATOR, GUARDRAIL, LLM, PROMPT, RERANKER, RETRIEVER, TOOL, UNKNOWN'
      - name: annotation_score
        in: query
        required: false
        schema:
          type: integer
          maximum: 1
          minimum: 0
          description: Filter by trace annotation score (0 or 1).
          title: Annotation Score
        description: Filter by trace annotation score (0 or 1).
      - name: annotation_type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/AgenticAnnotationType'
          description: Filter by trace annotation type (i.e. 'human' or 'continuous_eval').
        description: Filter by trace annotation type (i.e. 'human' or 'continuous_eval').
      - name: continuous_eval_run_status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ContinuousEvalRunStatus'
          description: Filter by trace annotation run status (e.g. 'passed', 'failed', etc.).
        description: Filter by trace annotation run status (e.g. 'passed', 'failed', etc.).
      - name: continuous_eval_name
        in: query
        required: false
        schema:
          type: string
          description: Filter by continuous eval name.
          title: Continuous Eval Name
        description: Filter by continuous eval name.
      - name: span_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Span IDs to filter on. Optional.
          title: Span Ids
        description: Span IDs to filter on. Optional.
      - name: session_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Session IDs to filter on. Optional.
          title: Session Ids
        description: Session IDs to filter on. Optional.
      - name: user_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: User ID substrings to filter on (case-insensitive). Returns results where user_id contains any of the provided values. Optional.
          title: User Ids
        description: User ID substrings to filter on (case-insensitive). Returns results where user_id contains any of the provided values. Optional.
      - name: span_name
        in: query
        required: false
        schema:
          type: string
          description: Return only results with this span name.
          title: Span Name
        description: Return only results with this span name.
      - name: span_name_contains
        in: query
        required: false
        schema:
          type: string
          description: Return only results where span name contains this substring.
          title: Span Name Contains
        description: Return only results where span name contains this substring.
      - name: status_code
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/StatusCodeEnum'
          - type: 'null'
          description: 'Status codes to filter on. Optional. Valid values: Ok, Error, Unset.'
          title: Status Code
        description: 'Status codes to filter on. Optional. Valid values: Ok, Error, Unset.'
      - name: query_relevance_eq
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Equal to this value.
          title: Query Relevance Eq
        description: Equal to this value.
      - name: query_relevance_gt
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Greater than this value.
          title: Query Relevance Gt
        description: Greater than this value.
      - name: query_relevance_gte
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Greater than or equal to this value.
          title: Query Relevance Gte
        description: Greater than or equal to this value.
      - name: query_relevance_lt
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Less than this value.
          title: Query Relevance Lt
        description: Less than this value.
      - name: query_relevance_lte
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Less than or equal to this value.
          title: Query Relevance Lte
        description: Less than or equal to this value.
      - name: response_relevance_eq
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Equal to this value.
          title: Response Relevance Eq
        description: Equal to this value.
      - name: response_relevance_gt
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Greater than this value.
          title: Response Relevance Gt
        description: Greater than this value.
      - name: response_relevance_gte
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Greater than or equal to this value.
          title: Response Relevance Gte
        description: Greater than or equal to this value.
      - name: response_relevance_lt
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Less than this value.
          title: Response Relevance Lt
        description: Less than this value.
      - name: response_relevance_lte
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Less than or equal to this value.
          title: Response Relevance Lte
        description: Less than or equal to this value.
      - name: tool_selection
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ToolClassEnum'
          description: Tool selection evaluation result.
        description: Tool selection evaluation result.
      - name: tool_usage
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ToolClassEnum'
          description: Tool usage evaluation result.
        description: Tool usage evaluation result.
      - name: trace_duration_eq
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Duration exactly equal to this value (seconds).
          title: Trace Duration Eq
        description: Duration exactly equal to this value (seconds).
      - name: trace_duration_gt
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Duration greater than this value (seconds).
          title: Trace Duration Gt
        description: Duration greater than this value (seconds).
      - name: trace_duration_gte
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Duration greater than or equal to this value (seconds).
          title: Trace Duration Gte
        description: Duration greater than or equal to this value (seconds).
      - name: trace_duration_lt
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Duration less than this value (seconds).
          title: Trace Duration Lt
        description: Duration less than this value (seconds).
      - name: trace_duration_lte
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Duration less than or equal to this value (seconds).
          title: Trace Duration Lte
        description: Duration less than or equal to this value (seconds).
      - name: total_token_count_eq
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Total token count exactly equal to this value.
          title: Total Token Count Eq
        description: Total token count exactly equal to this value.
      - name: total_token_count_gt
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Total token count greater than this value.
          title: Total Token Count Gt
        description: Total token count greater than this value.
      - name: total_token_count_gte
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Total token count greater than or equal to this value.
          title: Total Token Count Gte
        description: Total token count greater than or equal to this value.
      - name: total_token_count_lt
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Total token count less than this value.
          title: Total Token Count Lt
        description: Total token count less than this value.
      - name: total_token_count_lte
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Total token count less than or equal to this value.
          title: Total Token Count Lte
        description: Total token count less than or equal to this value.
      - name: prompt_token_count_eq
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Prompt token count exactly equal to this value.
          title: Prompt Token Count Eq
        description: Prompt token count exactly equal to this value.
      - name: prompt_token_count_gt
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Prompt token count greater than this value.
          title: Prompt Token Count Gt
        description: Prompt token count greater than this value.
      - name: prompt_token_count_gte
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Prompt token count greater than or equal to this value.
          title: Prompt Token Count Gte
        description: Prompt token count greater than or equal to this value.
      - name: prompt_token_count_lt
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Prompt token count less than this value.
          title: Prompt Token Count Lt
        description: Prompt token count less than this value.
      - name: prompt_token_count_lte
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Prompt token count less than or equal to this value.
          title: Prompt Token Count Lte
        description: Prompt token count less than or equal to this value.
      - name: completion_token_count_eq
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Completion token count exactly equal to this value.
          title: Completion Token Count Eq
        description: Completion token count exactly equal to this value.
      - name: completion_token_count_gt
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Completion token count greater than this value.
          title: Completion Token Count Gt
        description: Completion token count greater than this value.
      - name: completion_token_count_gte
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Completion token count greater than or equal to this value.
          title: Completion Token Count Gte
        description: Completion token count greater than or equal to this value.
      - name: completion_token_count_lt
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Completion token count less than this value.
          title: Completion Token Count Lt
        description: Completion token count less than this value.
      - name: completion_token_count_lte
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Completion token count less than or equal to this value.
          title: Completion Token Count Lte
        description: Completion token count less than or equal to this value.
      - name: span_count_eq
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Span count exactly equal to this value.
          title: Span Count Eq
        description: Span count exactly equal to this value.
      - name: span_count_gt
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Span count greater than this value.
          title: Span Count Gt
        description: Span count greater than this value.
      - name: span_count_gte
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Span count greater than or equal to this value.
          title: Span Count Gte
        description: Span count greater than or equal to this value.
      - name: span_count_lt
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Span count less than this value.
          title: Span Count Lt
        description: Span count less than this value.
      - name: span_count_lte
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Span count less than or equal to this value.
          title: Span Count Lte
        description: Span count less than or equal to this value.
      - name: include_experiment_traces
        in: query
        required: false
        schema:
          type: boolean
          description: Include traces originating from Arthur experiments. Defaults to true.
          default: true
          title: Include Experiment Traces
        description: Include traces originating from Arthur experiments. Defaults to true.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryTracesWithMetricsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/traces/metrics/:
    get:
      tags:
      - Spans
      summary: Compute Missing Metrics and Query Traces
      description: Query traces with comprehensive filtering and compute metrics. Returns traces containing spans that match the filters with computed metrics.
      operationId: query_spans_with_metrics_v1_traces_metrics__get
      deprecated: true
      security:
      - API Key: []
      parameters:
      - name: sort_by
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/TraceSortBy'
          description: Column to sort results by.
          default: start_time
        description: Column to sort results by.
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PaginationSortMethod'
          description: Sort the results (asc/desc)
          default: desc
        description: Sort the results (asc/desc)
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          description: Page size. Default is 10. Must be greater than 0 and less than 5000.
          default: 10
          title: Page Size
        description: Page size. Default is 10. Must be greater than 0 and less than 5000.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: Page number
          default: 0
          title: Page
        description: Page number
      - name: task_ids
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
          minItems: 1
          description: Task IDs to filter on. At least one is required.
          title: Task Ids
        description: Task IDs to filter on. At least one is required.
      - name: trace_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Trace IDs to filter on. Optional.
          title: Trace Ids
        description: Trace IDs to filter on. Optional.
      - name: start_time
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Inclusive start date in ISO8601 string format. Use local time (not UTC).
          title: Start Time
        description: Inclusive start date in ISO8601 string format. Use local time (not UTC).
      - name: end_time
        in: query
        required: false
        schema:
          type: string
          format: date-time
          description: Exclusive end date in ISO8601 string format. Use local time (not UTC).
          title: End Time
        description: Exclusive end date in ISO8601 string format. Use local time (not UTC).
      - name: tool_name
        in: query
        required: false
        schema:
          type: string
          description: Return only results with this tool name.
          title: Tool Name
        description: Return only results with this tool name.
      - name: span_types
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: 'Span types to filter on. Optional. Valid values: AGENT, CHAIN, EMBEDDING, EVALUATOR, GUARDRAIL, LLM, PROMPT, RERANKER, RETRIEVER, TOOL, UNKNOWN'
          title: Span Types
        description: 'Span types to filter on. Optional. Valid values: AGENT, CHAIN, EMBEDDING, EVALUATOR, GUARDRAIL, LLM, PROMPT, RERANKER, RETRIEVER, TOOL, UNKNOWN'
      - name: annotation_score
        in: query
        required: false
        schema:
          type: integer
          maximum: 1
          minimum: 0
          description: Filter by trace annotation score (0 or 1).
          title: Annotation Score
        description: Filter by trace annotation score (0 or 1).
      - name: annotation_type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/AgenticAnnotationType'
          description: Filter by trace annotation type (i.e. 'human' or 'continuous_eval').
        description: Filter by trace annotation type (i.e. 'human' or 'continuous_eval').
      - name: continuous_eval_run_status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ContinuousEvalRunStatus'
          description: Filter by trace annotation run status (e.g. 'passed', 'failed', etc.).
        description: Filter by trace annotation run status (e.g. 'passed', 'failed', etc.).
      - name: continuous_eval_name
        in: query
        required: false
        schema:
          type: string
          description: Filter by continuous eval name.
          title: Continuous Eval Name
        description: Filter by continuous eval name.
      - name: span_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Span IDs to filter on. Optional.
          title: Span Ids
        description: Span IDs to filter on. Optional.
      - name: session_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Session IDs to filter on. Optional.
          title: Session Ids
        description: Session IDs to filter on. Optional.
      - name: user_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: User ID substrings to filter on (case-insensitive). Returns results where user_id contains any of the provided values. Optional.
          title: User Ids
        description: User ID substrings to filter on (case-insensitive). Returns results where user_id contains any of the provided values. Optional.
      - name: span_name
        in: query
        required: false
        schema:
          type: string
          description: Return only results with this span name.
          title: Span Name
        description: Return only results with this span name.
      - name: span_name_contains
        in: query
        required: false
        schema:
          type: string
          description: Return only results where span name contains this substring.
          title: Span Name Contains
        description: Return only results where span name contains this substring.
      - name: status_code
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/StatusCodeEnum'
          - type: 'null'
          description: 'Status codes to filter on. Optional. Valid values: Ok, Error, Unset.'
          title: Status Code
        description: 'Status codes to filter on. Optional. Valid values: Ok, Error, Unset.'
      - name: query_relevance_eq
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Equal to this value.
          title: Query Relevance Eq
        description: Equal to this value.
      - name: query_relevance_gt
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Greater than this value.
          title: Query Relevance Gt
        description: Greater than this value.
      - name: query_relevance_gte
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Greater than or equal to this value.
          title: Query Relevance Gte
        description: Greater than or equal to this value.
      - name: query_relevance_lt
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Less than this value.
          title: Query Relevance Lt
        description: Less than this value.
      - name: query_relevance_lte
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Less than or equal to this value.
          title: Query Relevance Lte
        description: Less than or equal to this value.
      - name: response_relevance_eq
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Equal to this value.
          title: Response Relevance Eq
        description: Equal to this value.
      - name: response_relevance_gt
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Greater than this value.
          title: Response Relevance Gt
        description: Greater than this value.
      - name: response_relevance_gte
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Greater than or equal to this value.
          title: Response Relevance Gte
        description: Greater than or equal to this value.
      - name: response_relevance_lt
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Less than this value.
          title: Response Relevance Lt
        description: Less than this value.
      - name: response_relevance_lte
        in: query
        required: false
        schema:
          type: number
          maximum: 1
          minimum: 0
          description: Less than or equal to this value.
          title: Response Relevance Lte
        description: Less than or equal to this value.
      - name: tool_selection
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ToolClassEnum'
          description: Tool selection evaluation result.
        description: Tool selection evaluation result.
      - name: tool_usage
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/ToolClassEnum'
          description: Tool usage evaluation result.
        description: Tool usage evaluation result.
      - name: trace_duration_eq
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Duration exactly equal to this value (seconds).
          title: Trace Duration Eq
        description: Duration exactly equal to this value (seconds).
      - name: trace_duration_gt
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Duration greater than this value (seconds).
          title: Trace Duration Gt
        description: Duration greater than this value (seconds).
      - name: trace_duration_gte
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Duration greater than or equal to this value (seconds).
          title: Trace Duration Gte
        description: Duration greater than or equal to this value (seconds).
      - name: trace_duration_lt
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Duration less than this value (seconds).
          title: Trace Duration Lt
        description: Duration less than this value (seconds).
      - name: trace_duration_lte
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          description: Duration less than or equal to this value (seconds).
          title: Trace Duration Lte
        description: Duration less than or equal to this value (seconds).
      - name: total_token_count_eq
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Total token count exactly equal to this value.
          title: Total Token Count Eq
        description: Total token count exactly equal to this value.
      - name: total_token_count_gt
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Total token count greater than this value.
          title: Total Token Count Gt
        description: Total token count greater than this value.
      - name: total_token_count_gte
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Total token count greater than or equal to this value.
          title: Total Token Count Gte
        description: Total token count greater than or equal to this value.
      - name: total_token_count_lt
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Total token count less than this value.
          title: Total Token Count Lt
        description: Total token count less than this value.
      - name: total_token_count_lte
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Total token count less than or equal to this value.
          title: Total Token Count Lte
        description: Total token count less than or equal to this value.
      - name: prompt_token_count_eq
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Prompt token count exactly equal to this value.
          title: Prompt Token Count Eq
        descr

# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arthurai/refs/heads/main/openapi/arthurai-spans-api-openapi.yml