> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-qzjftw.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 agents. Generated from SDK source (`firecrawl` **v4.38.0**) and the v2 OpenAPI spec. ## 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 env var }); ``` ## 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 post-scrape browser actions. Requires a `scrapeId` from a prior scrape. ## Search ### Why use it Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with `site:` in the query string. ### Preferred SDK method `client.search(query, options?)` → `Promise` ### Example ```ts theme={null} const results = await client.search("site:docs.firecrawl.dev webhook retries", { sources: ["web", "news"], limit: 10, scrapeOptions: { formats: ["markdown"], onlyMainContent: true, }, }); for (const item of results.web ?? []) { console.log(item.url, item.title); } ``` Results are grouped by source: `results.web`, `results.news`, `results.images`. Do not access `results.data`. ### Parameters | Parameter | Type | Description | | --------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- | | `query` | `string` | Search query. Use `site:example.com` to scope to a domain. | | `options.sources` | `("web" \| "news" \| "images")[]` | Which result sources to include. | | `options.categories` | `("github" \| "developer" \| "research" \| "pdf")[]` | Filter web results by category. | | `options.includeDomains` | `string[]` | Restrict results to these domains. Mutually exclusive with `excludeDomains`. | | `options.excludeDomains` | `string[]` | Exclude results from these domains. Mutually exclusive with `includeDomains`. | | `options.limit` | `number` | Max 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. | | `options.timeout` | `number` | Request timeout in milliseconds. | | `options.highlights` | `boolean` | Generate query-relevant highlights. Defaults to `true`. | | `options.scrapeOptions` | `ScrapeOptions` | Scrape each search result (see Scrape parameters). | | `options.enterprise` | `("default" \| "anon" \| "zdr")[]` | Enterprise search options. `"zdr"` for Zero Data Retention. | ## Scrape ### Why use it Get structured content from a URL in one or more formats. ### Preferred SDK method `client.scrape(url, options?)` → `Promise` ### Example ```ts theme={null} const doc = await client.scrape("https://example.com/pricing", { formats: [ "markdown", "links", { type: "json", prompt: "Extract plan names and prices." }, ], onlyMainContent: true, waitFor: 1000, }); console.log(doc.markdown); ``` ### Parameters | Parameter | Type | Description | | ----------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `string` | The URL to scrape. | | `options.formats` | `FormatOption[]` | Output formats. Strings: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"audio"`, `"video"`. Objects: `{ 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 }] }`. | | `options.headers` | `Record` | Custom HTTP headers. | | `options.includeTags` | `string[]` | Only include content from these HTML tags. | | `options.excludeTags` | `string[]` | Exclude content from these HTML tags. | | `options.onlyMainContent` | `boolean` | Strip nav, footer, and boilerplate. | | `options.timeout` | `number` | Timeout in milliseconds. | | `options.waitFor` | `number` | Wait for page to render (milliseconds). | | `options.mobile` | `boolean` | Use a mobile viewport. | | `options.parsers` | `(string \| PDFParser)[]` | File parsers. `"pdf"` or `{ type: "pdf", mode?: "fast" \| "auto" \| "ocr", maxPages?, pages?, blocks?, pageMarkers? }`. | | `options.actions` | `ActionOption[]` | Pre-scrape browser actions: `wait`, `click`, `write`, `press`, `scroll`, `screenshot`, `scrape`, `executeJavascript`, `pdf`. | | `options.location` | `{ country?: string, languages?: string[] }` | Geo/language-aware scraping. | | `options.skipTlsVerification` | `boolean` | Skip TLS verification. | | `options.removeBase64Images` | `boolean` | Drop base64 images from markdown. | | `options.fastMode` | `boolean` | Faster scrapes with reduced fidelity. | | `options.blockAds` | `boolean` | Block ads and cookie popups. | | `options.proxy` | `"basic" \| "stealth" \| "enhanced" \| "auto" \| string` | Proxy mode or custom URL. | | `options.maxAge` | `number` | Accept cached data up to this age (milliseconds). Set to `0` to bypass index reuse. | | `options.minAge` | `number` | Accept cached data only if at least this old (milliseconds). | | `options.storeInCache` | `boolean` | Cache the result. | | `options.lockdown` | `boolean` | Serve only previously cached results; never make outbound requests. | | `options.profile` | `{ name: string, saveChanges?: boolean }` | Persistent browser profile. | | `options.redactPII` | `boolean \| RedactPIIOptions` | Redact personally identifiable information. | | `options.auditMetadata` | `{ username: string }` | User attribution for SIEM logging. | ## Interact ### Why use it Control the browser session tied to a scrape job. Use for clicks, form fills, code execution, or natural-language browser instructions. Requires a `scrapeId` from a prior scrape response. ### 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"); // Natural-language interaction const result = await client.interact(jobId, { prompt: "Click the pricing tab and summarize the plans.", }); // Code-based interaction const codeResult = await client.interact(jobId, { code: "console.log(await page.title());", language: "node", timeout: 60, }); // Stop the session when done await client.stopInteraction(jobId); ``` ### Parameters | Parameter | Type | Description | | --------------- | ------------------------------ | ------------------------------------------------------------------------------------------------ | | `jobId` | `string` | Scrape job ID from `document.metadata.scrapeId`. | | `args.code` | `string` | Code to execute in the browser session. At least one of `code` or `prompt` required. | | `args.prompt` | `string` | Natural-language instruction for the browser agent. At least one of `code` or `prompt` required. | | `args.language` | `"python" \| "node" \| "bash"` | Runtime for code execution. Defaults to `"node"`. | | `args.timeout` | `number` | Execution timeout in seconds. | `client.stopInteraction(jobId)` ends the browser session. Returns `{ success, sessionDurationMs?, creditsBilled?, error? }`. ## 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 in `formats` (for `json` or `changeTracking`) are converted to JSON Schema by the SDK. * `"json"` as a plain string in `formats` is rejected — use `{ type: "json", prompt?, schema? }`. * 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`