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

# Aggregate function logs

> Count GenAI function log lines and the conversations they belong to, bucketed by hour or day.

Counts the log lines your GenAI functions wrote, grouped by event, function, conversation, level, environment, project, error type or turn, and optionally bucketed by hour or day. Takes the same filters as [search](https://docs.poly.ai/api-reference/traces/endpoint/search-logs.md). Use it to see which events fire most, which functions raise, and when.

## Request

### Headers

**X-API-KEY** `string` *required*

Account API key with read access to conversations.

### Body

**from** `datetime` *required*

Inclusive window start, ISO 8601.

**to** `datetime` *required*

Exclusive window end. The window may span at most 30 days.

**aggs** `string[]` *required*

Aggregations to compute, one column each: `count` (log lines), `conversation_count`, `first_seen`, `last_seen` (earliest and latest timestamp).

**group\_by** `string[]`

Dimensions to group by, one column each: `event`, `function_name`, `conversation_id`, `level`, `client_env`, `project_id`, `error_type`, `turn_index`.

**interval** `string`

`hourly` or `daily`. Adds a leading `bucket` column. Omit for one unbucketed result per group.

**timezone** `string`

IANA timezone (for example `Europe/London`) applied to the buckets. Defaults to UTC.

**project\_id** `string`

Restrict to one agent. Omit to aggregate the whole account.

**conversation\_id** `string`

Matches the conversation ID or the call SID.

**function\_names** `string[]`

Function (tool) names, up to 20.

**levels** `string[]`

`debug`, `info`, `warning`, `error`, `critical`.

**client\_envs** `string[]`

Environments: `test`, `sandbox`, `pre-release`, `live`, `scenarios`.

**error\_types** `string[]`

Exception classes on failure lines, for example `KeyError`, up to 20.

**text** `object`

Whole-word, case-insensitive terms matched on the event label: `{ "all": [...], "any": [...], "none": [...] }`, up to 10 terms each.

**trace\_id** `string`

Trace ID of the function-execution span.

**span\_id** `string`

Span ID of the function-execution span.

**turn\_index** `integer`

0-based turn the function call belongs to. Must be an integer.

**sort** `object`

`{ "field": "<a group_by or aggs value>", "order": "asc" | "desc" }`. Applied after the ascending bucket sort.

**limit** `integer` (default: 20)

Rows per page, 1–100.

**offset** `integer` (default: 0)

Rows to skip, 0–1000.

## Response

**columns** `string[]`

Column names in row order: `bucket` (when `interval` is set), then each `group_by` dimension, then each aggregation.

**rows** `array[]`

One array per bucket and group, values in `columns` order.

**limit** `integer`

**offset** `integer`

**has\_more** `boolean`

## Examples

### Which functions log errors, and why

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.us.poly.ai/api/v1/traces/logs/aggregate \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT-V258TF29",
    "from": "2026-10-26T00:00:00Z",
    "to": "2026-10-28T00:00:00Z",
    "levels": ["error"],
    "aggs": ["count", "conversation_count"],
    "group_by": ["function_name", "error_type"],
    "sort": {"field": "count", "order": "desc"}
  }'
```

```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "columns": ["function_name", "error_type", "count", "conversation_count"],
  "rows": [
    ["send_sms", "", 19, 18]
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}
```

An empty `error_type` means the function logged the error itself and carried on; a class name means it raised.

### Log volume per day

```json Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "project_id": "PROJECT-V258TF29",
  "from": "2026-10-26T00:00:00Z",
  "to": "2026-10-28T00:00:00Z",
  "aggs": ["count"],
  "interval": "daily"
}
```

```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "columns": ["bucket", "count"],
  "rows": [
    ["2026-10-26T00:00:00+00:00", 3326],
    ["2026-10-27T00:00:00+00:00", 88]
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}
```

### Most frequent events in one conversation

```json Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "project_id": "PROJECT-V258TF29",
  "conversation_id": "CA3f2c1e9d6b7a4f8e9c0d1b2a3c4d5e6f",
  "from": "2026-10-26T00:00:00Z",
  "to": "2026-10-27T00:00:00Z",
  "aggs": ["count", "first_seen", "last_seen"],
  "group_by": ["turn_index", "event"]
}
```

## Errors

| Status | Meaning |
| - | - |
| `400` | `sort.field` is not one of the output columns. |
| `401` | Missing or invalid API key. |
| `403` | The key cannot read conversations. |
| `422` | `from` is not before `to`, the window exceeds 30 days, or a value is outside its enum or range. |
| `502` | The log backend did not answer. |