Firecrawl's Crawl Limit, Credit Pre-Check and Webhooks for AI Agents: What the Docs Say

Last fact-checked: November 17, 2026

Advertising disclosure: we may receive a commission if you sign up through the Firecrawl † links marked † in this article, at no extra cost to you. We have not run production workloads on Firecrawl; everything below comes from its official documentation. See our Advertising Disclosure.

Note on experience: we have not run Firecrawl crawls, tested its webhooks or measured its credit use. Pages were read through a web-fetch tool that summarises them, on November 17, 2026. Check the live docs before relying on any statement. "Not stated" means the page we read did not say.

An AI agent that is told to "crawl this docs site" can turn one call into thousands of billable pages. Firecrawl † documents a few controls that decide how far one crawl can go and how you find out what happened: a limit, a credit check before the crawl starts, async job status, and webhooks. This article lays out what the docs state, where two pages differ, and what they leave out. For credit prices per feature, see our earlier article on Firecrawl credits; here we only use the numbers the crawl page itself gives.

1. The one cap the docs describe: limit

The crawl page describes limit as the "maximum number of pages to crawl", and the API reference lists its default as 10000. So a crawl request that omits limit is allowed to run to 10,000 pages. The crawl page says each crawled page consumes 1 credit, with JSON mode adding 4 credits per page and PDF parsing costing 1 credit per PDF page. By those numbers, a default-limit crawl of a large site is a five-figure credit event if every page is returned.

Other parameters in the API reference narrow what gets crawled rather than what it may cost: includePaths and excludePaths (arrays of regex strings, up to 1,000 each), maxDiscoveryDepth, allowExternalLinks (default false), allowSubdomains (default false) and crawlEntireDomain (default false). The page describes maxDiscoveryDepth as hops from the root URL, not path segments; pages at the maximum depth are still scraped but their links are not followed. The default for maxDiscoveryDepth is not stated.

No credit-cap parameter is documented on the crawl pages we read. The only cost control described is limit, plus the pre-check below.

2. A credit check before the crawl starts

The crawl page says the endpoint checks that your remaining credits cover the limit before starting; if they do not, it returns a 402 (Payment Required), and it advises setting a lower limit to avoid this. The API reference lists 402 as a response code of the crawl endpoint.

What this means for an agent, as our reading rather than vendor guidance: a 402 on a crawl can come from a high limit against a low balance, even when the site itself is small. Lowering limit is the documented remedy. Whether the check reserves credits, and whether the check compares against limit alone or against limit times per-page add-ons, is not stated.

3. Async status: what to poll and what not to trust

POST /v2/crawl returns a job ID; you poll GET /v2/crawl/{id}. The crawl page lists the statuses scraping, completed, failed and cancelled; the status endpoint's field list shows three values and mentions cancelled only in the description of completedAt, so the two pages are not fully consistent. The status response includes total, completed, creditsUsed and expiresAt.

Three details matter to an agent loop:

4. Cancelling a crawl

The crawl page lists cancelled as a status but describes no way to cancel. The API reference has a separate cancel endpoint: DELETE /crawl/{id}, returning 200 with "status": "cancelled" on success and 404 if the job is not found. Whether credits already consumed are refunded is not stated.

5. Webhooks

Where the pages differ. The crawl page says a page Firecrawl could not scrape arrives with success: false and an error message. The events page we read says how failed pages appear is not stated. If your agent treats a missing crawl.page as "page skipped", check the live docs and the Get Crawl Errors endpoint first.

6. A cautious checklist (our reading, not vendor guidance)

7. What we could not confirm

† Referral link (Firecrawl). Related: ScraperAPI's max_cost and async jobs, retry budgets, burst limits.

Sources (checked November 17, 2026)

Not sure which article you need? See the task-by-task chooser.