Wallet & billing

How it works

1. Sign up — your account is created with a one-time grant of 300 credits. No card required.
2. Subscribe — pick Monthly ($5/mo, 1,000 credits per month) or Annual ($54/yr, 12,000 credits granted up front each year) from the dashboard.
3. Call the API — every call deducts its credit cost from your balance UPFRONT (before the LLM runs) so concurrent requests can't drive the balance negative.
4. Partial-success refund — if some providers fail, we refund credits proportionally before returning the response. x-balance-after-cents (unit: credits) always reflects the post-refund balance.
5. Top up when needed — paid plans can buy packs of 1k–100k credits at $4.00 per 1k (monthly) or $3.00 per 1k (annual).

Pricing

Free signup credits

New accounts get 300 credits on first auth, no card required. That's enough for a couple of fresh quick-mode calls plus dozens of cached re-checks — long enough to wire MentionsAPI into your project and decide whether to subscribe. Existing accounts are not retroactively credited.

Plans & top-up packs

Subscriptions and top-ups go through Stripe. Plan credits land automatically on each invoice; top-up packs are one-time charges that land within seconds of confirmation.

Response headers

Every billed endpoint returns the following headers — your code never has to make a separate balance call. The *-cents header names are historical; their unit is credits:

HTTP/1.1 200 OK
content-type: application/json
x-cost-cents: 85
x-balance-after-cents: 8423
x-cache-status: miss
x-mode: perplexity_live
x-ratelimit-limit: 60
x-ratelimit-remaining: 59

402 Payment Required

When your balance falls below the call's credit price, we return 402 with a typed body so your code can branch deterministically. balance_cents and required_cents are expressed in credits. The topup_url deep-links to the billing dashboard.

HTTP/1.1 402 Payment Required
content-type: application/json

{
  "error": "insufficient_balance",
  "message": "Insufficient credits. Subscribe or top up at https://mentionsapi.com/app/billing",
  "balance_cents": 40,
  "required_cents": 85,
  "topup_url": "https://mentionsapi.com/app/billing",
  "request_id": "req_01JBQ2K8H..."
}

Idempotency

Pass an Idempotency-Key header (1–200 chars). Replays within 24h return the original response and DO NOT re-deduct. This is Stripe-style: same key + same body = same response. Same key + different body = 422.

# First call: hits the LLMs, debits 130 credits
curl https://api.mentionsapi.com/v1/check \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Idempotency-Key: my-job-2026-04-25-001" \
  -H "Content-Type: application/json" \
  -d '{"mode":"quick","query":"...","brand":"..."}'

# Replay within 24h: returns the same response, debits 0 credits
curl https://api.mentionsapi.com/v1/check \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Idempotency-Key: my-job-2026-04-25-001" \
  -H "Content-Type: application/json" \
  -d '{"mode":"quick","query":"...","brand":"..."}'

Partial-result credits

When a multi-provider call (e.g. 4-provider mode:quick) partially fails — k of n engines return — the difference is automatically credited back to your wallet (a partial-result credit): cost = (success_count / requested_count) × mode_price. You only pay for what succeeded. The credit hits your wallet before the response returns; the x-balance-after-cents header is always the final post-credit value, in credits. If 0 of N providers succeed, the credit is 100%. Cached repeats settle at the cached price automatically — no action needed on your side.

Tracking spend

Use GET /v1/usage to pull aggregated credit cost by endpoint, by provider, by mode, with day or hour granularity. Free, no rate limit. Wire it into your monitoring stack to alert on burn deltas before they become budget surprises.