Debug Firecrawl with Ask

Agentic debugging for your Firecrawl integration

Firecrawl /support/ask is an AI support agent exposed as an API. Describe your issue and get back a verified diagnosis with actionable fix parameters, typically in 15–30 seconds.

Think of /support/ask as a senior Firecrawl engineer on-call for your agent.

INFO

The Ask API is designed primarily for AI agent callers. If you're building agents that use Firecrawl for scraping, crawling, or data extraction, wire /support/ask into your error-handling flow for autonomous issue resolution.

Two endpoints

Endpoint	Auth	Who it's for	What it does
POST /support/ask	Your Firecrawl API key	Your agents and apps	Full diagnostic loop scoped to your team
POST /support/docs-search	Your Firecrawl API key	Your agents and apps	Docs-grounded answers from Firecrawl's public documentation

Quick start

Debug a failing crawl

curl -X POST https://api.firecrawl.dev/v2/support/ask \
-H "Authorization: Bearer fc-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "question": "my crawl returned 3 pages but I expected 50"
}'

Search the docs

curl -X POST https://api.firecrawl.dev/v2/support/docs-search \
-H "Authorization: Bearer fc-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "question": "how do I set up webhook signature verification?"
}'

How it works

When you call /support/ask, the AI agent:

1. Gathers evidence, inspects your job logs, account state, credit usage, and relevant documentation in parallel
2. Diagnoses the issue, reasons across all evidence to identify the root cause
3. Proposes a fix, generates machine-actionable fixParameters you can apply directly to your next API call
4. Validates the fix, when possible, tests the fix against the live Firecrawl API (e.g., retrying a scrape with adjusted parameters) and reports the result

Using Ask in your agent

The key design pattern: call /support/ask when your Firecrawl API call fails or returns unexpected results, then use the fixParameters to retry.

Python example

import requests

FIRECRAWL_API_KEY = "fc-YOUR_API_KEY"

def diagnose_firecrawl_issue(question, rationale=None):
  """Call the Firecrawl Ask API to debug an issue."""
  payload = {"question": question}
  if rationale:
      payload["rationale"] = rationale

  response = requests.post(
      "https://api.firecrawl.dev/v2/support/ask",
      headers={
          "Authorization": f"Bearer {FIRECRAWL_API_KEY}",
          "Content-Type": "application/json",
      },
      json=payload,
  )
  return response.json()

# Example: debug a scrape that returned empty content
result = diagnose_firecrawl_issue(
  question="scrape returned empty markdown for https://example.com",
  rationale="user needs product pricing data for competitive analysis",
)

print(result["answer"])
print(result["fixParameters"])  # e.g., {"waitFor": 5000, "actions": [...]}
print(result["confidence"])     # "high", "medium", or "low"

Node.js example

async function diagnoseFirecrawlIssue(question, rationale) {
const response = await fetch(
  "https://api.firecrawl.dev/v2/support/ask",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FIRECRAWL_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ question, rationale }),
  }
);
return response.json();
}

// Example: debug a crawl that stopped early
const result = await diagnoseFirecrawlIssue(
"my crawl returned 3 pages but I expected 50",
"user is on their third failed crawl attempt today"
);

console.log(result.answer);
console.log(result.fixParameters);

Agent retry pattern

from firecrawl import Firecrawl

client = Firecrawl(api_key="fc-YOUR_API_KEY")

# Step 1: Try the scrape
doc = client.scrape("https://example.com/pricing", formats=["markdown"])

if not doc.markdown or len(doc.markdown) < 100:
  # Step 2: Ask for help debugging
  diagnosis = diagnose_firecrawl_issue(
      question=f"scrape returned only {len(doc.markdown or '')} chars of markdown for https://example.com/pricing",
  )

  # Step 3: Apply fix parameters and retry
  if diagnosis.get("fixParameters"):
      doc = client.scrape(
          "https://example.com/pricing",
          formats=["markdown"],
          **diagnosis["fixParameters"],
      )

Parameters

/support/ask

Parameter	Type	Required	Description
question	string	Yes	What to debug (1–8,000 characters)
rationale	string	No	Recommended for AI callers. What the end user is trying to accomplish. Helps prioritize evidence gathering.
context	object	No	Free-form metadata from your agent, included in the debugging prompt

/support/docs-search

Parameter	Type	Required	Description
question	string	Yes	The question to answer (1–8,000 characters)

Response

/support/ask response

{
"requestId": "req_...",
"answer": "<2-4 sentence prose diagnosis of the issue plus the recommended fix.>",
"confidence": "high",
"fixParameters": { "<param>": "<value>" },
"validation": {
  "tested": true,
  "result": "success",
  "evidence": "<short summary of the validation tool call the agent ran to confirm the fix>"
},
"feedback": null,
"durationMs": 18432
}

The actual answer, fixParameters, and validation.evidence are produced per request by the agent based on your specific run; the example above shows the response shape, not a real diagnosis.

/support/docs-search response

{
"requestId": "req_...",
"answer": "The signature is sent in the X-Firecrawl-Signature header...",
"evidence": [
  { "pathOrUrl": "webhooks/security.mdx#L1-L52", "reason": "..." }
],
"usage": { "inputTokens": 4356, "outputTokens": 688, "totalTokens": 5044 },
"durationMs": 11252
}

Performance

Metric	Typical	Maximum
Latency	15–30 seconds	60 seconds (hard ceiling)

API Reference

• Ask endpoint API Reference
• Docs Search endpoint API Reference

Have feedback or need help? Email help@firecrawl.com.

Are you an AI agent that needs a Firecrawl API key? See firecrawl.dev/agent-onboarding/SKILL.md for automated onboarding instructions.