> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Aggregate

> Run counts, groups, facets, and metrics over one aggregatable index.

## Endpoints

```http theme={null}
POST /video/{video_id}/aggregate/
POST /collection/{collection_id}/aggregate/
```

Use `aggregate()` for counts, groups, facets, and metrics.

## Request body

| Field        |               Type |    Required | Description                                                      |
| ------------ | -----------------: | ----------: | ---------------------------------------------------------------- |
| `index_name` |             string | conditional | Index name to aggregate. Required unless `index_id` is provided. |
| `index_id`   |             string | conditional | Index ID to aggregate. Required unless `index_name` is provided. |
| `group_by`   |             string |         yes | Aggregatable field to group by.                                  |
| `metric`     |             string |          no | Aggregation metric. Defaults to `count`.                         |
| `filter`     |        list/object |          no | Filter applied before aggregation.                               |
| `limit`      |            integer |          no | Maximum returned groups.                                         |
| `sort`       | list/string/object |          no | Sort aggregate rows when supported.                              |

`aggregate()` does not accept `return_fields` and does not return `Shot` objects.

## Example

```python theme={null}
response = collection.aggregate(
    index_name="objects",
    group_by="label",
    metric="count",
    limit=100,
)

counts = response["results"]
```

## Example with filters

```python theme={null}
response = collection.aggregate(
    index_name="objects",
    filter=[{"field": "max_score", "op": ">=", "value": 0.8}],
    group_by="label",
    metric="count",
    limit=100,
)

counts = response["results"]
```

## Response

`aggregate()` returns an envelope containing the aggregate rows and any migration warnings:

```json theme={null}
{
  "results": [
    {"label": "person", "count": 18},
    {"label": "car", "count": 7}
  ],
  "warnings": []
}
```

Use `response["results"]` for the aggregate rows. When the server includes warnings, the SDK also emits them as Python `UserWarning` messages.