> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8al6t2.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 with Firecrawl via the official Node.js SDK. It is generated from SDK source and the OpenAPI spec.

## Install

```bash theme={null}
npm install firecrawl
```

## Authenticate

```javascript theme={null}
import { Firecrawl } from "firecrawl";

const app = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
```

Or set the `FIRECRAWL_API_KEY` environment variable and omit `apiKey`:

```javascript theme={null}
const app = new Firecrawl();
```

## When To Use What

* **`search`** — Use when you start with a query and need to discover relevant pages. Returns web results, news, images, and optionally scraped page content.
* **`scrape`** — Use when you already have a URL and want structured page content (markdown, HTML, JSON extraction, screenshots, etc.).
* **`interact`** — Use when a page needs browser automation after scraping — clicks, form fills, or post-scrape dynamic content extraction.

## Search

### Why use it

Search the web for a query and get results with titles, URLs, descriptions, and optionally full page content. Supports filtering by domain, time range, category, and source type.

### Preferred SDK method

```
app.search(query, options?)
```

### Example

```javascript theme={null}
const results = await app.search("firecrawl web scraping", {
  limit: 5,
  scrapeOptions: { formats: ["markdown"] },
});

for (const result of results.web) {
  console.log(result.title, result.url);
  console.log(result.markdown); // available when scrapeOptions is set
}
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `query` | `string` | The search query (max 500 chars). **Required.** |
| `limit` | `number` | Max results to return per source type. Default: `10`. Range: 1–100. |
| `sources` | `Array<string \| object>` | Source types to search: `"web"`, `"news"`, `"images"`, `"alexandria"`. Default: `["web"]`. |
| `categories` | `Array<string \| object>` | Filter results by category: `"github"`, `"research"`, `"pdf"`, `"developer"`, `"gov"`. |
| `includeDomains` | `string[]` | Restrict results to these domains (hostnames only). Cannot combine with `excludeDomains`. |
| `excludeDomains` | `string[]` | Exclude results from these domains. Cannot combine with `includeDomains`. |
| `tbs` | `string` | Time-based filter. Predefined: `qdr:h` (hour), `qdr:d` (day), `qdr:w` (week), `qdr:m` (month), `qdr:y` (year). Custom: `cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`. Sort by date: `sbd:1`. Combinable. |
| `location` | `string` | Location for search results. |
| `country` | `string` | ISO 3166-1 alpha-2 country code. |
| `highlights` | `boolean` | Return query-relevant highlights. Default: `true`. |
| `timeout` | `number` | Timeout in milliseconds. |
| `ignoreInvalidURLs` | `boolean` | Skip invalid URLs instead of failing. |
| `scrapeOptions` | `ScrapeOptions` | Apply scrape options to each search result page to get full content. |
| `domainTools` | `boolean` | Include Alexandria tool contracts matched to result domains. |
| `toolDetail` | `"compact" \| "summary" \| "full"` | Detail level for returned tool contracts. Default: `"compact"`. |
| `integration` | `string` | Integration identifier. |
| `origin` | `string` | Origin label for telemetry. |

## Scrape

### Why use it

Scrape a URL and get its content in your chosen format — markdown, HTML, JSON (with schema-based extraction), screenshots, and more. Supports browser actions, caching, proxies, and PDF parsing.

### Preferred SDK method

```
app.scrape(url, options?)
```

### Example

```javascript theme={null}
const result = await app.scrape("https://example.com", {
  formats: ["markdown", "links"],
  onlyMainContent: true,
});

console.log(result.markdown);
console.log(result.links);
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `url` | `string` | The URL to scrape. **Required.** |
| `formats` | `FormatOption[]` | Output formats: `"markdown"`, `"html"`, `"rawHtml"`, `"links"`, `"images"`, `"screenshot"`, `"json"`, `"summary"`, `"audio"`, `"video"`, `"changeTracking"`, `"branding"`, `"product"`, `"menu"`, `"question"`, `"highlights"`. Default: `["markdown"]`. Some accept config objects. |
| `onlyMainContent` | `boolean` | Strip headers, navs, footers. Deterministic HTML filter, no LLM. Default: `true`. |
| `onlyCleanContent` | `boolean` | Additional LLM-based boilerplate removal pass. Default: `false`. |
| `includeTags` | `string[]` | Only include content from these HTML tags. |
| `excludeTags` | `string[]` | Exclude content from these HTML tags. |
| `headers` | `Record<string, string>` | Custom HTTP headers (cookies, user-agent, etc.). |
| `waitFor` | `number` | Extra delay in ms before fetching content, on top of smart-wait. Default: `0`. |
| `timeout` | `number` | Request timeout in ms. Min: 1000, default: 60000, max: 300000. |
| `mobile` | `boolean` | Emulate a mobile device. Default: `false`. |
| `maxAge` | `number` | Use cached result if younger than this (ms). Default: 172800000 (2 days). Set `0` to bypass cache. |
| `minAge` | `number` | Cache-only mode. Returns cached data if it exists, 404 otherwise. Set `1` to accept any cached data. |
| `storeInCache` | `boolean` | Cache this scrape result. |
| `actions` | `ActionOption[]` | Browser actions to perform before scraping (wait, click, type, scroll, screenshot, etc.). |
| `location` | `LocationConfig` | Geolocation: `{ country: string, languages?: string[] }`. |
| `parsers` | `Array<string \| object>` | File parsers. Default: `["pdf"]`. PDF parser supports `mode` (`"fast"`, `"auto"`, `"ocr"`), `maxPages`, `pages`, `blocks`, `pageMarkers`. |
| `proxy` | `string` | Proxy type: `"basic"`, `"stealth"`, `"enhanced"`, `"auto"`, or custom. |
| `skipTlsVerification` | `boolean` | Skip TLS cert verification. Default: `true`. |
| `removeBase64Images` | `boolean` | Strip base64 images from output. |
| `blockAds` | `boolean` | Block ads and cookie popups. |
| `fastMode` | `boolean` | Enable fast scraping mode. |
| `lockdown` | `boolean` | Serve only cached results. |
| `checkPromptInjection` | `boolean` | Scan content for prompt injection (adds 4 credits). |
| `redactPII` | `boolean \| RedactPIIOptions` | Redact personally identifiable information. |
| `profile` | `{ name: string, saveChanges?: boolean }` | Persistent browser profile for storage across sessions. |
| `domainTools` | `boolean` | Return Alexandria tool contracts matched to the scraped domain. |
| `toolDetail` | `"compact" \| "summary" \| "full"` | Detail level for tool contracts. |
| `integration` | `string` | Integration identifier. |
| `origin` | `string` | Origin label for telemetry. |

## Interact

### Why use it

After scraping a page, interact with it in a live browser session — execute code or natural-language prompts to click buttons, fill forms, navigate, and extract dynamic content.

### Preferred SDK method

```
app.interact(jobId, args)
```

### Example

```javascript theme={null}
const scrapeResult = await app.scrape("https://www.amazon.com", {
  formats: ["markdown"],
});
const scrapeId = scrapeResult.metadata?.scrapeId;

const response = await app.interact(scrapeId, {
  prompt: "Search for iPhone 16 Pro Max",
});
console.log(response.output);

const result = await app.interact(scrapeId, {
  code: "document.title",
  language: "node",
});
console.log(result.result);

await app.stopInteraction(scrapeId);
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `jobId` | `string` | The scrape job ID from a previous scrape's `metadata.scrapeId`. **Required.** |
| `code` | `string` | Code to execute in the browser sandbox. Provide `code` or `prompt`. Max 100,000 chars. |
| `prompt` | `string` | Natural-language instruction for the browser agent. Provide `code` or `prompt`. |
| `language` | `"python" \| "node" \| "bash"` | Language for code execution. Default: `"node"`. |
| `timeout` | `number` | Execution timeout in seconds. Min: 1, default: 30, max: 300. |
| `origin` | `string` | Origin label for telemetry. |

### Stopping an interaction

Call `app.stopInteraction(jobId)` to close the browser session and stop billing.

## Notes

* **Deprecated aliases:** `scrapeUrl` → `scrape`, `scrapeExecute` → `interact`, `stopInteractiveBrowser` / `deleteScrapeBrowser` → `stopInteraction`. Always use the preferred names.
* **Parameter naming:** All parameters use camelCase.
* **Package name:** `firecrawl` (npm).
* **Import:** `import { Firecrawl } from "firecrawl"`.
* **Base URL:** Defaults to `https://api.firecrawl.dev`. Override with `apiUrl` in the constructor for self-hosted instances.

## Source Of Truth

* `firecrawl/apps/js-sdk/firecrawl/src/v2/client.ts`
* `firecrawl/apps/js-sdk/firecrawl/src/v2/types.ts`
* `firecrawl/apps/js-sdk/firecrawl/src/v2/methods/scrape.ts`
* `firecrawl/apps/js-sdk/firecrawl/src/v2/methods/search.ts`
* `firecrawl-docs/api-reference/v2-openapi.json`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.