ArthurAI Traces API

openapi: 3.1.0
info:
  title: Arthur GenAI Engine Agent Discovery Traces API
  version: 2.1.688
tags:
- name: Traces
paths:
  /v1/traces:
    post:
      tags:
      - Traces
      summary: Receive Traces
      description: Receiver for OpenInference trace standard.
      operationId: receive_traces_v1_traces_post
      requestBody:
        content:
          application/json:
            schema:
              type: string
              contentMediaType: application/octet-stream
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      deprecated: true
      security:
      - API Key: []
  /api/v1/traces:
    post:
      tags:
      - Traces
      summary: Receive Traces
      description: Receiver for OpenInference trace standard.
      operationId: receive_traces_api_v1_traces_post
      security:
      - API Key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
              contentMediaType: application/octet-stream
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Traces
      summary: List Trace Metadata
      description: Get lightweight trace metadata for browsing/filtering operations. Returns metadata only without spans or metrics for fast performance. Set include_spans=true to include flat list of spans for each trace.
      operationId: list_traces_metadata_api_v1_traces_get
      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: include_spans
        in: query
        required: false
        schema:
          type: boolean
          description: Include flat list of spans for each trace. Defaults to false for performance.
          default: false
          title: Include Spans
        description: Include flat list of spans for each trace. Defaults to false for performance.
      - 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/TraceListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/traces/overview:
    post:
      tags:
      - Traces
      summary: Get Overview of Traces for each Task
      description: Get overview of traces for each task including trace count, total tokens, and success rate.
      operationId: get_traces_overview_api_v1_traces_overview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraceOverviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceOverviewListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - API Key: []
  /api/v1/traces/overview/timeseries:
    post:
      tags:
      - Traces
      summary: Get Time-Series Overview Data for a Task
      description: Get time-bucketed trace metrics (count, tokens, cost, success rate) for a single task.
      operationId: get_traces_timeseries_api_v1_traces_overview_timeseries_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraceTimeSeriesRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceTimeSeriesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - API Key: []
  /api/v1/traces/{trace_id}:
    get:
      tags:
      - Traces
      summary: Get Single Trace
      description: Get complete trace tree with existing metrics (no computation). Returns full trace structure with spans.
      operationId: get_trace_by_id_api_v1_traces__trace_id__get
      security:
      - API Key: []
      parameters:
      - name: trace_id
        in: path
        required: true
        schema:
          type: string
          title: Trace Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/traces/{trace_id}/metrics:
    get:
      tags:
      - Traces
      summary: Compute Missing Trace Metrics
      description: Compute all missing metrics for trace spans on-demand. Returns full trace tree with computed metrics.
      operationId: compute_trace_metrics_api_v1_traces__trace_id__metrics_get
      security:
      - API Key: []
      parameters:
      - name: trace_id
        in: path
        required: true
        schema:
          type: string
          title: Trace Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/traces/annotations/{annotation_id}:
    get:
      tags:
      - Traces
      summary: Get an annotation by id
      description: Get an annotation by id
      operationId: get_annotation_by_id_api_v1_traces_annotations__annotation_id__get
      security:
      - API Key: []
      parameters:
      - name: annotation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Annotation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgenticAnnotationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/traces/{trace_id}/annotations:
    get:
      tags:
      - Traces
      summary: List Annotations for a Trace
      description: List annotations for a trace
      operationId: list_annotations_for_trace_api_v1_traces__trace_id__annotations_get
      security:
      - API Key: []
      parameters:
      - name: trace_id
        in: path
        required: true
        schema:
          type: string
          title: Trace Id
      - 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: continuous_eval_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: ID of the continuous eval to filter on.
          title: Continuous Eval Id
        description: ID of the continuous eval to filter on.
      - name: annotation_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Annotation type to filter on.
          title: Annotation Type
        description: Annotation type to filter on.
      - name: annotation_score
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Annotation score to filter on.
          title: Annotation Score
        description: Annotation score to filter on.
      - name: run_status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ContinuousEvalRunStatus'
          - type: 'null'
          description: Run status to filter on.
          title: Run Status
        description: Run status to filter on.
      - name: created_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Inclusive start date for prompt creation in ISO8601 string format. Use local time (not UTC).
          title: Created After
        description: Inclusive start date for prompt creation in ISO8601 string format. Use local time (not UTC).
      - name: created_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Exclusive end date for prompt creation in ISO8601 string format. Use local time (not UTC).
          title: Created Before
        description: Exclusive end date for prompt creation in ISO8601 string format. Use local time (not UTC).
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgenticAnnotationsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Traces
      summary: Annotate a Trace
      description: Annotate a trace with a score and description (1 = liked, 0 = disliked)
      operationId: annotate_trace_api_v1_traces__trace_id__annotations_post
      security:
      - API Key: []
      parameters:
      - name: trace_id
        in: path
        required: true
        schema:
          type: string
          title: Trace Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgenticAnnotationRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgenticAnnotationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Traces
      summary: Delete an annotation from a trace
      description: Delete an annotation from a trace
      operationId: delete_annotation_from_trace_api_v1_traces__trace_id__annotations_delete
      security:
      - API Key: []
      parameters:
      - name: trace_id
        in: path
        required: true
        schema:
          type: string
          title: Trace Id
      responses:
        '204':
          description: Annotation deleted from trace.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AgenticAnnotationType:
      type: string
      enum:
      - human
      - continuous_eval
      title: AgenticAnnotationType
    MetricType:
      type: string
      enum:
      - QueryRelevance
      - ResponseRelevance
      - ToolSelection
      title: MetricType
    TraceOverviewResponse:
      properties:
        task_id:
          type: string
          title: Task Id
          description: Task ID
        trace_count:
          type: integer
          title: Trace Count
          description: Number of traces
        trace_token_count:
          type: integer
          title: Trace Token Count
          description: Total number of tokens in traces
        trace_token_cost:
          type: number
          title: Trace Token Cost
          description: Total token cost across traces
        eval_count:
          type: integer
          title: Eval Count
          description: Number of continuous-eval annotations
        continuous_eval_success_rate:
          type: number
          title: Continuous Eval Success Rate
          description: Fraction of continuous-eval annotations that passed
        last_active:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Active
          description: Most recent trace end time, or null if no traces in the window
      type: object
      required:
      - task_id
      - trace_count
      - trace_token_count
      - trace_token_cost
      - eval_count
      - continuous_eval_success_rate
      title: TraceOverviewResponse
      description: Response for trace overview
    TraceOverviewListResponse:
      properties:
        overviews:
          items:
            $ref: '#/components/schemas/TraceOverviewResponse'
          type: array
          title: Overviews
          description: Li

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