> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-823qpc.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Node.js Agent Quickstart > Canonical Firecrawl Node.js quickstart for external agents using search, scrape, and interact. # Firecrawl Node.js Agent Quickstart Canonical quickstart for external agents integrating with Firecrawl via the Node.js SDK. Generated from SDK source and the OpenAPI spec. ## Install ```bash theme={null} npm install firecrawl ``` Requires Node.js 22+. ## Authenticate ```javascript theme={null} import Firecrawl from "firecrawl"; const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" }); ``` Or use the `FIRECRAWL_API_KEY` environment variable: ```javascript theme={null} const firecrawl = new Firecrawl(); ``` Constructor accepts a string (API key) or an options object: | Option | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------- | | `apiKey` | `string` | API key. Falls back to `FIRECRAWL_API_KEY` env var, then keyless free tier (rate-limited per IP). | | `apiUrl` | `string` | Base URL. Defaults to `https://api.firecrawl.dev`. | | `timeoutMs` | `number` | Per-request timeout in milliseconds. | | `maxRetries` | `number` | Max automatic retries for transient failures. | | `backoffFactor` | `number` | Exponential backoff factor for retries. | ## When To Use What * **`search`**: Start with a query and discover relevant pages. Returns URLs, titles, descriptions, and optionally scraped content. * **`scrape`**: You already have a URL and want structured page content — markdown, HTML, screenshots, JSON extraction, etc. * **`interact`**: The page needs post-scrape browser actions — clicking, typing, executing code, or natural-language browser instructions. ## Search ### Why use it Discover web pages matching a query. Optionally scrape each result for full content in one call. ### Preferred SDK method `firecrawl.search(query, options?)` ### Example ```javascript theme={null} import Firecrawl from "firecrawl"; const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" }); const results = await firecrawl.search("firecrawl web scraping", { limit: 5 }); for (const result of results.web) { console.log(result.title, result.url); } ``` ### Parameters | Parameter | Type | Description | | ------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | `string` | Search query. Required (first positional argument). | | `limit` | `number` | Max number of results per source type. | | `sources` | `Array<"web" \| "news" \| "images">` | Result sources to include. Defaults to `["web"]`. | | `categories` | `Array<"github" \| "research" \| "pdf" \| "developer">` | Narrow results by category. Use when you want domain-specific filtering. | | `includeDomains` | `string[]` | Restrict to these domains. Mutually exclusive with `excludeDomains`. | | `excludeDomains` | `string[]` | Exclude these domains. Mutually exclusive with `includeDomains`. | | `tbs` | `string` | Time-based filter. Use `"qdr:h"` (past hour), `"qdr:d"` (day), `"qdr:w"` (week), `"qdr:m"` (month), `"qdr:y"` (year), or custom date ranges. | | `location` | `string` | Location string for geo-targeted results (e.g. `"San Francisco,California,United States"`). | | `ignoreInvalidURLs` | `boolean` | Skip invalid URLs instead of failing. Useful when piping results to other Firecrawl endpoints. | | `timeout` | `number` | Timeout in milliseconds. | | `highlights` | `boolean` | Generate query-relevant highlights. Defaults to `true`. Set `false` for raw provider descriptions. | | `scrapeOptions` | `ScrapeOptions` | Scrape each result page. Same parameters as the scrape endpoint below. | | `enterprise` | `Array<"default" \| "anon" \| "zdr">` | Enterprise options: `"zdr"` for zero data retention, `"anon"` for anonymized search. | | `threatProtection` | `ThreatProtectionOptions` | Per-request threat protection override. | | `integration` | `string` | Integration identifier for attribution. | | `origin` | `string` | Origin identifier. | Results are grouped by source: `results.web`, `results.news`, `results.images`, `results.developer`. ## Scrape ### Why use it Extract structured content from a single URL — markdown, HTML, screenshots, JSON extraction, audio, video, and more. ### Preferred SDK method `firecrawl.scrape(url, options?)` ### Example ```javascript theme={null} const result = await firecrawl.scrape("https://example.com", { formats: ["markdown", "links"], }); console.log(result.markdown); console.log(result.links); ``` ### Parameters | Parameter | Type | Description | | --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `url` | `string` | URL to scrape. Required (first positional argument). | | `formats` | `FormatOption[]` | Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Or format objects like `{ type: "json", schema: {...}, prompt: "..." }`, `{ type: "question", question: "..." }`, `{ type: "highlights", query: "..." }`. | | `headers` | `Record` | Custom HTTP headers for the request. Use for cookies, auth tokens, user-agent. | | `includeTags` | `string[]` | Only include content from these HTML tags. | | `excludeTags` | `string[]` | Exclude content from these HTML tags. | | `onlyMainContent` | `boolean` | Extract only main content, excluding headers/navs/footers. | | `timeout` | `number` | Timeout in milliseconds. Min `1000`, max `300000`. Default `60000`. | | `waitFor` | `number` | Additional wait in milliseconds before scraping. Use for JS-rendered content. | | `mobile` | `boolean` | Emulate a mobile device. Use for responsive pages or mobile-specific content. | | `parsers` | `Array` | Parser config. Use `["pdf"]` or `[{ type: "pdf", mode: "fast" \| "auto" \| "ocr", maxPages: number }]`. | | `actions` | `ActionOption[]` | Browser actions before scraping: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`. | | `location` | `{ country?: string, languages?: string[] }` | Location settings for geo-targeting and language preference. | | `skipTlsVerification` | `boolean` | Skip TLS certificate verification. | | `removeBase64Images` | `boolean` | Remove base64 images from markdown output. | | `fastMode` | `boolean` | Faster scrape with reduced accuracy. | | `blockAds` | `boolean` | Block ads and cookie popups. | | `proxy` | `"basic" \| "stealth" \| "enhanced" \| "auto"` | Proxy tier. `"auto"` retries with enhanced if basic fails. | | `maxAge` | `number` | Max age in ms of cached content for reuse. `0` bypasses cache. Default `172800000` (2 days). | | `minAge` | `number` | Cache-only mode. Returns cached data of at least this age in ms. Use `1` to accept any cached data. | | `storeInCache` | `boolean` | Store result in Firecrawl cache. | | `lockdown` | `boolean` | Serve only cached results, never make outbound requests. | | `redactPII` | `boolean \| RedactPIIOptions` | Redact PII from content. Pass `true` for defaults or `{ mode, entities, replaceStyle }`. | | `auditMetadata` | `{ username: string }` | User attribution for SIEM logging. | | `profile` | `{ name: string, saveChanges?: boolean }` | Persistent browser profile for shared state across sessions. | | `threatProtection` | `ThreatProtectionOptions` | Per-request threat protection override. | | `integration` | `string` | Integration identifier. | | `origin` | `string` | Origin identifier. | ## Interact ### Why use it Continue interacting with a live browser session after scraping. Execute code or send natural-language prompts to control the page — click buttons, fill forms, navigate, and extract dynamic content. ### Preferred SDK method `firecrawl.interact(jobId, args)` ### Example ```javascript theme={null} const result = await firecrawl.scrape("https://www.amazon.com", { formats: ["markdown"] }); const scrapeId = result.metadata?.scrapeId; await firecrawl.interact(scrapeId, { prompt: "Search for iPhone 16 Pro Max" }); const response = await firecrawl.interact(scrapeId, { prompt: "Click on the first result and tell me the price", }); console.log(response.output); await firecrawl.stopInteraction(scrapeId); ``` ### Parameters | Parameter | Type | Description | | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | | `jobId` | `string` | Scrape job ID. Required (first positional argument). Obtained from `result.metadata.scrapeId` of a previous scrape. | | `code` | `string` | Code to execute in the browser session. One of `code` or `prompt` is required. | | `prompt` | `string` | Natural-language instruction for the browser agent. One of `code` or `prompt` is required. | | `language` | `"python" \| "node" \| "bash"` | Language for code execution. Defaults to `"node"`. | | `timeout` | `number` | Execution timeout in seconds (1-300). | | `origin` | `string` | Origin identifier. | Call `firecrawl.stopInteraction(jobId)` to end the browser session when done. ## Notes * **camelCase parameters**: All options use camelCase (e.g. `onlyMainContent`, `includeTags`, `scrapeOptions`). * **Zod schema inference**: When using `{ type: "json", schema: zodSchema }` in `formats`, TypeScript narrows the `json` return type to `z.infer`. * **SearchData structure**: Access results via `results.web`, `results.news`, `results.images`, or `results.developer`. Accessing `results.data` throws an error. * **Timeout arithmetic**: The SDK adds 5000ms to the provided timeout for the HTTP request. For interact, timeout is in seconds (converted to ms internally). * **Deprecated aliases**: `scrapeExecute` -> `interact`, `stopInteractiveBrowser` / `deleteScrapeBrowser` -> `stopInteraction`, `scrapeUrl` -> `scrape`. ## Source Of Truth * SDK source: `firecrawl/apps/js-sdk/firecrawl/src/v2/client.ts`, `firecrawl/apps/js-sdk/firecrawl/src/v2/types.ts` * OpenAPI spec: `firecrawl-docs/api-reference/v2-openapi.json`