What happens when my credit balance is too low?

If your balance is below the worst-case fresh cost of the call you’re making, we return 402 insufficient_credits before dispatching the fan-out. The response body includes balance_cents and required_cents (both in credits) so your client can surface exactly how many credits are needed.

Billing

Q: What unit is MentionsAPI billing measured in?

Every priced response carries a usage.cost_cents field — that’s how many credits came out of your balance (the field name predates the credit model; its unit is credits). Credits are whole numbers (no fractional billing). A call that costs 250 credits debits exactly 250 credits.

Q: Am I charged when a call fails?

If zero providers succeed, you are not charged — cost_cents is 0. On partial success (e.g. 3 of 4 engines returned), the difference is automatically credited back to your wallet before the response returns — a partial-result credit. You only pay for what succeeded; no support ticket needed.

One pricing model, in credits, measured per call. Your plan grants credits every cycle (Monthly $5 → 1,000 credits, Annual $54 → 12,000 credits); each call debits cost_cents — the field name is historical, the unit is credits — from your balance. No invoices, no overage math, no guessing.

The unit: credits

Every priced response carries a usage.cost_cents field — that's how many credits came out of your balance (the field name predates the credit model; its unit is credits). Credits are whole numbers (no fractional billing). A call that costs 250 credits debits exactly 250 credits.

/v1/ask price ladder

Shape	Per call
Cache hit (any tier)	5 credits
Single provider, no web search	15 credits
Single provider, with web search	60 credits
Multi-provider (2–4), no web search	75 credits
Multi-provider (2–4), with web search	250 credits

Every API call deducts its credit cost from your balance. See the pricing page for plans and the full per-call credit table.

Other endpoints

GET /v1/mentions/search — flat 35 credits per call.
POST /v1/mentions/crawl — flat 650 credits per call.
POST /v1/extract_brands, GET /v1/usage, GET /v1/ask/:id, and all /v1/keys / /v1/webhooks / /v1/monitors management calls — free.

Failed calls & partial-result credits

If zero providers succeed, you are not charged — cost_cents is 0. On partial success (e.g. 3 of 4 engines returned), the difference is automatically credited back to your wallet before the response returns — a partial-result credit. You only pay for what succeeded; no support ticket needed. Cached repeats settle at the cached price automatically.

Insufficient credits

If your balance is below the worst-case fresh cost of the call you're making, we return 402 insufficient_credits before dispatching the fan-out: "Insufficient credits. Subscribe or top up at https://mentionsapi.com/app/billing". The response body includes balance_cents and required_cents (both in credits) so your client can surface exactly how many credits are needed.

Reading your usage

GET /v1/usage returns request counts, cache-hit counts, error counts, and per-provider breakdowns over any window you ask for. Use it to drive in-app meters or to reconcile credit burn against your plan's grants.

Getting more credits

Subscribe or buy top-up packs from the dashboard billing page. Plans grant credits every cycle; top-up packs (1k–100k credits, $4.00 per 1k on monthly, $3.00 per 1k on annual) require an active paid plan. The balance is held in the same credit unit the API returns, so what you see in the response and what you see in the dashboard are the same numbers.