> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-eiyh7n.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 This is the canonical quickstart for external agents integrating with Firecrawl using the official Node.js/TypeScript SDK. Generated from SDK source and OpenAPI spec. ## Install ```bash theme={null} npm install @mendable/firecrawl-js ``` ## Authenticate ```typescript theme={null} import Firecrawl from "@mendable/firecrawl-js"; const client = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" }); ``` Constructor options: | Option | Type | Default | Description | | --------------- | ---------------- | --------------------------- | ---------------------------------------------------------- | | `apiKey` | `string \| null` | `FIRECRAWL_API_KEY` env var | API key. Omit for keyless free tier (rate-limited per IP). | | `apiUrl` | `string \| null` | `https://api.firecrawl.dev` | Base URL. Falls back to `FIRECRAWL_API_URL` env var. | | `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`** — Use when you start with a query and need to discover relevant pages. Returns search results grouped by source type, optionally with scraped content. * **`scrape`** — Use when you already have a URL and want its content. Returns markdown, HTML, structured data, screenshots, or other formats. * **`interact`** — Use when the page needs post-scrape browser actions like clicking, filling forms, or executing code in the browser sandbox. ## Search ### Why use it Search the web and optionally scrape each result in one call. Start here when you have a question or topic but not a specific URL. ### Preferred SDK method ```typescript theme={null} client.search(query, options?) ``` ### Example ```typescript theme={null} const results = await client.search("firecrawl web scraping API", { limit: 5, scrapeOptions: { formats: ["markdown"] }, }); for (const item of results.web ?? []) { console.log(item.url, item.markdown?.slice(0, 200)); } ``` ### Parameters All parameters are optional unless noted. | Parameter | Type | Description | | ------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | | `query` | `string` | **Required (positional).** The search query. | | `sources` | `Array<"web" \| "news" \| "images" \| { type: ... }>` | Source types to search. | | `categories` | `Array<"github" \| "research" \| "pdf" \| "developer" \| { type: ... }>` | Filter by category. | | `includeDomains` | `string[]` | Restrict results to these domains. Mutually exclusive with `excludeDomains`. | | `excludeDomains` | `string[]` | Exclude results from these domains. | | `limit` | `number` | Max results to return. | | `tbs` | `string` | Time-based search filter (e.g. `"qdr:d"` for past day, `"qdr:w"` for past week). | | `location` | `string` | Geographic location for results. | | `ignoreInvalidURLs` | `boolean` | Exclude URLs invalid for other Firecrawl endpoints. | | `timeout` | `number` | Timeout in milliseconds. | | `highlights` | `boolean` | Generate query-relevant highlights. | | `scrapeOptions` | `ScrapeOptions` | Options applied when scraping each result. See Scrape parameters. | | `enterprise` | `Array<"default" \| "anon" \| "zdr">` | Enterprise zero data retention options. | | `threatProtection` | `ThreatProtectionOptions` | Per-request threat protection override. | | `integration` | `string` | Integration identifier. | | `origin` | `string` | Request origin tag. | ## Scrape ### Why use it Fetch and extract content from a single URL. Use when you have a specific page to read. ### Preferred SDK method ```typescript theme={null} client.scrape(url, options?) ``` ### Example ```typescript theme={null} const doc = await client.scrape("https://example.com", { formats: ["markdown", "links"], onlyMainContent: true, }); console.log(doc.markdown); console.log(doc.links); ``` ### Parameters All parameters are optional unless noted. | Parameter | Type | Description | | --------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `string` | **Required (positional).** The URL to scrape. | | `formats` | `FormatOption[]` | Output formats. String values: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`. Object variants: `{ type: "json", schema?, prompt? }`, `{ type: "screenshot", fullPage?, quality?, viewport? }`, `{ type: "changeTracking", modes, schema?, prompt?, tag? }`, `{ type: "attributes", selectors }`, `{ type: "question", question }`, `{ type: "highlights", query }`. | | `headers` | `Record` | Custom HTTP headers to send with the request. | | `includeTags` | `string[]` | HTML tags to include exclusively. | | `excludeTags` | `string[]` | HTML tags to exclude. | | `onlyMainContent` | `boolean` | Only return main content, excluding navbars/footers. | | `timeout` | `number` | Timeout in milliseconds. | | `waitFor` | `number` | Delay in ms before fetching content. | | `mobile` | `boolean` | Emulate a mobile device. | | `parsers` | `Array` | File processing parsers. PDF modes: `"fast"`, `"auto"`, `"ocr"`. | | `actions` | `ActionOption[]` | Browser actions to perform before scraping. Types: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`. | | `location` | `{ country?: string, languages?: string[] }` | Geolocation for proxy routing. | | `skipTlsVerification` | `boolean` | Skip TLS certificate verification. | | `removeBase64Images` | `boolean` | Remove base64 images from output. | | `fastMode` | `boolean` | Faster scraping with reduced accuracy. | | `useMock` | `string` | Use a mock response. | | `blockAds` | `boolean` | Block ads and cookie popups. | | `proxy` | `"basic" \| "stealth" \| "enhanced" \| "auto" \| string` | Proxy mode. | | `maxAge` | `number` | Use cached result if younger than this (ms). | | `minAge` | `number` | Minimum cache age (ms). Set to 1 for any cached data. | | `storeInCache` | `boolean` | Whether to cache the result. | | `lockdown` | `boolean` | Serve only cached results. No outbound request. | | `redactPII` | `boolean \| { mode?, entities?, replaceStyle? }` | Redact personally identifiable information. Modes: `"accurate"`, `"aggressive"`, `"fast"`. | | `threatProtection` | `ThreatProtectionOptions` | Per-request threat protection override. | | `auditMetadata` | `{ username: string }` | User attribution for SIEM logging. | | `profile` | `{ name: string, saveChanges?: boolean }` | Persistent browser storage profile. | | `integration` | `string` | Integration identifier. | | `origin` | `string` | Request origin tag. | ## Interact ### Why use it Execute code or natural-language prompts in the browser sandbox associated with a scrape job. Use after a scrape to click buttons, fill forms, navigate, or extract additional data. ### Preferred SDK method ```typescript theme={null} client.interact(jobId, args) ``` ### Example ```typescript theme={null} const doc = await client.scrape("https://example.com", { formats: ["markdown"], }); const jobId = doc.metadata?.jobId; const result = await client.interact(jobId, { code: "document.querySelector('button.load-more')?.click();", language: "node", timeout: 30, }); console.log(result.stdout); ``` ### Parameters | Parameter | Type | Description | | ---------- | ------------------------------ | --------------------------------------------------------------------------------------- | | `jobId` | `string` | **Required (positional).** The scrape job ID from a prior scrape. | | `code` | `string` | Code to execute in the browser sandbox. Required if `prompt` is not provided. | | `prompt` | `string` | Natural-language instruction for the browser agent. Required if `code` is not provided. | | `language` | `"python" \| "node" \| "bash"` | Runtime language for `code`. | | `timeout` | `number` | Execution timeout in seconds (1-300). | | `origin` | `string` | Request origin tag. | ### Related method ```typescript theme={null} client.stopInteraction(jobId) ``` Stops the interactive browser session and returns billing info. ## Notes * **Naming style:** All parameters use camelCase. * **Deprecated aliases:** * `scrapeUrl()` → use `scrape()` instead. * `scrapeExecute()` → use `interact()` instead. * `stopInteractiveBrowser()` and `deleteScrapeBrowser()` → use `stopInteraction()` instead. * **Async client:** The SDK is async by default (all methods return Promises). * **Zod schemas:** The `json` format accepts Zod schemas in addition to plain JSON Schema objects for the `schema` field. ## Source Of Truth * `firecrawl/apps/js-sdk/firecrawl/src/index.ts` * `firecrawl/apps/js-sdk/firecrawl/src/v2/client.ts` * `firecrawl/apps/js-sdk/firecrawl/src/v2/types.ts` * `firecrawl-docs/api-reference/v2-openapi.json`