firecrawl-efficiency

Get the content the user needs from Firecrawl for the fewest credits, and never let one request spend more than the user agreed to.

Prices and behaviour are a 2026-10-18 snapshot of the billing docs plus paid spikes. The documented plans, credit costs and rate limits were re-read against the billing, pricing and rate-limits pages on 2026-11-10 and are unchanged; the paid-spike observations were repeated on 2026-11-11 and matched. Firecrawl changes pricing often (its own pages disagreed on four points that day). When a figure matters and looks stale, check https://docs.firecrawl.dev/billing and the response's creditsUsed, trust those, and report the discrepancy.

Hard rules

Never use /agent in any form: REST /v2/agent, MCP firecrawl_agent / firecrawl_agent_status, CLI firecrawl agent, SDK agent() / start_agent / startAgent, or "parallel agents". It bills dynamically (a few hundred credits per run, maxCredits default 2,500), and the docs' own example costs 100–500 credits for what one scrape does for 1. If the user names it, explain this and offer the scrape/map route instead.
Never use /extract (token-billed, includeSubdomains on by default, and its docs push you to /agent) or the deprecated v1 deep-research and llmstxt endpoints.
Never send premium or provider-routed hosts: x.com, twitter.com, their subdomains and short-link/media hosts (t.co, twimg.com), and linkedin.com/lnkd.in. X costs 30 credits a request through Grok and LinkedIn 5–40 through data providers, and policy excludes them. Do not route around this with redirects, mirrors, or proxies. If a hostname's premium status is uncertain, do not send it to Firecrawl; use another permitted method.
Price before you spend. For anything beyond a single markdown scrape, run the guard and respect a nonzero exit:
```
python3 <skill-dir>/scripts/firecrawl_guard.py estimate crawl request.json --budget 100
```
It prints a worst-case credit figure and exits 0 ok, 2 warnings (read them), or 3 blocked (do not send). It refuses /agent, /extract, premium hosts, crawls without limit, and anything whose worst case exceeds --budget or cannot be bounded.
Confirm large spends. Before a job whose worst case is over 100 credits or over 5% of the balance, check the balance (firecrawl_guard.py balance, free) and tell the user the figure. Authorization for one job does not cover retries or a bigger one.