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

npm install firecrawl

Requires Node.js >= 22.

Authenticate

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<SearchData>

Example

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<Document>

Example

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<string, string>`	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<ScrapeExecuteResponse>

Example

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

Getting Started

Agent Quickstarts

AI Tools

Agent Harnesses

LLM SDKs and Frameworks

Agent Endpoint

Agentic Debugging

Cookbooks

Node.js Agent Quickstart

Firecrawl Node.js Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Notes

Source Of Truth

​Firecrawl Node.js Agent Quickstart

​Install

​Authenticate

​When To Use What

​Search

​Why use it

​Preferred SDK method

​Example

​Parameters

​Scrape

​Why use it

​Preferred SDK method

​Example

​Parameters

​Interact

​Why use it

​Preferred SDK method

​Example

​Parameters

​Notes

​Source Of Truth

Firecrawl Node.js Agent Quickstart

Install

Authenticate

When To Use What

Search

Why use it

Preferred SDK method

Example

Parameters

Scrape

Why use it

Preferred SDK method

Example

Parameters

Interact

Why use it

Preferred SDK method

Example

Parameters

Notes

Source Of Truth