Orq.ai Traces API

openapi: 3.2.0
info:
  title: orq.ai Traces API
  version: '2.0'
  description: orq.ai API documentation
servers:
- url: https://my.orq.ai
security:
- ApiKey: []
tags:
- name: Traces
  description: 'Query and inspect ingested trace data: search trace summaries, aggregate metrics, and read individual traces and their spans.'
paths:
  /v3/traces/aggregate:
    post:
      tags:
      - Traces
      summary: Aggregate traces
      description: Aggregate trace metrics using the structured trace filter contract.
      operationId: TracesAggregate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AggregateTracesRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregateTracesResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: traces
      x-speakeasy-name-override: aggregate
  /v3/traces/facets:
    get:
      tags:
      - Traces
      summary: List trace facets
      description: List trace fields that support facet value discovery.
      operationId: TracesListFacets
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTraceFacetsResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: traces
      x-speakeasy-name-override: list_facets
  /v3/traces/facets/{field}:
    get:
      tags:
      - Traces
      summary: List trace facet values
      description: List values and counts for one trace facet field.
      operationId: TracesListFacetValues
      parameters:
      - name: field
        in: path
        required: true
        schema:
          type: string
      - name: from
        in: query
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        schema:
          type: integer
          format: int32
      - name: filter_operator
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTraceFacetValuesResponse'
        '400':
          description: The request is invalid. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: traces
      x-speakeasy-name-override: list_facet_values
  /v3/traces/fields:
    get:
      tags:
      - Traces
      summary: List trace fields
      description: List currently supported static trace fields.
      operationId: TracesListFields
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTraceFieldsResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: traces
      x-speakeasy-name-override: list_fields
  /v3/traces/query:
    post:
      tags:
      - Traces
      summary: Query traces with OQL
      description: Run an OQL trace query over a time range. OQL selects the traces to return.
      operationId: TracesQueryOql
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryTracesRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryTracesResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: traces
      x-speakeasy-name-override: query
  /v3/traces/search:
    post:
      tags:
      - Traces
      summary: Search traces
      description: Search trace summaries using the structured trace filter contract. See the filter grammar for the field and operator reference.
      operationId: TracesSearch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchTracesRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchTracesResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: traces
      x-speakeasy-name-override: search
  /v3/traces/{trace_id}:
    get:
      tags:
      - Traces
      summary: Get trace
      description: Retrieve one trace summary by trace id.
      operationId: TracesGet
      parameters:
      - name: trace_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTraceResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The resource does not exist. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: traces
      x-speakeasy-name-override: get
  /v3/traces/{trace_id}/spans:
    get:
      tags:
      - Traces
      summary: List trace spans
      description: List canonical span summaries for a trace.
      operationId: TracesListSpans
      parameters:
      - name: trace_id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          format: int32
      - name: page_token
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTraceSpansResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: traces
      x-speakeasy-name-override: list_spans
  /v3/traces/{trace_id}/spans/{span_id}:
    get:
      tags:
      - Traces
      summary: Get trace span
      description: Retrieve one hydrated span.
      operationId: TracesGetSpan
      parameters:
      - name: trace_id
        in: path
        required: true
        schema:
          type: string
      - name: span_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTraceSpanResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The resource does not exist. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: traces
      x-speakeasy-name-override: get_span
  /v3/traces/{trace_id}/conversation:
    get:
      tags:
      - Traces
      summary: Get trace conversation
      description: Return ordered OpenResponses items from the selected model-call span. Prefers spans with output outside evaluator subtrees unless `span_id` is given.
      operationId: TracesGetConversation
      parameters:
      - name: trace_id
        in: path
        required: true
        schema:
          type: string
      - name: span_id
        in: query
        description: Read the conversation from this span instead of the automatically selected one.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTraceConversationResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The resource does not exist. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: traces
      x-speakeasy-name-override: get_conversation
      x-code-samples:
      - lang: typescript
        label: Node.js
        source: 'await orq.traces.getConversation({ traceId: "6b9bf4d94704f936d11b3f4ffb7bcd78" });

          '
components:
  schemas:
    ListTraceFacetValuesResponse:
      type: object
      properties:
        field:
          type: string
        values:
          type: array
          items:
            $ref: '#/components/schemas/TraceFacetValue'
        has_more:
          type: boolean
    TraceCompute:
      type: object
      properties:
        metric:
          type: string
        op:
          type: string
    TraceCost:
      type: object
      properties:
        input:
          type: number
          format: double
        output:
          type: number
          format: double
        cache_read:
          type: number
          format: double
        cache_write:
          type: number
          format: double
        reasoning:
          type: number
          format: double
        web_search:
          type: number
          format: double
        total:
          type: number
          format: double
        currency:
          type: string
        cached:
          type: number
          format: double
        audio_input:
          type: number
          format: double
        audio_output:
          type: number
          format: double
        accepted_prediction:
          type: number
          format: double
        rejected_prediction:
          type: number
          format: double
        billable:
          type: boolean
        pricing_tier:
          type: string
        threshold_exceeded:
          type: boolean
        integration_id:
          type: string
    SearchTracesResponse:
      type: object
      properties:
        object:
          enum:
          - list
          type: string
          description: Object discriminator; always `list`.
        data:
          type: array
          items:
            $ref: '#/components/schemas/TraceSummary'
        has_more:
          type: boolean
        next_page_token:
          type: string
        meta:
          $ref: '#/components/schemas/TraceSearchMeta'
    SpanSummary:
      type: object
      properties:
        object:
          type: string
        trace_id:
          type: string
        span_id:
          type: string
        parent_span_id:
          type: string
        name:
          type: string
        type:
          type: string
        operation:
          type: string
        status:
          type: string
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        duration_ms:
          type: number
          format: double
        provider:
          type: string
        model:
          type: string
        usage:
          $ref: '#/components/schemas/TraceUsage'
        cost:
          $ref: '#/components/schemas/TraceCost'
        has_detail:
          type: boolean
        level:
          type: integer
          format: int32
        has_children:
          type: boolean
        trace_framework:
          type: string
          description: "Row badge inputs, so the tree does not need a detail fetch per span:\n trace_framework is set on the trace root, leading_span_type where the\n ingest marked one, guardrail_enabled on evaluator spans run as guardrails."
        leading_span_type:
          type: string
        guardrail_enabled:
          type: boolean
    ListTraceSpansResponse:
      type: object
      properties:
        object:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/SpanSummary'
        has_more:
          type: boolean
        next_page_token:
          type: string
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        code:
          type: integer
          description: gRPC status code, when the service reports one.
        details:
          type: array
          items: {}
          description: Additional error details, when the service reports any.
      required:
      - message
    TraceSummary:
      type: object
      properties:
        object:
          enum:
          - trace
          type: string
          description: Object discriminator; always `trace`.
        trace_id:
          type: string
        root_span_id:
          type: string
        leading_span_id:
          type: string
        name:
          type: string
        operation:
          type: string
        status:
          type: string
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        duration_ms:
          type: number
          format: double
        project_id:
          type: string
        identity_id:
          type: string
        session_id:
          type: string
        thread_id:
          type: string
        product:
          type: string
        providers:
          type: array
          items:
            type: string
        models:
          type: array
          items:
            type: string
        agent:
          $ref: '#/components/schemas/TraceAgent'
        usage:
          $ref: '#/components/schemas/TraceUsage'
        cost:
          $ref: '#/components/schemas/TraceCost'
        id:
          type: string
        span_id:
          type: string
        parent_id:
          type: string
        type:
          type: string
        context:
          $ref: '#/components/schemas/TraceContext'
        attributes:
          type: object
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        duration:
          type: number
          format: double
    GetTraceSpanResponse:
      type: object
      properties:
        span:
          $ref: '#/components/schemas/SpanDetail'
    AggregateTracesRequest:
      type: object
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        filters:
          type: array
          items:
            $ref: '#/components/schemas/TraceFilter'
        group_by:
          type: array
          items:
            type: string
        compute:
          type: array
          items:
            $ref: '#/components/schemas/TraceCompute'
        limit:
          type: integer
          format: int32
        filter_operator:
          type: string
    ListTraceFacetsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TraceFacet'
    TraceUsage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          format: uint32
        completion_tokens:
          type: integer
          format: uint32
        total_tokens:
          type: integer
          format: uint32
        prompt_cached_tokens:
          type: integer
          format: uint32
        prompt_audio_tokens:
          type: integer
          format: uint32
        completion_reasoning_tokens:
          type: integer
          format: uint32
        completion_audio_tokens:
          type: integer
          format: uint32
        completion_accepted_prediction_tokens:
          type: integer
          format: uint32
        completion_rejected_prediction_tokens:
          type: integer
          format: uint32
        prompt_cache_creation_tokens:
          type: integer
          format: uint32
    TraceSearchMeta:
      type: object
      properties:
        request_id:
          type: string
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        row_count:
          type: integer
          format: int32
    TraceAgent:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    GetTraceResponse:
      type: object
      properties:
        trace:
          $ref: '#/components/schemas/TraceSummary'
    TraceFilter:
      type: object
      properties:
        field:
          type: string
        op:
          type: string
        values:
          type: array
          items:
            type: string
    TraceSort:
      type: object
      properties:
        field:
          type: string
        order:
          type: string
    QueryTracesResponse:
      type: object
      properties:
        object:
          type: string
        search:
          $ref: '#/components/schemas/SearchTracesResponse'
    GetTraceConversationResponse:
      type: object
      properties:
        trace_id:
          type: string
        span_id:
          type: string
          description: Span the items were read from; empty when the trace holds no model call. Read its detail with GetTraceSpan.
        items:
          type: array
          items:
            type: object
          description: Ordered OpenResponses items, including recorded instructions as a leading system message.
    TraceField:
      type: object
      properties:
        name:
          type: string
        label:
          type: string
        type:
          type: string
        scope:
          type: string
        match:
          type: string
        operators:
          type: array
          items:
            type: string
        facet:
          type: boolean
        sortable:
          type: boolean
        groupable:
          type: boolean
        aliases:
          type: array
          items:
            type: string
        enum_values:
          type: array
          items:
            type: string
    SearchTracesRequest:
      required:
      - from
      - to
      type: object
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        filters:
          type: array
          items:
            $ref: '#/components/schemas/TraceFilter'
        filter_operator:
          type: string
        query:
          type: string
        sort:
          type: array
          items:
            $ref: '#/components/schemas/TraceSort'
        limit:
          type: integer
          format: int32
        page_token:
          type: string
    TraceContext:
      type: object
      properties:
        trace_id:
          type: string
        span_id:
          type: string
    SpanDetail:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/SpanSummary'
        attributes:
          type: object
    AggregateTracesResponse:
      type: object
      properties:
        object:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/TraceAggregateRow'
    TraceFacet:
      type: object
      properties:
        field:
          type: string
        label:
          type: string
        type:
          type: string
    ListTraceFieldsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TraceField'
    TraceFacetValue:
      type: object
      properties:
        value:
          type: string
        count:
          type: integer
          format: uint32
    QueryTracesRequest:
      required:
      - from
      - to
      - oql
      type: object
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        oql:
          type: string
        limit:
          type: integer
          format: int32
        page_token:
          type: string
    TraceAggregateRow:
      type: object
      properties:
        group:
          type: object
          additionalProperties:
            type: string
        metrics:
          type: object
          additionalProperties:
            type: number
            format: double
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  url: https://docs.orq.ai
  description: orq.ai Documentation
x-speakeasy-timeout: 600000