Balance and billing

Your organisation has a balance. Requests draw it down; top-ups build it up. There is no monthly reset and nothing expires — what you paid for stays yours until you use it.

Where the number comes from

balance = everything paid in − everything spent

Both sides count from the beginning, not from the first of the month. That is why the remainder carries over on its own: it is not stored anywhere to be reset, it is the difference between two running totals.

The console shows the balance on every page. This month on the Keys tab is a separate figure, there to answer "how fast are we going" — it takes no part in the calculation.

Reading it from code

One call, one number — what this key can still spend:

curl https://api.sociaro.com/v1/balance -H "Authorization: Bearer $SOCIARO_API_KEY"

{"remaining": 312.58}

US dollars, and the same figure the console shows: your organisation's limit minus what it has spent. That is the only balance there is — keys and teams do not carry separate budgets, so every key in your organisation reads the same number.

When there is nothing left you get a 429 and no number. That is deliberate. The figure would be zero or below, and a number you cannot spend is not an answer; top up and ask again.

It excludes work still running. A generation is billed when it completes, so clips in flight are not subtracted here yet. Read it right after submitting a batch and you are reading the figure from before you submitted.

Refusals: 401 the key is missing or invalid · 404 the key belongs to no organisation · 409 your organisation has no spending limit configured — contact your account manager · 429 nothing left, or too many requests · 502 our own check failed, retry · 503 temporarily unavailable.

Topping up

On the Billing tab: add a card, then top up. Payment happens on Stripe's own page — the card never touches us.

Automatic top-up charges the saved card when the balance falls below a threshold you set. You choose the threshold, the amount, and a daily maximum that nothing can exceed. If the card is declined in a way that needs you present, top-up switches itself off and we e-mail you rather than retrying a card that cannot work.

Running out

A request that would spend beyond the balance is refused with 429 and a plain reason:

{"error": {"message": "budget exceeded for this organisation: its spend has reached the balance it was topped up to. Top up in the console to continue."}}

Nothing is charged for a refused request, and the refusal appears in your Logs so you can see it happened rather than guessing from a status code your code swallowed.

What a request costs

Chat and completion models are billed per token, at the rate on the model's own page. Image and video models are billed per image or per second of output, by resolution.

Media jobs are billed from what the vendor reports it rendered, not from what was asked for. If you request 1080p and the vendor delivers 720p, you pay for 720p. A job we cannot price is withheld rather than delivered free — you are never billed for something you did not receive, and never given something nobody could price.

Seeing where it went

Spend breaks the period down by key, and each key opens into a day-by-day view. Logs lists individual requests with their model, duration and cost, and exports to CSV.