---
title: "Search traces"
method: POST
path: "/v3/traces/search"
tags: ["Traces"]
---

# Search traces

`POST /v3/traces/search`

Search trace summaries using the structured trace filter contract.

## Request body

- SearchTracesRequest
  - `from` string, date-time, required
  - `to` string, date-time, required
  - `filters` TraceFilter[]
    - `field` string
    - `op` string
    - `values` string[]
  - `filter_operator` string
  - `query` string
  - `sort` TraceSort[]
    - `field` string
    - `order` string
  - `limit` integer
  - `page_token` string

## Response `200`

OK

- 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/1072e5ba28ab/schema)