---
title: "Query traces with OQL"
method: POST
path: "/v3/traces/query"
tags: ["Traces"]
---

# Query traces with OQL

`POST /v3/traces/query`

Run an OQL trace query. OQL is validated against the trace field registry and compiled through the trace planner.

## Request body

- QueryTracesRequest
  - `from` string, date-time, required
  - `to` string, date-time, required
  - `oql` string, required
  - `limit` integer
  - `page_token` string

## Response `200`

OK

- QueryTracesResponse
  - `object` string
  - `search` SearchTracesResponse
    - `object` 'list' — Object discriminator; always `list`.
    - `data` TraceSummary[]
      - `object` 'trace' — Object discriminator; always `trace`.
      - `trace_id` string
      - `root_span_id` string
      - `leading_span_id` string
      - `name` string
      - `operation` string
      - `status` string
      - `started_at` string, date-time
      - `ended_at` string, date-time
      - `duration_ms` number, double
      - `project_id` string
      - `identity_id` string
      - `session_id` string
      - `thread_id` string
      - `product` string
      - `providers` string[]
      - `models` string[]
      - `agent` TraceAgent
        - `id` string
        - `name` string
      - `usage` TraceUsage
        - `prompt_tokens` integer
        - `completion_tokens` integer
        - `total_tokens` integer
        - `prompt_cached_tokens` integer
        - `prompt_audio_tokens` integer
        - `completion_reasoning_tokens` integer
        - `completion_audio_tokens` integer
        - `completion_accepted_prediction_tokens` integer
        - `completion_rejected_prediction_tokens` integer
      - `cost` TraceCost
        - `input` number, double
        - `output` number, double
        - `cache_read` number, double
        - `cache_write` number, double
        - `reasoning` number, double
        - `web_search` number, double
        - `total` number, double
        - `currency` string
        - `cached` number, double
        - `audio_input` number, double
        - `audio_output` number, double
        - `accepted_prediction` number, double
        - `rejected_prediction` number, double
        - `billable` boolean
        - `pricing_tier` string
        - `threshold_exceeded` boolean
        - `integration_id` string
      - `id` string
      - `span_id` string
      - `parent_id` string
      - `type` string
      - `context` TraceContext
        - `trace_id` string
        - `span_id` string
      - `attributes` object
      - `start_time` string, date-time
      - `end_time` string, date-time
      - `duration` number, double
    - `has_more` boolean
    - `next_page_token` string
    - `meta` TraceSearchMeta
      - `request_id` string
      - `from` string, date-time
      - `to` string, date-time
      - `row_count` integer

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/versions/6a22c53a2580/schema)