> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8bz2qg.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 Firecrawl with Node.js. Generated from SDK source and OpenAPI spec. ## Install ```bash theme={null} npm install firecrawl ``` Requires Node.js 22+. ## Authenticate ```javascript theme={null} import Firecrawl from 'firecrawl'; const app = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" }); ``` Or set the `FIRECRAWL_API_KEY` environment variable and omit `apiKey`: ```javascript theme={null} const app = new Firecrawl(); ``` Constructor options: | Option | Type | Default | | --------------- | ---------------- | ------------------------------- | | `apiKey` | `string \| null` | `process.env.FIRECRAWL_API_KEY` | | `apiUrl` | `string \| null` | `"https://api.firecrawl.dev"` | | `timeoutMs` | `number` | — | | `maxRetries` | `number` | — | | `backoffFactor` | `number` | — | ## When To Use What * **search**: Start with a query, discover relevant URLs, and get their content in one call. * **scrape**: You already have a URL and want its page content as markdown, HTML, JSON, or other formats. * **interact**: The page needs clicks, form fills, or post-scrape browser actions on a live session. ## Search ### Why use it Search the web for a query and get scraped content from the top results. Combines discovery and content extraction in one call. ### Preferred SDK method `search(query, options?)` ### Example ```javascript theme={null} const results = await app.search("firecrawl web scraping", { limit: 5 }); for (const result of results.web) { console.log(result.title, result.url); console.log(result.markdown); } ``` ### Parameters | Parameter | Type | Description | | ------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `query` | `string` | **Required.** Search query (max 500 chars). | | `limit` | `number` | Max results per source type. Must be positive. | | `sources` | `Array<"web" \| "news" \| "images" \| {type: string}>` | Sources to search. Default: `[{type: "web"}]`. | | `categories` | `Array<"github" \| "research" \| "pdf" \| "developer">` | Category filters. | | `includeDomains` | `string[]` | Restrict to these domains. Cannot combine with `excludeDomains`. | | `excludeDomains` | `string[]` | Exclude these domains. Cannot combine with `includeDomains`. | | `tbs` | `string` | Time-based filter (e.g. `"qdr:d"` past day, `"qdr:w"` past week, `"qdr:m"` past month). | | `location` | `string` | Geo-targeting location string. | | `ignoreInvalidURLs` | `boolean` | Exclude invalid URLs from results. | | `timeout` | `number` | Timeout in ms. Must be positive. | | `highlights` | `boolean` | Generate query-relevant highlights. Default: `true`. | | `scrapeOptions` | `ScrapeOptions` | Scrape options applied to each result page. | | `enterprise` | `Array<"default" \| "anon" \| "zdr">` | Enterprise zero data retention options. | | `threatProtection` | `ThreatProtectionOptions` | Per-request threat protection override. | | `integration` | `string` | Integration identifier. | | `origin` | `string` | Origin label for telemetry. | Response groups results by source: `results.web`, `results.news`, `results.images`, `results.developer`. ## Scrape ### Why use it Get the content of a single URL as markdown, HTML, JSON, screenshots, or other formats. ### Preferred SDK method `scrape(url, options?)` ### Example ```javascript theme={null} const result = await app.scrape("https://example.com", { formats: ["markdown", "links"], onlyMainContent: true }); console.log(result.markdown); console.log(result.links); ``` ### Parameters | Parameter | Type | Description | | --------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `string` | **Required.** URL to scrape. | | `formats` | `FormatOption[]` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Also accepts config objects (see below). Default: `["markdown"]`. | | `headers` | `Record` | Custom HTTP headers. | | `includeTags` | `string[]` | HTML tags to include. | | `excludeTags` | `string[]` | HTML tags to exclude. | | `onlyMainContent` | `boolean` | Strip navbars, footers, boilerplate. Default: `true`. | | `timeout` | `number` | Timeout in ms. Default: `60000`. Min: `1000`, Max: `300000`. | | `waitFor` | `number` | Extra delay in ms before fetching content. | | `mobile` | `boolean` | Emulate a mobile device. | | `parsers` | `Array` | File processing controls. Default: `["pdf"]`. | | `actions` | `ActionOption[]` | Browser actions before content capture: `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`. | | `location` | `{country?: string, languages?: string[]}` | Geo settings. Country defaults to `"US"`. | | `skipTlsVerification` | `boolean` | Skip TLS certificate verification. | | `removeBase64Images` | `boolean` | Remove base64 images from markdown. Default: `true`. | | `fastMode` | `boolean` | Enable fast mode. | | `blockAds` | `boolean` | Block ads and cookie popups. Default: `true`. | | `proxy` | `"basic" \| "stealth" \| "enhanced" \| "auto"` | Proxy type. `"enhanced"` costs up to 5 credits. Default: `"auto"`. | | `maxAge` | `number` | Cache threshold in ms. Returns cached version if younger. Default: 2 days. | | `minAge` | `number` | Cache-only mode minimum age in ms. | | `storeInCache` | `boolean` | Store result in Firecrawl cache. Default: `true`. | | `lockdown` | `boolean` | Cache-only, no outbound requests. | | `redactPII` | `boolean \| RedactPIIOptions` | Redact PII. Pass `true` for defaults or `{mode?: "accurate"\|"aggressive"\|"fast", entities?: string[], replaceStyle?: "tag"\|"mask"\|"remove"}`. | | `threatProtection` | `ThreatProtectionOptions` | Threat protection override with `mode`, `riskScoreThreshold`, `blacklist`, `whitelist`, `blockedTlds`, `failurePolicy`. | | `auditMetadata` | `{username: string}` | SIEM logging user attribution. | | `profile` | `{name: string, saveChanges?: boolean}` | Persistent browser profile. | | `integration` | `string` | Integration identifier. | | `origin` | `string` | Origin label. | #### Format config objects | Format | Config fields | | ---------------- | ---------------------------------------------------------------------------------------------------------------- | | `json` | `{type: "json", schema?: object, prompt?: string}` — structured extraction with optional JSON Schema and prompt. | | `screenshot` | `{type: "screenshot", fullPage?: boolean, quality?: number, viewport?: {width, height}}` | | `changeTracking` | `{type: "changeTracking", modes: ("git-diff"\|"json")[], schema?: object, prompt?: string, tag?: string}` | | `question` | `{type: "question", question: string}` — ask a question about the page. | | `highlights` | `{type: "highlights", query: string}` — extract text relevant to a query. | | `attributes` | `{type: "attributes", selectors: [{selector: string, attribute: string}]}` | ## Interact ### Why use it Control a live browser session tied to a scrape job. Click buttons, fill forms, navigate, and extract dynamic content using code or natural-language prompts. ### Preferred SDK method `interact(jobId, args)` ### Example ```javascript theme={null} const result = await app.scrape("https://www.amazon.com", { formats: ["markdown"] }); const scrapeId = result.metadata?.scrapeId; await app.interact(scrapeId, { prompt: "Search for iPhone 16 Pro Max" }); const response = await app.interact(scrapeId, { prompt: "Click on the first result and tell me the price" }); console.log(response.output); await app.stopInteraction(scrapeId); ``` ### Parameters | Parameter | Type | Description | | ---------- | ------------------------------ | --------------------------------------------------------------------------- | | `jobId` | `string` | **Required.** Scrape job ID from `result.metadata.scrapeId`. | | `code` | `string` | Code to execute in the browser sandbox. One of `code` or `prompt` required. | | `prompt` | `string` | Natural-language instruction. One of `code` or `prompt` required. | | `language` | `"python" \| "node" \| "bash"` | Runtime for code execution. Default: `"node"`. | | `timeout` | `number` | Execution timeout in seconds. Min: 1, Max: 300. | | `origin` | `string` | Origin label for telemetry. | Stop the session when done: ```javascript theme={null} await app.stopInteraction(scrapeId); ``` ## Notes * Parameter names use **camelCase** (e.g. `onlyMainContent`, `includeTags`, `scrapeOptions`). * `includeDomains` and `excludeDomains` on search are mutually exclusive. * Deprecated aliases (do not use in new code): * `scrapeExecute()` → use `interact()` * `stopInteractiveBrowser()` / `deleteScrapeBrowser()` → use `stopInteraction()` * `scrapeUrl()` → use `scrape()` * `crawlUrl()` → use `crawl()` * `mapUrl()` → use `map()` ## Source Of Truth * `firecrawl/apps/js-sdk/firecrawl/src/v2/client.ts` * `firecrawl/apps/js-sdk/firecrawl/src/v2/types.ts` * `firecrawl/apps/js-sdk/firecrawl/src/index.ts` * `firecrawl-docs/api-reference/v2-openapi.json`