xcrawl-scrape

XCrawl スクレイプ

概要

このスキルは、XCrawl スクレイプ API を使用して単一ページを抽出します。 デフォルトの動作は生のレスポンスをそのまま返すことで、上流 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>

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

Field	Type	Required	Default	Description
url	string	Yes	-	対象 URL
mode	string	No	sync	sync または async
proxy	object	No	-	プロキシ設定
request	object	No	-	リクエスト設定
js_render	object	No	-	JS レンダリング設定
output	object	No	-	出力設定
webhook	object	No	-	非同期 Webhook 設定（mode=async）

proxy

Field	Type	Required	Default	Description
location	string	No	US	ISO-3166-1 alpha-2 の国コード（例：US / JP / SG）
sticky_session	string	No	自動生成	スティッキーセッション ID。同じ ID の場合は同じ出口の再利用を試みます

request

Field	Type	Required	Default	Description
locale	string	No	en-US,en;q=0.9	Accept-Language に影響します
device	string	No	desktop	desktop / mobile。UA とビューポートに影響します
cookies	object map	No	-	Cookie のキーと値のペア
headers	object map	No	-	ヘッダーのキーと値のペア
only_main_content	boolean	No	true	メインコンテンツのみを返します
block_ads	boolean	No	true	広告リソースのブロックを試みます
skip_tls_verification	boolean	No	true	TLS 検証をスキップします

js_render

Field	Type	Required	Default	Description
enabled	boolean	No	true	ブラウザーのレンダリングを有効にします
wait_until	string	No	load	load / domcontentloaded / networkidle
viewport.width	integer	No	-	ビューポートの幅（デスクトップ 1920、モバイル 402）
viewport.height	integer	No	-	ビューポートの高さ（デスクトップ 1080、モバイル 874）

output

Field	Type	Required	Default	Description
formats	string[]	No	["markdown"]	出力形式
screenshot	string	No	viewport	full_page / viewport（formats に screenshot が含まれる場合のみ）
json.prompt	string	No	-	抽出プロンプト
json.json_schema	object	No	-	JSON Schema

output.formats の列挙値：

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

webhook

Field	Type	Required	Default	Description
url	string	No	-	コールバック URL
headers	object map	No	-	カスタムコールバックヘッダー
events	string[]	No	["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. ユーザーの目標を抽出条件として言い換えます。

• URL の範囲、必須フィールド、許容される null、求められる精度。

2. スクレイピングリクエストの本文を作成します。

• 必要なオプションだけを残します。
• output.formats を明示的に指定することを推奨します。

3. スクレイピングを実行し、タスクのメタデータを記録します。

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

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

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

出力条件

以下を返します。

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

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

ガードレール

• 未対応の出力フィールドを作り出さないでください。
• コアロジックにプロバイダー固有のツールスキーマをハードコードしないでください。
• ページ構造が不安定な場合は、不確実性を明示してください。