Billing - ZeroGen Docs

Runs 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 run’s billing

Every run 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 run uses 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 run 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 run, for example because it was refused, so nothing was held or charged. `quotedMicroUsd` is also `null`.

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

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

For a byok run, 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 run 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/runs/quote. It holds nothing. For details, see Models in the API. 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 run would pass the organization’s monthly spend limit or the project’s monthly budget.
`409`	`invalid_state`	The run uses 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 runs that haven’t settled. A hold isn’t a charge.
`availableMicroUsd`	What a new run’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.organizationMonthly.enforced`	`true` when Stop work when the limit is reached is on, so runs that would pass the limit are refused. When `false`, the limit only sets off alerts.
`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 run’s quote and admission decide whether it can start.

In the app

ZeroGen’s app calls a run a generation, and shows a quote as the estimated cost before you generate. Settings › Billing shows the balance as Credit balance, Held, and Available to start, which match balanceMicroUsd, heldMicroUsd, and availableMicroUsd. Owners and Admins add credits and set spend limits there. For details, see Credits and billing and Spend limits and budgets.

​Money fields

​A run’s billing

​Billing states

​What’s charged

​Check the cost before you start

​Read your balance

​In the app