# Credits and billing

Prepaid API credits at $0.02 with volume bonuses, holds and max_credits, credits_charged, the 402 refusal, auto-recharge, alerts, and expiry.

Source: https://magistermarketing.com/docs/api/credits-and-billing

API calls spend **API credits**: a prepaid balance that belongs to your organization and is billed apart from any Magister plan. Plan credits stay for chat and MCP; API credits are only for API keys, and the API keeps working when a plan's payment is overdue.

**Price** — $0.02 a credit (50 credits per dollar), with 10% more credits from $100 and 20% more from $500. Buy any whole amount from $10 to $2,000. A new API account starts with 300 free credits.

| You pay | Credits | Bonus | You get |
| --- | --- | --- | --- |
| $20 | 1,000 | none | 1,000 |
| $50 | 2,500 | none | 2,500 |
| $100 | 5,000 | +500 (10%) | 5,500 |
| $500 | 25,000 | +5,000 (20%) | 30,000 |
| $2,000 | 100,000 | +20,000 (20%) | 120,000 |

**Buying** — owners and admins choose **Settings → Developers → API billing → Add credits** and pay by card on Stripe Checkout. The credits land as soon as the payment does, and the receipt is listed on the same page. Purchased credits are good for 12 months; the soonest to expire are spent first.

**What a request costs** — a request is charged what it actually used, in credits, and says so in `credits_charged` on every successful response. A request refused before it starts costs nothing; one that fails partway costs what it used. Free endpoints answer `credits_charged: 0`. A job's charge grows while it runs; its final `credits_charged` is on [the job](https://magistermarketing.com/docs/api/jobs-and-webhooks) once it finishes. The `X-Magister-Credits-Remaining` header on each successful response (and on a 402) is your balance.

**Holds** — before a paid request starts, it holds the most it is likely to cost (about twice its usual cost) against your balance. Your **available** credits are the balance less what running requests hold; a request whose hold is more than what is available is refused with a 402, before any provider is called. The hold is released when the request finishes, and only what it used is charged. A run rarely spends past its hold.

| Endpoint | Typical cost (credits) | Holds up to |
| --- | --- | --- |
| POST /v1/brand/extract | about 2, measured per run | 20 |
| POST /v1/web/map | about 1 per map | 4 |
| POST /v1/competitors/discover | about 3 per lookup | 8 |
| POST /v1/keywords/research | about 12 (median of 17 runs, 30 days); a lookup that finds nothing is not billed | 40 |
| POST /v1/audits/site | about 100, measured per run (the full marketing audit) | 240 |

An AI visibility check holds, for each engine, its number of answers times that engine's ceiling (the engines table), plus 3. The default check (3 questions on the 3 default engines) holds up to 57 and usually costs about 22.

**max_credits** — every job endpoint takes `max_credits`. A job whose hold is above it is refused with **402** `limit_reached`, `reason: max_credits_exceeded` and `estimated_credits`, and costs nothing. Use it as a guard against an unexpectedly large request (many questions or engines, for example).

**Out of credits** — a request the balance cannot cover answers **402**:

```json
{
  "error": "limit_reached",
  "reason": "credits_exhausted",
  "message": "Not enough API credits: this request holds up to 33 and 12.5 are available. Add credits to continue.",
  "retryable": false,
  "available_credits": 12.5,
  "top_up_url": "https://magistermarketing.com/developers/billing"
}
```

`GET /v1/credits` (free, `read`) returns `balance`, `held`, `available` and `price_per_credit_usd`.

**Auto-recharge** — save a card (your first purchase saves one) and turn on **Auto-recharge** on API billing: when the balance falls below your threshold (500 credits unless you change it), Magister charges the card the amount you set ($10 to $2,000), at most your monthly limit. Each declined charge emails your owners and admins (or your billing email) and sends an `auto_recharge.failed` webhook event. A declined card is tried once more a day later; a second decline in a row turns auto-recharge off.

**Disputed payments** — disputing a payment for API credits turns auto-recharge off. The disputed card (or a wallet card, such as Apple Pay, that can't be told apart from it) can no longer be saved for auto-recharge; save a different card, or write to [team@magistermarketing.com](mailto:team@magistermarketing.com) if the dispute was a mistake.

**Low-balance alerts** — Magister emails your owners and admins (or the billing email you set) and sends a `balance.low` webhook event once each time the balance falls below your alert threshold (1,000 credits unless you change it). It alerts again only after the balance has gone back above it.

**Usage and requests** — **Settings → Developers → Usage** shows credits per day and per endpoint (with a CSV export), and **Requests** lists every paid or async request with its status, error code and cost.