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

# Credits and usage

> Understand available Credits, pending reservations, and account API usage.

Call `GET /v1/usage` before paid work and while diagnosing a generation that appears to be holding Credits.

```bash theme={null}
curl https://api.mint.gg/v1/usage \
  -H "Authorization: Bearer $MINT_API_KEY"
```

## Estimate Credit requirements

Call `POST /v1/pricing:estimate` immediately before starting paid work when your integration needs to show or check the expected Credit requirement.

```bash theme={null}
curl -X POST https://api.mint.gg/v1/pricing:estimate \
  -H "Authorization: Bearer $MINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "model_generation",
    "generationPreset": "standard",
    "generationMode": "auto"
  }'
```

The estimator is read-only. It does not create an operation or asset, reserve Credits, change the Credit balance, or start provider work. Do not send an `Idempotency-Key`.

The response separates the Credits planned for the first stage from the conservative total:

```json theme={null}
{
  "object": "pricing_estimate",
  "operation": "model_generation",
  "credits": {
    "requiredToStart": 173,
    "estimatedTotal": 798
  },
  "stages": [
    {
      "stage": "preview",
      "credits": 173,
      "conditional": false
    },
    {
      "stage": "final",
      "credits": 625,
      "conditional": false
    }
  ],
  "pricingFactors": {
    "generationPreset": "standard",
    "generationMode": "auto"
  }
}
```

In `review` mode, the final stage is marked `conditional: true` because the client must approve a Preview before Mint starts final work. `estimatedTotal` still includes that stage. Single-stage work such as Audio generation or 3D Model optimization returns one `operation` stage.

Estimates use normalized public factors. For example, Audio returns its normalized `durationSeconds`, Asset Packs return the priced `itemCount`, and existing-resource actions resolve the owned asset before returning an estimate. The request accepts only fields relevant to its `operation`; use the [OpenAPI contract](https://api.mint.gg/openapi.json) for the complete operation union.

Treat the result as advisory. It represents conservative planned reservations, while finalized spend can be lower. The subsequent operation and its `credits` fields are authoritative.

## Credit fields

* `totalAvailable`: Credits currently available for new work.
* `monthlyRemaining`: available included monthly Credits.
* `monthlyAllowance` and `monthlyUsed`: current monthly allocation and settled use.
* `topUpBalance`: available non-monthly Usage Credits.
* `totalReserved`: Credits pending across in-progress work.
* `monthlyReserved`: pending Credits allocated from the monthly allowance.
* `topUpReserved`: pending Credits allocated from the top-up balance.

Available fields do not include pending reservations. The reserved fields explain the capacity temporarily protected for work already accepted by Mint.

## Reservation lifecycle

Mint reserves the displayed Credit amount before paid provider work. A reservation is released when work fails before provider submission, stays reserved while work is active, and settles after provider-backed work completes. Expiration is a last-resort recovery backstop, not the expected waiting time.

Each operation can also expose `credits.estimated`, `credits.reserved`, `credits.finalized`, and `credits.availableAfterReservation`. The available balance is refreshed after both reservations and settlements. Use these operation fields for one request and `GET /v1/usage` for the account-wide view.

If an operation reports `billing_required`, read its `billing.requiredCredits`, `billing.availableCredits`, and `billing.actionUrl`. When the operation already has a Preview or intermediate resource, add Credits or restore billing and call:

```bash theme={null}
curl -X POST https://api.mint.gg/v1/operations/$OPERATION_ID:resume \
  -H "Authorization: Bearer $MINT_API_KEY" \
  -H "Idempotency-Key: resume-$OPERATION_ID"
```

If billing blocked the request before Mint created a resource, retry the original request with the same `Idempotency-Key`. Mint reopens the blocked operation and preserves its operation ID.

This continues the existing operation and preserves any completed Preview or intermediate work.

## API usage

`apiUsage` aggregates API requests and settled Credits for the authenticated Mint account.

* `requestCount` includes authenticated operations that Mint rejects with `billing_required`.
* `succeededCount` and `failedCount` count terminal asynchronous operations. Validation and billing-required responses are not terminal failures.
* `creditsUsed` includes only finalized Credits. It can trail active work until reservations settle.