---
title: "List traces"
method: GET
path: "/internal/v1/traces/{project_id}"
tags: ["Querying"]
---

# List traces

`GET /internal/v1/traces/{project_id}`

List individual traces using correlated sub-queries. Use this to find specific traces matching complex multi-span criteria. Requires parallel arrays: query[], alias[], system[] with matching lengths. One alias must be 'root' to identify the root span query. Additional sub-queries filter traces where child spans match specific criteria. Systems: spans:all, httpserver:all, db:postgresql, log:error, etc. Returns root spans for matching traces sorted by time (DESC by default). Use list_trace_groups instead when you need aggregated trace metrics. Use list_spans instead when you don't need cross-span trace correlation. Documentation: https://uptrace.dev/features/querying/spans

## Path parameters

- `project_id` integer, required

## Query parameters

- `time_start` string, date-time, required — RFC3339 timestamp.
- `time_end` string, date-time, required — RFC3339 timestamp.
- `query` string[]
- `alias` string[]
- `system` string[]
- `sort_by` string[]
- `sort_dir` SortDirection[]
- `limit` integer

## Response `200`

List of matching traces.

- object
  - `spans` Span[], required — Root spans for matching traces.
    - `id` string, required — Span ID (hex-encoded).
    - `parentId` string — Parent span ID (hex-encoded, empty for root spans).
    - `traceId` string, required — Trace ID (hex-encoded).
    - `standalone` boolean — Whether the span is standalone (not part of a trace).
    - `projectId` integer — Project ID.
    - `groupId` string — Group ID (uint64 as string).
    - `type` string — Telemetry type (spans, events, logs, funcs).
    - `system` string — Detected system (e.g., httpserver:all, db:postgresql, log:error).
    - `kind` string — Span kind (client, server, producer, consumer, internal).
    - `name` string, required — Span name.
    - `eventName` string — Event name (for event spans).
    - `displayName` string — Human-readable operation summary.
    - `time` number, double, required — Span start time as unix milliseconds.
    - `duration` number, double, required — Duration in milliseconds.
    - `statusCode` string, required — Status code (ok, error, unset).
    - `statusMessage` string — Optional status message.
    - `attrs` object — Span attributes as key-value map. Keys include type suffix (e.g., service_name::str, count::int).
    - `events` object[] — Child event spans.
    - `logs` object[] — Child log spans.
    - `links` object[] — Span links to other spans.
      - `traceId` string
      - `spanId` string
      - `attrs` object
  - `count` integer, required — Total count of matching traces.
  - `query` object[] — Parsed query parts with error state.
  - `join` array[] — Parsed sub-query clauses for each non-root joined alias. One entry per non-root sub-query passed in query[]/alias[]/system[].
    - object[]
  - `sorting` OrderItem[] — Applied sorting configuration.
    - `key` string
    - `order` 'asc' | 'desc'
  - `search` object[] — Applied search matchers.
  - `whereAttrs` object — Map of WHERE attribute names to their matched values.

## Other responses

- `400` — Invalid request
- `401` — Authentication required
- `403` — Insufficient permissions
- `500` — Internal server error

---

[API](https://skmtc.net/uptrace/apis/uptrace-json-api.md) · [All operations](https://skmtc.net/uptrace/apis/uptrace-json-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/uptrace/uptrace-json-api/versions/550c8881ab9a/schema)