> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Account and billing

> Balance, credits, refunds, usage reporting, and how the request-rate allowance grows.

# Account and billing

## How does billing work?

One USD balance per account, drawn down as work completes. There is no subscription and no monthly commitment — credits are added up front and consumed.

* **Text** is metered per token, priced separately for input, cached input, and output.
* **Tasks** — image, video, effect, workflow — reserve credits on submission and settle on completion.

## Where do I see what I have spent?

Two places, showing the same figures:

* The [dashboard](https://beatapi.io/dashboard), for calls, tokens, cost, and the per-key breakdown.
* `GET /v1/usage`, for the same data programmatically — including `by_model`, `by_capability`, and `by_api_key`.

## What happens when a task fails?

The reservation is refunded. `GET /v1/tasks/{task_id}` reports the refund on the task itself, and `GET /v1/usage` reports `credits_refunded` alongside `credits_settled`.

This matters for your own accounting: if your ledger records the reservation and never reads the refund, your numbers drift from the invoice. Reconcile both.

## Why is my balance negative?

`credit_balance` can go below zero. A long-running task settles at completion, so work already accepted finishes and bills even if the balance reached zero while it was running. Add credits and the balance returns to positive.

## What happens at zero?

Every paid operation on the account starts returning `402 insufficient_credits` — this is account-wide, not per-key. A balance above zero but below the price of a request gets the same `402`. Tasks already accepted continue to completion. Nothing is deleted and no key is revoked; adding credits resumes service immediately.

A key that carries its own spending limit and has used it up is a different case: it answers `401 invalid_api_key`, with a message saying the key is exhausted, while the account's other keys keep working. Keys created in the dashboard have no limit of their own; switch to one of those.

If anything you run is user-facing, alert on `402` rather than discovering it from a user.

## How is the request-rate allowance decided?

By lifetime paid top-ups, not by plan. Adding credits moves the account up a tier, permanently — the tier never falls back, because the figure it is based on only ever increases.

The current allowance and the next tier are on the dashboard, and in `GET /api/user/self` under `rate_limit`:

```jsonc
"rate_limit": {
  "enabled": true,
  "window_minutes": 1,
  "success_count": 20,
  "next_tier": { "min_topup_quota": 50000000, "success_count": 30 }
}
```

Two things it deliberately does not tell you: promotional credits and referral bonuses do not count toward a tier, and the figure shown excludes any stricter limit attached to an individual key.

Free models (the Free category, such as `jev-1.14-free`) sit outside these tiers. They have a fixed per-account limit of their own: 1 successful request per minute before the first top-up, at most 10 per minute after any top-up however much was paid. It is counted separately from the tier above, so free calls do not use up the paid allowance, and a request over it gets `429` with `Retry-After`.

## Do credits expire?

No. The balance stays until it is spent.

## Why does the same prompt cost different amounts?

Four reasons, in rough order of how often they surprise people:

1. **Output length varies.** Output is the expensive half of a text call, and the model decides how long it is unless you cap it.
2. **Cached input is cheaper than fresh input.** Repeating a long system prompt can hit the cache and cost a fraction of the first call.
3. **Some models bill by time of day.** The two DeepSeek HC (high-cache) models double on weekdays 09:00–12:00 and 14:00–18:00 Beijing time, while the regular paid DeepSeek models bill one rate at all hours; Hunyuan `hy3` has its own daily peak window. The [pricing page](https://beatapi.io/pricing) footnotes give the exact hours.
4. **Some models bill by context length.** The GPT-5.6 and Grok families charge a higher rate past a context threshold. A long agent session crosses it silently.

Every response's usage record shows which rate was applied.

## Can I see cost per application?

Give each application its own API key. `by_api_key` in `GET /v1/usage` then attributes tasks and credits per key with no further work.

## How do I add credits?

From the [dashboard](https://beatapi.io/dashboard). The balance updates as soon as the payment is confirmed; there is nothing to enable afterwards.

## How do I get help with a charge?

Open a support ticket from the [dashboard](https://beatapi.io/dashboard) with the `request_id` of the call in question, or the task ID. Both resolve to a single record.