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: List of trace overviews
        count:
          type: integer
          title: Count
          description: Total number of trace overviews
      type: object
      required:
      - overviews
      - count
      title: TraceOverviewListResponse
      description: Response for list of trace overviews
    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
    TraceMetadataResponse:
      properties:
        prompt_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Prompt Token Count
          description: Number of prompt tokens
        completion_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Completion Token Count
          description: Number of completion tokens
        total_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Token Count
          description: Total number of tokens
        prompt_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Prompt Token Cost
          description: Cost of prompt tokens in USD
        completion_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Completion Token Cost
          description: Cost of completion tokens in USD
        total_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Token Cost
          description: Total cost in USD
        trace_id:
          type: string
          title: Trace Id
          description: ID of the trace
        task_id:
          type: string
          title: Task Id
          description: Task ID this trace belongs to
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
          description: User ID if available
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
          description: Session ID if available
        start_time:
          type: string
          format: date-time
          title: Start Time
          description: Start time of the earliest span
        end_time:
          type: string
          format: date-time
          title: End Time
          description: End time of the latest span
        span_count:
          type: integer
          title: Span Count
          description: Number of spans in this trace
        duration_ms:
          type: number
          title: Duration Ms
          description: Total trace duration in milliseconds
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the trace was first created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: When the trace was last updated
        input_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Content
          description: Root span input value from trace metadata
        output_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Output Content
          description: Root span output value from trace metadata
        annotations:
          anyOf:
          - items:
              $ref: '#/components/schemas/AgenticAnnotationResponse'
            type: array
          - type: 'null'
          title: Annotations
          description: Annotations for the trace.
        spans:
          anyOf:
          - items:
              $ref: '#/components/schemas/SpanWithMetricsResponse'
            type: array
          - type: 'null'
          title: Spans
          description: Flat list of spans in this trace (only populated when include_spans=true).
      type: object
      required:
      - trace_id
      - task_id
      - start_time
      - end_time
      - span_count
      - duration_ms
      - created_at
      - updated_at
      title: TraceMetadataResponse
      description: Lightweight trace metadata for list operations
    ToolClassEnum:
      type: integer
      enum:
      - 0
      - 1
      - 2
      title: ToolClassEnum
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TraceOverviewRequest:
      properties:
        task_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Task Ids
          description: Optional list of task IDs to get the overview of traces for
        start_time:
          type: string
          format: date-time
          title: Start Time
          description: Start time of the traces to get the overview of
        end_time:
          type: string
          format: date-time
          title: End Time
          description: End time of the traces to get the overview of
      type: object
      required:
      - start_time
      - end_time
      title: TraceOverviewRequest
      description: Request schema for getting the overview of traces for each task
    TraceTimeSeriesResponse:
      properties:
        task_id:
          type: string
          title: Task Id
          description: Task ID
        points:
          items:
            $ref: '#/components/schemas/TraceTimeSeriesPoint'
          type: array
          title: Points
          description: Time buckets ordered ascending by timestamp
      type: object
      required:
      - task_id
      - points
      title: TraceTimeSeriesResponse
      description: Response for time-bucketed trace metrics for a single task.
    TraceTimeSeriesPoint:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Inclusive start of the bucket
        trace_count:
          type: integer
          title: Trace Count
          description: Number of traces in the bucket
        trace_token_count:
          type: integer
          title: Trace Token Count
          description: Total tokens in the bucket
        trace_token_cost:
          type: number
          title: Trace Token Cost
          description: Total token cost in the bucket
        continuous_eval_success_rate:
          type: number
          title: Continuous Eval Success Rate
          description: Fraction of continuous-eval annotations that passed in the bucket
      type: object
      required:
      - timestamp
      - trace_count
      - trace_token_count
      - trace_token_cost
      - continuous_eval_success_rate
      title: TraceTimeSeriesPoint
      description: Metrics for a single time bucket, one per Analyze-page chart series.
    MetricResultResponse:
      properties:
        id:
          type: string
          title: Id
          description: ID of the metric result
        metric_type:
          $ref: '#/components/schemas/MetricType'
          description: Type of the metric
        details:
          anyOf:
          - type: string
          - type: 'null'
          title: Details
          description: JSON-serialized metric details
        prompt_tokens:
          type: integer
          title: Prompt Tokens
          description: Number of prompt tokens used
        completion_tokens:
          type: integer
          title: Completion Tokens
          description: Number of completion tokens used
        latency_ms:
          type: integer
          title: Latency Ms
          description: Latency in milliseconds
        span_id:
          type: string
          title: Span Id
          description: ID of the span this result belongs to
        metric_id:
          type: string
          title: Metric Id
          description: ID of the metric that generated this result
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Time the result was created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Time the result was last updated
      type: object
      required:
      - id
      - metric_type
      - prompt_tokens
      - completion_tokens
      - latency_ms
      - span_id
      - metric_id
      - created_at
      - updated_at
      title: MetricResultResponse
    AgenticAnnotationResponse:
      properties:
        id:
          type: string
          title: Id
          description: ID of the annotation
        annotation_type:
          $ref: '#/components/schemas/AgenticAnnotationType'
          description: Type of annotation
        trace_id:
          type: string
          title: Trace Id
          description: ID of the trace this annotation belongs to
        continuous_eval_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Continuous Eval Id
          description: ID of the continuous eval this annotation belongs to
        continuous_eval_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Continuous Eval Name
          description: Name of the continuous eval this annotation belongs to
        eval_type:
          anyOf:
          - $ref: '#/components/schemas/EvalType'
          - type: 'null'
          description: 'Type of eval: ''llm_eval'' or ''ml_eval'''
        eval_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Eval Name
          description: Name of the eval the continuous eval used when scoring
        eval_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Eval Version
          description: Version of the eval the continuous eval used when scoring
        annotation_score:
          anyOf:
          - type: integer
          - type: 'null'
          title: Annotation Score
          description: Binary score for a positive or negative annotation.
        annotation_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Annotation Description
          description: Description of the annotation.
        input_variables:
          anyOf:
          - items:
              $ref: '#/components/schemas/VariableTemplateValue'
            type: array
          - type: 'null'
          title: Input Variables
          description: Input variables for the continuous eval
        run_status:
          anyOf:
          - $ref: '#/components/schemas/ContinuousEvalRunStatus'
          - type: 'null'
          description: Status of the continuous eval run
        cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Cost
          description: Cost of the continuous eval run
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Time the annotation was created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Time the annotation was last updated
      type: object
      required:
      - id
      - annotation_type
      - trace_id
      - created_at
      - updated_at
      title: AgenticAnnotationResponse
    VariableTemplateValue:
      properties:
        name:
          type: string
          title: Name
          description: Name of the variable
        value:
          type: string
          title: Value
          description: Value of the variable
      type: object
      required:
      - name
      - value
      title: VariableTemplateValue
    EvalType:
      type: string
      enum:
      - llm_eval
      - ml_eval
      title: EvalType
    TraceResponse:
      properties:
        prompt_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Prompt Token Count
          description: Number of prompt tokens
        completion_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Completion Token Count
          description: Number of completion tokens
        total_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Token Count
          description: Total number of tokens
        prompt_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Prompt Token Cost
          description: Cost of prompt tokens in USD
        completion_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Completion Token Cost
          description: Cost of completion tokens in USD
        total_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Token Cost
          description: Total cost in USD
        trace_id:
          type: string
          title: Trace Id
          description: ID of the trace
        start_time:
          type: string
          format: date-time
          title: Start Time
          description: Start time of the earliest span in this trace
        end_time:
          type: string
          format: date-time
          title: End Time
          description: End time of the latest span in this trace
        input_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Content
          description: Root span input value from trace metadata
        output_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Output Content
          description: Root span output value from trace metadata
        root_spans:
          items:
            $ref: '#/components/schemas/NestedSpanWithMetricsResponse'
          type: array
          title: Root Spans
          description: Root spans (spans with no parent) in this trace, with children nested
          default: []
        annotations:
          anyOf:
          - items:
              $ref: '#/components/schemas/AgenticAnnotationResponse'
            type: array
          - type: 'null'
          title: Annotations
          description: Annotations for this trace.
      type: object
      required:
      - trace_id
      - start_time
      - end_time
      title: TraceResponse
      description: Response model for a single trace containing nested spans
    PaginationSortMethod:
      type: string
      enum:
      - asc
      - desc
      title: PaginationSortMethod
    TraceSortBy:
      type: string
      enum:
      - start_time
      - total_token_count
      - total_token_cost
      - span_count
      title: TraceSortBy
    AgenticAnnotationRequest:
      properties:
        annotation_score:
          type: integer
          maximum: 1.0
          minimum: 0.0
          title: Annotation Score
          description: Binary score for whether a traces has been liked or disliked (0 = disliked, 1 = liked)
        annotation_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Annotation Description
          description: Description of the annotation
      type: object
      required:
      - annotation_score
      title: AgenticAnnotationRequest
    ListAgenticAnnotationsResponse:
      properties:
        annotations:
          items:
            $ref: '#/components/schemas/AgenticAnnotationResponse'
          type: array
          title: Annotations
          description: List of annotations
        count:
          type: integer
          title: Count
          description: Total number of annotations
      type: object
      required:
      - annotations
      - count
      title: ListAgenticAnnotationsResponse
    TraceListResponse:
      properties:
        count:
          type: integer
          title: Count
          description: Total number of traces matching filters
        display_currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Currency
          description: Currency code for cost fields
        traces:
          items:
            $ref: '#/components/schemas/TraceMetadataResponse'
          type: array
          title: Traces
          description: List of trace metadata
      type: object
      required:
      - count
      - traces
      title: TraceListResponse
      description: Response for trace list endpoint
    NestedSpanWithMetricsResponse:
      properties:
        prompt_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Prompt Token Count
          description: Number of prompt tokens
        completion_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Completion Token Count
          description: Number of completion tokens
        total_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Token Count
          description: Total number of tokens
        prompt_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Prompt Token Cost
          description: Cost of prompt tokens in USD
        completion_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Completion Token Cost
          description: Cost of completion tokens in USD
        total_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Token Cost
          description: Total cost in USD
        id:
          type: string
          title: 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_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Span Kind
        span_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Span Name
        start_time:
          type: string
          format: date-time
          title: Start Time
        end_time:
          type: string
          format: date-time
          title: End Time
        task_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Id
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        status_code:
          type: string
          title: Status Code
          description: Status code for the span (Unset, Error, Ok)
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        raw_data:
          additionalProperties: true
          type: object
          title: Raw Data
        input_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Content
          description: Span input value from raw_data.attributes.input.value
        output_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Output Content
          description: Span output value from raw_data.attributes.output.value
        metric_results:
          items:
            $ref: '#/components/schemas/MetricResultResponse'
          type: array
          title: Metric Results
          description: List of metric results for this span
          default: []
        children:
          items:
            $ref: '#/components/schemas/NestedSpanWithMetricsResponse'
          type: array
          title: Children
          description: Child spans nested under this span
          default: []
      type: object
      required:
      - id
      - trace_id
      - span_id
      - start_time
      - end_time
      - status_code
      - created_at
      - updated_at
      - raw_data
      title: NestedSpanWithMetricsResponse
      description: Nested span response with children for building span trees
    TraceTimeSeriesRequest:
      properties:
        task_id:
          type: string
          title: Task Id
          description: Task ID to get time-series metrics for
        start_time:
          type: string
          format: date-time
          title: Start Time
          description: Inclusive start boundary of the time window
        end_time:
          type: string
          format: date-time
          title: End Time
          description: Exclusive end boundary of the time window
        bucket_size:
          $ref: '#/components/schemas/TaskAnalyticsBucketSize'
          description: Size of each time bucket
      type: object
      required:
      - task_id
      - start_time
      - end_time
      - bucket_size
      title: TraceTimeSeriesRequest
      description: 'Request schema for time-bucketed trace metrics for a single task.


        The caller (frontend) owns interval -> window + bucket-size resolution and

        passes the resolved start_time, end_time, and bucket_size; the backend just

        buckets and zero-fills, mirroring the Analyze page aggregation.'
    StatusCodeEnum:
      type: string
      enum:
      - Ok
      - Error
      - Unset
      title: StatusCodeEnum
    ContinuousEvalRunStatus:
      type: string
      enum:
      - pending
      - passed
      - running
      - failed
      - skipped
      - error
      title: ContinuousEvalRunStatus
    TaskAnalyticsBucketSize:
      type: string
      enum:
      - hour
      - day
      - week
      title: TaskAnalyticsBucketSize
      description: Time bucket granularity for task analytics time-series metrics.
    SpanWithMetricsResponse:
      properties:
        prompt_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Prompt Token Count
          description: Number of prompt tokens
        completion_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Completion Token Count
          description: Number of completion tokens
        total_token_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Token Count
          description: Total number of tokens
        prompt_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Prompt Token Cost
          description: Cost of prompt tokens in USD
        completion_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Completion Token Cost
          description: Cost of completion tokens in USD
        total_token_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Token Cost
          description: Total cost in USD
        id:
          type: string
          title: 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_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Span Kind
        span_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Span Name
        start_time:
          type: string
          format: date-time
          title: Start Time
        end_time:
          type: string
          format: date-time
          title: End Time
        task_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Id
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        status_code:
          type: string
          title: Status Code
          description: Status code for the span (Unset, Error, Ok)
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        raw_data:
          additionalProperties: true
          type: object
          title: Raw Data
        input_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Content
          description: Span input value from raw_data.attributes.input.value
        output_content:
          anyOf:
          - type: string
          - type: 'null'
          title: Output Content
          description: Span output value from raw_data.attributes.output.value
        metric_results:
          items:
            $ref: '#/components/schemas/MetricResultResponse'
          type: array
          title: Metric Results
          description: List of metric results for this span
          default: []
      type: object
      required:
      - id
      - trace_id
      - span_id
      - start_time
      - end_time
      - status_code
      - created_at
      - updated_at
      - raw_data
      title: SpanWithMetricsResponse
  securitySchemes:
    API Key:
      type: http
      description: Bearer token authentication with an API key
      scheme: bearer