---
title: "List spans"
method: GET
path: "/api/v1/tracing/{project_id}/spans"
tags: ["Querying"]
---

# List spans

`GET /api/v1/tracing/{project_id}/spans`

List spans (public API). Stable API for listing spans by trace_id, span_id, or parent_id. Best for retrieving known spans when you already have an ID. For advanced filtering with UQL queries (WHERE, search, system filtering), use list_spans instead. 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.
- `trace_id` string
- `id` integer
- `parent_id` integer
- `limit` integer

## Response `200`

List of spans.

- object
  - `spans` Span[], required — Array of span objects.
    - `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
  - `hasMore` boolean — Whether more results exist beyond the limit.

## 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/revisions/550c8881ab9a/schema)