> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8bb4v8.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. Canonical Firecrawl Node.js quickstart for external agents. Aligned with `firecrawl` **v4.32.0** (`firecrawl/apps/js-sdk/firecrawl`) and the v2 OpenAPI spec. Method names, parameters, and types match the SDK public API. ## Install ```bash theme={null} npm install firecrawl ``` ## Authenticate ```ts theme={null} import { Firecrawl } from "firecrawl"; const client = new Firecrawl({ apiKey: process.env.FIRECRAWL_API_KEY, // apiUrl: "https://api.firecrawl.dev" // optional; falls back to FIRECRAWL_API_URL or cloud default }); ``` ## 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 other browser actions after a scrape has created a session. For multi-step interactive flows, prefer `interact` over scrape-time `actions`. ## Search ### 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`. ### Preferred SDK method `client.search(query, options?)` → `Promise` ### Example ```ts theme={null} const results = await client.search("site:docs.firecrawl.dev webhook retries"); for (const item of results.web ?? []) { console.log(item.url, item.title); } ``` ### Parameters | Parameter | Type | Description | | --------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------ | | `query` | `string` | The search query. Use `site:example.com` to limit results to a domain. | | `options.sources` | `("web" \| "news" \| "images")[]` | Which search sources to query. | | `options.categories` | `("github" \| "research" \| "pdf" \| "developer")[]` | Filter results by category. | | `options.includeDomains` | `string[]` | Restrict results to these domains. Mutually exclusive with `excludeDomains`. | | `options.excludeDomains` | `string[]` | Exclude these domains. Mutually exclusive with `includeDomains`. | | `options.limit` | `number` | Cap the number of results. | | `options.tbs` | `string` | Time-based filter (e.g. `qdr:d`, `qdr:w`, `sbd:1,qdr:m`). | | `options.location` | `string` | Location string for localized results. | | `options.ignoreInvalidURLs` | `boolean` | Drop URLs that cannot be scraped by other endpoints. | | `options.timeout` | `number` | Request timeout in milliseconds. | | `options.highlights` | `boolean` | Generate query-relevant highlights. Defaults to true server-side. | | `options.scrapeOptions` | `ScrapeOptions` | Scrape each search result (see Scrape parameters). | | `options.enterprise` | `("default" \| "anon" \| "zdr")[]` | Enterprise options. `"zdr"` for zero data retention, `"anon"` for anonymized search. | **Return value:** `SearchData` with optional arrays `web`, `news`, `images`, `developer`. Do not access `result.data` — it throws an error directing you to use `result.web`, `result.news`, etc. ## Scrape ### Why use it Use scrape when you already have a URL and want structured content in one or more formats. ### Preferred SDK method `client.scrape(url, options?)` → `Promise` ### Example ```ts theme={null} const doc = await client.scrape("https://docs.firecrawl.dev", { formats: ["markdown"] }); console.log(doc.markdown); ``` ### Parameters | Parameter | Type | Description | | ----------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `url` | `string` | The URL to scrape. | | `options.formats` | `FormatOption[]` | Output formats. Plain strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"audio"`, `"video"`. Object formats: `{ type: "json", prompt?, schema? }`, `{ type: "question", question }`, `{ type: "highlights", query }`, `{ type: "screenshot", fullPage?, quality?, viewport? }`, `{ type: "changeTracking", modes, schema?, prompt?, tag? }`, `{ type: "attributes", selectors: [{ selector, attribute }] }`. Note: plain string `"json"` is rejected — use the object form. | | `options.headers` | `Record` | Custom request headers. | | `options.includeTags` | `string[]` | Include only specific HTML tags. | | `options.excludeTags` | `string[]` | Exclude specific HTML tags. | | `options.onlyMainContent` | `boolean` | Strip nav, footer, and other boilerplate. | | `options.timeout` | `number` | Timeout in milliseconds. | | `options.waitFor` | `number` | Wait for the page to render (milliseconds). | | `options.mobile` | `boolean` | Use a mobile viewport. | | `options.parsers` | `("pdf" \| { type: "pdf", mode?, maxPages? })[]` | File parsing controls. PDF modes: `"fast"`, `"auto"`, `"ocr"`. | | `options.actions` | `ActionOption[]` | Pre-scrape browser actions. Types: `wait`, `screenshot`, `click`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `pdf`. | | `options.location` | `{ country?, languages? }` | Geo or language-aware scraping. | | `options.skipTlsVerification` | `boolean` | Skip TLS verification. | | `options.removeBase64Images` | `boolean` | Drop base64 images from markdown output. | | `options.fastMode` | `boolean` | Faster scrapes with reduced fidelity. | | `options.blockAds` | `boolean` | Block ads and cookie popups. | | `options.proxy` | `"basic" \| "stealth" \| "enhanced" \| "auto"` | Proxy mode. | | `options.maxAge` | `number` | Use cached data up to this age (milliseconds). | | `options.minAge` | `number` | Use cached data only if at least this old (milliseconds). | | `options.storeInCache` | `boolean` | Cache the result. | | `options.lockdown` | `boolean` | Only serve cached results, never make an outbound request. | | `options.redactPII` | `boolean \| RedactPIIOptions` | Redact personally identifiable information. Options: `mode`, `entities`, `replaceStyle`. | | `options.profile` | `{ name, saveChanges? }` | Persistent browser profile shared across scrapes and interactions. | | `options.auditMetadata` | `{ username }` | User attribution for SIEM logging. | ## Interact ### Why use it Use `interact` for code or natural-language control of the browser session tied to a scrape job (via `metadata.scrapeId`). The SDK requires at least one of `code` or `prompt`. For flows that go beyond quick pre-scrape tweaks, prefer `interact` over scrape-time `actions`. ### Preferred SDK method `client.interact(jobId, args)` → `Promise` ### Example ```ts theme={null} const doc = await client.scrape("https://example.com", { formats: ["markdown"] }); const jobId = doc.metadata?.scrapeId; if (!jobId) throw new Error("Missing scrapeId from scrape response"); const result = await client.interact(jobId, { prompt: "Click the pricing tab and summarize the plans." }); ``` ### Parameters | Parameter | Type | Description | | --------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `jobId` | `string` | Scrape job ID from `document.metadata.scrapeId`. | | `args.code` | `string` | Code to run in the browser session (e.g. Playwright `page` usage). Provide `code` or `prompt` (at least one required). | | `args.prompt` | `string` | Natural-language instruction for the browser agent. Provide `code` or `prompt` (at least one required). | | `args.language` | `"python" \| "node" \| "bash"` | Runtime language. Default: `"node"`. | | `args.timeout` | `number` | Execution timeout in seconds. | ### Stop session `client.stopInteraction(jobId)` → `Promise` Ends the scrape-bound browser session. Response includes `success`, `sessionDurationMs`, `creditsBilled`. ## Notes * Deprecated aliases: `scrapeExecute` → `interact`; `stopInteractiveBrowser` and `deleteScrapeBrowser` → `stopInteraction`; `scrapeUrl` → `scrape`. * The default `Firecrawl` export is the v2 client; v1 remains under `client.v1`. * Zod schemas passed to `formats` (for `json` or `changeTracking`) are converted to JSON Schema by the SDK. * The package declares **Node.js >= 22** in `engines`. ## Source Of Truth * `firecrawl/apps/js-sdk/firecrawl/package.json` * `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`