v1

latestOpenAPI 3.1.0MIT2026-07-1393128198.4 KB
Querying

List spans

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

get/internal/v1/spans/{project_id}

Path parameters

project_idinteger required

Uptrace project ID.

Query parameters

time_startstring date-time required

RFC3339 timestamp.

Start time (inclusive) as RFC3339 timestamp.

time_endstring date-time required

RFC3339 timestamp.

End time (exclusive) as RFC3339 timestamp.

querystring

UQL query to filter spans (e.g., where service_name = 'myservice').

wherestring

Additional WHERE clause appended to the query.

searchstring

Full-text search for spans containing the given text.

search_attrsstring[]

Attribute names to search within when using search. Can be repeated for multiple attributes.

systemstring[]

Filter by system (e.g., log:error, db:postgresql). Can be repeated for multiple systems.

sort_bystring[]

Column names to sort by. Can be repeated for multi-column sort. Defaults to time.

sort_dirSortDirection[]

Sort direction for each sort_by column. Must match sort_by count. Defaults to DESC.

duration_gteinteger

Duration greater than or equal to N (milliseconds).

duration_ltinteger

Duration less than N (milliseconds).

limitinteger

Limit number of results.

Response

List of matching spans.

countinteger required

Total count of matching spans.

queryobject[]

Parsed query parts with error state.

searchobject[]

Applied search matchers.

whereAttrsobject

Map of WHERE attribute names to their matched values.