Get a factory's token spend over a window
Returns one factory’s token spend between startTime and endTime (epoch ms, inclusive) — totals, and breakdowns by source, model, agent worker and task. Requires permission factories:read and cost:read, both at the factory’s home.
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
Query Parameters
Response
Factory spend
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.

