UPuptrace
Querying

List groups

Aggregate spans into groups using UQL queries. Use this to get aggregated metrics like request count, error rate, or latency percentiles. Aggregate functions: count(), avg(), sum(), min(), max(), p50(), p75(), p90(), p99(), uniq(), apdex(). Supports GROUP BY (e.g. group by service_name), HAVING (e.g. having p50(_dur_ms) > 100ms), WHERE filters, full-text search, system filtering (e.g. httpserver:all, db:postgresql), and duration filtering. Example query: 'perMin(count()) | group by host_name'. Returns grouped rows with dynamic columns based on the query. Use list_spans instead when you need individual span details. Use timeseries instead when you need time-bucketed data for charts. Documentation: https://uptrace.dev/features/querying/spans

get/internal/v1/spans/{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 aggregation query (e.g., perMin(count()) | group by host_name).

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.

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

Aggregated span groups.

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.