Skip to main content
GET
Get a factory's token spend over a window
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

GET /api/v2/factories/getSpend?factoryId=&startTime=&endTime=&taskId= returns one factory’s token spend between startTime and endTime (epoch milliseconds, inclusive) as a FactorySpend: totals, and breakdowns by source, model, agent worker and task. With taskId, only this factory’s events for that task are summed and byTask is null; a task’s spend can be attributed to more than one factory, and a task with no spend in this factory returns zero totals. The 10,000-event bound counts all of this factory’s events in the window, so a task read on a busy factory can be partial; events in other factories never count. Spend is factory token-event attribution; it is not the deployment cost rollup (GET /api/v2/cost/summary). Two permissions at the factory’s home. Your credential’s scopes must reach both factories:read and cost:read, and your role grants must hold both at the factory’s home org unit or above it. The scopes are checked on the request: a key scoped to factories:read alone is refused with 403 and requiredPermission: "cost:read", whatever its role grants hold. The cost:read role grant is checked at the factory’s home, not where your key acts: a factory you may read without cost:read at its home is refused the same way. Bounds. startTime must not be after endTime (a one-millisecond window is valid), and the window may span at most 30 days; anything else is 400 bad_request. The read sums at most 10,000 events, newest first. meta.partial is always present: when it is true, more events existed, and every event from coveredFrom through endTime was summed and none older. Continue with endTime set to coveredFrom - 1; when that is before startTime, nothing is left to read. If more than 10,000 events share one millisecond, that millisecond is summed in part and is coveredFrom, so the continuation still advances. Each breakdown holds at most 100 entries by costCents descending, and its truncated is true when more existed. Cost. Each costCents is summed in micro-dollars and rounded to cents once, so many sub-cent turns still add up. People. Agent workers are listed one by one in byAgentWorker. Every human worker’s spend is one humanWorkers row with no worker ID. A missing, malformed, or unreadable factory ID, or a malformed taskId, is 404 resource_missing with the message Factory not found.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Path Parameters

factoryId
string
required

Query Parameters

startTime
integer
required

Window start, epoch milliseconds (inclusive).

endTime
integer
required

Window end, epoch milliseconds (inclusive); at most 30 days after startTime.

taskId
string

Limit the spend to one of this factory's tasks; byTask is then null.

Minimum string length: 1

Response

Factory spend

data
object
required

One factory's token spend over a window: totals, and breakdowns by source, model, agent worker and task (byTask is null when the read named one task, whose events in this factory alone are summed). Each breakdown holds at most 100 entries by costCents descending, with truncated set when more existed. Every human worker's spend is one humanWorkers row with no worker id. When the response's meta.partial is true, every event from coveredFrom through the window's end was summed and none older (more than 10,000 events in one millisecond: that millisecond is summed in part); otherwise coveredFrom is null. Each costCents is summed in micro-dollars and rounded to cents once, so sub-cent turns count. Spend is factory token-event attribution, not the deployment cost rollup.

meta
object
required