---
title: "List trace spans"
method: GET
path: "/v3/traces/{trace_id}/spans"
tags: ["Traces"]
---

# List trace spans

`GET /v3/traces/{trace_id}/spans`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v3/traces/{trace_id}/spans`
- Auth: HTTP bearer

List canonical span summaries for a trace.

## Path parameters

- `trace_id` string, required

## Query parameters

- `limit` integer
- `page_token` string

## Response `200`

OK

- ListTraceSpansResponse
  - `object` string
  - `data` SpanSummary[]
    - `object` string
    - `trace_id` string
    - `span_id` string
    - `parent_span_id` string
    - `name` string
    - `type` string
    - `operation` string
    - `status` string
    - `started_at` string, date-time
    - `ended_at` string, date-time
    - `duration_ms` number, double
    - `provider` string
    - `model` 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
    - `has_detail` boolean
    - `level` integer
    - `has_children` boolean
    - `trace_framework` string: Framework that produced the trace, recorded on the root span.
    - `leading_span_type` string: Span type assigned at ingest when the trace has one.
    - `guardrail_enabled` boolean: Whether the span is an evaluator span running as a guardrail.
    - `finish_reasons` string[]: Why the span's generation stopped, for example stop, length or content_filter.
    - `rule_attributes` object
  - `has_more` boolean
  - `next_page_token` string

## 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-29** `928a71e92252`: 1 info
  - added the optional property `data/items/rule_attributes` to the response with the `200` status
- **2026-10-29** `33d63277cd4e`: 1 warning
  - removed the optional property `data/items/rule_attributes` from the response with the `200` status
- **2026-10-29** `ccec1a4526ee`: 1 info
  - added the optional property `data/items/rule_attributes` to the response with the `200` status
- **2026-10-28** `58f2f0cd5c1e`: 1 warning
  - removed the optional property `data/items/rule_attributes` from the response with the `200` status
- **2026-10-27** `9ebbd48998b8`: 1 info
  - added the optional property `data/items/rule_attributes` to the response with the `200` status

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v3/traces/:trace_id/spans/get.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)