xcrawl

XCrawl

概要

このスキルは、ユーザーが特定の API やサブスキルを指定せずに XCrawl を直接求めた場合の、デフォルトの XCrawl エントリーポイントです。 現在は、XCrawl Scrape API による単一ページの抽出を対象としています。 デフォルトの動作は未加工のパススルーです。上流 API のレスポンス本文をそのまま返します。

ルーティングの指針

• ユーザーが特定の URL を 1 つ以上抽出したい場合は、このスキルを使用し、デフォルトで XCrawl Scrape を選択します。
• ユーザーがサイトの URL を検出したい場合は、XCrawl Map API を優先します。
• ユーザーが複数ページまたはサイト全体をクロールしたい場合は、XCrawl Crawl API を優先します。
• ユーザーがキーワードベースで検出したい場合は、XCrawl Search API を優先します。

必須のローカル設定

このスキルを使用する前に、ユーザーはローカル設定ファイルを作成し、XCRAWL_API_KEY を記述する必要があります。

パス：~/.xcrawl/config.json

{
  "XCRAWL_API_KEY": "<your_api_key>"
}

API キーはローカル設定ファイルからのみ読み取ってください。グローバル環境変数を必須にしないでください。

クレジットとアカウントの設定

XCrawl API の使用にはクレジットが消費されます。 ユーザーがアカウントを持っていない場合、または利用可能なクレジットがない場合は、https://dash.xcrawl.com/ での登録を案内してください。 登録後、リクエストを実行する前に、無料の 1000 クレジットプランを有効にできます。

ツールの権限ポリシー

curl と node のランタイム権限のみを要求してください。 Python、シェルヘルパースクリプト、その他のランタイム権限は要求しないでください。

API の概要

• スクレイプの開始：POST /v1/scrape
• 非同期結果の取得：GET /v1/scrape/{scrape_id}
• ベース URL：https://run.xcrawl.com
• 必須ヘッダー：Authorization: Bearer <XCRAWL_API_KEY>

使用例

cURL（同期）

API_KEY="$(node -e "const fs=require('fs');const p=process.env.HOME+'/.xcrawl/config.json';const k=JSON.parse(fs.readFileSync(p,'utf8')).XCRAWL_API_KEY||'';process.stdout.write(k)")"

curl -sS -X POST "https://run.xcrawl.com/v1/scrape" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{"url":"https://example.com","mode":"sync","output":{"formats":["markdown","links"]}}'

cURL（非同期の作成と結果の取得）

API_KEY="$(node -e "const fs=require('fs');const p=process.env.HOME+'/.xcrawl/config.json';const k=JSON.parse(fs.readFileSync(p,'utf8')).XCRAWL_API_KEY||'';process.stdout.write(k)")"

CREATE_RESP="$(curl -sS -X POST "https://run.xcrawl.com/v1/scrape" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{"url":"https://example.com/product/1","mode":"async","output":{"formats":["json"]},"json":{"prompt":"Extract title and price."}}')"

echo "$CREATE_RESP"

SCRAPE_ID="$(node -e 'const s=process.argv[1];const j=JSON.parse(s);process.stdout.write(j.scrape_id||"")' "$CREATE_RESP")"

curl -sS -X GET "https://run.xcrawl.com/v1/scrape/${SCRAPE_ID}" \
  -H "Authorization: Bearer ${API_KEY}"

Node

node -e '
const fs=require("fs");
const apiKey=JSON.parse(fs.readFileSync(process.env.HOME+"/.xcrawl/config.json","utf8")).XCRAWL_API_KEY;
const body={url:"https://example.com",mode:"sync",output:{formats:["markdown","json"]},json:{prompt:"Extract title and publish date."}};
fetch("https://run.xcrawl.com/v1/scrape",{
  method:"POST",
  headers:{"Content-Type":"application/json",Authorization:`Bearer ${apiKey}`},
  body:JSON.stringify(body)
}).then(async r=>{console.log(await r.text());});
'

リクエストパラメーター

リクエストのエンドポイントとヘッダー

• エンドポイント：POST https://run.xcrawl.com/v1/scrape
• ヘッダー：
• Content-Type: application/json
• Authorization: Bearer <api_key>

リクエスト本文：トップレベルのフィールド

フィールド	型	必須	デフォルト	説明
url	string	はい	-	対象 URL
mode	string	いいえ	sync	sync または async
proxy	object	いいえ	-	プロキシ設定
request	object	いいえ	-	リクエスト設定
js_render	object	いいえ	-	JS レンダリング設定
output	object	いいえ	-	出力設定
webhook	object	いいえ	-	非同期 Webhook 設定（mode=async）

proxy

フィールド	型	必須	デフォルト	説明
location	string	いいえ	US	ISO-3166-1 alpha-2 国コード。例：US / JP / SG
sticky_session	string	いいえ	自動生成	スティッキーセッション ID。同じ ID の場合、同じ出口の再利用を試みます

request

フィールド	型	必須	デフォルト	説明
locale	string	いいえ	en-US,en;q=0.9	Accept-Language に影響します
device	string	いいえ	desktop	desktop / mobile。ユーザーエージェントとビューポートに影響します
cookies	object map	いいえ	-	Cookie のキーと値のペア
headers	object map	いいえ	-	ヘッダーのキーと値のペア
only_main_content	boolean	いいえ	true	メインコンテンツのみを返します
block_ads	boolean	いいえ	true	広告リソースのブロックを試みます
skip_tls_verification	boolean	いいえ	true	TLS 検証をスキップします

js_render

フィールド	型	必須	デフォルト	説明
enabled	boolean	いいえ	true	ブラウザーでのレンダリングを有効にします
wait_until	string	いいえ	load	load / domcontentloaded / networkidle
viewport.width	integer	いいえ	-	ビューポートの幅（デスクトップ 1920、モバイル 402）
viewport.height	integer	いいえ	-	ビューポートの高さ（デスクトップ 1080、モバイル 874）

output

フィールド	型	必須	デフォルト	説明
formats	string[]	いいえ	["markdown"]	出力形式
screenshot	string	いいえ	viewport	full_page / viewport（formats に screenshot が含まれる場合のみ）
json.prompt	string	いいえ	-	抽出プロンプト
json.json_schema	object	いいえ	-	JSON Schema

output.formats の列挙値：

• html
• raw_html
• markdown
• links
• summary
• screenshot
• json

webhook

フィールド	型	必須	デフォルト	説明
url	string	いいえ	-	コールバック URL
headers	object map	いいえ	-	カスタムコールバックヘッダー
events	string[]	いいえ	["started","completed","failed"]	イベント：started / completed / failed

レスポンスパラメーター

同期作成レスポンス（mode=sync）

フィールド	型	説明
scrape_id	string	タスク ID
endpoint	string	常に scrape
version	string	バージョン
status	string	completed / failed
url	string	対象 URL
data	object	結果データ
started_at	string	開始時刻（ISO 8601）
ended_at	string	終了時刻（ISO 8601）
total_credits_used	integer	使用したクレジットの合計

data のフィールド（output.formats に基づく）：

• html、raw_html、markdown、links、summary、screenshot、json
• metadata（ページのメタデータ）
• traffic_bytes
• credits_used
• credits_detail

credits_detail のフィールド：

フィールド	型	説明
base_cost	integer	基本スクレイプコスト
traffic_cost	integer	トラフィックコスト
json_extract_cost	integer	JSON 抽出コスト

非同期作成レスポンス（mode=async）

フィールド	型	説明
scrape_id	string	タスク ID
endpoint	string	常に scrape
version	string	バージョン
status	string	常に pending

非同期結果レスポンス（GET /v1/scrape/{scrape_id}）

フィールド	型	説明
scrape_id	string	タスク ID
endpoint	string	常に scrape
version	string	バージョン
status	string	pending / crawling / completed / failed
url	string	対象 URL
data	object	同期時の data と同じ形式
started_at	string	開始時刻（ISO 8601）
ended_at	string	終了時刻（ISO 8601）

ワークフロー

1. デフォルトの XCrawl エントリー動作を通じて、リクエストを分類します。

• ユーザーが抽出対象の具体的な URL を提示した場合は、デフォルトで XCrawl Scrape を使用します。
• ユーザーが map、crawl、または search の動作を明確に求めている場合は、このエンドポイントがそれらに対応すると装わず、専用の XCrawl API に振り分けます。

2. ユーザーの目的を抽出条件として言い換えます。

• URL の範囲、必須フィールド、許容される null 値、精度への期待を明確にします。

3. scrape リクエスト本文を作成します。

• 必要なオプションのみを指定します。
• output.formats は明示的に指定することを優先します。

4. scrape を実行し、タスクのメタデータを記録します。

• scrape_id、status、タイムスタンプを追跡します。
• 非同期の場合は、completed または failed になるまでポーリングします。

5. 生の API レスポンスをそのまま返します。

• デフォルトではフィールドを合成したり、要約したりしないでください。

出力仕様

以下を返します：

• 使用したエンドポイントとモード（sync または async）
• リクエストに使用した request_payload
• 各 API 呼び出しの生のレスポンス本文
• リクエストが失敗した場合はエラーの詳細

ユーザーが明示的に要約を求めない限り、要約を生成しないでください。

ガードレール

• XCrawl Scrape が map、crawl、または search のセマンティクスにも対応しているかのように説明しないでください。
• ユーザーの意図が URL 抽出の場合にのみ、デフォルトで scrape を使用してください。
• サポートされていない出力フィールドを作り出さないでください。
• プロバイダー固有のツールスキーマをコアロジックにハードコードしないでください。
• ページ構造が不安定な場合は、不確実性を明示してください。