> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-4orfll.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Node.js Agent Quickstart > Canonical Firecrawl Node.js/TypeScript quickstart for external agents using search, scrape, and interact. # Firecrawl Node.js Agent Quickstart This file is the canonical quickstart for external agents integrating with Firecrawl using the Node.js/TypeScript SDK. It is 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 app = new Firecrawl("fc-YOUR_API_KEY"); ``` The API key can also be set via the `FIRECRAWL_API_KEY` environment variable. Omitting the key uses the keyless free tier (rate-limited per IP). **Client options:** | Option | Type | Default | Description | | --------------- | ---------------- | ----------------------------- | -------------------------------------------- | | `apiKey` | `string \| null` | `FIRECRAWL_API_KEY` env var | API key for authentication | | `apiUrl` | `string \| null` | `"https://api.firecrawl.dev"` | Base URL for the API | | `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 ranked results with optional scraping of each result. * **`scrape`**: Use when you already have a URL and want its content in markdown, HTML, JSON, or other formats. * **`interact`**: Use when a page needs post-scrape browser actions — clicking, filling forms, running code, or prompting an AI agent in the browser. ## Search ### Why use it Search the web for a query and get back ranked results. Optionally scrape each result page inline by passing `scrapeOptions`. ### Preferred SDK method ```typescript theme={null} app.search(query, options?) ``` ### Example ```typescript theme={null} const results = await app.search("firecrawl web scraping API", { limit: 5, scrapeOptions: { formats: ["markdown"] }, }); for (const item of results.web ?? []) { console.log(item.title, item.url); } ``` ### Parameters | Parameter | Type | Description | | ------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | `query` | `string` | **Required.** The search query (max 500 chars). | | `limit` | `number` | Max results to return. Must be positive. | | `sources` | `Array<"web" \| "news" \| "images" \| { type: string }>` | Which result sources to include. Default: web only. | | `categories` | `Array<"github" \| "research" \| "pdf" \| object>` | Filter results by category. | | `includeDomains` | `string[]` | Restrict results to these domains. Cannot combine with `excludeDomains`. | | `excludeDomains` | `string[]` | Exclude results from these domains. Cannot combine with `includeDomains`. | | `tbs` | `string` | Time-based search filter (e.g. `"qdr:d"` for past day, `"qdr:w"` for past week). | | `location` | `string` | Location string for geo-targeted results. | | `ignoreInvalidURLs` | `boolean` | Ignore invalid URLs in results. | | `timeout` | `number` | Timeout in milliseconds. 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` | Enterprise per-request threat protection override. | | `integration` | `string` | Integration identifier for tracking. | **Returns:** `SearchData` with optional `.web`, `.news`, and `.images` arrays depending on `sources`. ## Scrape ### Why use it Scrape a single URL and get its content as markdown, HTML, structured JSON, screenshots, or other formats. ### Preferred SDK method ```typescript theme={null} app.scrape(url, options?) ``` ### Example ```typescript theme={null} const doc = await app.scrape("https://example.com", { formats: ["markdown", "links"], onlyMainContent: true, }); console.log(doc.markdown); ``` ### Parameters | Parameter | Type | Description | | --------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `string` | **Required.** The URL to scrape. | | `formats` | `FormatOption[]` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"json"`, `"changeTracking"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`, or objects like `{ type: "question", question: "..." }` and `{ type: "highlights", query: "..." }`. | | `onlyMainContent` | `boolean` | Extract only the main content, excluding headers/navs/footers. | | `includeTags` | `string[]` | HTML tags to include in output. | | `excludeTags` | `string[]` | HTML tags to exclude from output. | | `timeout` | `number` | Timeout in milliseconds (1000–300000). | | `waitFor` | `number` | Delay in ms before fetching content. | | `mobile` | `boolean` | Emulate a mobile device. | | `headers` | `Record` | Custom HTTP headers to send with the request. | | `actions` | `ActionOption[]` | Browser actions to perform before scraping: `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`. | | `parsers` | `Array` | Parser configs. Include `"pdf"` to extract PDF content to markdown. | | `location` | `{ country?: string; languages?: string[] }` | Geo-location for proxy routing. | | `skipTlsVerification` | `boolean` | Skip TLS certificate verification. | | `removeBase64Images` | `boolean` | Remove base64 images from output. | | `fastMode` | `boolean` | Enable fast mode (less accuracy). | | `blockAds` | `boolean` | Block ads and cookie popups. | | `proxy` | `"basic" \| "stealth" \| "enhanced" \| "auto"` | Proxy tier. `auto` tries basic first, retries with enhanced on failure. | | `maxAge` | `number` | Use cached result if younger than this (ms). `0` bypasses cache. | | `storeInCache` | `boolean` | Store result in Firecrawl cache. | | `lockdown` | `boolean` | Serve from cache only; never makes outbound request. | | `redactPII` | `boolean \| RedactPIIOptions` | Redact PII from returned content. | | `auditMetadata` | `{ username: string }` | User attribution for SIEM logging. | | `profile` | `{ name: string; saveChanges?: boolean }` | Persistent browser profile for session continuity. | | `integration` | `string` | Integration identifier. | | `autoResume` | `boolean` | SDK-only. Auto-retry when a large doc outlives the request window. Default: `true`. | | `threatProtection` | `ThreatProtectionOptions` | Enterprise per-request threat protection override. | **Returns:** `Document` with fields like `markdown`, `html`, `rawHtml`, `links`, `images`, `screenshot`, `metadata`, etc. ## Interact ### Why use it Execute code or send a natural-language prompt in the browser session of a previous scrape job. Use this for clicking buttons, filling forms, navigating multi-step flows, or running arbitrary JavaScript/Python/Bash in the browser sandbox. ### Preferred SDK method ```typescript theme={null} app.interact(jobId, args) ``` ### Example ```typescript theme={null} const doc = await app.scrape("https://example.com", { formats: ["markdown"], }); const jobId = doc.metadata.jobId; const result = await app.interact(jobId, { code: "document.querySelector('button.load-more').click();", language: "node", timeout: 30, }); console.log(result.stdout); ``` ### Parameters | Parameter | Type | Description | | ---------- | ------------------------------ | --------------------------------------------------------------------------------------------- | | `jobId` | `string` | **Required.** The scrape job ID (from `doc.metadata.jobId`). | | `code` | `string` | Code to execute. One of `code` or `prompt` is required. | | `prompt` | `string` | Natural-language instruction for the AI browser agent. One of `code` or `prompt` is required. | | `language` | `"python" \| "node" \| "bash"` | Execution language. Default: `"node"`. | | `timeout` | `number` | Execution timeout in seconds (1–300). | **Returns:** `ScrapeExecuteResponse` with `success`, `stdout`, `stderr`, `result`, `exitCode`, `killed`, `error`, and optional `liveViewUrl` / `interactiveLiveViewUrl`. **Stop the session:** ```typescript theme={null} await app.stopInteraction(jobId); ``` ## Notes * All parameter names use **camelCase** (e.g. `onlyMainContent`, `skipTlsVerification`, `scrapeOptions`). * `includeDomains` and `excludeDomains` on search are mutually exclusive. * The `SearchData` return type has `.web`, `.news`, and `.images` arrays. Accessing `.data` throws a helpful migration error. * **Deprecated aliases** (use the preferred names instead): * `scrapeUrl()` → `scrape()` * `scrapeExecute()` → `interact()` * `stopInteractiveBrowser()` / `deleteScrapeBrowser()` → `stopInteraction()` ## 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`