Skip to main content
Canonical Firecrawl curl source of truth for agents. Aligned with api-reference/v2-openapi.json (server base URL https://api.firecrawl.dev/v2).

​
Authenticate

Every request requires a Bearer token in the Authorization header.

​
When To Use What

  • search: use when you start with a query and need discovery.
  • scrape: use when you already have a URL and want page content.
  • interact: use when the page needs clicks, forms, or post-scrape browser actions.
  • support/ask: use when a Firecrawl API call fails or returns unexpected results and you need a diagnosis.
  • support/docs-search: use when you need to look up Firecrawl documentation.

​
Why use it

Use search to discover relevant pages from a query, then pick URLs to scrape or interact with. You can constrain results to a site with site:, for example site:docs.firecrawl.dev crawl webhooks.

​
Endpoint

POST /search

​
Simple Example

​
Complex Example

​
Response

  • data.web, data.images, data.news: result arrays; which keys appear depends on sources (by default only data.web is populated).
  • Web and news items include fields such as title, url, and (when scrapeOptions / formats request it) markdown, html, rawHtml, links, screenshot, audio, video, and metadata.
  • Image items include title, imageUrl, url, imageWidth, imageHeight, and position.
  • warning: optional human-readable notice (nullable).
  • id: search job id string.
  • creditsUsed: integer credits charged for the call.

​
Parameters

  • query
    • Type: string (required, max length 500)
    • Use when: you need a search query.
    • Notes: use site:example.com to limit results to a domain.
  • limit
    • Type: integer (minimum 1, maximum 100, default 10)
    • Use when: you want to cap results per source type.
  • sources
    • Type: array of typed source objects (default [{"type": "web"}])
    • Use when: you want to control which sources are searched.
    • Confirmed object shapes:
      • { "type": "web" } with optional per-source tbs and location
      • { "type": "news" }
      • { "type": "images" }
  • categories
    • Type: array of typed category objects (default [])
    • Use when: you want to filter results by category.
    • Confirmed object shapes:
      • { "type": "developer" }
      • { "type": "research" }
      • { "type": "pdf" }
  • includeDomains
    • Type: array of strings (hostnames, no protocol or path)
    • Use when: you want to restrict results to specific domains.
    • Notes: cannot be used with excludeDomains.
  • excludeDomains
    • Type: array of strings (hostnames, no protocol or path)
    • Use when: you want to exclude results from specific domains.
    • Notes: cannot be used with includeDomains.
  • tbs
    • Type: string
    • Use when: you need a time-based filter.
    • Values: qdr:h (hour), qdr:d (day), qdr:w (week), qdr:m (month), qdr:y (year), cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY (custom range), sbd:1 (sort by date). Combinable, e.g. sbd:1,qdr:w.
  • location
    • Type: string
    • Use when: you want localized results (e.g. "San Francisco,California,United States").
  • country
    • Type: string (default "US")
    • Use when: you want ISO 3166-1 alpha-2 geo-targeting (e.g. "US", "DE").
  • safe
    • Type: boolean
    • Use when: you want to filter explicit content (SafeSearch). Omit for default (no filter).
  • timeout
    • Type: integer (milliseconds, default 60000)
    • Use when: you need a request timeout.
  • ignoreInvalidURLs
    • Type: boolean (default false)
    • Use when: you want to drop URLs that cannot be scraped by other Firecrawl endpoints.
  • highlights
    • Type: boolean (default true)
    • Use when: you want query-relevant highlights in results. Set false for provider descriptions/snippets without highlighting.
  • enterprise
    • Type: array of strings ("anon" or "zdr")
    • Use when: you need enterprise zero-data-retention search.
    • Values:
      • "zdr": end-to-end zero data retention (10 credits / 10 results)
      • "anon": anonymized zero data retention (2 credits / 10 results)
  • scrapeOptions
    • Type: object (full ScrapeOptions, default {})
    • Use when: you want to scrape each search result (see Scrape parameters for all fields).
  • threatProtection
    • Type: object
    • Use when: you need a per-request threat-protection override (enterprise). See threatProtection under Scrape parameters.

​
Scrape

​
Why use it

Use scrape when you already have a URL and want structured content in one or more formats.

​
Endpoint

POST /scrape

​
Simple Example

​
Complex Example

​
Response

  • markdown, summary, html, rawHtml, screenshot, audio, video, links: present based on requested formats.
  • actions: when the request included scrape-time actions, contains ordered results such as screenshots, scrapes, javascriptReturns, and pdfs.
  • metadata: page metadata (title, sourceURL, url, statusCode, error, and other extracted fields).
  • warning: optional extraction or formatting notice.
  • changeTracking: present when the changeTracking format is requested.

​
Parameters

  • url
    • Type: string (URI format, required)
    • Use when: you want to scrape a specific page.
  • formats
    • Type: array of format strings or format objects (default ["markdown"])
    • Use when: you want one or more output formats.
    • Format types:
      • "markdown": markdown content
      • "html": cleaned HTML
      • "rawHtml": raw HTML
      • "rawBase64": raw base64-encoded file content
      • "links": page links
      • "images": image URLs
      • "screenshot": screenshot output. Object options: fullPage (boolean, default false), quality (integer 1-100), viewport (object with width and height)
      • "summary": summary output
      • "json": LLM-based JSON extraction. Object options: schema (JSON Schema object), prompt (string), checkPromptInjection (boolean, default false, +4 credits)
      • "changeTracking": change tracking. Object options: modes (array of "git-diff" | "json"), schema (object), prompt (string), tag (string, nullable)
      • "branding": branding profile output
      • "product": product data output
      • "menu": menu data output
      • "audio": audio extraction (MP3 from video URLs like YouTube, returns signed URL)
      • "video": video extraction (returns signed URL)
      • "question": ask a question about the page. Requires question (string, max 10000 chars)
      • "highlights": find relevant source text. Requires query (string, max 10000 chars)
    • String shorthand: "markdown" is equivalent to {"type": "markdown"}.
  • onlyMainContent
    • Type: boolean (default true)
    • Use when: you want to strip nav, footer, and other boilerplate. Deterministic HTML-level filter, no LLM involved.
  • onlyCleanContent
    • Type: boolean (default false)
    • Use when: you want an additional LLM-based pass to remove residual boilerplate (cookie banners, ad blocks, social widgets, breadcrumbs, newsletter signups, comment sections, related-article lists). Can be combined with onlyMainContent. Not supported on zero-data-retention requests.
  • includeTags
    • Type: array of strings
    • Use when: you want to include only specific HTML tags.
  • excludeTags
    • Type: array of strings
    • Use when: you want to exclude specific HTML tags.
  • maxAge
    • Type: integer (milliseconds, default 172800000 = 2 days)
    • Use when: you want cached data up to a maximum age. Enables up to 500% speed improvement.
  • minAge
    • Type: integer (milliseconds)
    • Use when: you want cache-only lookup without triggering a fresh scrape. Set to 1 to accept any cached data regardless of age. Returns 404 with SCRAPE_NO_CACHED_DATA on cache miss.
  • headers
    • Type: object
    • Use when: you need custom HTTP headers (cookies, user-agent, etc.).
  • waitFor
    • Type: integer (milliseconds, default 0)
    • Use when: you need extra delay for page rendering (in addition to Firecrawl’s smart wait).
  • mobile
    • Type: boolean (default false)
    • Use when: you want a mobile viewport. Useful for responsive pages and mobile screenshots.
  • skipTlsVerification
    • Type: boolean (default true)
    • Use when: you need to skip TLS certificate verification.
  • timeout
    • Type: integer (milliseconds, default 60000, minimum 1000, maximum 300000)
    • Use when: you need a request timeout.
  • parsers
    • Type: array of objects (default [{"type": "pdf"}])
    • Use when: you need file parsing controls.
    • PDF parser shape: { "type": "pdf", "mode": "fast" | "auto" | "ocr", "maxPages": integer (1-10000), "pages": boolean, "blocks": boolean, "pageMarkers": boolean }
      • mode (default "auto"): "fast" text-only, "auto" text-first with OCR fallback, "ocr" forces OCR on every page.
      • maxPages: cap pages parsed (1 credit per page).
      • pages (default false): include per-page markdown array.
      • blocks (default false): include per-page typed layout blocks with bounding boxes.
      • pageMarkers (default false): insert <!-- page N --> markers between pages in the markdown.
    • Pass an empty array [] to return the raw PDF as base64 at a flat 1-credit rate.
  • actions
    • Type: array of action objects
    • Use when: you need lightweight pre-scrape browser actions.
    • Action types:
      • wait: either milliseconds (integer, min 1) or selector (CSS selector string) required.
      • screenshot: optional fullPage (boolean), quality (integer 1-100), viewport (object with width, height).
      • click: selector required (CSS selector), all optional (boolean, default false, clicks all matches).
      • write: text required (click to focus the input first).
      • press: key required (e.g. "Enter").
      • scroll: direction ("up" or "down", default "down"), optional selector.
      • scrape: no additional fields, scrapes current page content.
      • executeJavascript: script required (JavaScript string).
      • pdf: optional format (A0-A6, Letter, Legal, Tabloid, Ledger; default Letter), landscape (boolean, default false), scale (number, default 1).
  • location
    • Type: object with country (string, default "US") and languages (string array)
    • Use when: you need geo or language-aware scraping. Uses appropriate proxy and emulates language/timezone.
  • removeBase64Images
    • Type: boolean (default true)
    • Use when: you want to drop base64 images from markdown output. Alt text is preserved with a placeholder URL.
  • blockAds
    • Type: boolean (default true)
    • Use when: you want ad and cookie popup blocking.
  • proxy
    • Type: string (default "auto")
    • Use when: you need proxy control.
    • Values: "basic" (fast, sites with none to basic anti-bot), "enhanced" (advanced anti-bot, slower but more reliable, same credit cost), "auto" (retries with enhanced if basic fails).
  • storeInCache
    • Type: boolean (default true)
    • Use when: you want Firecrawl to cache the result. Forced false for sensitive parameters like actions or headers.
  • lockdown
    • Type: boolean (default false)
    • Use when: you need cache-only mode for compliance/air-gapped environments. Never makes outbound requests. Returns 404 on cache miss. Treated as zero data retention. 5 credits on hit, 1 on miss.
  • redactPII
    • Type: boolean or object (default false)
    • Use when: you want PII redaction on returned markdown.
    • Pass true for defaults, or an object:
      • mode: "accurate" (default, model-only precision), "aggressive" (model + heuristics for higher recall), "fast" (heuristics only, no model)
      • entities: array of "PERSON", "EMAIL", "PHONE", "LOCATION", "FINANCIAL", "SECRET" (omit for all)
      • replaceStyle: "tag" (default, e.g. <EMAIL>), "mask" (replaces with *), "remove" (deletes text)
  • profile
    • Type: object with name (string, 1-128 chars, required) and optional saveChanges (boolean, default true)
    • Use when: you want a persistent browser profile (cookies, localStorage, sessions) shared across scrapes and interactions.
  • threatProtection
    • Type: object
    • Use when: you need a per-request threat-protection override (enterprise feature).
    • Fields:
      • mode: "off" or "normal" (URL scanning via Google Web Risk, +2 credits per URL scanned)
      • riskScoreThreshold: integer 0-100, score at or above which a URL is blocked (lower = stricter)
      • blacklist: array of domains to always block (plain domains or wildcard globs, max 1000)
      • whitelist: array of domains to always allow (wins over all other rules, max 1000)
      • blockedTlds: array of TLDs to block (lowercase, no leading dot, e.g. "zip", max 1000)
      • failurePolicy: "open" (allow on classifier failure) or "closed" (block on failure)
  • auditMetadata
    • Type: object with username (string, max 1024 chars, required)
    • Use when: you need SIEM-logging user attribution (enterprise feature).
  • zeroDataRetention
    • Type: boolean (default false)
    • Use when: you want zero data retention for this scrape. Contact help@firecrawl.dev to enable.

​
Interact

​
Why use it

Use interact when a page requires browser actions or code execution after a scrape starts.

​
Endpoint

POST /scrape/{jobId}/interact

​
Simple Example

​
Complex Example

​
Response

  • cdpUrl: raw Chrome DevTools Protocol WebSocket URL for direct Playwright/Puppeteer/CDP connections (nullable).
  • liveViewUrl: read-only live view URL for the browser session (nullable).
  • interactiveLiveViewUrl: interactive live view URL where viewers can control the browser (nullable).
  • stdout: standard output from code execution (nullable).
  • result: alias for stdout (nullable).
  • stderr: standard error output (nullable).
  • exitCode: exit code of the executed process (nullable).
  • killed: whether the process was killed due to timeout.
  • error: error message if the code raised an exception (nullable).

​
Parameters

  • jobId (path)
    • Type: string (UUID, required)
    • Use when: you have the scrape job id for the live browser session.
  • code (JSON body)
    • Type: string (required, min length 1, max length 100000)
    • Use when: you want to run code in the scrape-bound browser sandbox.
  • language (JSON body)
    • Type: string (default "node")
    • Use when: you need a specific runtime.
    • Values: "python", "node", "bash"
  • timeout (JSON body)
    • Type: integer (seconds, minimum 1, maximum 300, default 30)
    • Use when: you need an execution timeout.
  • origin (JSON body)
    • Type: string
    • Use when: you want a telemetry label for execution tracking.

​
Stop session

DELETE /scrape/{jobId}/interact
No JSON body. Response: { "success": true }.

​
Ask (Agentic Debugging)

​
Why use it

Use ask when a Firecrawl API call fails or returns unexpected results. The AI support agent diagnoses the issue, proposes fix parameters, and optionally validates the fix against the live API. Typical latency: 15-30 seconds.

​
Simple Example

​
Parameters

  • question
    • Type: string (required, 1-8000 chars)
    • Use when: you need to describe the issue.
  • rationale
    • Type: string (1-2000 chars)
    • Use when: you are an AI agent calling on behalf of a user. Describe what the user is trying to accomplish.
  • context
    • Type: object (free-form)
    • Use when: you want to pass metadata from your agent into the debugging prompt.

​
Why use it

Use docs-search to look up Firecrawl documentation with a docs-grounded AI answer and source citations.

​
Simple Example

​
Parameters

  • question
    • Type: string (required, 1-8000 chars)
    • Use when: you need a docs-grounded answer.

​
Source Of Truth

  • firecrawl-docs/api-reference/v2-openapi.json