> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8bz2qg.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AskでFirecrawlをデバッグ

> 失敗したジョブまたはFirecrawl連携の問題を、エージェント型サポートAPIでデバッグ

Firecrawl `/support/ask` は、APIとして提供されるAIサポートエージェントです。問題を説明すると、検証済みの診断結果と、すぐに使える修正パラメータが返されます。通常は15〜30秒で応答します。

**`/support/ask` は、あなたのエージェントのために待機するシニアFirecrawlエンジニアのようなものです。**

<Info>
  Ask API は主に **AIエージェントからの呼び出し** を想定して設計されています。Firecrawl をスクレイピング、クロール、またはデータ抽出に使うエージェントを構築している場合は、自律的な問題解決のために `/support/ask` をエラーハンドリングフローに組み込んでください。
</Info>

<div id="two-endpoints">
  ## 2つのエンドポイント
</div>

| エンドポイント                     | 認証                  | 対象         | できること                       |
| --------------------------- | ------------------- | ---------- | --------------------------- |
| `POST /support/ask`         | お使いのFirecrawl APIキー | エージェントとアプリ | チームのスコープ内で完全な診断ループを実行       |
| `POST /support/docs-search` | お使いのFirecrawl APIキー | エージェントとアプリ | Firecrawlの公開ドキュメントに基づく回答を返す |

<div id="quick-start">
  ## クイックスタート
</div>

<div id="debug-a-failing-crawl">
  ### 失敗したクロールをデバッグする
</div>

```bash theme={null}
curl -X POST https://api.firecrawl.dev/v2/support/ask \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "my crawl returned 3 pages but I expected 50"
  }'
```

<div id="search-the-docs">
  ### ドキュメントを検索
</div>

```bash theme={null}
curl -X POST https://api.firecrawl.dev/v2/support/docs-search \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "how do I set up webhook signature verification?"
  }'
```

<div id="debug-a-failed-job">
  ## 失敗したジョブをデバッグする
</div>

スクレイピング、クロール、バッチスクレイプ、検索、マップ、抽出など、すべてのFirecrawlジョブは`/support/ask`でデバッグできます。失敗内容を自然な言葉で説明し、ジョブIDがわかる場合は含めてください。エージェントは回答前に、そのジョブのログとアカウントの状態を取得します。

```bash theme={null}
curl -X POST https://api.firecrawl.dev/v2/support/ask \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "debug failed job 0f8c9a1b-4e2d-47a1-9c3f-1b2d3e4f5a6b — crawl of https://example.com failed after 12 pages",
    "rationale": "user needs the full docs site indexed before their demo"
  }'
```

できるだけ多くの情報を含めてください。情報が多いほど、原因を絞り込みやすくなります。

| 詳細                            | 役立つ理由                                                         |
| ----------------------------- | ------------------------------------------------------------- |
| Job ID                        | エージェント がその ジョブのログ、ステータス、ページごとの結果を直接確認できます                     |
| Target URL                    | bot protection、JS rendering、robots rules など、サイト固有の阻害要因を特定できます |
| error message または status code | レート制限 や credit の枯渇と、スクレイピングレベルの失敗を切り分けられます                    |
| 期待していた結果                      | 完全な失敗と、content が欠落したまま "成功" した ジョブ を区別できます                    |
| `rationale`                   | エージェント がエンドユーザーの目的を把握し、適切な根拠を優先できるようになります                     |

<div id="what-ask-checks-for-common-failures">
  ### Ask が一般的な失敗で確認する項目
</div>

| 症状                          | エージェントが調査する内容                                                                     |
| --------------------------- | --------------------------------------------------------------------------------- |
| ジョブのステータスが `failed`         | ジョブログ、上流の HTTP ステータス、プロキシと再試行の履歴                                                  |
| クロールで返されたページ数が想定より少ない       | `limit`、`maxDiscoveryDepth`、`includePaths`/`excludePaths`、サイトマップのカバレッジ、robots ルール |
| Markdown が空、または途中で切れている     | クライアントサイドレンダリング、`waitFor` のタイミング、必要な `actions`、`onlyMainContent` によるトリミング         |
| `401` / `402` / `429` レスポンス | API キーの有効性と制限、残りのクレジット、プランのレート制限                                                  |
| ジョブが停止したまま、またはタイムアウトする      | キューの状態、ページ単位のタイムアウト、プランごとのジョブ同時実行数                                                |
| webhook が送信されない             | 配信の試行、エンドポイントのレスポンス、署名確認の失敗                                                       |

ジョブ ID がありませんか？ [アクティビティログ](https://www.firecrawl.dev/app/logs)で行の URL にカーソルを合わせて **Copy ID** をクリックするか、ジョブの開始時に返された `id` を使用してください。

<div id="debug-from-activity-logs">
  ### アクティビティログからデバッグする
</div>

自分でリクエストを作成しなくても、ダッシュボードで同じエージェントを実行できます。[アクティビティログ](https://www.firecrawl.dev/app/logs)を開き、失敗した行の **アクション** 列にあるスパークルボタンを探してください。ツールチップには **問題をデバッグ** と表示されます。このボタンは、失敗したジョブ、または子リクエストでエラーが発生して完了したジョブにのみ表示されるため、成功したジョブや進行中のジョブには表示されません。

クリックするとすぐに診断が開始され、プロンプトを入力する必要はありません。Firecrawl は、そのジョブの URL、エンドポイント、ステータス、エラーメッセージ、スクレイピングパラメータを `/support/ask` を支える同じエージェントに送信します。エージェントはジョブのログとアカウントの状態を読み取ります。スクレイピングされたページコンテンツが含まれることはありません。

開いたパネルには、次の情報が表示されます。

| 要素          | 内容                                                 |
| ----------- | -------------------------------------------------- |
| 診断          | 問題の原因と変更すべき内容についてのエージェントの説明                        |
| 信頼度バッジ      | 高、中、低 — エージェントが回答にどの程度確信を持っているか                    |
| **検証済み**バッジ | エージェントが提案した修正をテストし、成功した場合に表示されます                   |
| 推奨される修正     | 修正後のパラメータを JSON で表示します。コピーボタンを使って次のリクエストに貼り付けてください |
| ソース         | 回答の根拠となったドキュメントページへのリンク                            |

診断で解決しない場合は、パネル下部の **サポートチケットを開く** を選択してください。エージェントの分析がすでに添付されたチケットが作成されるため、失敗内容を改めて説明する必要はありません。

<Info>
  ダッシュボードでのデバッグは、チームごとに1時間あたり30回までです。また、チームには少なくとも1つの API キーが必要です。エージェントは自身のキーで実行されるため、参照できるのは自身のジョブのみです。
</Info>

診断を取得したら、返された `fixParameters` を適用して再試行してください。詳しくは、以下の[エージェント再試行パターン](#agent-retry-pattern)を参照してください。

<div id="how-it-works">
  ## 仕組み
</div>

`/support/ask` を呼び出すと、AI エージェントは次の処理を行います。

1. **証拠を収集** — ジョブのログ、アカウントの状態、クレジットの使用状況、関連ドキュメントを並行して調べます
2. **問題を診断** — 集めた証拠全体をもとに推論し、根本原因を特定します
3. **修正を提案** — 次回の API 呼び出しに直接適用できる、機械処理可能な `fixParameters` を生成します
4. **修正を検証** — 可能な場合は、実際の Firecrawl API に対して修正をテストし (例: パラメータを調整してスクレイピングを再試行) 、結果を報告します

<div id="using-ask-in-your-agent">
  ## エージェントで Ask を使う
</div>

重要な設計パターン: Firecrawl API の呼び出しが失敗したり、想定外の結果が返ってきたりした場合は、`/support/ask` を呼び出し、その後 `fixParameters` を使って再試行します。

<div id="python-example">
  ### Python の例
</div>

```python theme={null}
import requests

FIRECRAWL_API_KEY = "fc-YOUR_API_KEY"

def diagnose_firecrawl_issue(question, rationale=None):
    """Call the Firecrawl Ask API to debug an issue."""
    payload = {"question": question}
    if rationale:
        payload["rationale"] = rationale

    response = requests.post(
        "https://api.firecrawl.dev/v2/support/ask",
        headers={
            "Authorization": f"Bearer {FIRECRAWL_API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
    )
    return response.json()


# 例: 空のコンテンツを返したスクレイピングをデバッグする
result = diagnose_firecrawl_issue(
    question="scrape returned empty markdown for https://example.com",
    rationale="user needs product pricing data for competitive analysis",
)

print(result["answer"])
print(result["fixParameters"])  # 例: {"waitFor": 5000, "actions": [...]}
print(result["confidence"])     # "high"、"medium"、または "low"
```

<div id="nodejs-example">
  ### Node.js の例
</div>

```javascript theme={null}
async function diagnoseFirecrawlIssue(question, rationale) {
  const response = await fetch(
    "https://api.firecrawl.dev/v2/support/ask",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.FIRECRAWL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ question, rationale }),
    }
  );
  return response.json();
}

// 例: 途中で停止したクロールをデバッグする
const result = await diagnoseFirecrawlIssue(
  "my crawl returned 3 pages but I expected 50",
  "user is on their third failed crawl attempt today"
);

console.log(result.answer);
console.log(result.fixParameters);
```

<div id="agent-retry-pattern">
  ### エージェントの再試行パターン
</div>

```python theme={null}
from firecrawl import Firecrawl

client = Firecrawl(api_key="fc-YOUR_API_KEY")

# ステップ1: スクレイピングを試みる
doc = client.scrape("https://example.com/pricing", formats=["markdown"])

if not doc.markdown or len(doc.markdown) < 100:
    # ステップ2: デバッグの支援を求める
    diagnosis = diagnose_firecrawl_issue(
        question=f"scrape returned only {len(doc.markdown or '')} chars of markdown for https://example.com/pricing",
    )

    # ステップ3: 修正パラメータを適用して再試行する
    if diagnosis.get("fixParameters"):
        doc = client.scrape(
            "https://example.com/pricing",
            formats=["markdown"],
            **diagnosis["fixParameters"],
        )
```

<div id="parameters">
  ## パラメータ
</div>

<div id="supportask">
  ### `/support/ask`
</div>

| パラメータ       | 型      | 必須  | 説明                                                        |
| ----------- | ------ | --- | --------------------------------------------------------- |
| `question`  | string | はい  | デバッグしたい内容 (1〜8,000文字)                                     |
| `rationale` | string | いいえ | AI 呼び出し元に推奨。エンドユーザーが何を達成しようとしているかを示します。証拠収集の優先順位付けに役立ちます。 |
| `context`   | object | いいえ | エージェントからの任意形式のメタデータ。デバッグ用promptに含まれます                     |

<div id="supportdocs-search">
  ### `/support/docs-search`
</div>

| パラメータ      | 型      | 必須 | 説明                  |
| ---------- | ------ | -- | ------------------- |
| `question` | string | はい | 回答対象の質問 (1〜8,000文字) |

<div id="response">
  ## レスポンス
</div>

<div id="supportask-response">
  ### `/support/ask` のレスポンス
</div>

```json theme={null}
{
  "requestId": "req_...",
  "answer": "<2-4 sentence prose diagnosis of the issue plus the recommended fix.>",
  "confidence": "high",
  "fixParameters": { "<param>": "<value>" },
  "validation": {
    "tested": true,
    "result": "success",
    "evidence": "<short summary of the validation tool call the agent ran to confirm the fix>"
  },
  "feedback": null,
  "durationMs": 18432
}
```

実際の`answer`、`fixParameters`、`validation.evidence`は、各リクエストについて、実行内容に応じてエージェントが生成します。上記の例は実際の診断結果ではなく、レスポンスの形式を示したものです。

<div id="supportdocs-search-response">
  ### `/support/docs-search` のレスポンス
</div>

```json theme={null}
{
  "requestId": "req_...",
  "answer": "The signature is sent in the X-Firecrawl-Signature header...",
  "evidence": [
    { "pathOrUrl": "webhooks/security.mdx#L1-L52", "reason": "..." }
  ],
  "usage": { "inputTokens": 4356, "outputTokens": 688, "totalTokens": 5044 },
  "durationMs": 11252
}
```

<div id="performance">
  ## パフォーマンス
</div>

| 指標    | 一般的    | 最大          |
| ----- | ------ | ----------- |
| レイテンシ | 15〜30秒 | 60秒 (厳密な上限) |

<div id="api-reference">
  ## APIリファレンス
</div>

* [Ask エンドポイントのAPIリファレンス](/ja/api-reference/endpoint/ask)
* [Docs Search エンドポイントのAPIリファレンス](/ja/api-reference/endpoint/docs-search)

フィードバックやサポートが必要な場合は、[help@firecrawl.com](mailto:help@firecrawl.com) までメールでご連絡ください。

> Firecrawl APIキーが必要なAIエージェントですか？自動オンボーディング手順については、[firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) をご覧ください。