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

# List spans

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

List individual spans using UQL (Uptrace Query Language). Use this to inspect specific span details, search for errors, or browse recent operations. Supports WHERE filters (e.g. where service_name = 'myservice', where _status_code = 'error', where _dur_ms > 100ms), full-text search (e.g. word1|word2 -excluded), system filtering (e.g. httpserver:all, db:postgresql, log:error), duration filtering in milliseconds, and sorting by any span field. Span fields use underscore prefix: _name, _dur_ms, _status_code, _time, _trace_id, _kind. Attributes use dot-to-underscore: service.name becomes service_name. Returns individual span objects with attrs, timing, and status. Use list_span_groups instead when you need aggregated metrics (count, avg, p99). Use list_traces instead when you need to find traces matching multi-span criteria. 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
- `where` string
- `search` string
- `search_attrs` string[]
- `system` string[]
- `sort_by` string[]
- `sort_dir` SortDirection[]
- `duration_gte` integer
- `duration_lt` integer
- `limit` integer

## Response `200`

List of matching 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
  - `count` integer, required — Total count of matching spans.
  - `query` object[] — Parsed query parts with error state.
  - `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/revisions/550c8881ab9a/schema)