> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mage.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing and retention

> How the Mage API charges Gems: the price of a request, when it is charged and refunded, cancellations, auto top-up, and how long results and inputs are kept.

Every API request is paid in Gems from your account. Membership plans and their unlimited models do not apply to the API.

## Prices

The price depends on the model and its settings: resolution, duration, and on some models the number of references. Each model's page shows the price of its default settings. Before you submit, `GET /v1/account` shows the balance; after you submit, `billing.gems_charged` on the request shows the exact charge. A request the balance cannot cover is refused with `402 insufficient_gems` and `gems_required`, and nothing is charged.

## When Gems move

| Event                                    | Gems                                                                      |
| ---------------------------------------- | ------------------------------------------------------------------------- |
| The request is accepted                  | Charged. `billing.gems_charged` is the price.                             |
| The generation fails                     | Refunded. The status read shows `gems_refunded`.                          |
| The model's lab blocks the output        | Refunded.                                                                 |
| Mage's content policy forbids the output | Kept, as in the app. The request reports `failed` with `content_blocked`. |
| You cancel the request                   | Kept, as in the app.                                                      |
| The request is refused before it runs    | Nothing is charged.                                                       |

## Auto top-up

If auto top-up is on for your account, an API request that needs more Gems than the balance holds triggers it exactly as a generation in the app would, including the charge to your card. Turn it off in Settings if you want API spend bounded by the balance. See [how Gems work](/plans/how-gems-work).

## Retention

Results and inputs live in a 30-day temporary area. A result's `expires_at` and an upload ticket's `url_expires_at` say when each URL stops working. A completed request stays `completed` after its media expires; only the download stops. Copy anything you want to keep to your own storage.