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

# List groups

`GET /internal/v1/spans/{project_id}/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

## 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`

Aggregated span groups.

- GroupsResult — Result of a span group aggregation query.
  - `groups` object[], required — Array of group rows with dynamic columns. Each row may contain __hash, __name, __query metadata fields.
  - `columns` QueryColumn[] — Column definitions describing the result schema.
    - `name` string, required — Column name.
    - `expr` string — Column expression as written in the query.
    - `unit` string — Column unit (e.g., ms, bytes).
    - `isNum` boolean — Whether the column contains numeric values.
    - `isAgg` boolean — Whether the column is an aggregation.
    - `isGroup` boolean — Whether the column is a GROUP BY key.
    - `aggFunc` string — Aggregation function applied to this column.
  - `hasMore` boolean — Whether more results exist beyond the limit.
  - `query` object[] — Parsed query parts with error state.
  - `join` array[] — Parsed sub-query clauses for each joined alias. Populated only by list_trace_groups (one entry per non-root sub-query); empty for span groups.
    - object[]
  - `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/versions/550c8881ab9a/schema)