Fetch metrics for an Assistant
Filter /v1/metrics/bulkAll by context.assistantId to retrieve an Assistant's aggregated usage and fixed-rate cost estimates.
Use an organization-scoped API key for this v1 endpoint. Project-scoped keys cannot access it. The pricing values use legacy fixed rates. For recorded Assistant costs, use /metrics/v2/billing/assistants/<assistant-id>.
Endpoint
Code
Use case: fetch consumption for a single Assistant
Goal
Use the initial Assistant's ID in the context filter. Conversation summaries belong to the Assistant that answered the call, including when the call transfers to another Assistant.
Request
Code
The
contextparameter is URL-encoded. The decoded value is:Code
Query parameters
| Parameter | Value | Description |
|---|---|---|
from | 2026-03-10T08:00:00.000Z | Start of the time window (ISO 8601) |
to | 2026-03-20T08:00:00.000Z | End of the time window (ISO 8601) |
context | {"assistantId":"d66f9abb-52d9-4547-ab51-45d27868f949"} | JSON object filtering events by Assistant ID |
metrics | See below | Comma-separated list of metrics to retrieve |
Metrics requested
| Metric | Description |
|---|---|
duration | Total conversation duration (seconds) |
indivisibleDuration | Billed duration blocks (minutes) |
usage.tts.characters | Characters sent to text-to-speech |
usage.conversational.inputTextTokens | Input tokens consumed by the conversational AI |
usage.conversational.outputTextTokens | Output tokens produced by the conversational AI |
usage.conversational.cachedTextTokens | Cached tokens reused by the conversational AI |
Example response
These aggregates are illustrative, with rounded averages and prices rounded to six decimal places.
Code
Reading the response
Each object corresponds to one metric, aggregated across matching conversation summaries owned by this Assistant within the time window. The count reflects summary events containing that metric; it is not a count of model requests or handoffs.
| Field | Type | Description |
|---|---|---|
timestamp | string | Start of the aggregation window (matches from) |
metric | string | Name of the metric |
data.sum | number | Total value across all conversations for this Assistant |
data.avg | number | Average value per conversation |
data.min | number | Lowest value recorded in a single conversation |
data.max | number | Highest value recorded in a single conversation |
data.count | number | Number of matching summary events containing this metric |
pricing | number | Estimated cost in EUR for this metric over the full time window |
Difference vs. the traceId use case
| Dimension | traceId filter | context.assistantId filter |
|---|---|---|
| Scope | Single conversation | Summaries owned by the initial Assistant |
data.count | Normally 1 when a matching summary contains the metric | N conversations in the time window |
data.avg/min/max | Identical to sum for one matching event | Reflects the spread across matching summary events |
| Typical use | Inspect one call's usage | Monitor usage attributed to the initial Assistant |
Notes
- The
contextparameter must be a valid JSON object, URL-encoded in the query string. assistantIdis a recorded context field whose value is the UUID of the initial Assistant. Filters can also match other recorded context fields, such asconversationIdormode.- Combine with
projectIdto scope results further to a specific project within an organisation. - Summing the
pricingvalues gives a fixed-rate estimate for the selected metrics. It does not give recorded billing costs. frommust be beforeto.bulkAllusesgranularity=alland returns one row per requested metric, including a zero row when no data matches.- Your organization scope is applied automatically;
projectIdcan narrow the query within that Organization.
Related endpoints
| Endpoint | When to use |
|---|---|
/v1/metrics/bulkAll | Retrieve multiple metrics aggregated over the full time window |
/v1/metrics/:metric | Retrieve one metric as a time series (hourly, daily…) for this Assistant |