Node - Firecrawl Docs

Node.js アプリケーションから、単一ページをスクレイピングし、サイト全体をクロールし、URL をマップできます。SDK がページネーション、リトライ、非同期ジョブのポーリングを処理するため、返されたデータの利用に集中できます。

インストール#

npm で SDK をインストールします:

Node

// npm install firecrawlimport { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({  // 開始にAPIキーは不要です — より高いrate limitsのために追加してください:  // apiKey: "fc-YOUR-API-KEY",});

使い方#

firecrawl.dev から API キーを取得します。
環境変数 FIRECRAWL_API_KEY に API キーを設定するか、Firecrawl クラスにパラメータとして渡します。

Note

API キーがありませんか？ キーなしで Firecrawl を作成し、キー不要の Free ティアで scrape、search、interact を利用できます (IP ごとにレート制限あり — Rate Limits を参照) 。それ以外のすべてのメソッドにはキーが必要です。

エラーハンドリング付きで SDK を使用する例は次のとおりです:

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});// ウェブサイトをスクレイピングするconst scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {  formats: ['markdown', 'html'],});console.log(scrapeResponse)// ウェブサイトをクロールするconst crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {  limit: 100,  scrapeOptions: {    formats: ['markdown', 'html'],  }});console.log(crawlResponse)

URLをスクレイピングする#

scrape メソッドを使用すると、単一のURLをスクレイピングして構造化されたページデータを取得できます。

Node

// ウェブサイトをスクレイピングする：const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });console.log(scrapeResult)

アップロードしたファイルの解析#

URLを指定してスクレイピングする代わりに、ローカルファイル (html、pdf、docx、xlsx など) をアップロードする場合は parse を使用します。 parse は changeTracking や、screenshot、branding、actions、waitFor、location、mobile などのブラウザ専用オプションには対応していません。

Node

const parsed = await firecrawl.parse(  {    data: "<html><body><h1>Node Parse</h1></body></html>",    filename: "upload.html",    contentType: "text/html",  },  {    formats: ["markdown"],  },);console.log(parsed.markdown);

Web サイトをクロールする#

crawl メソッドを使用すると、単一の URL から Web サイト全体をクロールできます。ページ数の上限を設定したり、特定のドメインのみに制限したり、出力フォーマットを選択したりできます。自動ページネーションと手動ページネーションについては、Pagination を参照してください。

Node

const job = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 5, pollInterval: 1, timeout: 120 });console.log(job.status);

サイトマップのみクロール#

sitemap: "only" を使用すると、サイトマップ内の URL のみをクロールします (開始URLは常に対象に含まれ、HTML リンクの探索は行われません) 。

Node

const job = await firecrawl.crawl('https://docs.firecrawl.dev', {  sitemap: 'only',  limit: 25,});console.log(job.status, job.data.length);

クロールを開始#

startCrawl を使うと、完了を待たずにクロールを開始できます。このメソッドは、後からポーリングできるジョブ ID を返します。完了まで待って処理をブロックしたい場合は、代わりに crawl を使用してください。ページングの挙動と制限については Pagination を参照してください。

Node

const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });console.log(id);

クロールのステータスを確認する#

checkCrawlStatus メソッドを使うと、クロールがまだ実行中か、完了したか、失敗したかを確認できます。startCrawl から返されたジョブ ID を渡します。

Node

const status = await firecrawl.getCrawlStatus("<crawl-id>");console.log(status);

クロールのキャンセル#

実行中のクロールは、cancelCrawl メソッドでキャンセルできます。startCrawl が返すジョブ ID を渡してください。

Node

const ok = await firecrawl.cancelCrawl("<crawl-id>");console.log("キャンセル済み:", ok);

Web サイトのマッピング#

Web サイト上のすべての URL を検出するには、map メソッドを使用します。開始 URL を渡すと、検出されたページの一覧が返されます。

Node

const res = await firecrawl.map('https://firecrawl.dev', { limit: 10 });console.log(res.links);

エージェントの実行#

agent メソッドを使用して、調査または抽出タスクをエージェントに渡します。prompt、出力形式を指定する任意の schema、実行で消費できるクレジットの上限を設定する maxCredits を指定します。

Node

import { Firecrawl } from 'firecrawl';import { z } from 'zod';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });const result = await firecrawl.agent({  prompt: "Find the founders of Firecrawl",  schema: z.object({    founders: z.array(z.object({      name: z.string().describe("Full name of the founder"),      role: z.string().describe("Role or position").optional(),      background: z.string().describe("Professional background").optional()    })).describe("List of founders")  }),  model: "spark-2",  maxCredits: 100});console.log(result.data);

エージェントの実行は非同期です。startAgent を使用するとすぐにジョブ ID が返され、その後 getAgentStatus でポーリングできます。

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });// エージェントジョブを開始const started = await firecrawl.startAgent({  prompt: "Find the founders of Firecrawl"});// 状態を確認if (started.id) {  const status = await firecrawl.getAgentStatus(started.id);  console.log(status.status, status.data);}

各実行では、実行トレースと出力スナップショットも記録されます。これらは getAgentTrace と getAgentSnapshot で取得できます。イベントスキーマとすべてのパラメータについては、Agent を参照してください。

WebSockets を使って Web サイトをクロールする#

watcher(jobId, options) を使うと、クロール結果をリアルタイムで受け取れます。ジョブ全体の完了を待たずに、各ページがクロールされるたびに受け取れます。

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });// クロールを開始して監視するconst { id } = await firecrawl.startCrawl('https://mendable.ai', {  excludePaths: ['blog/*'],  limit: 5,});const watcher = firecrawl.watcher(id, { kind: 'crawl', pollInterval: 2, timeout: 120 });watcher.on('document', (doc) => {  console.log('DOC', doc);});watcher.on('error', (err) => {  console.error('ERR', err?.error || err);});watcher.on('done', (state) => {  console.log('DONE', state.status);});// 監視を開始（WS と HTTP のフォールバック）await watcher.start();

ページネーション#

Firecrawl の /crawl と batch の各エンドポイントは、追加のデータがある場合に next URL を返します。Node SDK はデフォルトで自動ページネーションを行い、すべてのドキュメントを集約します。その場合は next が null になります。自動ページネーションを無効にしたり、上限を設定したりできます。

クロール#

最も手軽なのはウェイター方式の crawl を使うことです。あるいはジョブを開始して、ページングを手動で行ってください。

シンプルなクロール (自動ページ送り、デフォルト)

既定のフローはウェブサイトのクロールを参照してください。

ページネーション制御付きの手動クロール (単一ページ)

ジョブを開始し、autoPaginate: false を指定して1ページずつ取得します。

Node

const crawlStart = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 5 });const crawlJobId = crawlStart.id;const crawlSingle = await firecrawl.getCrawlStatus(crawlJobId, { autoPaginate: false });console.log('単一ページのクロール:', crawlSingle.status, 'ドキュメント数:', crawlSingle.data.length, '次:', crawlSingle.next);

制限付きの手動クロール (自動ページネーション + 早期停止)

自動ページネーションはオンのまま、maxPages、maxResults、または maxWaitTime で早めに停止します。

Node

const crawlLimited = await firecrawl.getCrawlStatus(crawlJobId, {  autoPaginate: true,  maxPages: 2,  maxResults: 50,  maxWaitTime: 15,});console.log('クロール制限:', crawlLimited.status, 'ドキュメント数:', crawlLimited.data.length, '次:', crawlLimited.next);

バッチスクレイプ#

waiter メソッド batchScrape を使うか、ジョブを開始して手動でページングします。

シンプルなバッチスクレイプ (自動ページネーション、デフォルト)

既定のフローは Batch Scrape を参照してください。

ページネーション制御による手動バッチスクレイプ (単一ページ)

ジョブを開始し、autoPaginate: false を指定して1ページずつ取得します。

Node

const batchStart = await firecrawl.startBatchScrape([  'https://docs.firecrawl.dev',  'https://firecrawl.dev',], { options: { formats: ['markdown'] } });const batchJobId = batchStart.id;const batchSingle = await firecrawl.getBatchScrapeStatus(batchJobId, { autoPaginate: false });console.log('バッチ単一ページ:', batchSingle.status, 'ドキュメント数:', batchSingle.data.length, '次:', batchSingle.next);

制限付きの手動バッチスクレイプ (自動ページネーション＋早期停止)

自動ページネーションは有効のまま、maxPages、maxResults、または maxWaitTime で早期停止します。

Node

const batchLimited = await firecrawl.getBatchScrapeStatus(batchJobId, {  autoPaginate: true,  maxPages: 2,  maxResults: 100,  maxWaitTime: 20,});console.log('バッチ制限:', batchLimited.status, 'ドキュメント:', batchLimited.data.length, '次:', batchLimited.next);

ブラウザ#

クラウドブラウザセッションを起動し、リモートでコードを実行します。

セッションを作成する#

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });const session = await firecrawl.browser({ ttl: 600 });console.log(session.id);          // セッションIDconsole.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...

コードを実行#

Node

const result = await firecrawl.browserExecute(session.id, {  code: 'await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',});console.log(result.result); // "Hacker News"

Pythonの代わりにJavaScriptを実行する場合:

Node

const result = await firecrawl.browserExecute(session.id, {  code: 'await page.goto("https://example.com"); const t = await page.title(); console.log(t);',  language: "node",});

agent-browserでbashを実行します:

Node

const result = await firecrawl.browserExecute(session.id, {  code: "agent-browser open https://example.com && agent-browser snapshot",  language: "bash",});

プロファイル#

セッションをまたいでブラウザの状態 (クッキー、localStorage など) を保存し、再利用できます。

Node

const session = await firecrawl.browser({  ttl: 600,  profile: {    name: "my-profile",    saveChanges: true,  },});

CDP 経由で接続する#

Playwright をフルに制御するには、CDP URL を使用して直接接続します。

Node

import { chromium } from "playwright";const browser = await chromium.connectOverCDP(session.cdpUrl);const context = browser.contexts()[0];const page = context.pages()[0] || await context.newPage();await page.goto("https://example.com");console.log(await page.title());await browser.close();

セッションの一覧表示と終了#

Node

// アクティブなセッションを一覧表示するconst { sessions } = await firecrawl.listBrowsers({ status: "active" });for (const s of sessions) {  console.log(s.id, s.status, s.createdAt);}// セッションを閉じるawait firecrawl.deleteBrowser(session.id);

スクレイピングに紐づくインタラクティブセッション#

スクレイピングジョブIDを使うと、そのスクレイピングで再現されたページコンテキストに対して続けて操作できます。

interact(jobId, {...}) は、スクレイピングに紐づくブラウザセッション内でコードを実行します。
最初の interact 呼び出しでは、スクレイピングコンテキストからセッションが自動的に初期化されます。
同じジョブIDに対する以降の interact 呼び出しでは、そのままライブのブラウザ状態が再利用されます。
stopInteraction(jobId) は、完了後にインタラクティブセッションを停止します。

Node

const doc = await firecrawl.scrape("https://example.com", {  actions: [{ type: "click", selector: "a[href='/pricing']" }],});const scrapeJobId = doc.metadata?.scrapeId;if (!scrapeJobId) throw new Error("Missing scrape job id");const run = await firecrawl.interact(scrapeJobId, {  code: "console.log(await page.url())",  language: "node",  timeout: 60,});console.log(run.stdout);await firecrawl.stopInteraction(scrapeJobId);

エラーハンドリング#

この SDK は Firecrawl API から返されるあらゆるエラーに対して、わかりやすい例外を送出します。上記の例に示すように、呼び出しは try/catch ブロックで囲んでください。

Firecrawl API キーが必要な AI agent ですか？自動オンボーディング手順については、firecrawl.dev/agent-onboarding/SKILL.md を参照してください。