Credits and balances
How Piloterr credits work, and how to top up your balance.
Every billable call spends credits from your workspace. The dashboard Usage panel under Settings → Subscription shows three balances. The API usage endpoint reports a combined runway so you can alert from code without parsing every bucket.
Usage
Current period38,400
10,000
3,780
Subscription
Pro · renews on the 1st
The three balances
| Balance | What it is | Resets |
|---|---|---|
| Subscription quota | API calls included in your plan | Yes — at the start of each billing period (from Stripe when available, otherwise the calendar month). Unused quota does not roll over. |
| One-time API pack | Additional API quota from a one-time purchase | Never — consumed until depleted, across billing periods |
| Pay-as-you-go credits | A separate ledger used only after subscription quota and API packs are empty | Never — grants stay until spent |
In the dashboard those three bars appear under Settings → Subscription → Usage (and in the sidebar API usage panel). On the usage endpoint (/v2/usage), the subscription object is the combined API quota (subscription + remaining packs). Pay-as-you-go sits under credits. Top-level remaining is both added together.
Consumption order
Subscription quota first
Billable calls fill the plan allowance for the current period.
Then one-time API packs
When the period allowance is used up, remaining pack quota is consumed next. Packs are attributed in purchase order.
Then pay-as-you-go credits
Only if the combined API quota cannot cover the endpoint cost do we debit the pay-as-you-go ledger.
Otherwise the call is refused
The API returns 402 with Payment required, and the request is not executed.
What gets billed
| Outcome | Credits |
|---|---|
200 or 201 (successful / accepted billable response) | Yes — the endpoint's credit cost |
404 | Usually yes — unless that endpoint marks 404 as free (shown in the Library and on the endpoint page) |
401, 402, 400, 5xx, and most other errors | No — and any pay-as-you-go hold is released |
| Per-row endpoints with 0 results | Free |
| Per-row endpoints with N results | N × the per-row cost — all or nothing (insufficient balance → 402 before any rows are returned) |
/v2/usage and job status URLs | Always free — no quota check |
Each endpoint declares its cost in the Library (and in the API reference): N credits per call or per row. The balance is checked before the work starts, so a job is never accepted without the credits to pay for it. Polling a job status never costs credits.
Buy more capacity
Open subscription settings
Go to Settings → Subscription and click View all plans (or open https://app.piloterr.com/pricing).
Pick a one-time pack
Depending on the product, a pack adds to API quota (one-time API pack) or to the pay-as-you-go ledger. It never changes your subscription tier by itself. Larger packs usually cost less per credit.
Confirm the payment
Capacity is available as soon as payment succeeds, and an invoice is emailed to the billing address.
Purchased packs also appear under Settings → Subscription → One-time packs. To refill automatically when the combined balance drops, see Auto top-up.
Where to read history
| Screen | What it shows |
|---|---|
| Settings → Subscription → Usage | Live remaining / used for the three balances in the current period |
| API Logs | Every request with status, duration, and credits charged — including subscription and pack usage |
| Settings → Credits | The pay-as-you-go ledger only: grants (rewards, some pack types, auto top-up) and spends that happened after API quota was empty. Filter by member or type. |
Usage endpoint (/v2/usage) | Machine-readable snapshot: remaining, subscription, credits, renewal_date — free to call |
If Settings → Credits looks empty while Analytics shows traffic, that is expected: subscription and pack consumption never appear on that page. Use API Logs or the Usage bars instead.
When you see 402
| Message | Meaning | What to do |
|---|---|---|
Payment required | No subscription quota, packs, or pay-as-you-go left for this call's cost | Buy a pack, upgrade the plan, or enable auto top-up |
You have open invoices: … | An unpaid invoice is blocking the account | Settle it under Settings → Invoices — balance alone is not enough |
Insufficient credits: X required, Y available | A per-row endpoint would return more rows than you can afford | Top up, or narrow the request so fewer rows come back |
FAQ
- Does unused plan quota roll over? No. The subscription bucket resets each billing period.
- Do one-time packs expire at month end? No. They stay until consumed.
- Do all keys share the same balances? Yes — quota is workspace-wide.
- Does checking usage cost credits? No.
/v2/usageand job status paths are free. - Why is dashboard Usage split but
/usage.subscriptioncombined? So a singleremainingnumber is enough for alerts; open the dashboard when you need the three-way split.