Firecrawl MCP Server

Overview Schema Source Related Servers Discussions Admin

Firecrawl crawl status

firecrawl_check_crawl_status

Read-only

Retrieve the current status, progress, and available results for an existing crawl ID without starting or modifying the crawl.

Instructions

Retrieve the current status, progress, and available results for an existing crawl ID. This only reads Firecrawl job state and does not start or modify the crawl.

Input Schema

Name	Required	Description	Default
`id`	Yes

Output Schema

Name	Required	Description
`id`	No	Crawl identifier, for `firecrawl_check_crawl_status`.
`url`	No	The URL the crawl started from.
`data`	No	Scraped documents collected by the crawl.
`next`	No	URL of the next page of results, when the data is paginated.
`error`	No	Error message or error object when the call did not succeed.
`total`	No	Pages the crawl expects to visit.
`status`	No	Crawl state, such as `scraping`, `completed`, or `failed`.
`success`	No	Whether the API call succeeded.
`warning`	No	Non-fatal warning about the result.
`completed`	No	Pages crawled so far.
`expiresAt`	No	When the crawl results expire.
`creditsUsed`	No	Credits the crawl consumed.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.0.2Oct 29, 2026

changedInput schema / $schema

Previous value: -"https://json-schema.org/draft/2020-12/schema"New value: +"http://json-schema.org/draft-07/schema#"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "description": "Crawl job state and the documents collected so far.",
+  "properties": {
+    "completed": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Pages crawled so far."
+    },
+    "creditsUsed": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Credits the crawl consumed."
+    },
+    "data": {
+      "description": "Scraped documents collected by the crawl."
+    },
+    "error": {
+      "description": "Error message or error object when the call did not succeed."
+    },
+    "expiresAt": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "When the crawl results expire."
+    },
+    "id": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Crawl identifier, for `firecrawl_check_crawl_status`."
+    },
+    "next": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "URL of the next page of results, when the data is paginated."
+    },
+    "status": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Crawl state, such as `scraping`, `completed`, or `failed`."
+    },
+    "success": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Whether the API call succeeded."
+    },
+    "total": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Pages the crawl expects to visit."
+    },
+    "url": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The URL the crawl started from."
+    },
+    "warning": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Non-fatal warning about the result."
+    }
+  },
+  "type": "object"
+}

First observedv1.0.1Jul 5, 2026

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and the description's 'only reads Firecrawl job state' largely restates them. It does add the useful fact that results become available incrementally with progress, but says nothing about polling cadence, terminal states, or behavior on an expired/invalid ID.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the operation and followed by the scope boundary. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be explained, and the read-only, non-mutating nature is covered. The only real gap is polling/terminal-state guidance, which is minor for a status-read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the id parameter, and it does clarify that it is an 'existing crawl ID' rather than a URL or job name. It adds no detail on where such an ID comes from or its expected format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Retrieve') plus resource ('current status, progress, and available results') scoped to an existing crawl ID, which distinguishes it from the starting tool. It stops short of naming firecrawl_crawl explicitly, so sibling differentiation is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'for an existing crawl ID' implies this is a follow-up to starting a crawl and that a valid ID is a prerequisite. It never says when to prefer this over firecrawl_crawl or what to do if no crawl exists yet, leaving the workflow to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.