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

# List span groups with filters

`POST /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 using the same query parameters as GET and optional standard Respan filters in the request body.

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

## Request body

- object
  - `filters` object: Narrows what's grouped. Each key is a field to filter on, and each value is a condition: `{"<field>": {"operator": "<operator>", "value": [...]}}`. Each span, trace or thread must match every condition. To set two conditions on one field, such as a range, pass a list of conditions. **Operators:** `""` (equals, the default), `not`, `in`, `not_in`, `lt`, `lte`, `gt`, `gte`, `contains`, `not_contains`, `icontains` (ignores case), `startswith`, `not_startswith`, `endswith`, `not_endswith`, `empty`, `not_empty`. Put values in a list: `""` and `in` match any of the listed values, and `not` and `not_in` match none of them. Other operators take one value; for `empty` and `not_empty`, send `[""]`. **Fields** depend on `group_by`: - `trace`: trace fields such as `total_cost`, `error_count`, `span_count`, `customer_identifier` and `metadata__<key>`, plus span fields such as `model`, which match a trace when any of its spans matches. - `thread`: thread fields such as `thread_identifier`, `customer_identifier`, `number_of_requests`, `total_cost` and `total_tokens`. - Any other value: span columns, such as `model`, `provider_id`, `deployment_name`, `customer_identifier`, `custom_identifier`, `organization_key_id`, `prompt_id`, `log_type`, `status_code`, `cost`, `latency`, `prompt_tokens`, `completion_tokens` and `total_request_tokens`, plus `metadata__<key>` (values are strings). Aliases such as `total_tokens` don't work. **Example:** ```json { "status_code": {"operator": "not", "value": [200]}, "metadata__plan": {"operator": "", "value": ["pro"]} } ```

## 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-filter` removed and replaced with `spans_request_logs_groups_filter`

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

---

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