Your balance changes for two kinds of reasons: credits added or removed (a pack you bought, your monthly allocation, an adjustment) and credits spent on work. The credit ledger records the first kind; usage history records the second. Together they explain your balance.
Two balances
Your credits sit in two pools, shown together as one balance on Credits & billing:
| Pool | Where it comes from | Expires |
|---|---|---|
| Plan credits | Your subscription's monthly allocation | At the end of each billing cycle. Unused plan credits don't roll over |
| Pack credits | Credit packs you buy | Never |
Plan credits are spent first, then pack credits.
What the ledger records
| Entry | Meaning |
|---|---|
| Credit pack purchase | A pack you bought: pack credits added |
| Monthly allocation | Your plan's credits for the new cycle |
| Credits expired | Plan credits left over at the end of a cycle, or after a cancelled plan's last paid period ended |
| Adjustment | Credits added or removed by our team, for example a goodwill credit or a correction |
| Email finder, LinkedIn lookup | Credits held when a search starts |
| Email finder refund, LinkedIn lookup refund | Credits returned when the result cost less than was held, or nothing was found |
Each entry has the amount (positive when added, negative when removed), which pool it affected, the balance of that pool after the change, a short description and the date.
How holds and refunds work
Some actions hold the most they could cost while they run, then return the difference when they finish. For example, an email search may hold the price of a found email; if nothing is found, the hold is returned in full. While work runs, your balance can look lower than you expect. It settles when the work finishes.
Read the ledger
The ledger is available through the API:
curl "https://api.filtrat.io/v1/billing/ledger?page=1&limit=50" \
-H "Authorization: Bearer ak_your_key"Entries come newest first, up to 200 per page. Each one looks like this:
{
"id": "…",
"event_type": "subscription_grant",
"balance_kind": "subscription",
"amount": 25000,
"balance_after": 25000,
"description": "…",
"created_at": "2026-10-01T00:00:12"
}For your plan and both balances at once, use GET /v1/billing/status. It returns subscription_credits_balance, payg_credits_balance, total_balance, your plan and when the current period ends.
Reconciling your balance
To check where credits went over a period:
- Start from your balance at the beginning.
- Add the ledger's purchases, allocations and positive adjustments.
- Subtract expired credits and the total in usage history for the period.
If the numbers don't match, or you think something was charged twice, see Credits missing or charged twice.
Invoices
Payments and invoices are separate from the ledger. You'll find them on Credits & billing. See Invoices, upgrades and cancelling.