ArthurAI Sessions API

openapi: 3.1.0
info:
  title: Arthur GenAI Engine Agent Discovery Sessions API
  version: 2.1.688
tags:
- name: Sessions
paths:
  /api/v1/traces/sessions:
    get:
      tags:
      - Sessions
      summary: List Session Metadata
      description: Get session metadata with pagination and filtering. Returns aggregated session information.
      operationId: list_sessions_metadata_api_v1_traces_sessions_get
      security:
      - API Key: []
      parameters:
      - 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: 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: user_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: User IDs to filter on. Optional.
          title: User Ids
        description: User IDs to filter on. Optional.
      - name: trace_ids
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Trace IDs to filter on. Returns sessions containing at least one matching trace. Optional.
          title: Trace Ids
        description: Trace IDs to filter on. Returns sessions containing at least one matching trace. 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: include_experiment_sessions
        in: query
        required: false
        schema:
          type: boolean
          description: Include sessions originating from Arthur experiments. Defaults to false for most uses.
          default: false
          title: Include Experiment Sessions
        description: Include sessions originating from Arthur experiments. Defaults to false for most uses.
      - 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/traces/sessions/{session_id}:
    get:
      tags:
      - Sessions
      summary: Get Session Traces
      description: Get all traces in a session. Returns list of full trace trees with existing metrics (no computation).
      operationId: get_session_traces_api_v1_traces_sessions__session_id__get
      security:
      - API Key: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionTracesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/traces/sessions/{session_id}/metrics:
    get:
      tags:
      - Sessions
      summary: Compute Missing Session Metrics
      description: Get all traces in a session and compute missing metrics. Returns list of full trace trees with computed metrics.
      operationId: compute_session_metrics_api_v1_traces_sessions__session_id__metrics_get
      security:
      - API Key: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          title: Session 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionTracesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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
    AgenticAnnotationType:
      type: string
      enum:
      - human
      - continuous_eval
      title: AgenticAnnotationType
    MetricType:
      type: string
      enum:
      - QueryRelevance
      - ResponseRelevance
      - ToolSelection
      title: MetricType
    SessionMetadataResponse:
      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
        session_id:
          type: string
          title: Session Id
          description: Session identifier
        task_id:
          type: string
          title: Task Id
          description: Task ID this session belongs to
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
          description: User ID if available
        trace_ids:
          items:
            type: string
          type: array
          title: Trace Ids
          description: List of trace IDs in this session
        trace_count:
          type: integer
          title: Trace Count
          description: Number of traces in this session
        span_count:
          type: integer
          title: Span Count
          description: Total number of spans in this session
        earliest_start_time:
          type: string
          format: date-time
          title: Earliest Start Time
          description: Start time of earliest trace
        latest_end_time:
          type: string
          format: date-time
          title: Latest End Time
          description: End time of latest trace
        duration_ms:
          type: number
          title: Duration Ms
          description: Total session duration in milliseconds
      type: object
      required:
      - session_id
      - task_id
      - trace_ids
      - trace_count
      - span_count
      - earliest_start_time
      - latest_end_time
      - duration_ms
      title: SessionMetadataResponse
      description: Session summary metadata
    SessionTracesResponse:
      properties:
        session_id:
          type: string
          title: Session Id
          description: Session identifier
        count:
          type: integer
          title: Count
          description: Number of traces in this session
        display_currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Currency
          description: Currency code for cost fields
        traces:
          items:
            $ref: '#/components/schemas/TraceResponse'
          type: array
          title: Traces
          description: List of full trace trees
      type: object
      required:
      - session_id
      - count
      - traces
      title: SessionTracesResponse
      description: Response for session traces endpoint
    ContinuousEvalRunStatus:
      type: string
      enum:
      - pending
      - passed
      - running
      - failed
      - skipped
      - error
      title: ContinuousEvalRunStatus
    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
    SessionListResponse:
      properties:
        count:
          type: integer
          title: Count
          description: Total number of sessions matching filters
        display_currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Currency
          description: Currency code for cost fields
        sessions:
          items:
            $ref: '#/components/schemas/SessionMetadataResponse'
          type: array
          title: Sessions
          description: List of session metadata
      type: object
      required:
      - count
      - sessions
      title: SessionListResponse
      description: Response for session list endpoint
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  securitySchemes:
    API Key:
      type: http
      description: Bearer token authentication with an API key
      scheme: bearer