meta.asOf, the newest rollup time across the returned rows: the rollups are written on a schedule, so an empty data with a null asOf means the window has not been accrued yet, not zero spend.
Operations
Reads:GET /api/v3/cost-summary— getCostSummary — the deployment’s spend totals per bucketGET /api/v3/customers/{customerId}/cost— getCustomerCost — one customer’s spend per bucket (External App credentials only)
Deployment-root authority
The cost summary covers the whole deployment, so it is decided at the deployment root: your role grants must holdcost:read there. Every migrated API key’s root compatibility grant does. A credential holding cost:read only where it acts — an org unit below the root, or a partner organization’s root — gets 403 with requiredPermission: "cost:read". GET /api/v3/me/actor reports the acting-unit check only, so its permissionSatisfied for this operation is necessary, not sufficient. A per-organization summary does not exist: the rollups carry no org unit.
Completeness
The summary always carriesmeta.partial. It scans at most 10,000 stored rows and returns at most 2,000 totals, newest first. When either bound stops it, or a stored total’s rollup overflowed, meta.partial is true and the oldest buckets are the ones missing: narrow the range or use a coarser bucket.
Common workflow
CostAggregate schema and customer items the CustomerCostAggregate schema. Storage identifiers, the customer id and rollup bookkeeping are not returned, and there is no agent, model, workflow or tier breakdown. Over MCP, forge_call_operation reaches the same reads with operationId getCostSummary and getCustomerCost.
Related
- Your own budget — the acting org unit’s budget
- Budgets and cost — conceptual background

