Endpoints
The three
aggregate and logs endpoints are experimental — their schema may change.
Base URL and authentication
Send an account API key in theX-API-KEY header (Authorization: Bearer <key> is also accepted). The key needs read access to conversations. Create keys from the API Keys tab in Agent Studio; see API keys.
Keys are region-specific. Use the host of the region your account lives in.
Every request body accepts an optional
project_id. Omit it to query the whole account; set it to narrow to one agent. The value is the Agent ID shown in Agent Studio (PROJECT-xxxxxxxx). A project outside your account returns no rows, not an error (an ungrouped aggregate returns a single zero count).
Concepts
Spans
A span is one timed operation with a name, a status (Ok, Error or Unset), a duration and a few allowlisted attributes. Spans nest: a polyai.turn span contains the LLM, function and retrieval spans that produced that turn’s response. Common span names:
Each span carries the
turn_index it belongs to (0-based). Function spans also carry function_name. Spans may carry a layer (conversation, telephony, voice, asr, tts, harness, gen_ai, tool, retrieval); it is empty on spans that predate the attribute.
Measures
Timing aggregates run over one measure per request:
Filter on
span_name when you use the last two. In a group where no span carries the measure, p50/p95/p99 return 0 and avg/min/max return null; count still counts every span.
Error types
Failed spans carry anerror_type that says why. Filter and group on it.
Function logs
Everylog.info(...), log.warning(...) or log.error(...) call inside a GenAI function becomes one log line. The API returns each line’s event label (the message you logged) and promoted columns, never the raw line or its payload, so no transcript or customer data can leak through it.
Each line is linked to the span it ran in: trace_id and span_id identify the polyai.function.execution span, and turn_index is the turn that triggered the call. Pass a span_id from a span search to read exactly the lines that one execution wrote. The three fields are empty on lines from functions deployed before this linking was introduced; publish or promote the agent to refresh them.
Lines the function runtime writes about itself (for example when a function cannot be loaded) are excluded.
Time windows and paging
The conversation endpoints and
spans/search take an optional window with no cap, and page the same way.
from is inclusive, to exclusive, both ISO 8601. Timestamps in responses are UTC; the span endpoints return them without an offset suffix, the log endpoints with +00:00. Every response carries has_more. logs/search also echoes the from and to it used: pass them back on the next page so new log lines do not shift the results.
Aggregate responses are tabular: columns names the fields, and each entry in rows lists values in that order. When you set interval, the first column is bucket.