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

# Search traces

`POST /v3/traces/search`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v3/traces/search`
- Auth: HTTP bearer

Search trace summaries using the structured trace filter contract. See the [filter grammar](/ai-studio/observability/traces#filter-grammar) for the field and operator reference.

## 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
      - `prompt_cache_creation_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

## Other responses

- `401`: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.

## Changes

> 554 revisions in range; 71 not diffed.

- **2026-10-23** `0b4e519a544f`: 1 info
  - added the non-success response with the status `401`
- **2026-10-23** `732aed62833a`: 1 info
  - removed the non-success response with the status `401`
- **2026-10-22** `4f826b2c3a0e`: 1 info
  - added the non-success response with the status `401`
- **2026-10-22** `8f0dc569f247`: 1 info
  - removed the non-success response with the status `401`
- **2026-10-21** `08b800d640e6`: 1 info
  - added the non-success response with the status `401`

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v3/traces/search/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)