Orq.ai Telemetry API

openapi: 3.2.0
info:
  title: orq.ai Telemetry API
  version: '2.0'
  description: orq.ai API documentation
servers:
- url: https://my.orq.ai
security:
- ApiKey: []
tags:
- name: Telemetry
  description: Unified query envelope for traces, metrics, and logs. One request shape, one filter dialect, and one response shape per source, validated by a per-source registry.
paths:
  /v3/telemetry/capabilities:
    get:
      tags:
      - Telemetry
      summary: List telemetry capabilities
      description: Lists the caller-scoped metrics, operations, units, query modes, result kinds, dimensions, and filter operators supported by the unified telemetry query service.
      operationId: TelemetryListCapabilities
      parameters:
      - name: source
        in: query
        schema:
          $ref: '#/components/schemas/TelemetrySource'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTelemetryCapabilitiesResponse'
        '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: telemetry
      x-speakeasy-name-override: listCapabilities
  /v3/telemetry/facet-values:
    post:
      tags:
      - Telemetry
      summary: List telemetry facet values
      description: Lists caller-scoped values for one source, metric, and field while applying sibling structured filters. Reporting metrics use metric-aware rollups; raw trace metrics preserve trace facet semantics.
      operationId: TelemetryListFacetValues
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListTelemetryFacetValuesRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTelemetryFacetValuesResponse'
        '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: telemetry
      x-speakeasy-name-override: listFacetValues
  /v3/telemetry/query:
    post:
      tags:
      - Telemetry
      summary: Query telemetry
      description: Canonical neutral query envelope for traces, metrics, and logs. Select a source, compute list, and time range; optionally group, filter, bucket, sort, limit, and include totals.
      operationId: TelemetryQuery
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryTelemetryRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryTelemetryResponse'
        '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: telemetry
      x-speakeasy-name-override: query
components:
  schemas:
    TelemetryMetricCapability:
      type: object
      properties:
        name:
          type: string
        label:
          type: string
        description:
          type: string
        unit:
          type: string
        operations:
          type: array
          items:
            type: string
        default_operation:
          type: string
        modes:
          type: array
          items:
            $ref: '#/components/schemas/TelemetryQueryMode'
        result_kinds:
          type: array
          items:
            $ref: '#/components/schemas/TelemetryResultKind'
        value_cardinality:
          $ref: '#/components/schemas/TelemetryValueCardinality'
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/TelemetryDimensionCapability'
        dimension_sets:
          type: array
          items:
            $ref: '#/components/schemas/TelemetryDimensionSetCapability'
    TraceCompute:
      type: object
      properties:
        metric:
          type: string
        op:
          type: string
    TelemetryQueryMode:
      type: string
      enum:
      - TELEMETRY_QUERY_MODE_SCALAR
      - TELEMETRY_QUERY_MODE_TIME_SERIES
    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
    TelemetryRow:
      type: object
      properties:
        timestamp:
          type: string
          description: "Unset when the resolved grain is \"none\" — one row per group, not a\n time series."
          format: date-time
        group:
          type: object
          additionalProperties:
            type: string
        metrics:
          type: object
          additionalProperties:
            type: number
            format: double
    TelemetryValueCardinality:
      type: string
      enum:
      - TELEMETRY_VALUE_CARDINALITY_SINGLE
      - TELEMETRY_VALUE_CARDINALITY_MULTIPLE
    QueryTelemetryRequest:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/TelemetrySource'
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        compute:
          type: array
          items:
            $ref: '#/components/schemas/TraceCompute'
        grain:
          type: string
          description: "Empty string and \"none\" are equivalent: a single row per group instead\n of a time series."
        group_by:
          type: array
          items:
            type: string
        filters:
          type: array
          items:
            $ref: '#/components/schemas/TraceFilter'
        filter_operator:
          type: string
        limit:
          type: integer
          description: 'Scalar queries: maximum returned rows, default 100. Time-series queries: optional maximum number of distinct groups; exceeding it fails the query instead of truncating timelines. Time-series results are complete within safety budgets of 5000 rows, 5000 buckets, and 50000 metric values. Queries are limited to 90 days and 30 seconds of execution.'
          format: int32
        time_zone:
          type: string
        include_totals:
          type: boolean
        mode:
          enum:
          - timeseries
          - scalar
          type: string
          description: Value shaping. `timeseries` buckets by grain; `scalar` returns one row per group. When omitted, grain selects the compatible shape.
        sort:
          enum:
          - desc
          - asc
          type: string
          description: Ordering for scalar/top-list rows. Defaults to `desc`.
        interval_seconds:
          type: integer
          description: Explicit bucket width in seconds. Takes precedence over `grain` when both are set.
          format: int32
        selected_range_seconds:
          type: integer
          description: The span originally selected, before live extended [from, to). `grain:"auto"` resolves bucket width from this span, independent of how far [from, to) has since grown.
          format: int32
    TraceFilter:
      type: object
      properties:
        field:
          type: string
        op:
          type: string
        values:
          type: array
          items:
            type: string
    QueryTelemetryResponse:
      type: object
      properties:
        object:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/TelemetryRow'
        totals:
          $ref: '#/components/schemas/TelemetryRow'
        meta:
          $ref: '#/components/schemas/QueryTelemetryMeta'
        request:
          $ref: '#/components/schemas/QueryTelemetryRequest'
        has_more:
          type: boolean
    TelemetryDimensionCapability:
      type: object
      properties:
        name:
          type: string
        label:
          type: string
        type:
          type: string
        groupable:
          type: boolean
        filter_operators:
          type: array
          items:
            type: string
        key_prefix:
          type: string
    QueryTelemetryMeta:
      type: object
      properties:
        effective_grain:
          type: string
        warnings:
          type: array
          items:
            type: string
        row_count:
          type: integer
          format: int32
        request_id:
          type: string
        currency:
          type: string
    ListTelemetryFacetValuesResponse:
      type: object
      properties:
        field:
          type: string
        values:
          type: array
          items:
            $ref: '#/components/schemas/TraceFacetValue'
        has_more:
          type: boolean
    TelemetryDimensionSetCapability:
      type: object
      properties:
        name:
          type: string
        group_by:
          type: array
          items:
            type: string
        filters:
          type: array
          items:
            type: string
    TelemetrySourceCapability:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/TelemetrySource'
        label:
          type: string
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/TelemetryMetricCapability'
    TelemetryResultKind:
      type: string
      enum:
      - TELEMETRY_RESULT_KIND_SCALAR
      - TELEMETRY_RESULT_KIND_GROUPED_SCALAR
      - TELEMETRY_RESULT_KIND_TIME_SERIES
      - TELEMETRY_RESULT_KIND_GROUPED_TIME_SERIES
    ListTelemetryCapabilitiesResponse:
      type: object
      properties:
        sources:
          type: array
          items:
            $ref: '#/components/schemas/TelemetrySourceCapability'
    TelemetrySource:
      type: string
      enum:
      - TELEMETRY_SOURCE_TRACES
      - TELEMETRY_SOURCE_METRICS
      - TELEMETRY_SOURCE_LOGS
    TraceFacetValue:
      type: object
      properties:
        value:
          type: string
        count:
          type: integer
          format: uint32
    ListTelemetryFacetValuesRequest:
      type: object
      properties:
        source:
          $ref: '#/components/schemas/TelemetrySource'
        metric:
          type: string
        field:
          type: string
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        filters:
          type: array
          items:
            $ref: '#/components/schemas/TraceFilter'
        filter_operator:
          type: string
        limit:
          type: integer
          format: int32
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  url: https://docs.orq.ai
  description: orq.ai Documentation
x-speakeasy-timeout: 600000