Aggregate cost across a time window

GET

/v1/cost/aggregate

curl --request GET \
  --url 'https://example.com/v1/cost/aggregate?groupBy=example&scopeKind=tenant&inherit=true' \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

Primary consumer path for dashboards. groupBy is required (comma-separated dimensions from the closed set); time range is required (both from and to, or both omitted for the default last-30-days window echoed back in timeRange). Filters compose on top of the time window. ?scopeKind + ?scopeId + ?inherit narrow the aggregate to a specific scope — reconciles byte-for-byte with the same scoped /records list.

Authorizations

• bearerAuth

Parameters

Query Parameters

groupBy

required

string

Comma-separated list of dimensions to aggregate over. Each value must be one of agentId | runId | category | providerId | day | month | tenant | conversationId. Duplicates collapse.

from

string format: date-time

ISO 8601 timestamp; records with occurredAt >= from. Required on /v1/cost/aggregate (or both endpoints omitted for default last-30-days window).

to

string format: date-time

ISO 8601 timestamp; records with occurredAt <= to. Required on /v1/cost/aggregate (or both endpoints omitted for default last-30-days window).

category

string

Filter to a specific category (llm.inference, tool.invocation, storage.write, sandbox.exec, …). Exact match.

providerId

string

Filter records to this provider id (exact match).

agentId

string

Filter records to this agent id (exact match).

runId

string format: uuid

Filter records to this run id (exact match).

conversationId

string format: uuid

Filter records to this conversation id (exact match).

scopeKind

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string

Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

scopeId

string

>= 1 characters

Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.

inherit

boolean

default: true

Default true. false = literal-at-this-scope only (admin/audit view). Load-bearing for policy/config-scoped resources (mcp-endpoints); documented no-op for content-scoped resources (agents/flows/tools/…).

Responses

200

Aggregate rollup.

Media typeapplication/json

object

groups

required

Array<object>

object

key

required

One entry per requested groupBy dimension. null = distinct “unattributed” bucket (records had no value for that dimension).

object

key

additional properties

string | null

count

required

integer

totalUsd

required

number

totalUsd

required

number

totalRecords

required

integer

timeRange

required

object

from

required

string format: date-time

to

required

string format: date-time

groupBy

required

The dimensions the server actually grouped by — echoed so callers can round-trip the response without re-parsing the request URL.

Array<string>

Allowed values: agentId runId category providerId day month tenant conversationId

Example

{
  "groupBy": [
    "agentId"
  ]
}

400

Missing / malformed groupBy, unknown dimension, missing one endpoint of the time range, or from > to.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}