API ドキュメント

エンドポイントは 1 つ、フィールドは op だけ。すべてのエンドポイントが同じリクエスト形式です。

クイックスタート

まず何が返ってくるか見たい場合は Playground へ。このページを先に読む必要はありません。

登録してキーを取得し（無料プランは 100 クレジット）、次を実行します：

curl -X POST https://widefetch.com/v1/call \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"google.search","params":{"keyword":"vector database"}}'

認証

Authorization: Bearer sk_…。キーはコンソールで発行され、全体が表示されるのは発行時の 1 回だけです（保存されるのはハッシュのみ）。

失効は即時に反映されます。キーが漏れたら失効させて新しいキーを発行してください。

呼び出し

POST /v1/call

フィールド	型	説明
op	string	呼び出すエンドポイント（下の表を参照）
params	object	そのエンドポイントのパラメータ

上限付き同期：約 25 秒以内に終わる呼び出しは結果をそのまま返します。超えた場合は status: "running" と request_id を返すので、それでポーリングします。ブラウザ系のエンドポイント（executor: browser）は時間がかかりやすく、http と api は通常 1〜2 秒で返ります。

{
  "request_id": "req_7Qn1vK…",
  "status": "done",          // done | running | failed
  "outcome": "ok",
  "credits_charged": 1,      // 0 when the call failed
  "timing": {
    "queued_ms": 400,
    "ran_ms": 8100,
    "attempts": 1            // >1 means it was retried
  },
  "result": { "items": [ … ] }
}

ポーリング

GET /v1/requests/{request_id}

レスポンス形式は上と同じです。2 秒ごとにポーリングし、5 秒まで間隔を広げてください。

課金ルール

失敗した呼び出しは無料です。CAPTCHA、レート制限、タイムアウト、未対応のレスポンスはこちらの責任として自動で返還されます。
結果 0 件は課金されます。「見つからなかった」は失敗ではなく答えであり、コストはすでに発生しています。

課金される outcome

no_resultsokverified_page

課金されない outcome

bad_paramscancelledcaptchaclaim_timeoutneeds_mappingnot_configuredrate_limitedtimeouttransient

一覧にない outcome はすべて無料です。デフォルトで課金すると、こちらの不具合があなたの請求になってしまうからです。

エンドポイント

op	credit	パラメータ	説明
brave.search	1	keyword*, limit, region, language	Web 検索結果：タイトル、URL、スニペット。高速で、大量の並列呼び出しに向いています。	試す
github.repo	1	repo*	GitHub リポジトリ 1 件：スター、フォーク、未解決 issue、言語、ライセンス、トピック。	試す
github.search	1	query*, sort, order, limit	GitHub リポジトリ検索。スター数、フォーク数、更新日時で並べ替え。	試す
google.search	1	keyword*, limit, language, region	Google のオーガニック検索結果：タイトル、URL、ドメイン、スニペット。	試す
google.trends	1	keyword*, region	Google トレンドの検索インタレスト：過去 2 年間の週次系列（0–100）。	試す
hn.comments	1	keyword*, limit, sort, since	Hacker News のコメント検索：原文、投稿者、元のスレッド。	試す
hn.item	1	id*, comments	Hacker News のスレッド全体：本文とすべてのコメント。	試す
hn.search	1	keyword*, limit, sort, since, min_points	Hacker News の投稿：タイトル、リンク、投稿者、ポイント、コメント数、日時。	試す

エラーコード

コード	意味	対処
400	パラメータが不正、または op が存在しない	リクエストを修正。課金なし
401	キーが誤っているか失効済み	別のキーを使う
402	クレジット不足	アップグレードするか月次リセットを待つ
403	このキーの許可リストにその op がない	レスポンスの `error` フィールドを確認
429	レートまたは同時実行数の上限超過	間隔を空けてリトライ。課金なし
502	こちら側または上流の問題	リトライ。課金なし

レート制限

各キーのデフォルトは毎分 60 回、同時実行数には上限があります。超えるとキューではなく 429 が返ります。

より高い上限が必要な場合はご連絡ください。