Sume balance in USD micros vs cents vs credits: which to use

Do your budget math in USD micros (one millionth of a dollar), not cents. GET /v1/balance returns available_amount_usd_micros, available_amount_usd_cents and available_credits; the last two are cent values kept for compatibility, so anything priced below a cent is rounded in them. A hundred five-second Grok Imagine clips are $6.25 in micros and $7.00 if you round each clip up to a whole cent first.

This matters most for the cheap endpoints: text-to-speech, background removal, low-quality images and short Grok clips all bill fractions of a cent.

What does the balance response contain?

The Usage docs say the balance is USD-denominated and that compatibility fields can expose rounded cent values as credits. In the API code that builds the response, available_amount_usd_cents and available_credits are the same number, and state is funded when the micros figure is above zero and empty otherwise. The expiration block adds next_expires_at, expiring_soon_days (30) and the micros and cents amounts that fall inside that window.

The expiry cent fields are rounded down. A balance of 1,230,000 micros reads as 123 cents, and 1,239,999 micros would also read as 123.

How far apart can micros and cents drift?

Quotes in the pricing package carry the billable amount in micros plus a cents field that is rounded up. Rounding up per item and summing overstates a batch, while rounding down understates it. The table shows the per-item gap for rates read from the package.

Which field should each task use?

Pick the unit by the question you are answering.

• Funding a batch: sum micros across items, then convert the total to dollars once.
• Showing a balance to a person: cents are fine, since a human reads 123 cents as $1.23.
• Alerting on a threshold: compare micros, so a balance of 4,990 micros is not rounded up to look like 1 cent of headroom.
• Reporting what a run cost: read debited_usd_micros from the run-scoped GET /v1/usage summary, which the docs call the figure to quote.
• Never sum ledger rows yourself; the Usage docs warn that a refunded row keeps its hold amount.

A conversion you can paste

This helper turns a micros balance into dollars and shows both cent roundings, so a dashboard can print whichever is appropriate.

import math


def describe(micros: int) -> str:
    dollars = micros / 1_000_000
    up = math.ceil(micros / 10_000)
    down = micros // 10_000
    return f"{dollars:.6f} USD, {down} cents floor, {up} cents ceil"


for value in (62_500, 1_239_999, 6_250_000):
    print(value, describe(value))

Where the balance is held

A new job reserves its estimate at submit, per Generation admission, and a failed job releases it. When you compare a balance read to your own tally, expect open holds to explain small gaps; the run-scoped held_usd_micros field reports them separately.