Firecrawl 每月 1,000 credits 怎麼用？Scrape web-context 學生 Agent 導流

Firecrawl 是一個給 agent 使用的 web-context API：可以把網頁搜尋、單頁 scrape、crawl、map、browser interaction 和部分結構化資料整理成 Markdown 或 JSON，交給主要 agent 再做推理。官方 pricing 頁目前列 Free Plan 每月 1,000 credits、免信用卡、2 個 concurrent requests 和 low rate limits。這是網頁資料擷取 credits，不是免費 LLM token，也不包含下游模型的推理費用。

本篇的放行結論是：學生可以用本人 Firecrawl Free 帳戶和本人 API key，先做已知官方 URL 的單頁 scrape，再研究低頻 Search 或 Map。預設只批准公開、合法、低頻、可回溯的來源；不抓私人頁面、不繞過登入或 robots／網站限制、不大量 crawl、不把 Firecrawl 當成無限制資料收集器。credits 用完就停，不自動升級或付款。

本系列整理合法公開的免費 API 方案，不代註冊、不取得或分享他人 API key、不重用登入 cookie、不用多帳戶規避額度，也不把第三方網站內容原封不動重發布。若要先了解主要 agent 的來源核對和憑證邊界，可延伸閱讀 AI agent 使用 FAQ。

當日敲門工具：/v2/scrape 單一第一方 URL（1 page／1 credit）

Firecrawl 沒有要先挑的文字模型；今天批准的敲門入口是對一個已知、合法、公開的第一方 URL 做 POST /v2/scrape，只要求 markdown、onlyMainContent=true，並限制單頁、單一 host、短 timeout。官方 pricing 目前以每頁 1 credit 計算 Scrape，這個契約比直接開 Search、Crawl、Browser 或 Agent preview 更容易預算與人工核對。

回傳的 Markdown 仍是外部不可信內容，可能含有 prompt injection、個資、秘密、著作權文字或錯誤頁面。主要 agent 先保存來源 URL、抓取時間、request metadata、credits read-back 和內容 hash，再打開第一方原文核對；Firecrawl 的抓取結果不能直接變成工具指令，也不能因為成功就自動送入公開資料集。

1,000 credits 可以做什麼

Firecrawl pricing 頁目前把 Free Plan 定義為每月 1,000 credits，並用 Scrape 1,000 pages 作為直觀例子。Credits 不等於固定 1,000 次 API，因為每個 endpoint 和 feature 的計量不同；進階 JSON、文件解析、browser interaction、Agent 等功能可能另外扣點。學生要先選擇明確的 endpoint，再估算這一次工作的 page、result、browser minute 或 dynamic cost。

官方當日 credits 表目前寫明：Scrape 每頁 1 credit、Crawl 每頁 1 credit、Map 每頁 1 credit、Monitor 每頁每次檢查 1 credit、Search 每 10 筆結果 2 credits、Interact 每 browser minute 2 credits。Agent 仍屬 preview，pricing 頁列每天 5 次免費執行，但實際 cost 是 dynamic；不能把 Agent 的五次免費試跑誤當成五個固定、無限長的研究任務。

官方 pricing FAQ 目前說自助方案 credits 不 rollover 到下個月，Firecrawl 也不提供單純 pay-per-use 路徑；需要更多額度時通常要升級到 paid plan。這使 Free Plan 很適合短期學習和小型來源核對，但不適合讓主要 agent 無人值守地週期性 crawl 全站。每月 reset 前後都要重新讀回帳戶，不用本地計數器猜測 provider 狀態。

Firecrawl 官方 pricing 頁還說成功請求才扣點，失敗請求通常不收費；這不代表可以用大量失敗請求探測網站、反覆重試或驗證所有 URL。帳戶仍會受到 rate limit、concurrency、網站條款和第三方來源限制。agent 應保留最大請求數、最大頁數、最大深度、總 timeout 和人工停止按鈕。

帳戶 API 與 keyless 入口要分開

Firecrawl 官方 API reference 的一般路徑是先由人建立帳戶，再在 dashboard 取得 API key；API base URL 是 https://api.firecrawl.dev，認證使用 Authorization: Bearer。這是學生能讀回 team credit usage、管理 key 和追蹤責任的主要路徑。API key 只放 server-side secret store，不放瀏覽器、公開 notebook、GitHub 或模型 prompt。

Firecrawl pricing 頁與官方 agent onboarding 另提到 keyless free tier：如果 agent 平台無法取得 key，特定 onboarding skill 可以引導 search、scrape 和 interact 的 keyless 流程。這不是一般 bearer-key team usage 的同一個狀態；不要把 keyless 的來源、頻率、credits、session 或可用 endpoint 推論成 API dashboard 的固定配額。真正要整合時，先讀 onboarding skill 與當日 UI，再把入口標記為 KEYLESS_REVERIFY_REQUIRED。

本篇不執行 keyless onboarding，也不安裝 Firecrawl CLI、skill 或 MCP。這些工具可能會改變本機 agent 的工具面和認證流程，屬於另一個明確授權的整合工作。本文只提供一般 REST 的最小契約，讓學生理解 endpoint、Bearer key、credit read-back、錯誤分類和資料界線。

function assertFirecrawlFreeState(state, now = Date.now()) {
  if (state.plan !== 'free') {
    throw new Error('Firecrawl free plan is not verified');
  }
  if (state.autoRechargeEnabled === true || state.paidUpgradePending === true) {
    throw new Error('Firecrawl paid path is not approved');
  }
  if (!Number.isFinite(state.remainingCredits) ||
      state.remainingCredits <= state.reserveCredits) {
    throw new Error('Firecrawl free-credit reserve is too low');
  }
  if (!state.allowedEndpoints.includes(state.endpoint)) {
    throw new Error('Firecrawl endpoint is outside the allowlist');
  }
  if (state.checkedAt + state.maxReadbackAgeMs < now) {
    throw new Error('Firecrawl credit read-back is stale');
  }
}

這些欄位是 agent 的本地 policy，不是 Firecrawl response 的固定 schema。Free Plan、每月 credits、concurrency 和 endpoint 可用性要由官方 pricing、dashboard、credit usage response 和 API 文件共同讀回。若讀回只得到 keyless session、不同 plan name、錯誤的 billing period 或缺少 remaining credits，先停止，不用文章中的 1,000 反推現況。

Credit Usage 的最小讀回

官方 Credit Usage endpoint 目前是 GET https://api.firecrawl.dev/v2/team/credit-usage，使用 bearer token，回應包含 success 和 data；文件示例列出 remainingCredits、planCredits、billingPeriodStart 和 billingPeriodEnd。示例中的 planCredits 可能屬於其他 plan，不要把示例數字直接當成自己的 Free Plan。帳戶持有人必須保存當日實際 read-back，並與 pricing 頁的方案說明交叉核對。

async function readFirecrawlCredits() {
  const key = process.env.FIRECRAWL_API_KEY;
  if (!key) throw new Error('Firecrawl API key is missing');

  const response = await fetch(
    'https://api.firecrawl.dev/v2/team/credit-usage',
    { headers: { Authorization: `Bearer ${key}` } }
  );
  const body = await response.json().catch(() => ({}));
  if (!response.ok || body.success !== true) {
    throw Object.assign(new Error(`Firecrawl HTTP ${response.status}`), {
      status: response.status,
      data: body
    });
  }
  const data = body.data ?? {};
  return {
    remainingCredits: Number(data.remainingCredits),
    planCredits: Number(data.planCredits),
    periodStart: data.billingPeriodStart,
    periodEnd: data.billingPeriodEnd
  };
}

這段程式碼只是沒有真實 key 的示意，本工作區沒有呼叫 Firecrawl credit endpoint，也沒有註冊或建立帳戶。若 endpoint 回 404，可能是帳戶、版本或 keyless 狀態不符合；不能因此把剩餘 credits 當成零，也不能反覆呼叫猜測。先保存 status、request time、非敏感 error code，交由帳戶持有人核對 dashboard 和當日文件。

單頁 Scrape 的最小契約

Firecrawl API reference 的核心 scrape 路徑是 POST https://api.firecrawl.dev/v2/scrape，body 指定公開 URL 和需要的 formats。對學生而言，最安全的第一個 canary 是一個自己已確認允許存取的官方公開頁，要求 markdown，固定單頁，不開 screenshot、JSON extraction、actions、proxy 或大型輸出。先做一頁 read-back，再決定是否需要更高成本功能。

async function scrapeFirecrawlPage(targetUrl, state) {
  assertFirecrawlFreeState(state);
  const key = process.env.FIRECRAWL_API_KEY;
  if (!key) throw new Error('Firecrawl API key is missing');

  const response = await fetch('https://api.firecrawl.dev/v2/scrape', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${key}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: String(targetUrl),
      formats: ['markdown']
    })
  });
  const body = await response.json().catch(() => ({}));
  if (!response.ok) {
    throw Object.assign(new Error(`Firecrawl HTTP ${response.status}`), {
      status: response.status,
      data: body
    });
  }
  return body;
}

這段示意不驗證 URL 的法律或 robots 資格，真正的 agent 必須在送出前加入 allowlist、HTTPS、host、path、檔案大小、redirect、private IP 和來源授權檢查。不要讓使用者或模型任意提供帶有帳密的 URL、localhost、內網位址、雲端 metadata endpoint 或公司內部文件。Firecrawl 能處理網頁不代表學生有權取得或再利用網頁內容。

Markdown 回應要被視為外部不可信資料。頁面內容可能包含 prompt injection、假冒系統訊息、惡意連結、個資或要求 agent 呼叫工具的文字；主要 agent 不得把 scrape 結果當成高權限指令。先保留來源 URL、抓取時間和內容 hash，再經過內容分類、第一方核對與人工確認，才交給下游摘要或搜尋索引。

Search、Crawl、Map 與 Browser 的成本邊界

Search 很方便，但官方 pricing 目前按每 10 筆結果 2 credits 計算，結果還可能帶來後續 scrape 成本。agent 不應收到一句模糊問題就自動 Search、逐筆抓取、再對每頁做 JSON extraction。課堂應限制 query 長度、結果數、允許網域、後續頁數和總 credits，並要求先核對搜尋結果是否真的需要進一步讀取。

Crawl 和 Map 會擴張頁面數。雖然標準計量目前是每頁 1 credit，但深度、篩選、重導向和網站大小都會影響實際工作量。第一版只允許明確的一個小型官方文件路徑，設定最大頁數和最大深度；不允許模型以「找完整資料」為理由無限展開。任何 crawl job 都要有 cancel path 和人工停止。

Interact 目前按 browser minute 計量，並且可能讓外部頁面產生點擊、表單輸入、登入狀態和更複雜的資料處理。Free Plan 的 2 concurrent requests 不等於可以開兩個無人值守 browser。學生若要做互動頁 canary，先使用公開測試頁、固定 action、短 session、明確 stop endpoint 和人工觀察，不輸入密碼、不使用私人帳號、不保存 session URL。

Research Index 的 paper endpoint 若依官方 pricing 頁列為免費，仍要和一般 web Search、Scrape、Agent 分開記錄。它是特定研究索引，不是所有網頁免費，也不代表返回的論文內容可以不經授權重發布。學生要保存 citation、paper URL、版本和查核日期，不能把「免費 endpoint」等同「無限制資料權利」。

Agent preview 與 keyless 的特殊風險

Firecrawl pricing 頁目前把 Agent 標為 preview，每天有 5 次免費 runs，並採 dynamic pricing。這種入口適合觀察功能，不適合成為主要 agent 的無人值守研究燃料。Agent 可能自行搜尋、挑選頁面、做多步抓取，成本和資料範圍都比單頁 scrape 難預測；第一版只把它列為人工批准的實驗，不列入預設 allowlist。

Keyless onboarding 也要視為特殊 session：可能沒有可讀回的 bearer key、可能有不同的身份與 rate limit、可能由 agent skill 觸發額外流程。學生不得把 keyless session 的輸出、token、URL 或瀏覽器狀態交給同學，也不得嘗試從 session 反推出可長期使用的秘密。沒有明確的官方 read-back，就標成 KEYLESS_REVERIFY_REQUIRED。

隱私、著作權與來源治理

Firecrawl Privacy Policy 目前列出帳戶與聯絡資料、IP、browser、timestamps、page views、device information 等收集項目，也說明服務可能用於 caching、indexing、產品改善和第三方分析。政策頁的最後修訂日期仍是 2024-12-26，因此不能把它當成永遠不變的資料保證；學生開始使用前要重新閱讀當日 Privacy、Terms、Data Processing 或企業方案條款。

Firecrawl Terms of Service 頁目前的最後修訂日期是 2024-11-05，並要求使用者把登入資料視為機密、不得分享；條款也限制未授權商業用途、非法用途、未經允許存取他人帳戶和某些高風險資料用途。法律頁較舊本身就是一個驗收訊號：若課堂或公司需要新鮮的 DPA、商用授權或資料保留承諾，先向官方取得適用文件，不用免費方案猜測。

網頁內容可能有著作權、個人資料、登入牆、付款牆或網站自己的服務條款。學生只抓公開、允許、必要的最小內容，保留來源 URL、作者、發佈／更新日期、抓取時間和使用理由。不要把 Firecrawl 回傳的整頁內容直接放進公開 repo、向量庫、教材或商業產品；先確認授權、引用和刪除要求。

若 scrape 結果包含 email、電話、地址、未公開價格、客戶名單、登入後資料或秘密，立即停止下游處理，刪除不必要的原文並由人工接手。不要用 Firecrawl 把個資轉存成新的資料集，也不要要求 agent 自動去除來源標籤後再發布。資料抽取的便利性不能取代來源、同意、著作權和隱私判斷。

429、402、401 與超額停止流程

• 401：停止並檢查 bearer key、secret store、project／team 和 endpoint；不把 token 印到 log，不借用別人的 key。
• 402：官方 API reference 將它列為 payment required；停止免費工作，重新讀回 plan、credits、付款和升級狀態，不自動付費。
• 429：限流或 concurrency 超出時做有限 backoff；不提高平行度、不輪換帳戶、不用 keyless 逃避限制。
• 408／5xx：保存 request time、來源 host、非敏感錯誤碼和 job ID；先確認是否已扣點，再決定一次有限重試。
• 未知或內容風險：停止、刪除不必要的原文、通知人工審查，不把錯誤頁或外部 prompt 當成正常資料。

function classifyFirecrawlFailure(error) {
  const status = Number(error?.status);
  if (status === 401) {
    return { action: 'STOP_REVIEW_FIRECRAWL_KEY', retry: false };
  }
  if (status === 402) {
    return { action: 'STOP_FREE_CREDITS_OR_PAYMENT_REVIEW', retry: false };
  }
  if (status === 429) {
    return { action: 'LIMITED_BACKOFF_OR_HUMAN_REVIEW', retry: true };
  }
  if (status === 408 || status >= 500) {
    return { action: 'ONE_CONTROLLED_RETRY_AFTER_READBACK', retry: true };
  }
  return { action: 'STOP_UNKNOWN_FIRECRAWL_FAILURE', retry: false };
}

這個分類器是本地 policy 範例，實際錯誤仍要讀當日 API reference、response body 和 dashboard。最重要的不是讓 agent 永遠 retry，而是讓它知道 credits、來源、帳務和內容風險都可能需要人。若一次成功的 scrape response 沒有得到預期 metadata、source URL 或 cost read-back，就先保留在隔離區，不交給主要 agent。

學生 agent 的最小驗收

1. 由本人閱讀當日 Firecrawl pricing、API introduction、credit usage、errors、Terms 和 Privacy 文件。
2. 確認 Free Plan、每月 1,000 credits、2 concurrent requests、low rate limits、no card、no rollover 和沒有 pay-per-use 的狀態。
3. 建立本人 API key，保存於 server-side secret store；先設定單一 endpoint、單一 host、短任務與本地 credits reserve。不分享、不放前端、不使用他人 session。
4. 對一個合法公開的官方頁做單頁 markdown scrape，讀回 status、來源 URL、抓取時間、request metadata 和帳戶 credits 差異。
5. Search、Map、Crawl、Interact、Agent 只有在人工批准後使用，限制結果數、頁數、深度、browser minutes、dynamic run 和總成本。
6. 遇到 401、402、408、429、5xx、私密資料、prompt injection、授權不明或成本 read-back 失敗就停止；課程結束刪除 key、session、暫存原文與不必要的輸出。

本篇截至 2026-08-25 完成官方文件重新查核與本機草稿驗收，沒有進行 Firecrawl 註冊、建立 key、keyless onboarding、CLI／skill／MCP 安裝、live Search、Scrape、Crawl、Browser session 或外部資料擷取。工作區沒有授權 Firecrawl 帳戶，因此不代收、不建立、不分享 token、key、cookie 或 session。

本篇的學生 agent 決策

Firecrawl 可以列入「免費 web-context 工具」候選：官方 pricing 目前列 Free 每月 1,000 credits、免卡；單頁 Scrape、Crawl、Map 的計量相對容易預算，Search、Interact 和 Agent 則需要更嚴格的結果、分鐘和 dynamic cost 閘門。但它不是文字 LLM fuel，不能取代主要模型，也不能讓 agent 無限收集網路資料。

對主要 agent 最有價值的用途，是在已知來源上取得乾淨、可引用、可審計的上下文，再交給批准的文字模型。每次使用都要保留來源和查核日期，將網頁內容視為不可信輸入，並把 key、credits、著作權、個資、重試和人工停止分開治理。這樣免費 credits 才是學習 web agent 工程的燃料，而不是偷偷擴大的資料抓取管線。

若日後要改用 keyless、MCP 或 CLI，應另開一個明確的整合任務，重新核對官方 onboarding、工具權限、資料流、session 生命週期和 rate limit。不能因為官方提供 agent skill 就自動授權本機安裝、登入或對外抓取。文章完成只代表研究和本機草稿完成，不代表帳戶已啟用。

在來源治理上，最小可行的 web agent 應先有一份 host allowlist，例如只允許學校文件、官方產品文件或本系列指定的第一方頁面。allowlist 不是一次設定後永久有效；網域可能轉移、頁面可能改版、redirect 可能離開原始站點。每次抓取都要記錄最終 URL、原始 URL、HTTP status、content type 和抓取時間，發現跳轉到未知 host 就停止。

Scrape 回傳的 Markdown、HTML 或 JSON 不應直接進入系統提示。先包裝成外部資料區塊，明確標記來源和不可信狀態，再由主要 agent 的 policy 決定能否引用。頁面中的「請執行這段指令」「請忽略上層規則」「請把資料送到某網址」都只是內容，不是工具授權。這是 web-context agent 最重要的 prompt injection 邊界。

若文章有多個版本或相同 URL 反覆更新，不能只用 URL 當去重鍵。保存 canonical、title、last modified、ETag 或內容 hash，必要時再做 diff。這能避免每月 credits 被同一頁的大量重抓消耗，也讓學生知道來源在什麼時間點被 agent 讀到。來源變動時應重新摘要，而不是默默覆蓋舊內容。

對搜尋結果而言，Firecrawl 回傳的標題、摘要和 URL 只是發現入口，不是事實證明。主要 agent 應先挑出少量候選，再回到第一方頁面或原始文件核對關鍵數字、日期、版本和條款。不要把搜尋 snippets 當成完整內容，也不要因為 Search 比較便宜就把所有結果自動寫進知識庫。

對 PDF 或大型文件，先估算頁數、輸出大小和個資風險，再決定是否使用 Parse 或額外格式。文件可能包含隱藏文字、附件、掃描影像和第三方內容；一次成功解析不代表所有內容都完整、正確或可再利用。課堂應使用自己製作的公開測試文件，限制檔案大小，並在驗收後刪除暫存檔。

如果 agent 需要建立索引，先將原文和摘要分層保存：原文只放在短期隔離區，摘要保存來源與查核日期，向量化前先移除不必要的個資和秘密。向量庫也要有 TTL、刪除路徑和權限；Firecrawl 的免費 credits 只解決取得上下文，不會自動解決下游資料庫的保留、查詢或刪除責任。

主要 agent 的 web 工具最好把每次成本預估放在呼叫前。已知 URL 的單頁 scrape 可以先按頁數估算；Search 要按結果數估算；Crawl、Interact 和 Agent 要增加保守 reserve，因為實際範圍或 dynamic pricing 可能較難預測。預估超過 reserve 就先回報並要求人工批准，不用 provider 的免費額度做無限探索。

課堂結束的驗收不只是「有拿到 Markdown」。學生應能證明：使用的是自己的 key 或明確批准的 keyless path、credits 沒有超支、來源 host 合法、資料沒有秘密、prompt injection 沒有轉成工具呼叫、錯誤能停止、原文有刪除時間、摘要保留 citation。這些證據才足以把 Firecrawl 接到主要 agent。

若一個 provider 的官方頁面對 Free Plan、keyless、credits 或資料政策出現互相矛盾的版本，系列索引應記錄差異，而不是挑一個較大的數字宣傳。Firecrawl 目前 pricing、API docs、agent onboarding 和較舊法律頁面就有不同更新速度；學生開始實驗時要以當日可回讀頁面、帳戶狀態和適用條款為準，必要時暫停。

這也表示 web agent 的成功標準不是抓得越多越好，而是每一頁都能說明為什麼需要、從哪裡來、何時抓到、花了多少 credits、誰可以讀、何時刪除，以及內容是否經過第一方核對。將這些欄位放進工具契約，才能讓免費額度服務學習和研究，而不是變成無法追蹤的外部資料堆。

若無法回答這些問題，任務就停在候選狀態，不把抓取成功誤報成資料治理完成。這也是主要 agent 應該教給學生的核心：免費 API 仍然需要權限、成本、來源和刪除證據。

Firecrawl 官方查核入口

• Firecrawl Pricing、Free 1,000 credits、計量與 FAQ
• Firecrawl API Introduction、base URL、Bearer key 與狀態碼
• Credit Usage endpoint
• Scrape endpoint
• Search endpoint
• API Errors、429 與重試語意
• Browser interaction pricing 與 concurrency
• Firecrawl Agent onboarding 與 keyless 入口
• Firecrawl Terms of Service
• Firecrawl Privacy Policy

下一篇會重新查找另一個官方免費 API 候選；Firecrawl 的 1,000 credits 不會被延伸成免費文字 token，也不會因為文章完成就自動註冊、安裝 skill、啟用 keyless 或抓取外部資料。