> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-4ti4xi.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 file is the canonical quickstart for external agents integrating Firecrawl via 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 client = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" }); ``` The API key can also be set via the `FIRECRAWL_API_KEY` environment variable. If omitted, the client falls back to keyless free tier (rate-limited per IP). ## When To Use What * **`search`**: Use when you start with a query and need to discover relevant URLs and their content. Returns results from web, news, and image sources. * **`scrape`**: Use when you already have a specific URL and want its page content in markdown, HTML, JSON, or other formats. * **`interact`**: Use when the page needs post-scrape browser actions like clicking, typing, scrolling, or executing code in a live browser session. ## Search ### Why use it Search the web for a query and optionally scrape the results. Returns categorized results from web, news, and image sources with optional content extraction. ### 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.title, item.url); } ``` ### Parameters | Parameter | Type | Description | | ------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------- | | `query` | `string` | The search query (first argument, required). | | `sources` | `Array<"web" \| "news" \| "images">` | Which search indices to query. | | `categories` | `Array<"github" \| "research" \| "pdf" \| "developer">` | Filter results by category. | | `includeDomains` | `string[]` | Restrict results to these domains. Cannot be used with `excludeDomains`. | | `excludeDomains` | `string[]` | Exclude results from these domains. Cannot be used with `includeDomains`. | | `limit` | `number` | Maximum number of results to return. Server default: `10`. | | `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 search. | | `ignoreInvalidURLs` | `boolean` | Ignore invalid URLs in results. | | `timeout` | `number` | Timeout in milliseconds. Server default: `60000`. | | `highlights` | `boolean` | Generate query-relevant highlights. Default: `true`. | | `scrapeOptions` | `ScrapeOptions` | Nested scrape configuration applied to each result. | | `enterprise` | `Array<"default" \| "anon" \| "zdr">` | Enterprise search options for Zero Data Retention. | | `threatProtection` | `ThreatProtectionOptions` | Per-request threat protection overrides. | | `integration` | `string` | Integration identifier. | | `origin` | `string` | Origin identifier. | ## Scrape ### Why use it Scrape a single URL and get its content in one or more formats. Supports browser automation, LLM extraction, screenshots, and more. ### Preferred SDK method ```typescript theme={null} client.scrape(url, options?) ``` ### Example ```typescript theme={null} const doc = await client.scrape("https://example.com", { formats: ["markdown", "html"], onlyMainContent: true, }); console.log(doc.markdown); ``` ### Parameters | Parameter | Type | Description | | --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `string` | The URL to scrape (first argument, required). | | `formats` | `FormatOption[]` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"summary"`, `"changeTracking"`, `"json"`, `"attributes"`, `"branding"`, `"product"`, `"menu"`, `"audio"`, `"video"`, or typed objects (see below). Server default: `["markdown"]`. | | `onlyMainContent` | `boolean` | Strip boilerplate, keep main content only. Server default: `true`. | | `headers` | `Record` | Custom HTTP headers to send with the request. | | `includeTags` | `string[]` | HTML tags to exclusively include. | | `excludeTags` | `string[]` | HTML tags to exclude. | | `timeout` | `number` | Timeout in milliseconds. Min: `1000`, max: `300000`. Server default: `60000`. | | `waitFor` | `number` | Delay in milliseconds before fetching content. Server default: `0`. | | `mobile` | `boolean` | Emulate mobile device viewport and user-agent. Server default: `false`. | | `parsers` | `Array` | Parser configurations (e.g. `"pdf"` or `{ type: "pdf", mode: "auto", maxPages: 10 }`). Server default: `["pdf"]`. | | `actions` | `ActionOption[]` | Browser automation actions to perform before scraping. See Actions below. | | `location` | `LocationConfig` | Location settings: `{ country?: string, languages?: string[] }`. Default country: `"US"`. | | `skipTlsVerification` | `boolean` | Skip TLS certificate verification. | | `removeBase64Images` | `boolean` | Remove base64-encoded images from markdown output. Server default: `true`. | | `fastMode` | `boolean` | Enable fast mode for faster scrapes with reduced accuracy. | | `blockAds` | `boolean` | Block advertisements and cookie popups. Server default: `true`. | | `proxy` | `"basic" \| "stealth" \| "enhanced" \| "auto"` | Proxy tier. `"basic"`: fast. `"enhanced"`: advanced anti-bot (up to 5 credits). `"auto"`: tries basic first, retries with enhanced. Server default: `"auto"`. | | `maxAge` | `number` | Use cached result if younger than this many milliseconds. Server default: `172800000` (2 days). | | `minAge` | `number` | Cache-only mode. Set to `1` for any cached data. Returns 404 on cache miss. | | `storeInCache` | `boolean` | Cache the scrape result. Server default: `true`. | | `lockdown` | `boolean` | Only serve cached results, never make outbound requests. | | `redactPII` | `boolean \| RedactPIIOptions` | Redact personally identifiable information. Pass `true` for defaults or an options object. | | `threatProtection` | `ThreatProtectionOptions` | Per-request threat protection overrides. | | `auditMetadata` | `{ username: string }` | User attribution for SIEM logging. | | `profile` | `{ name: string, saveChanges?: boolean }` | Persistent browser profile for session continuity. | | `integration` | `string` | Integration identifier. | | `origin` | `string` | Origin identifier. | | `useMock` | `string` | Use mock data. | #### Format objects | Type | Fields | | ---------------------- | ------------------------------------------------------------------------------------------------------------- | | `JsonFormat` | `{ type: "json", prompt?: string, schema?: object \| ZodSchema }` | | `ScreenshotFormat` | `{ type: "screenshot", fullPage?: boolean, quality?: number, viewport?: { width, height } }` | | `ChangeTrackingFormat` | `{ type: "changeTracking", modes: ("git-diff" \| "json")[], schema?: object, prompt?: string, tag?: string }` | | `AttributesFormat` | `{ type: "attributes", selectors: { selector: string, attribute: string }[] }` | | `QuestionFormat` | `{ type: "question", question: string }` | | `HighlightsFormat` | `{ type: "highlights", query: string }` | #### Actions | Type | Fields | | ------------------- | -------------------------------------------------------------------------------------------- | | `wait` | `{ type: "wait", milliseconds?: number, selector?: string }` | | `screenshot` | `{ type: "screenshot", fullPage?: boolean, quality?: number, viewport?: { width, height } }` | | `click` | `{ type: "click", selector: string }` | | `write` | `{ type: "write", text: string }` | | `press` | `{ type: "press", key: string }` | | `scroll` | `{ type: "scroll", direction: "up" \| "down", selector?: string }` | | `scrape` | `{ type: "scrape" }` | | `executeJavascript` | `{ type: "executeJavascript", script: string }` | | `pdf` | `{ type: "pdf", format?: string, landscape?: boolean, scale?: number }` | ## Interact ### Why use it Execute code or send natural-language prompts in a live browser session tied to a scrape job. Use for post-scrape interactions like clicking buttons, filling forms, or running scripts. ### 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.title", language: "node", }); console.log(result.stdout); await client.stopInteraction(jobId); ``` ### Parameters | Parameter | Type | Description | | ---------- | ------------------------------ | ----------------------------------------------------------------- | | `jobId` | `string` | The scrape job ID (first argument, required). | | `code` | `string` | Code to execute in the browser sandbox. | | `prompt` | `string` | Natural-language instruction for the browser agent. | | `language` | `"python" \| "node" \| "bash"` | Execution language. Server default: `"node"`. | | `timeout` | `number` | Execution timeout in seconds. Range: 1-300. Server default: `30`. | | `origin` | `string` | Origin identifier for telemetry. | Use `client.stopInteraction(jobId)` to end the browser session when done. ## Notes * **Naming style**: All parameters use camelCase. * **Deprecated aliases**: `scrapeUrl()` is deprecated in favor of `scrape()`. `scrapeExecute()` is deprecated in favor of `interact()`. `stopInteractiveBrowser()` and `deleteScrapeBrowser()` are deprecated in favor of `stopInteraction()`. * **Zod schema support**: The `scrape()` method accepts Zod schemas in `JsonFormat` and will narrow the return type accordingly. * **Async**: All methods return Promises. ## Source Of Truth * `/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`