Aggregate spans

POST

api

traces

spans

aggregate

Aggregate spans

curl --request POST \
  --url https://api.example.com/api/v1/traces/spans/aggregate \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "from": {},
  "to": {},
  "aggs": [
    "<string>"
  ],
  "measure": "<string>",
  "group_by": [
    "<string>"
  ],
  "interval": "<string>",
  "timezone": "<string>",
  "project_id": "<string>",
  "span_name": "<string>",
  "status_code": "<string>",
  "function_name": "<string>",
  "error_type": "<string>",
  "conversation_id": "<string>",
  "client_env": [
    "<string>"
  ],
  "sort": {},
  "limit": 123,
  "offset": 123
}
'

import requests

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

payload = {
    "from": {},
    "to": {},
    "aggs": ["<string>"],
    "measure": "<string>",
    "group_by": ["<string>"],
    "interval": "<string>",
    "timezone": "<string>",
    "project_id": "<string>",
    "span_name": "<string>",
    "status_code": "<string>",
    "function_name": "<string>",
    "error_type": "<string>",
    "conversation_id": "<string>",
    "client_env": ["<string>"],
    "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>'],
    measure: '<string>',
    group_by: ['<string>'],
    interval: '<string>',
    timezone: '<string>',
    project_id: '<string>',
    span_name: '<string>',
    status_code: '<string>',
    function_name: '<string>',
    error_type: '<string>',
    conversation_id: '<string>',
    client_env: ['<string>'],
    sort: {},
    limit: 123,
    offset: 123
  })
};

fetch('https://api.example.com/api/v1/traces/spans/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/spans/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>'
    ],
    'measure' => '<string>',
    'group_by' => [
        '<string>'
    ],
    'interval' => '<string>',
    'timezone' => '<string>',
    'project_id' => '<string>',
    'span_name' => '<string>',
    'status_code' => '<string>',
    'function_name' => '<string>',
    'error_type' => '<string>',
    'conversation_id' => '<string>',
    'client_env' => [
        '<string>'
    ],
    '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/spans/aggregate"

	payload := strings.NewReader("{\n  \"from\": {},\n  \"to\": {},\n  \"aggs\": [\n    \"<string>\"\n  ],\n  \"measure\": \"<string>\",\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"span_name\": \"<string>\",\n  \"status_code\": \"<string>\",\n  \"function_name\": \"<string>\",\n  \"error_type\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"client_env\": [\n    \"<string>\"\n  ],\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/spans/aggregate")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": {},\n  \"to\": {},\n  \"aggs\": [\n    \"<string>\"\n  ],\n  \"measure\": \"<string>\",\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"span_name\": \"<string>\",\n  \"status_code\": \"<string>\",\n  \"function_name\": \"<string>\",\n  \"error_type\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"client_env\": [\n    \"<string>\"\n  ],\n  \"sort\": {},\n  \"limit\": 123,\n  \"offset\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/traces/spans/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  \"measure\": \"<string>\",\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"span_name\": \"<string>\",\n  \"status_code\": \"<string>\",\n  \"function_name\": \"<string>\",\n  \"error_type\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"client_env\": [\n    \"<string>\"\n  ],\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
}

Aggregates the spans in a time window into one row per bucket and group. Use it for latency breakdowns per turn or per span, error rates per function or per error type, and trends over hours, days, weeks or months. See the overview for the span, measure and error-type vocabulary.

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: p50, p95, p99, avg, min, max (over measure), count, error_count, error_rate (errors divided by count, null when count is 0), conversation_count.

string

default:"duration_ms"

Per-span value the timing aggregations run over: duration_ms, time_to_first_token_ms (set on polyai.llm_gateway.provider_call spans) or time_to_first_byte_ms (set on TTS spans). Filter on span_name for the last two: where no span carries the measure, percentiles return 0 and avg/min/max return null.

string[]

Dimensions to group by, one column each: span_name, service, layer, project_id, client_env, turn_index, function_name, flow_name, step_name, deployment_version, error_type.

string

Time bucket: hourly, daily, weekly or monthly. 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

Exact span name, for example polyai.turn.

string

Ok, Error or Unset.

string

Restrict to the spans of one GenAI function.

string

Restrict to spans that failed for this reason, for example LLM_PROVIDER_UNAVAILABLE or function_error.

string

Restrict to one conversation.

string[]

Restrict to environments: test, sandbox, pre-release, live, scenarios. pre-release is the Staging environment.

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. Timing values are milliseconds.

integer

boolean

true when another page exists.

Examples

Latency and error rate per span

curl -X POST https://api.us.poly.ai/api/v1/traces/spans/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",
    "aggs": ["p50", "p95", "count", "error_count", "error_rate"],
    "group_by": ["span_name"],
    "sort": {"field": "count", "order": "desc"},
    "limit": 10
  }'

{
  "columns": ["span_name", "p50", "p95", "count", "error_count", "error_rate"],
  "rows": [
    ["polyai.turn", 896.16, 2645.03, 5207, 0, 0.0],
    ["polyai.rag.query", 37.57, 45.88, 5084, 0, 0.0],
    ["polyai.llm_gateway.provider_call", 1226.5, 2140.77, 3495, 49, 0.014],
    ["polyai.function.execution", 62.4, 151.42, 1949, 0, 0.0]
  ],
  "limit": 10,
  "offset": 0,
  "has_more": false
}

Time to first token per turn, hourly

Request

{
  "project_id": "PROJECT-V258TF29",
  "from": "2026-10-26T00:00:00Z",
  "to": "2026-10-27T00:00:00Z",
  "span_name": "polyai.llm_gateway.provider_call",
  "measure": "time_to_first_token_ms",
  "aggs": ["p95"],
  "group_by": ["turn_index"],
  "interval": "hourly",
  "timezone": "Europe/London"
}

Why LLM calls failed

Request

{
  "project_id": "PROJECT-V258TF29",
  "from": "2026-10-26T00:00:00Z",
  "to": "2026-10-28T00:00:00Z",
  "status_code": "Error",
  "aggs": ["count"],
  "group_by": ["error_type"]
}

Response

{
  "columns": ["error_type", "count"],
  "rows": [
    ["LLM_PROVIDER_UNAVAILABLE", 89]
  ],
  "limit": 20,
  "offset": 0,
  "has_more": false
}

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 trace backend did not answer.

Last modified on November 10, 2026

⌘I

Aggregate spans

curl --request POST \
  --url https://api.example.com/api/v1/traces/spans/aggregate \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "from": {},
  "to": {},
  "aggs": [
    "<string>"
  ],
  "measure": "<string>",
  "group_by": [
    "<string>"
  ],
  "interval": "<string>",
  "timezone": "<string>",
  "project_id": "<string>",
  "span_name": "<string>",
  "status_code": "<string>",
  "function_name": "<string>",
  "error_type": "<string>",
  "conversation_id": "<string>",
  "client_env": [
    "<string>"
  ],
  "sort": {},
  "limit": 123,
  "offset": 123
}
'

import requests

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

payload = {
    "from": {},
    "to": {},
    "aggs": ["<string>"],
    "measure": "<string>",
    "group_by": ["<string>"],
    "interval": "<string>",
    "timezone": "<string>",
    "project_id": "<string>",
    "span_name": "<string>",
    "status_code": "<string>",
    "function_name": "<string>",
    "error_type": "<string>",
    "conversation_id": "<string>",
    "client_env": ["<string>"],
    "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>'],
    measure: '<string>',
    group_by: ['<string>'],
    interval: '<string>',
    timezone: '<string>',
    project_id: '<string>',
    span_name: '<string>',
    status_code: '<string>',
    function_name: '<string>',
    error_type: '<string>',
    conversation_id: '<string>',
    client_env: ['<string>'],
    sort: {},
    limit: 123,
    offset: 123
  })
};

fetch('https://api.example.com/api/v1/traces/spans/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/spans/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>'
    ],
    'measure' => '<string>',
    'group_by' => [
        '<string>'
    ],
    'interval' => '<string>',
    'timezone' => '<string>',
    'project_id' => '<string>',
    'span_name' => '<string>',
    'status_code' => '<string>',
    'function_name' => '<string>',
    'error_type' => '<string>',
    'conversation_id' => '<string>',
    'client_env' => [
        '<string>'
    ],
    '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/spans/aggregate"

	payload := strings.NewReader("{\n  \"from\": {},\n  \"to\": {},\n  \"aggs\": [\n    \"<string>\"\n  ],\n  \"measure\": \"<string>\",\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"span_name\": \"<string>\",\n  \"status_code\": \"<string>\",\n  \"function_name\": \"<string>\",\n  \"error_type\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"client_env\": [\n    \"<string>\"\n  ],\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/spans/aggregate")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": {},\n  \"to\": {},\n  \"aggs\": [\n    \"<string>\"\n  ],\n  \"measure\": \"<string>\",\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"span_name\": \"<string>\",\n  \"status_code\": \"<string>\",\n  \"function_name\": \"<string>\",\n  \"error_type\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"client_env\": [\n    \"<string>\"\n  ],\n  \"sort\": {},\n  \"limit\": 123,\n  \"offset\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/traces/spans/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  \"measure\": \"<string>\",\n  \"group_by\": [\n    \"<string>\"\n  ],\n  \"interval\": \"<string>\",\n  \"timezone\": \"<string>\",\n  \"project_id\": \"<string>\",\n  \"span_name\": \"<string>\",\n  \"status_code\": \"<string>\",\n  \"function_name\": \"<string>\",\n  \"error_type\": \"<string>\",\n  \"conversation_id\": \"<string>\",\n  \"client_env\": [\n    \"<string>\"\n  ],\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

Latency and error rate per span

Time to first token per turn, hourly

Why LLM calls failed

Errors

​Request

​Headers

​Body

​Response

​Examples

​Latency and error rate per span

​Time to first token per turn, hourly

​Why LLM calls failed

​Errors

Request

Headers

Body

Response

Examples

Latency and error rate per span

Time to first token per turn, hourly

Why LLM calls failed

Errors