Aggregate function logs

POST

api

traces

logs

aggregate

Aggregate function logs

curl --request POST \
  --url https://api.example.com/api/v1/traces/logs/aggregate \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "from": {},
  "to": {},
  "aggs": [
    "<string>"
  ],
  "group_by": [
    "<string>"
  ],
  "interval": "<string>",
  "timezone": "<string>",
  "project_id": "<string>",
  "conversation_id": "<string>",
  "function_names": [
    "<string>"
  ],
  "levels": [
    "<string>"
  ],
  "client_envs": [
    "<string>"
  ],
  "error_types": [
    "<string>"
  ],
  "text": {},
  "trace_id": "<string>",
  "span_id": "<string>",
  "turn_index": 123,
  "sort": {},
  "limit": 123,
  "offset": 123
}
'

import requests

url = "https://api.example.com/api/v1/traces/logs/aggregate"

payload = {
    "from": {},
    "to": {},
    "aggs": ["<string>"],
    "group_by": ["<string>"],
    "interval": "<string>",
    "timezone": "<string>",
    "project_id": "<string>",
    "conversation_id": "<string>",
    "function_names": ["<string>"],
    "levels": ["<string>"],
    "client_envs": ["<string>"],
    "error_types": ["<string>"],
    "text": {},
    "trace_id": "<string>",
    "span_id": "<string>",
    "turn_index": 123,
    "sort": {},
    "limit": 123,
    "offset": 123
}
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: {},
    to: {},
    aggs: ['<string>'],
    group_by: ['<string>'],
    interval: '<string>',
    timezone: '<string>',
    project_id: '<string>',
    conversation_id: '<string>',
    function_names: ['<string>'],
    levels: ['<string>'],
    client_envs: ['<string>'],
    error_types: ['<string>'],
    text: {},
    trace_id: '<string>',
    span_id: '<string>',
    turn_index: 123,
    sort: {},
    limit: 123,
    offset: 123
  })
};

fetch('https://api.example.com/api/v1/traces/logs/aggregate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/traces/logs/aggregate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from' => [
        
    ],
    'to' => [
        
    ],
    'aggs' => [
        '<string>'
    ],
    'group_by' => [
        '<string>'
    ],
    'interval' => '<string>',
    'timezone' => '<string>',
    'project_id' => '<string>',
    'conversation_id' => '<string>',
    'function_names' => [
        '<string>'
    ],
    'levels' => [
        '<string>'
    ],
    'client_envs' => [
        '<string>'
    ],
    'error_types' => [
        '<string>'
    ],
    'text' => [
        
    ],
    'trace_id' => '<string>',
    'span_id' => '<string>',
    'turn_index' => 123,
    'sort' => [
        
    ],
    'limit' => 123,
    'offset' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/traces/logs/aggregate"

	payload := strings.NewReader("{\n  \"from\": {},\n  \"to\": {},\n  \"aggs\": [\n    \"<string>\"\n  ],\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"sort\": {},\n  \"limit\": 123,\n  \"offset\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/traces/logs/aggregate")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": {},\n  \"to\": {},\n  \"aggs\": [\n    \"<string>\"\n  ],\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"sort\": {},\n  \"limit\": 123,\n  \"offset\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/traces/logs/aggregate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": {},\n  \"to\": {},\n  \"aggs\": [\n    \"<string>\"\n  ],\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"sort\": {},\n  \"limit\": 123,\n  \"offset\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "columns": [
    "<string>"
  ],
  "rows": [
    [
      {}
    ]
  ],
  "limit": 123,
  "offset": 123,
  "has_more": true
}

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. Use it to see which events fire most, which functions raise, and when.

Request

Headers

string

required

Account API key with read access to conversations.

Body

datetime

required

Inclusive window start, ISO 8601.

datetime

required

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

string[]

required

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

string[]

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

string

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

string

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

string

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

string

Matches the conversation ID or the call SID.

string[]

Function (tool) names, up to 20.

string[]

debug, info, warning, error, critical.

string[]

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

string[]

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

object

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

string

Trace ID of the function-execution span.

string

Span ID of the function-execution span.

integer

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

object

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

integer

default:"20"

Rows per page, 1–100.

integer

default:"0"

Rows to skip, 0–1000.

Response

string[]

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

array[]

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

integer

boolean

Examples

Which functions log errors, and why

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"}
  }'

{
  "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

Request

{
  "project_id": "PROJECT-V258TF29",
  "from": "2026-10-26T00:00:00Z",
  "to": "2026-10-28T00:00:00Z",
  "aggs": ["count"],
  "interval": "daily"
}

Response

{
  "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

Request

{
  "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.

Last modified on November 10, 2026

⌘I

Aggregate function logs

curl --request POST \
  --url https://api.example.com/api/v1/traces/logs/aggregate \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "from": {},
  "to": {},
  "aggs": [
    "<string>"
  ],
  "group_by": [
    "<string>"
  ],
  "interval": "<string>",
  "timezone": "<string>",
  "project_id": "<string>",
  "conversation_id": "<string>",
  "function_names": [
    "<string>"
  ],
  "levels": [
    "<string>"
  ],
  "client_envs": [
    "<string>"
  ],
  "error_types": [
    "<string>"
  ],
  "text": {},
  "trace_id": "<string>",
  "span_id": "<string>",
  "turn_index": 123,
  "sort": {},
  "limit": 123,
  "offset": 123
}
'

import requests

url = "https://api.example.com/api/v1/traces/logs/aggregate"

payload = {
    "from": {},
    "to": {},
    "aggs": ["<string>"],
    "group_by": ["<string>"],
    "interval": "<string>",
    "timezone": "<string>",
    "project_id": "<string>",
    "conversation_id": "<string>",
    "function_names": ["<string>"],
    "levels": ["<string>"],
    "client_envs": ["<string>"],
    "error_types": ["<string>"],
    "text": {},
    "trace_id": "<string>",
    "span_id": "<string>",
    "turn_index": 123,
    "sort": {},
    "limit": 123,
    "offset": 123
}
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    from: {},
    to: {},
    aggs: ['<string>'],
    group_by: ['<string>'],
    interval: '<string>',
    timezone: '<string>',
    project_id: '<string>',
    conversation_id: '<string>',
    function_names: ['<string>'],
    levels: ['<string>'],
    client_envs: ['<string>'],
    error_types: ['<string>'],
    text: {},
    trace_id: '<string>',
    span_id: '<string>',
    turn_index: 123,
    sort: {},
    limit: 123,
    offset: 123
  })
};

fetch('https://api.example.com/api/v1/traces/logs/aggregate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/traces/logs/aggregate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from' => [
        
    ],
    'to' => [
        
    ],
    'aggs' => [
        '<string>'
    ],
    'group_by' => [
        '<string>'
    ],
    'interval' => '<string>',
    'timezone' => '<string>',
    'project_id' => '<string>',
    'conversation_id' => '<string>',
    'function_names' => [
        '<string>'
    ],
    'levels' => [
        '<string>'
    ],
    'client_envs' => [
        '<string>'
    ],
    'error_types' => [
        '<string>'
    ],
    'text' => [
        
    ],
    'trace_id' => '<string>',
    'span_id' => '<string>',
    'turn_index' => 123,
    'sort' => [
        
    ],
    'limit' => 123,
    'offset' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/traces/logs/aggregate"

	payload := strings.NewReader("{\n  \"from\": {},\n  \"to\": {},\n  \"aggs\": [\n    \"<string>\"\n  ],\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"sort\": {},\n  \"limit\": 123,\n  \"offset\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/traces/logs/aggregate")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": {},\n  \"to\": {},\n  \"aggs\": [\n    \"<string>\"\n  ],\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"sort\": {},\n  \"limit\": 123,\n  \"offset\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/traces/logs/aggregate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": {},\n  \"to\": {},\n  \"aggs\": [\n    \"<string>\"\n  ],\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"function_names\": [\n    \"<string>\"\n  ],\n  \"levels\": [\n    \"<string>\"\n  ],\n  \"client_envs\": [\n    \"<string>\"\n  ],\n  \"error_types\": [\n    \"<string>\"\n  ],\n  \"text\": {},\n  \"trace_id\": \"<string>\",\n  \"span_id\": \"<string>\",\n  \"turn_index\": 123,\n  \"sort\": {},\n  \"limit\": 123,\n  \"offset\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "columns": [
    "<string>"
  ],
  "rows": [
    [
      {}
    ]
  ],
  "limit": 123,
  "offset": 123,
  "has_more": true
}

API reference

Models

Build & deploy

Runtime & data

Monitoring

Legacy

Request

Headers

Body

Response

Examples

Which functions log errors, and why

Log volume per day

Most frequent events in one conversation

Errors

​Request

​Headers

​Body

​Response

​Examples

​Which functions log errors, and why

​Log volume per day

​Most frequent events in one conversation

​Errors

Request

Headers

Body

Response

Examples

Which functions log errors, and why

Log volume per day

Most frequent events in one conversation

Errors