Aggregate spend

Spend grouped by agent, customer, user, model, day and more.

Returns spend grouped by one or more dimensions.

This is what cost dashboards read. Results are always confined to the organisation named in parent; the organisation is never taken from filter, so a caller cannot widen its own scope.

Request

  • GET /v1/organisations/{organisation}/activities:aggregate
  • GET /v1/organisations/{organisation}/workspaces/{workspace}/activities:aggregate

Parameters

Name In Type Required What it is
groupBy query list of string no Dimensions to group by. Repeat the parameter for several: groupBy=agent&groupBy=model. Leave it out for one total.
filter query string no Keeps only matching calls: terms of field = value joined by AND, e.g. user = "8c21e0b4".
startTime query timestamp yes Start of the window to aggregate, inclusive.
endTime query timestamp yes End of the window to aggregate, exclusive.
pageSize query integer no Maximum rows to return.
pageToken query string no A page token from a previous response, to retrieve the next page.
agent query string no Confines the aggregate to one agent's activities.
timeZone query string no The IANA time zone date and hour groups are cut in, such as Africa/Nairobi, so a day is the reader's organisation's day.
readMask query string no The fields of AggregateRow to fill in, such as estimatedCostMicros and activityCount.

Response

Field Type What it is
rows list of object One row per combination of the requested dimensions.
nextPageToken string Token to retrieve the next page, empty when there are no more.

Each item of the list

Field Type What it is
dimensions map The row's value for each dimension you grouped by, e.g. {"agent": "organisations/acme/agents/atlas"}.
estimatedCostMicros int64 as string Cost in millionths of a US dollar: "3182400000" is $3,182.40.
activityCount int64 as string How many activities the row covers.
failedCount int64 as string How many of the activities failed or were denied: neither produced the work the call was made for.
failedCostMicros int64 as string What the failed calls cost.
retryCostMicros int64 as string What the retries cost: money spent doing the same piece of work again, in millionths of a US dollar.
distinctRequests int64 as string How many distinct requests and people the activities belong to.
distinctUsers int64 as string How many distinct people the activities were done for.
billedCostMicros int64 as string Sum of billedCostMicros over the matching activities.
totalTokens int64 as string Sum of totalTokens over the matching activities.
promptTokens int64 as string Sums of each kind of token, kept apart because each is priced at its own rate and a total cannot be taken back apart once summed.
candidateTokens int64 as string Sum of candidateTokens, the output tokens, over the matching activities.
cachedTokens int64 as string Sum of cachedTokens over the matching activities.
cacheWriteTokens int64 as string Sum of cacheWriteTokens over the matching activities.
reasoningTokens int64 as string Sum of reasoningTokens over the matching activities.
truncatedCount int64 as string How many hit a limit and did partial work.
unpricedCount int64 as string How many model calls used tokens and were priced at nothing, which is what a call looks like when the rate card could not match its model.
modelCalls int64 as string How many of the activities were model calls, and how many tool calls, by the same rule as the kind dimension.
toolCalls int64 as string How many of the activities were tool calls.
p50DurationMs int64 as string Duration at the 50th and 95th percentile, in milliseconds, over the activities that reported one.
p95DurationMs int64 as string Duration at the 95th percentile, in milliseconds.
avgDurationMs int64 as string The mean and the slowest duration, in milliseconds, over the activities that reported one.
maxDurationMs int64 as string The slowest duration, in milliseconds, over the activities that reported one.
emptyResultCount int64 as string How many calls succeeded and returned nothing usable.
firstOccurredAt timestamp When the earliest and latest of the activities finished.
lastOccurredAt timestamp When the latest of the activities finished.
firstStartedAt timestamp When the earliest of the activities started: the least of occurredAt less durationMs.
charges list of object Sums of each charged line beyond the token classes, one entry per priceable unit, e.g. audio output tokens, web searches, citation tokens.
unnormalisedCount int64 as string How many of the activities carried counts the server could not read, because usageFormat named a convention it does not know.
lostRecords int64 as string Records the recorders of the matching agents reported losing in the window, such as records dropped when their queue was full.
unrecognisedCalls int64 as string Calls the recorders of the matching agents saw through an instrumented client and did not recognise, such as embeddings, so nothing was recorded for them.
errorClassLabel string The label for the row's errorClass, e.g. Rate limit exceeded, where the rows are grouped by it; the same label Activity.failure carries, so a failures panel and a single failure read in the same words.
errorClassExplanation string The sentence for the row's errorClass where the rows are grouped by it, e.g. `The provider rejected the request as sent.
errorClassOwner string Whose the row's errorClass is, where the rows are grouped by it: ours, provider or unknown.
failedRequests int64 as string How many of the requests the activities belong to had at least one call that failed or was denied, whether or not the request went on to finish.
endedInFailureRequests int64 as string How many of the requests ended in failure: the last call recorded for the request, across the whole window rather than this row alone, failed or was denied.
maxPromptTokens int64 as string The largest prompt of any one call in the row, in tokens, cached tokens included.
maxCandidateTokens int64 as string The longest answer of any one call in the row, in tokens, reasoning included.

The OpenAPI document has every field. All methods.