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

# Check credits and usage for the Percify API

> See your Percify credit balance, monthly API spend and per-key caps on the developer page, in each creditsSpent field, or with the MCP check_usage tool.

Percify API calls spend the same credits as the app, from your account balance. The REST API has no balance endpoint, so you track spending in three places: the `creditsSpent` field on every generation, the stats on the developer page at [app.percify.io/home/developer](https://app.percify.io/home/developer), and the `check_usage` tool of the [MCP server](/mcp-server), which returns your remaining balance.

## Where to see what you spent

| Where                                                           | What it shows                                                                            |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `creditsSpent` in `POST /v1/run` and `GET /v1/generations/{id}` | Credits charged for that run. Failed runs show the amount that was refunded.             |
| Developer page stat cards                                       | **Credit balance**, **Used this month**, **API runs** (last 14 days) and **Active keys** |
| Developer page **Usage trends**                                 | Credits spent per day over the last 14 days                                              |
| Developer page **Recent activity**                              | Each run's status, model, audio length, cost, duration, start time and run id            |
| Each key in **API keys**                                        | Credits that key used this month, against its **Monthly credit cap** when one is set     |
| MCP tool `check_usage`                                          | `remainingCredits`, `monthCredits`, `monthRuns`, `monthApiRuns` and `topUpUrl`           |

Monthly figures count the current calendar month. **Used this month** and `monthCredits` leave out failed runs, whose credits were refunded.

## Cap what a key can spend

Set a **Monthly credit cap** when you create a key on the developer page. A run that would take the key past its cap is refused before it is charged:

```json 429 Too Many Requests theme={"system"}
"API key monthly credit limit reached (500 credits)."
```

The count resets at the start of each calendar month. To change a cap, create a new key with the new cap and revoke the old one.

## What happens when credits run out?

A run your balance cannot cover is refused with `400` and nothing is charged. The `message` starts with `Not enough credits`, then names the credits the run needs, your current balance and the top-up link `https://app.percify.io/billing`.

Add credits with **Top up credits** on the developer page or at [app.percify.io/billing](https://app.percify.io/billing). Plans, credit packs and billing are explained in [Plans and payments](/percify/payments).

## Check the balance from an agent

MCP clients can ask for the balance directly. A `check_usage` call returns JSON like this:

```json theme={"system"}
{
  "remainingCredits": 2140,
  "monthCredits": 860,
  "monthRuns": 57,
  "monthApiRuns": 41,
  "topUpUrl": "https://app.percify.io/billing"
}
```

`monthApiRuns` counts runs started with an API key. `monthRuns` also counts generations started in the Percify app.

## Related

<CardGroup cols={2}>
  <Card title="Estimate cost" href="/api-reference/generations/estimate">
    Know a run's price before it spends.
  </Card>

  <Card title="Authentication" href="/percify/api-auth">
    Create keys with a monthly cap.
  </Card>

  <Card title="How credits work" href="/percify/credits">
    What credits buy across Percify.
  </Card>

  <Card title="Not enough credits" href="/troubleshooting/not-enough-credits">
    Fix a blocked generation.
  </Card>
</CardGroup>