> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-l3hcjj.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. Generated from SDK source (`firecrawl` **v4.38.0**) and the v2 OpenAPI spec. Method names, parameters, and types match the SDK public API. ## Install ```bash theme={null} npm install firecrawl ``` Requires Node.js >= 22. ## 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:`, 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", { sources: ["web"], limit: 5, scrapeOptions: { formats: ["markdown"], onlyMainContent: true, }, }); for (const item of results.web ?? []) { console.log(item.url, item.title); } ``` **Wrong turn to avoid:** `search()` does not return `{ data: [...] }`. Web results are in `result.web`, news in `result.news`, images in `result.images`. ### Parameters | Parameter | Type | Description | | --------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------- | | `query` | `string` | Search query. Use `site:example.com` to limit to a domain. | | `options.sources` | `("web" \| "news" \| "images")[]` | Which source indexes to search. | | `options.categories` | `("developer" \| "research" \| "pdf" \| "github")[]` | Filter results by category. | | `options.includeDomains` | `string[]` | Only include these domains. Cannot combine with `excludeDomains`. | | `options.excludeDomains` | `string[]` | Exclude these domains. Cannot combine with `includeDomains`. | | `options.limit` | `number` | Max results to return. | | `options.tbs` | `string` | Time-based filter (e.g. `qdr:d` for past day, `qdr:w` for past week). | | `options.location` | `string` | Localized results (e.g. `"San Francisco,California,United States"`). | | `options.ignoreInvalidURLs` | `boolean` | Drop URLs that cannot be scraped. | | `options.highlights` | `boolean` | Return query-relevant text highlights. Defaults to `true` server-side. | | `options.timeout` | `number` | Request timeout in milliseconds. | | `options.scrapeOptions` | `ScrapeOptions` | Scrape each search result (see Scrape parameters). | | `options.enterprise` | `("default" \| "anon" \| "zdr")[]` | Enterprise search controls. | ## Scrape ### Why use it Fetch structured content from a URL in one or more formats. Use when you already have the URL. ### Preferred SDK method `client.scrape(url, options?)` → `Promise` ### Example ```ts theme={null} const doc = await client.scrape("https://example.com/pricing", { formats: [ "markdown", { type: "json", prompt: "Extract plan names and prices." }, ], onlyMainContent: true, }); console.log(doc.markdown); console.log(doc.json); ``` ### Parameters | Parameter | Type | Description | | ----------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `url` | `string` | URL to scrape. | | `options.formats` | `FormatOption[]` | Output formats (see below). | | `options.headers` | `Record` | Custom request headers. | | `options.includeTags` | `string[]` | Include only these HTML tags. | | `options.excludeTags` | `string[]` | Exclude these HTML tags. | | `options.onlyMainContent` | `boolean` | Strip nav, footer, 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` | `("pdf" \| PDFParser)[]` | File parsing controls (e.g. `{ type: "pdf", mode: "auto", maxPages: 5 }`). | | `options.actions` | `ActionOption[]` | Pre-scrape browser actions (click, wait, write, press, scroll, scrape, executeJavascript, screenshot, 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"` | Proxy mode. | | `options.maxAge` | `number` | Use cached data up to this age (milliseconds). | | `options.storeInCache` | `boolean` | Cache the result. | | `options.lockdown` | `boolean` | Serve only cached results; never make outbound request. | | `options.profile` | `{ name: string; saveChanges?: boolean }` | Persistent browser profile across scrapes and interactions. | **Format options:** String formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"attributes"`, `"branding"`, `"audio"`, `"video"`. Object formats: * `{ type: "json", prompt?: string, schema?: object }` — at least one of `prompt` or `schema` required. * `{ type: "question", question: string }` — question-answer extraction. * `{ type: "highlights", query: string }` — relevant source-text extraction. * `{ type: "screenshot", fullPage?: boolean, quality?: number, viewport?: { width, height } }` * `{ type: "changeTracking", modes: ("git-diff" | "json")[], schema?, prompt?, tag? }` — `modes` required. * `{ type: "attributes", selectors: { selector: string, attribute: string }[] }` ## Interact ### Why use it Control the browser session tied to a scrape job. Use for clicks, form fills, code execution, or natural-language instructions after a scrape creates a session. Requires `scrapeId` from `document.metadata.scrapeId`. ### 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.", }); // Or code-based interaction const codeResult = await client.interact(jobId, { code: "console.log(await page.title());", language: "node", timeout: 60, }); // Clean up await client.stopInteraction(jobId); ``` ### Parameters | Parameter | Type | Description | | --------------- | ------------------------------ | --------------------------------------------------- | | `jobId` | `string` | Scrape job ID from `document.metadata.scrapeId`. | | `args.code` | `string` | Code to run in the browser session. | | `args.prompt` | `string` | Natural-language instruction for the browser agent. | | `args.language` | `"python" \| "node" \| "bash"` | Runtime for code execution. Default: `"node"`. | | `args.timeout` | `number` | Execution timeout in seconds. | At least one of `code` or `prompt` must be provided. **Stop session:** `client.stopInteraction(jobId)` ends the browser session. Returns `{ success, sessionDurationMs?, creditsBilled?, error? }`. ## Notes * Deprecated aliases: `scrapeExecute` → `interact`; `stopInteractiveBrowser` / `deleteScrapeBrowser` → `stopInteraction`. * The default `Firecrawl` export is the v2 client; v1 remains under `client.v1`. * Zod schemas passed in `formats` (for `json` or `changeTracking`) are auto-converted to JSON Schema by the SDK, and the return type narrows accordingly. * The SDK auto-resumes scrapes for large documents (PDFs) that outlive the request window (up to 5 retries / 20 minutes). * 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`