UPuptrace
Querying

List trace groups

Aggregate traces into groups using correlated sub-queries. Use this to find trace patterns and get aggregated trace metrics. 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 grouped rows with dynamic columns. Use list_traces instead when you need individual trace details. Use list_span_groups instead when you don't need cross-span trace correlation. Documentation: https://uptrace.dev/features/querying/spans

get/internal/v1/traces/{project_id}/groups

Request

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 for each sub-query. Must have the same count as alias and system. Can be repeated.

aliasstring[]

Alias for each sub-query. One alias must be 'root'. Can be repeated.

systemstring[]

System for each sub-query (e.g., spans:all, log:error). Can be repeated.

sort_bystring[]

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

sort_dirSortDirection[]

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

limitinteger

Limit number of results.

Response

Trace groups result.

groupsobject[] required

Array of group rows with dynamic columns. Each row may contain __hash, __name, __query metadata fields.

hasMoreboolean

Whether more results exist beyond the limit.

queryobject[]

Parsed query parts with error state.

searchobject[]

Applied search matchers.

whereAttrsobject

Map of WHERE attribute names to their matched values.

Changes

No recorded changes to this operation across all 1 revision of this API.