Document credit exhaustion per plan and complete the scrape modifier table

[rakshith48]

Summary

Two additions to billing.mdx, both read from code rather than from prose elsewhere. Draft because the exhaustion section states billing behavior that Billing should ratify before it goes live (checklist at the bottom).

1. Running Out of Credits becomes a per-plan, per-setting table and names the overage allowance a paid plan carries while pay-as-you-go is on.
2. Additional credit costs for scrape options gains the modifiers the API bills that the table did not list, and an explicit row saying enhanced proxies carry no surcharge.

Plus a one-sentence note explaining the 5,000 / 6,500 / 8,000 style cells in the paid plans table.

Why

Pricing agent-listening report, session ax-orch-20260908-084522, 24 buyer questions across 6 agents.

Finding 1 (credit exhaustion), the most consequential disagreement in the study. Asked "what happens if I go over my credit limit", agents answered three incompatible ways: hard stop with 402 (codex), automatic overage billing by default (sonnet), and hard stop unless opt-in recharge (opus). The page on origin/main says only:

If your credits run out and pay-as-you-go is off, requests that consume credits return an HTTP 402. If pay-as-you-go is on, we add a new 5 USD increment of credits when your balance reaches zero.

That is true but incomplete. It does not say what happens when the monthly pay-as-you-go limit is reached, and it does not mention the overage allowance, so an agent that sees a balance go negative has no owned source to explain it.

Finding 3 (modifier disagreement). Agents agree on the 1-credit base and disagree on modifiers, quoting the same plan as up to 5x more expensive. Third-party pages still say "Stealth Mode is a 5x cost multiplier". docs/features/enhanced-mode says 1 credit, but billing.mdx, the page an agent lands on for cost questions, never mentioned enhanced proxies at all, and omitted several +4 modifiers documented only on features/scrape.mdx and features/pii-redaction.mdx.

Sources for every figure

Statement	Source
Free: 402 at zero, no pay-as-you-go	already on this page (#free-plan)
Paid, pay-as-you-go off ($0 limit): 402, no charge	firecrawl-web utils/autumn/billing-controls.ts, PAYG branch: topUpsEnabled = effectiveDollars !== 0, overageAllowed.enabled: topUpsEnabled
Paid, pay-as-you-go on: one 5 USD increment at zero, repeated until the monthly limit (purchaseLimit in batches per month; null = no cap)	same file, autoTopups[0].threshold: 0, purchaseLimit.limit: batchLimit
Overage allowance 1,500 / 30,000 / 150,000 / 600,000 by tier	firecrawl-web lib/billing/payg.ts:197-202, PAYG_PLAN_OVERAGE_CREDITS, applied as spendLimits[0].overageLimit in billing-controls.ts
"headroom, not extra credits you keep"	the doc comment on PAYG_PLAN_OVERAGE_CREDITS
Manual purchases do not count toward the limit	already on this page (#how-the-limit-caps-your-monthly-spend)
question/query, highlights, audio, video: +4 each	firecrawl apps/api/src/lib/scrape-billing.ts:187-204
redactPII: +4, plus +4 per extra PDF page	scrape-billing.ts:224-234; matches features/pii-redaction.mdx:85-87
lockdown cache hit +4 (5 total), miss 1 credit	scrape-billing.ts:142-144 and :111-115; matches features/lockdown.mdx:67-70
Enhanced proxy +0, escalated retry not charged separately	firecrawl 2a0182d56 (2026-08-17, "Stop charging the +4 credit surcharge for enhanced proxies (#4324)"); matches features/enhanced-mode.mdx:51

Changes

• billing.mdx only. English source; locales are generated per the repo guideline.
• ## Running Out of Credits: heading and anchor unchanged (linked from #free-plan). The two sentences become a three-row table plus two paragraphs. The "To resume usage" list is kept.
• ### Additional credit costs for scrape options: eight rows added, one worked example added (JSON + PII = 9).
• ### Paid plans: one sentence under the table explaining multi-figure cells.

For Billing to confirm before undrafting

• The allowance applies on all four paid tiers while top-ups are enabled. Code says so (Hobby 1,500, Standard 30,000). Internal understanding was "Growth and above"; if Hobby/Standard should not be public, the sentence needs trimming, not the code.
• How usage inside the allowance is settled (next top-up, next invoice, or written off). The page deliberately does not say.
• Accounts on the legacy Smart Upgrade or auto-recharge billing models follow different branches in billing-controls.ts and are not described here. Confirm that is acceptable for the public page, or add a line pointing them at help@.
• Whether the hit-side lockdown cost belongs in the modifier table or only on features/lockdown.mdx.

Verification

• Every linked page exists on origin/main: features/scrape.mdx, features/pii-redaction.mdx, features/lockdown.mdx, features/enhanced-mode.mdx. Anchors reused (#pay-as-you-go, #free-plan, #running-out-of-credits) are unchanged.
• No mintlify CLI on this machine, so broken-links / validate were not run; the diff is plain Markdown tables and paragraphs with no new components.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
firecrawl	🟢 Ready	View Preview	Sep 9, 2026, 8:59 AM

💡 Tip: Enable Automations to automatically generate PRs for you.