Skip to main content
The Cost domain exposes two reads over the pre-aggregated spend rollups. Both carry 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 bucket
  • GET /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 hold cost: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 carries meta.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

Summary items follow the 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.