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

# List trace groups

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

## 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[]
- `alias` string[]
- `system` string[]
- `sort_by` string[]
- `sort_dir` SortDirection[]
- `limit` integer

## Response `200`

Trace groups result.

- 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)