API endpointリファレンス

リクエストパラメーターとレスポンスフォーマットを含む、すべてのFourA API endpointのリファレンス。

ベースURL

https://eu.api.foura.ai/api

認証

すべてのリクエストで、X-API-Key ヘッダーに API キーを含める必要があります:

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'

APIキーの作成と管理は、Dashboardで行います。キーにはpk_live_プレフィックスが使用されます。

レスポンスヘッダー

/api/*からのすべてのレスポンスには、2つの相関ヘッダーが含まれます:

ヘッダー	値	説明
`X-FourA-Request-Id`	UUID	リクエストに割り当てられた一意のID。4xxおよび5xxを含むすべてのレスポンスで返されます。手元でログに記録してください。
`X-FourA-Credits`	integer	このリクエストで消費されたクレジット。成功時および失敗時に返されます(どちらの場合も処理が実行されたため)。どのアウトカムが請求対象となるかについては、Request Outcomesを参照してください。

同じリクエストIDが、DashboardのActivity Log(24時間保持、キーごとに最新200件)におけるリクエストおよびレスポンスのペイロードプレビューのキーとなります。これにより、後で正確なリクエストを検索し、Activityから直接Playgroundへリプレイすることができます。サポートにお問い合わせの際にこのIDを含めると、リクエストを数秒で特定できます。

$ curl -i -X POST https://eu.api.foura.ai/api/single/ \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"method": "GET", "url": "https://example.com"}'

HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
x-foura-credits: 2
...

完全なリストと使用上のヒントについては、Response Headersを参照してください。

エンドポイント

MCP経由でこれらのエンドポイントを使用しますか？ @fouradata/mcpサーバーは、4つのエンドポイントすべてをネイティブなMCPツール(foura_auto、foura_single、foura_proxy、foura_browser)としてラップします。これらは同じ入力形状を持ち、トークンに最適化された大規模レスポンス処理のためのoffload_largeオプトインを備えています。

FourAは4つのリクエストエンドポイントを提供し、それぞれが異なるシナリオに最適化されています:

エンドポイント	最適な用途
`POST /auto/`	スマートフェッチ。URLを渡すと、FourAは機能する最も安価なパス(ダイレクト、ローテーションproxy、またはブラウザ)を選択し、ホストごとに機能したものを記憶します。
`POST /single/`	高速なHTTPリクエスト、静的ページ、API
`POST /proxy/`	自動proxyローテーション、オプションのターゲット可視な国スコープを備えた保護されたサイト
`POST /browser/`	JavaScriptでレンダリングされたページ、SPA
`GET /profiles`	`single`および`proxy`用のブラウザプロファイルカタログ。公開、APIキー不要。

それぞれを選択するタイミングの詳細なウォークスルーについては、Choosing the Right EndpointおよびSmart Fetch guideを参照してください。

ターゲットURLの制限

プライベート、ループバック、または予約済みのIP範囲(RFC 5735、RFC 6598、IPv6予約ブロック)に解決されるターゲットは、リクエストがFourAを出る前に400エラーで拒否されます。パブリックなホスト名とIPのみが転送されます。

{ "error": "Target <ip> resolves to a private/reserved IP" }

Smart Fetch (Auto)

POST /api/auto/

URLと任意のvalidateルールを渡します。FourAはコストを考慮したラダー(安価なdirect probe、rotated proxy、full browser)をたどり、ルールが受け入れるresponseを返す最初の段階で停止します。同じホストへの繰り返しの呼び出しでは、代わりにウォームセッションがリプレイされるため、2回目のアクセスは安価になります。

リトライ、プールサイズ、proxyの数を調整する必要はありません。FourAがホストごとにこれらを学習します。

Request Body

Parameter	Type	Required	Default	Description
`url`	string	Yes	-	ターゲットURL
`method`	string	No	`"GET"`	HTTPメソッド
`headers`	[string, string][]	No	-	[name, value]のペアからなるカスタムheader
`data`	any	No	-	non-GET request用のrequest body
`validate`	object	No	-	成功基準。Single Requestの`validate`と同じ形式(下記参照)。コンテンツとチャレンジページを区別できるように、実際のページの見た目をautoに伝えます。
`returnSession`	boolean	No	`true`	`/api/single/`または`/api/browser/`を介してリプレイできるように、成功したセッション(`proxy`、`cookies`、`userAgent`)をresponseに含めます。
`forceProxy`	boolean	No	`true`	常にrotating proxyを経由してルーティングします。ターゲットが許可する場合により安価な直接パスを許可するには、`false`を設定します(一部の防御はproxyトラフィックに対してより厳格です)。
`timeout_ms`	integer	No	`120000`	呼び出し全体の合計時間バジェット(ミリ秒)。すべてのサブ試行はこのバジェット内で実行されます。最小値`5000`、最大値`180000`。
`ignoreProxies`	string[]	No	-	すべてのサブ試行で回避するproxy ID。以前の`/api/auto/`または`/api/proxy/`のresponseで返されたIDを使用します。
`followRedirects`	integer	No	`5`	安価なラダー階層で追従する最大リダイレクト数。無効にするには`0`を指定します。最大値`20`。

Response

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}

フィールド	型	説明
`status`	number	ターゲットからのHTTPステータス。
`data`	string or object	レスポンスボディ。
`headers`	array or object	ターゲットのレスポンスヘッダー。singleおよびproxyラングはホップごとのヘッダーオブジェクトの配列を返し、browserラングはフラットなオブジェクトを返します。
`meta.rung`	string	どのラダーのラングがレスポンスを配信したか。以下のいずれか: `probe` (安価な直接リクエスト)、`proxy` (ローテーティングproxy)、`browser` (完全なブラウザレンダリング)、`cache` (ウォームセッションのリプレイ)、または `fail` (承認されたレスポンスを生成したラングなし)。
`meta.solved`	boolean	この呼び出し中にボットチャレンジが解決されたかどうか。
`meta.attempts`	number	成功するまでに行われたサブリトライ回数。
`meta.credits`	number	この呼び出しで消費された合計クレジット。`X-FourA-Credits`と一致します。
`session.proxy`	string	レスポンスを配信したproxyのエンコード済みID。SingleまたはBrowserリクエストで再利用します。`returnSession`が`true`の場合に存在します。
`session.cookies`	array	成功した試行からのcookie。`returnSession`が`true`の場合に存在します。
`session.userAgent`	string	成功した試行で使用されたUser-Agent。`returnSession`が`true`の場合に存在します。
`error`	string	呼び出しが失敗した場合のエラーメッセージ。

例

curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'

注意点

Autoはコーディネーターです。内部的にSingle、Proxy、またはBrowserを呼び出し、APIキーを各サブコールに転送します。各サブコールはアクティビティログに表示されます。外側の/api/auto/呼び出しによって個別の課金行が追加されることはありません。
実際のページにのみ存在する部分文字列をvalidate.data.acceptに渡してください。これがないと、Autoは実際のステータス200と、ステータス200で返されるチャレンジ用のインタースティシャル画面を区別できません。
timeout_msは呼び出し全体の上限を設定します。保護されたサイトへの初回のコールドアクセスには数十秒かかる場合がありますが、再利用されたウォームセッションは通常1秒未満で完了します。

Single Request

POST /api/single/

実際のブラウザを起動することなく、実際のブラウザに近い通信特性を持つHTTPリクエストを送信します。これは最も高速なエンドポイントです。

リクエストボディ

パラメータ	型	必須	デフォルト	説明
`method`	string	はい	-	HTTPメソッド: GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS
`url`	string	はい	-	ターゲットURL。キャッシュバスティングのための現在のタイムスタンプを挿入するには、URLの任意の場所に`{ts}`を使用します。
`headers`	[string, string][]	いいえ	-	[name, value]ペアのカスタムヘッダー
`unblocker`	boolean	いいえ	`true`	リアルなブラウザヘッダー(User-Agent、Sec-Ch-Ua、Sec-Fetch-*、Accept-Encoding)を送信します。デフォルトでオンです。プレーンなクライアントシグネチャを送信するには`false`を設定します。
`timeout_ms`	number	いいえ	15000	ミリ秒単位の全体タイムアウト(最大: 120000)
`connect_timeout_ms`	number	いいえ	5000	ミリ秒単位の接続タイムアウト
`accept_timeout_ms`	number	いいえ	5000	ミリ秒単位のAcceptタイムアウト(接続の受け入れを待つ時間)
`server_response_timeout_ms`	number	いいえ	15000	ミリ秒単位のサーバー応答タイムアウト(最初のバイトを待つ時間)
`dns_cache_timeout_sec`	number	いいえ	120	秒単位のDNSキャッシュTTL(最大: 240)
`followRedirects`	number	いいえ	disabled	追跡する最大リダイレクト数(0〜20)。無効にするには省略します。
`tryJsonData`	boolean	いいえ	false	可能であればレスポンス本文をJSONとして解析します
`returnBuffer`	boolean	いいえ	false	デコードされた文字列の代わりに生のバッファを返します
`data`	any	いいえ	-	リクエスト本文(文字列またはオブジェクト、JSONに自動シリアライズされます)
`proxy`	string	いいえ	-	同じ出口を固定するための、以前のレスポンスからのプロキシID。不透明な文字列をそのまま渡します。生のプロキシアドレスは`400 Invalid proxy format`で拒否されます。
`browser`	string	いいえ	Chrome	提示するブラウザ: Chrome、Edge、Safari、Firefox、またはTor。ブラウザプロファイルを参照してください。
`os`	string	いいえ	-	提示するオペレーティングシステム: Windows、macOS、Android、またはiOS。ファミリ名はすべてのバージョンを受け入れます。
`version`	string	いいえ	newest	カタログにリストされている、提示するブラウザのバージョン。複数が適合する場合は最新のものが優先されます。
`profile`	string	いいえ	-	上記の3つのフィールドの代わりとなる、`GET /api/profiles`からの正確なプロファイルID。
`validate`	object	いいえ	-	レスポンス検証ルール(以下を参照)

ブラウザプロファイル

デフォルトでは、リクエストは最新のGoogle Chromeを提示します。一部のターゲットは特定のブラウザを受け入れ、他のブラウザを拒否するため、browser、os、およびversionを使用して測定されたプロファイルのカタログを絞り込み、profileを使用してIDで1つを選択します。

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

ルール:

選択にはunblockerが必要です(デフォルトでオン)。unblockerがオフの場合、ブラウザのheaderは送信されないため、リクエストは不完全に適用されるのではなく拒否されます。
複数のプロファイルが一致する場合、最新バージョンが優先されます。
カタログに存在しない組み合わせを指定すると、利用可能なものを明記したエラーが返されます。異なるブラウザとしてリクエストが送信されることはありません。
同じ4つのフィールドが、requestオブジェクト(POST /proxy/内)で利用可能です。

GET /api/profilesは完全なカタログを返し、APIキーは不要です:

{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}

osFamilyは、ピッカーを構築する際のフィルタリング値です。osは、表示用のリリース名を保持します。

バリデーションルール

validateオブジェクトを使用すると、成功と失敗の条件を定義できます。fail条件に一致した場合、リクエストは失敗として扱われます。accept条件が設定されている場合、一致するレスポンスのみが成功として扱われます。

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}

フィールド	型	説明
`validate.status.accept`	number[]	許可する HTTP ステータスコード
`validate.status.fail`	number[]	拒否する HTTP ステータスコード
`validate.headers.accept`	object	必須となる header のキーと値のペア
`validate.headers.fail`	object	失敗のトリガーとなる header のキーと値のペア
`validate.data.accept`	string[]	response 本文に必須となる文字列
`validate.data.fail`	string[]	失敗のトリガーとなる response 本文の文字列

例

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://example.com/products",
    "timeout_ms": 10000
  }'

レスポンス:

{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "nginx", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342,
  "proxy": "A1B2C3"
}

ターゲットが本文の取得過程でボットチェックを実行した場合、レスポンスにはベンダー名とチェックを通過したかどうかを示すdefenseオブジェクトも含まれます:

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}

フィールド	型	説明
`status`	number	ターゲットからのHTTPステータスコード
`headers`	array	リダイレクトホップごとのオブジェクト1つ。それぞれにステータスラインとすべてのレスポンスヘッダーを含む`result`フィールドがあります。複数値ヘッダー(`Set-Cookie`、`Link`、`WWW-Authenticate`)は文字列の配列として返されます。
`data`	string/object	レスポンスボディ (`tryJsonData`がtrueの場合はJSON)
`total_time`	number	合計リクエスト時間(秒)
`proxy`	string	リクエストが通過したproxyのエンコード済みID (リクエストに`proxy`が提供された場合のみ)。後続の呼び出しで再利用して、同じ出口を固定します。
`defense`	object	ターゲットがこのリクエストでボットチェックを実行した場合にのみ存在します。`defense.solved`はチェックをクリアしたかどうかを示します。すべてのフィールドと完全なベンダーリストについては、Anti-Bot Defensesを参照してください。
`error`	string	リクエストが失敗した場合のエラーメッセージ

Proxy Request

POST /api/proxy/

失敗時に自動再試行するローテーティングproxiesを介してリクエストをルーティングします。オプションで、選択をターゲットから見える出口の国のセットにスコープ設定できます。

Request Body

パラメータ	型	必須	デフォルト	説明
`request`	object	はい	-	単一のリクエストボディ (上記のSingle Requestと同じフィールド)
`timeout_ms`	number	いいえ	45000	すべての試行の全体的なタイムアウト(ミリ秒) (最大: 120000)
`maxTries`	number	いいえ	5	最大proxyローテーション試行回数 (最大: 90)
`ignoreProxies`	string[]	いいえ	-	ローテーションから除外するProxy ID (以前のレスポンスで返されたIDを使用)
`exitCountries`	string[]	いいえ	-	ターゲットから見える2文字の国コードの厳密な許可リスト (例: `["CZ", "GB"]`)。値はトリミング、大文字化、および重複排除されます。未知の出口を持つproxiesは除外され、リクエストは要求されていない国にフォールバックすることはありません。

exitCountriesスコープ設定

選択には、利用可能な最新のターゲットから見える国のメタデータを使用し、通常は約10分以内に更新されます。これはリクエスト中のライブジオロケーション検索ではありません。proxyホストアドレスから配信国を推測しないでください。

現在のプールに要求された国に一致するものがない場合、レスポンスはエラーエンベロープとともにHTTP 200を返します:

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

リクエストされたスコープを維持し、後で再試行してください。ワークフローの国に関する要件が明示的に変更された場合にのみ、スコープを変更または拡張してください。

例

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 3,
    "exitCountries": ["CZ", "GB"],
    "request": {
      "method": "GET",
      "url": "https://example.com/prices"
    }
  }'

レスポンス:

{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "A1B2C3",
  "exitCountry": "CZ",
  "total": 2.341
}

フィールド	型	説明
`proxy`	string	使用されたproxyのエンコード済み識別子。SingleまたはBrowser requestで `proxy` フィールドに渡して再利用するか、 `ignoreProxies` を使用して次のProxy requestでスキップします。
`exitCountry`	string	requestを処理したproxyの2文字の国コード(ターゲットから見える値)。requestで `exitCountries` が設定されている場合のみ存在します。responseを信頼する前に、要求したコードのいずれかであることを常に確認してください。
`total`	number	外側の実時間(秒、浮動小数点数)。proxyの選択、リトライ、成功した試行を含みます。 `total_time` は内側のrequestのみを示します。 `total` は常に `total_time` 以上になります。
`error`	string	requestが失敗した場合のエラーメッセージ。スコープミスの場合、 `code` は `no_eligible_proxy` となり、 `details.exitCountries` は正規化されたスコープを返します。

Single Requestのすべてのresponseフィールドも含まれており、その中には defense もあります。botチェックに遭遇したproxyの試行は、Singleと同様に報告されます。

Browser Request

POST /api/browser/

ChromeブラウザインスタンスでURLを開きます。ページがロードされ、JavaScriptが実行され、完全にレンダリングされたHTMLとcookie jarを取得します。

リクエストボディ

パラメータ	型	必須	デフォルト	説明
`url`	string	はい	-	ターゲットURL
`headers`	object	いいえ	-	キーと値のペアとしてのカスタムheader
`cookies`	array	いいえ	-	設定するcookie: `[{name, value, domain?}]`
`userAgent`	string	いいえ	-	カスタムUser-Agent文字列
`unblocker`	boolean	いいえ	`true`	ページロード時に一般的なbotチャレンジ(Cloudflare clearanceや類似のゲート)を自動解決します。デフォルトでオン。解決せずにチャレンジページを含むページが返す内容をそのままレンダリングするには、 `false` を設定します。
`proxy`	string	いいえ	-	以前のresponseのProxy ID。同じ出口を固定します。不透明な文字列をそのまま返します。生のproxyアドレスは `400 Invalid proxy format` で拒否されます。
`timeout_ms`	number	いいえ	30000	ページロードのタイムアウト(ミリ秒)(最大: 120000)
`checkStatus`	number	いいえ	-	期待されるHTTPステータス(異なる場合、requestは失敗します)
`checkText`	string	いいえ	-	レンダリングされたページに表示される必要があるテキスト

例

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

レスポンス:

{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]},
  "proxy": "A1B2C3"
}

フィールド	型	説明
`status`	number	ターゲットからのHTTPステータスコード
`headers`	object	Responseヘッダー
`body`	string または object	完全にレンダリングされたページコンテンツ。content-typeがHTMLの場合はstring HTML、ページがJSONを返し自動解析された場合はobjectになります。
`cookies`	array	ページからの完全なcookieオブジェクト。各cookieには`name`、`value`、`domain`、`path`、`expires`、`httpOnly`、`secure`、`sameSite`、その他のcookieプロパティが含まれます。
`userAgent`	string	使用されたブラウザのUser-Agent
`defenseSolved`	boolean	ボット防御に遭遇し、この呼び出しで実際にクリアされた場合は`true`になります。それ以外の場合は存在しません。15クレジットと30クレジットのコストの基準になります。
`defenses`	object	`present`はページ読み込み中に認識されたすべてのベンダーをリストし、`cleared`は最終ページがクリアランスを保持しているベンダーをリストします。ベンダーは`present`に表示されても、`cleared`に表示されない場合があります。Anti-Bot Defensesを参照してください。
`proxy`	string	リクエストが通過したproxyのエンコードされたID (リクエストに`proxy`が指定された場合のみ)。同じ出口を維持するために、後続の呼び出しでこれを再利用します。
`error`	string	リクエストが失敗した場合のエラーメッセージ

HTTPステータスコード

コード	意味
200	リクエスト完了 (ターゲットのresponseについては内部の`status`を確認してください)
400	無効なリクエストボディ、パラメータ、またはプライベート/予約範囲内のターゲットIP
401	APIキーが欠落しているか無効です
429	レート制限を超過しました
500	内部サーバーエラー
502	`Upstream unavailable`。FourAはエンジンに到達しましたが、応答が使用できませんでした。再試行してください。
503	サービスが一時的に無効になっているか容量に達しているか、またはエンジン再起動中の`Backend service unavailable`です
504	`Upstream timeout`。エンジンはこのリクエストの時間予算内に終了しませんでした。`timeout_ms`を上げるか、再試行してください。

次のステップ

Smart Fetch (Auto): FourAにパスを自動選択させるタイミング
Choosing the Right Endpoint: Single、Proxy、またはBrowserを手動で選択するタイミング
Authentication: APIキーの管理
Error Handling: エラーの適切な処理
Anti-Bot Defenses: defenseフィールドの読み取りとクリアランスの再実行
Rate Limits: リクエスト制限の理解
Quick Start: 30秒での最初のリクエスト

最終更新日: 2026年8月12日