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, and the check_usage tool of the 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:

429 Too Many Requests

"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. Plans, credit packs and billing are explained in Plans and payments.

Check the balance from an agent

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

{
  "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

Estimate cost

Know a run’s price before it spends.

Authentication

Create keys with a monthly cap.

How credits work

What credits buy across Percify.

Not enough credits

Fix a blocked generation.