API Documentation
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.
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 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:
{
"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 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.