Billing

Generations from live keys are billed to your organization’s balance, which every member and project shares. ZeroGen reports what it holds before the work and what it charges after.

Money fields

Every amount is an integer number of micro-USD, in a field whose name ends in MicroUsd. One US dollar is 1,000,000 micro-USD, so 42000 is USD 0.042. Integers keep amounts exact; convert to dollars only for display.

A generation’s billing

Every generation has a billing object:

{
  "mode": "platform",
  "state": "held",
  "hold": {
    "state": "running",
    "endedAt": null
  },
  "quotedMicroUsd": 42000,
  "heldMicroUsd": 42000,
  "chargedMicroUsd": null
}

Field	Description
`mode`	Who pays. `platform`: ZeroGen bills your organization. `byok`: the generation runs on your organization’s own provider key, so the provider bills you and ZeroGen charges nothing. `test`: a test key ran it, and nothing is charged.
`state`	`held`, `charged`, `released`, or `null`.
`hold`	Present only while `state` is `held`.
`quotedMicroUsd`	The quote: the maximum expected charge, which ZeroGen held when the generation started.
`heldMicroUsd`	While `held`, the amount held now. Otherwise `null`. A held amount is never a charge.
`chargedMicroUsd`	The final charge once `charged`, and `0` once `released`. Otherwise `null`.

Billing states

`state`	Meaning
`held`	An amount is held and nothing is charged yet.
`charged`	`chargedMicroUsd` is the final charge.
`released`	The hold ended with no charge.
`null`	Billing never admitted the generation, for example because it was refused, so nothing was held or charged. `quotedMicroUsd` is also `null`.

While a generation is held, hold.state reports where it stands. It reports facts, not a prediction of the charge:

`hold.state`	Meaning
`running`	The generation hasn’t ended.
`ended`	The generation ended, and the hold is still pending. `hold.endedAt` is when it ended.
`needs_attention`	The hold has stayed pending 30 minutes after the generation ended, or 24 hours after it started with no end recorded, so ZeroGen is looking into it.

For a byok generation, quotedMicroUsd is 0, heldMicroUsd is 0 while held, and chargedMicroUsd is 0 once charged.

What’s charged

The charge follows the work the provider actually reports, so it can differ from the quote. In rare cases, it can be higher than the quote.
A failed output isn’t charged for its output, but a generation is still charged for billable work that actually happened, such as accepting the request.
Cancelling stops unfinished outputs. Outputs that a provider already finished are kept and charged.

Check the cost before you start

To see a cost before you start, request a quote with POST /v1/generations/quote. It holds nothing. For details, see Models. To cap a create, send maxCostMicroUsd. If the quote is higher, the create fails with 402 cost_limit_exceeded and starts nothing. maxCostMicroUsd caps the quote, not the final charge. A create can also fail before it starts with these errors:

Status	Code	Cause
`402`	`insufficient_balance`	The available balance can’t cover the quote.
`402`	`spend_limit_reached`	The generation would pass the organization’s monthly spend limit or the project’s monthly budget.
`409`	`invalid_state`	The generation runs on your organization’s own provider key and has no provider list price, so only a person can start it, in ZeroGen.

Read your balance

GET /v1/balance returns your organization’s funds. It needs the account:read scope. Add projectId to include that project’s monthly budget.

curl "https://api.zerogen.com/v1/balance?projectId=5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d" \
  -H "Authorization: Bearer $ZEROGEN_API_KEY"

{
  "currency": "USD",
  "balanceMicroUsd": 250000000,
  "heldMicroUsd": 42000,
  "availableMicroUsd": 249958000,
  "unlimited": false,
  "limits": {
    "organizationMonthly": {
      "limitMicroUsd": 1000000000,
      "spentMicroUsd": 81250000,
      "enforced": true
    },
    "projectMonthly": {
      "limitMicroUsd": 200000000,
      "spentMicroUsd": 12500000
    }
  }
}

Field	Description
`balanceMicroUsd`	The organization’s balance. It can be negative.
`heldMicroUsd`	The amount held for generations that haven’t settled. A hold isn’t a charge.
`availableMicroUsd`	What a new generation’s quote must fit within. It can be negative.
`unlimited`	When `true`, ZeroGen skips the funds check. Usage is still charged.
`limits.organizationMonthly`	The organization’s monthly spend limit, with this UTC month’s spend, or `null` when there’s none.
`limits.projectMonthly`	With `projectId`, that project’s monthly budget and this UTC month’s spend. Otherwise `null`.

A limit’s limitMicroUsd can be null. If your organization’s balance isn’t available, the response is 503 unavailable. The balance is a point-in-time read. A generation’s quote and admission decide whether it can start.

Get started

Generate

Conventions

Money fields

A generation’s billing

Billing states

What’s charged

Check the cost before you start

Read your balance

​Money fields

​A generation’s billing

​Billing states

​What’s charged

​Check the cost before you start

​Read your balance

Money fields

A generation’s billing

Billing states

What’s charged

Check the cost before you start

Read your balance