---
title: "List span groups"
method: GET
path: "/api/request-logs/groups/"
tags: ["Spans"]
---

# List span groups

`GET /api/request-logs/groups/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/request-logs/groups/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Group spans by a supported dimension and return one aggregate row per group. `trace` and `thread` roll spans up through their dedicated entity views.

## Query parameters

- `group_by` 'model' | 'provider_id' | 'organization_key_id' | 'prompt_id' | 'deployment_id' | 'deployment_name' | 'custom_identifier' | 'customer_identifier' | 'trace' | 'thread'
- `sort_by` string
- `start_time` string, date-time
- `end_time` string, date-time
- `environment` string
- `page` integer
- `page_size` integer

## Response `200`

Paginated groups and aggregate metrics.

- object
  - `count` integer, required: Number of results on this page, not the total. Request pages until `next` is null to get every result.
  - `next` string, nullable
  - `previous` string, nullable
  - `current_filters` object
  - `filters_data` object
  - `results` object[], required
    - `date_group` string, date-time
    - `model` string
    - `provider_id` string
    - `organization_key_id` string
    - `prompt_id` string
    - `deployment_id` string
    - `deployment_name` string
    - `custom_identifier` string
    - `customer_identifier` string
    - `trace_unique_id` string
    - `thread_identifier` string
    - `number_of_requests` integer, nullable
    - `span_count` integer, nullable
    - `total_cost` number, nullable
    - `total_tokens` integer, nullable
    - `error_count` integer, nullable
    - `error_percentage` number, nullable
    - `average_cost` number, nullable
    - `average_tokens` integer, nullable
    - `average_latency` number, nullable
    - `average_ttft` number, nullable
    - `average_tps` number, nullable
    - `cache_hit_percentage` number, nullable

## Other responses

- `400`: Unsupported group_by value. Invalid sort_by falls back to number_of_requests.
- `403`: The API key is missing, invalid or expired, or it doesn't grant analytics read access.

## Changes

- **2026-10-21** `c30bcb383ee8`: 21 breaking, 4 info
  - the response property `next` became nullable for the status `200`
  - the response property `previous` became nullable for the status `200`
  - the response property `results/items/average_cost` became nullable for the status `200`
  - the response property `results/items/average_latency` became nullable for the status `200`
  - …21 more
- **2026-10-02** `b830b79cfd52`: 1 warning, 2 info
  - removed the optional property `total_count` from the response with the `200` status
  - removed the non-success response with the status `401`
  - the response property `detail` became required for the status `403`
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `request-logs-groups-list` removed and replaced with `spans_request_logs_groups_list`
- **2026-08-22** `b18c72975097`: 3 warning
  - for the `query` request parameter `page_size`, the max was set to `1000.00`
  - for the `query` request parameter `page`, the min was set to `1.00`
  - for the `query` request parameter `page_size`, the min was set to `1.00`

[Operation history](https://skmtc.dev/keywordsai/apis/respan-api/changes/api/request-logs/groups/get.md)

---

[API](https://skmtc.dev/keywordsai/apis/respan-api.md) - [All operations](https://skmtc.dev/keywordsai/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keywordsai/apis/respan-api/revisions/900841387635?raw)