ドキュメント › APIリファレンス › API endpointリファレンス

API endpointリファレンス

すべてのFourA API endpointのリファレンスです。requestパラメータおよびresponse形式を含みます。

Base URL

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

認証

すべてのrequestには、X-API-Key headerにAPI keyを含める必要があります:

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"}'

DashboardでAPIキーを作成および管理します。キーにはプレフィックスpk_live_が使用されます。

Response Headers

/api/*からのレスポンスには、2つの関連付け用headerが含まれます:

Header Value Description
X-FourA-Request-Id UUID requestに割り当てられた一意のID。FourAが完全に読み取れないbodyを除き、4xxおよび5xxを含むすべてのresponseで返されます(400 Invalid JSON in request bodyおよび413はIDが割り当てられる前に拒否されます)。クライアント側でログに記録してください。
X-FourA-Credits integer このrequestで消費されたクレジット。成功か失敗かを問わず、エンジンに到達したすべてのresponseで返されます(いずれの場合も処理が実行されたため)。エンジン実行前にFourAが拒否した呼び出し(キーの欠落または無効、プランやプラットフォームの制限、拒否されたターゲットまたはproxy ID)には含まれません。課金対象となる結果についてはRequest Outcomesを参照してください。

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

$ 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を参照してください。

Endpoints

MCP経由でこれらのエンドポイントを使用する場合: @fouradata/mcpサーバーは、4つのエンドポイントすべてをネイティブMCPツール（foura_auto、foura_single、foura_proxy、foura_browser）としてラップしています。同じ入力形状に加え、トークン効率の良い大容量レスポンス処理のためのoffload_largeオプトインも提供します。

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

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

各エンドポイントの選択基準に関する詳細なガイドについては、Choosing the Right EndpointおよびSmart Fetch guideを参照してください。

Target URL Restrictions

プライベート、ループバック、または予約済みIP範囲（RFC 5735、RFC 6598、IPv6予約済みブロック）に解決されるターゲットは、リクエストがFourAから送信される前に400エラーで拒絶されます。パブリックホスト名およびIPのみが転送されます。

{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }

Smart Fetch (Auto)

POST /api/auto/

URLと任意のvalidateルールを渡します。FourAはコストを考慮したラダー（低コストな直接プローブ、ローテーションproxy、フルブラウザ）を順に実行し、ルールに合致するレスポンスが返された最初の段階で停止します。同一ホストへの再リクエスト時はウォームセッションが再利用されるため、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 - GET以外のrequest用request body
validate object No - 成功判定基準。Single Requestのvalidateと同じ形式です（下記参照）。正常なページ構造をautoに指定し、正規コンテンツとチャレンジページを識別できるようにします。
returnSession boolean No true 成功したセッション情報（proxy, cookies, userAgent）をresponseに含め、/api/single/または/api/browser/で再利用可能にします。
forceProxy boolean No true 常にローテーション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 テキスト形式の response body。どのラダー層が処理した場合でもテキストとして返されます。JSON ページは JSON テキストとして返されるため、自身でパースしてください。
headers array or object ターゲットの response header。Single および proxy 層はホップごとの header オブジェクトの配列を返し、browser 層はフラットなオブジェクトを返します。
meta.rung string レスポンスを返送したラダー層。次のいずれか: probe（低コストな直接リクエスト）、proxy（ローテーション proxy）、browser（完全なブラウザレンダリング）、cache（ウォームセッションの再利用）、warmup（サイトのエントリページを先に取得し、その cookie で詳細 URL を開いた）、または 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 keyを転送します。Autoの呼び出しはActivity LogおよびOverview上で1件のrequestとして記録され、サブコールのクレジット合計が適用されます。サブコールはその試行（attempts）として配下にリストされ、個別のrequestとしてはカウントされません。
  • 実際のページにのみ含まれる部分文字列を指定してvalidate.data.acceptを渡してください。これがない場合、Autoは実際の200応答と、ステータス200で返されるチャレンジ中間ページを区別できません。
  • timeout_msは呼び出し全体の上限時間を設定します。保護されたサイトへの初回コールドアクセスには数十秒かかる場合がありますが、再利用されたウォームセッションは通常1秒未満で完了します。

Single Request

POST /api/single/

実際のブラウザを起動することなく、ブラウザに酷似した通信特性を持つHTTP requestを送信します。最も高速なendpointです。

Request Body

パラメータ 型 必須 デフォルト 説明
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 接続受付タイムアウト (接続受付を待機する時間、ミリ秒単位)
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 デコードされた文字列の代わりにRAWバッファを返します
data any いいえ - リクエストボディ (文字列またはオブジェクト、JSONに自動シリアライズ)
proxy string いいえ - 同一の出口に固定するための、過去のレスポンスに含まれるプロキシID。不透明な文字列をそのまま返行します。生のプロキシアドレスは 400 Invalid proxy format で拒否されます。一部のIDは固定できません: 出口の固定 を参照してください。
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 いいえ - レスポンス検証ルール (下記参照)

Browser profiles

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

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

ルール:

  • 選択にはunblockerが必要です(デフォルトで有効)。unblockerが無効の場合、ブラウザヘッダーが送信されないため、中途半端に適用されるのではなくリクエストが拒否されます。
  • 複数のプロファイルが一致する場合、最新のバージョンが優先されます。
  • カタログに存在しない組み合わせの場合は、利用可能な項目を示すエラーが返されます。リクエストが別のブラウザとして送信されることはありません。
  • POST /proxy/のrequestオブジェクト内でも同じ4つのフィールドを使用できます。

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

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

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

バリデーションルール

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

{
  "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 必須となるヘッダーのキーと値のペア
validate.headers.fail object 失敗と判定されるヘッダーのキーと値のペア
validate.data.accept string[] response body に含まれる必要がある文字列
validate.data.fail string[] 失敗と判定される response body 内の文字列

例

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
  }'

Response:

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

ターゲットがbodyの取得前にbotチェックを実行した場合、responseにはベンダー名およびチェックをクリアできたかどうかを示す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 リダイレクトホップごとのオブジェクト。各オブジェクトにはステータスラインとすべてのレスポンス header を含む result フィールドがあります。複数値の header (Set-Cookie, Link, WWW-Authenticate) は文字列の配列として返されます。
data string/object レスポンス body (tryJsonData が true の場合は JSON)
total_time number 合計リクエスト時間 (秒)
proxy string リクエストが経由した proxy のエンコード済み ID (リクエストで proxy が指定された場合のみ)。後続の呼び出しで再利用して同じイグジットを固定します。
defense object ターゲットがこのリクエストで bot チェックを実行した場合、またはサイト独自の cookie を使用したリトライで body が生成された場合に存在します。defense.solved はチェックがクリアされたかを示し、defense.retry はリトライでコンテンツを取得できたかを示します。すべてのフィールドおよびシステムの完全なリストについては Site checks を参照してください。
error string リクエストが失敗した場合のエラーメッセージ

Proxy Request

POST /api/proxy/

ローテーションする proxy を経由してリクエストをルーティングし、失敗時には自動でリトライします。オプションで、ターゲットから認識されるイグジット国のセットに対象を絞り込むことができます。

Request Body

パラメータ 型 必須 デフォルト 説明
request object はい - 単一のリクエスト body (上記の Single Request と同じフィールド)
timeout_ms number いいえ 45000 すべての試行に対する全体のタイムアウト (ミリ秒、最大: 120000)
maxTries number いいえ 5 最大 proxy ローテーション試行回数 (最大: 90)
ignoreProxies string[] いいえ - ローテーションから除外する proxy ID (以前のレスポンスで返された ID を使用)
exitCountries string[] いいえ - ターゲットから認識される 2 文字の国コードの厳密な許可リスト (例: ["CZ", "GB"])。値はトリム、大文字化、および重複排除されます。イグジットが不明な proxy は除外され、リクエストが要求されていない国にフォールバックすることはありません。
exitClass string いいえ - standard または premium。premium は、保護されたターゲットで標準プールが失敗した場合に、リクエストをプレミアムイグジットにエスカレーションすることを許可します。プレミアムイグジットを含むプランが必要です。

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"
    }
  }'

Response:

{
  "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 のエンコード済み識別子。proxy フィールドとして渡すことで Single または Browser リクエストで再利用するか、ignoreProxies 経由で次の Proxy リクエストでスキップします。
exitCountry string リクエストを処理した proxy のターゲットから見える2文字の国コード。リクエストで exitCountries を設定した場合にのみ存在します。レスポンスを信頼する前に、要求したコードのいずれかであることを必ず検証してください。
exitClass string このリクエストを処理した exit のクラス。リクエストで指定された場合、成功したレスポンスに含まれます。premium は premium exit が body を返したことを意味し、standard は standard pool が返したことを意味します。失敗した呼び出しは何も返さないため exitClass は含まれません。試行結果については attemptReport を確認してください。
total number 外部の実時間（秒単位、float）。proxy 選択、リトライ、成功した試行を含みます。total_time は内部リクエストのみです。total は常に total_time 以上になります。
profile string ローテーションによって選択されたブラウザプロファイル。要求したものと異なっていた場合にのみ存在します。存在しない場合は、リクエストが記述どおりに送信されたことを意味します。動作したブラウザを維持するには、後続の呼び出しで id を profile として返してください。
error string リクエストが失敗した場合のエラーメッセージ。scope miss の場合、code は no_eligible_proxy となり、details.exitCountries に正規化された scope がエコーされます。
attemptReport object 失敗したすべての Proxy 呼び出しに存在します。試行で発生した事象をカウントするため、ブロックされたプール、停止したプール、一致しなかった validate ルールがすべて同じエラーとして扱われることはありません。下記を参照してください。

すべての Single Request レスポンスフィールドも含まれ、defense もその1つです。bot 検知に遭遇した proxy の試行は、Single と同じ方法で報告されます。

Proxy 呼び出しが失敗した理由

試行がどのような結果になっても Download maxTry limit reached の表示は同じであるため、失敗したすべての Proxy レスポンスにはエラーの横に attemptReport が含まれます。

{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
フィールド 型 説明
total integer 試行回数
noResponse integer 出口ノードが応答せず、サイトに到達しなかった回数
defense integer サイトは応答したが、その応答で Bot 検知が認識された回数
contentRejected integer HTTP 200 かつ Bot 検知なし、設定した validate.data のみにより拒否された回数
statusRejected integer サイトは応答し Bot 検知はなかったが、設定した validate.status により拒否された回数
other integer 応答があり、上記のいずれにも該当しない回数
vendors string[] タスク内で認識された Bot 検知ベンダー
profilesTried string[] タスクが送信したブラウザプロファイル（初回使用順）。default はリクエストが変更されずに送信されたことを意味します。
summary string 各カウントから生成された1文（ログ記録用として安全）

error 文字列は変更されないため、この文字列でマッチングを行うクライアントはそのまま動作します。各カウントへの対処方法: Proxy Request の試行回数が上限に達した理由。

exitClass

ターゲットによっては、何度試行しても標準プールの出口ノードを拒否する場合があります。exitClass: premium を指定すると、Proxy は標準プール内でのみローテーションするのではなく、該当リクエストを標準プールに加えてプレミアム出口ノードへエスカレーションできるようになります。

{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}

送信前に知っておくべき3つの点があります。

これは許可であり、強制的な指示ではありません。 標準プールが引き続き応答を競合し、通常は標準プールが勝利します。プレミアムイグジットが加わるのは、プールがリクエストに短いバジェットを費やした場合、またはターゲットが明示的にリクエストを拒否した場合のみです。プレミアムイグジットを試行する前に標準プールが応答したリクエストは通常の成功となり、プレミアムトラフィックは消費されません。プレミアムイグジットが試行されると、以下に説明するように、そのトラフィックがカウントされます。

レスポンスには実際に処理を行ったものが示されます。 クラスを指定すると、レスポンスに exitClass が返されます:

{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}

premium はプレミアムイグジットがボディを返したことを示します。standard はスタンダードプールが返したことを意味し、プレミアムイグジットを取得できなかった場合や、プランに含まれるプレミアムトラフィック（および追加購入分）が請求期間内で消費された場合にもこの結果になります。どちらもエラーではなく、月次の合計ではなくリクエストごとにプレミアムトラフィックを照合できます。同じ値が X-FourA-Exit-Class レスポンスヘッダーでも返されます（Response Headers を参照）。

プレミアムトラフィックはネットワーク上で測定されます。 プレミアムの試行では、ページが返されたかどうかに関係なく、圧縮および暗号化された状態でネットワーク上を通過した送受信バイト数がカウントされます。別のイグジットが応答した時点でまだ実行中だった試行は即座に停止され、カウントされません。プレミアムトラフィックはプレミアム利用枠にカウントされ、総帯域幅の内数としても計上されます（同じバイト数が2箇所で報告され、合算はされません）。プレミアムイグジットがページを配信した場合、そのトラフィックがリクエスト全体のトラフィックとなるため、スタンダードトラフィックとして重複カウントされることはありません。Usage & Limits ページには、総トラフィック、そのうちのプレミアム比率、測定基準となるプレミアム利用枠が表示されます。

フィールドの省略は standard を送信することと同じではありません。省略した場合は決定が未指定のままになりますが、standard を送信するとこのリクエストがプレミアムにエスカレーションしてはならないことを明示的に指定します。特定のジョブをプレミアムトラフィックから完全に除外するにはこの方法を使用します。

利用枠の使い切りはエラーではありません。 利用枠を使い切った後に premium を指定したリクエストも動作し続けます。スタンダードプールから配信され、レスポンスには standard が示されます。利用枠の使い切りによってジョブが停止することはありません。

exitClass: premium にはプレミアムイグジットを含むプランが必要です。それを含まないプランでは、リクエストがプレミアムイグジットを消費することは一切ありません。X-FourA-Limit: plan_limit_premium を伴う 403 で拒否されるか（Rate Limits を参照）、レスポンスに exitClass: standard が含まれた状態でスタンダードプールから配信されます。両方のケースを処理してください。

Browser Profile Rotation

Proxy はイグジットをローテーションします。サイトがイグジット元ではなく FourA が提示したブラウザを拒否した場合、Proxy はカタログ内の別のブラウザファミリーにも切り替えます。これにより試行回数が増えることはありません。ローテーションはリトライ時に送信する内容を変更するのみで、リトライが実行されるかどうかに影響しません。

また、Proxy はサイトが最後に受け入れたファミリーを一定期間記憶するため、同じサイトへの以降の呼び出しではデフォルトではなくそのファミリーから開始できます。ローテーションが選択したファミリーと同様に、レスポンスの profile にその名前が指定されます。

内部の request で明示的に指定された profile、browser、os、または version は上書きされません。クリアランスはそれを取得したシグネチャに紐付けられているため、独自の User-Agent または Cookie ヘッダーを持つリクエストも同様に上書きされません。

Browser Request

POST /api/browser/

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

Request Body

Parameter Type Required Default Description
url string Yes - 対象URL
headers object No - キーと値のペアによるカスタムヘッダー
cookies array No - 設定するCookie: [{name, value, domain?}]
userAgent string No - カスタムUser-Agent文字列
unblocker boolean No true ページ読み込み前に要求されるチェック（チャレンジページなど）を完了します。デフォルトで有効です。falseに設定すると、チャレンジページを含め、ページから返された内容をそのままレンダリングします。
proxy string No - 同一の出口を固定するための、以前のレスポンスに含まれるプロキシID。不透明な文字列をそのまま返してください。生のプロキシアドレスは400 Invalid proxy formatで拒否されます。
exitCountry string No - リクエストの出口となる国の2文字国コード（ISO 3166-1 alpha-2）。ブラウザの時計を一致するタイムゾーンに設定します。Matching the browser clock to the exitを参照してください。
timeout_ms number No 30000 ページ読み込みタイムアウト（ミリ秒、最大: 120000）
checkStatus number No - 期待されるHTTPステータス（異なる場合はリクエストが失敗）
checkText string No - レンダリングされたページ内に存在する必要があるテキスト

Matching the browser clock to the exit

Webページはブラウザのタイムゾーンを読み取り、認識したIPアドレスの国と比較できます。この不一致はBot検知における最も低コストなシグナルの1つですが、解消するための追加コストはかかりません。

トラフィックの出口となる国をexitCountryに設定すると、ブラウザはその国に該当するタイムゾーンを返します:

{
  "url": "https://example.com",
  "proxy": "A1B2C3",
  "exitCountry": "BR"
}

ルール:

  • 値は出口国です。つまりプロキシがホストされている場所ではなく、ターゲットから見える国を意味します。この2つは無視できない頻度で一致しません。
  • 省略した場合、FourAは判明している出口国を使用します。不明な場合は推測せずブラウザの時計を変更しません。
  • FourAが認識しない国コードは、フィールドを省略した場合と同様に扱われます。エラーにはなりません。
  • 時計のみが国に連動します。Accept-Languageおよびサイトが配信するコンテンツは変更されないため、ページで言語が勝手に切り替わることはありません。

userAgent パラメータ

userAgentを送信すると、ページ、Web Worker、ターゲットのすべてにその文字列がそのまま提示されます。FourAはそこから一致するClient Hints（sec-ch-ua、sec-ch-ua-platform、navigator.platform、および検出機能が明示的に要求する高エントロピー値）も導出するため、リクエストのヘッダーとJavaScriptで異なるブラウザが提示されることはありません。

レスポンス内のuserAgentは、実際に提示された値です。これはクリアランスを再利用する際に重要となります。cf_clearance cookieは、それを取得した出口およびUser-Agentにバインドされるため、使用したと想定される文字列ではなく、レスポンスで報告された文字列を送信してください。サイトチェックを参照してください。

非Chromium文字列（FirefoxのUser-Agentなど）を送信した場合、Chromiumブランドリストは付与されず、そのまま提示されます。

例

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"
  }'

Response:

{
  "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 レスポンス headers
body string or object 完全にレンダリングされたページコンテンツ。content-type が HTML の場合は HTML 文字列、ページが JSON を返して自動パースされた場合は object。
cookies array ページからの完全な cookie オブジェクト。各 cookie には name、value、domain、path、expires、httpOnly、secure、sameSite、およびその他の cookie プロパティが含まれます。
userAgent string 使用されたブラウザの User-Agent
defenseSolved boolean この呼び出しで bot 防御に遭遇し、正常にクリアされた場合は true。それ以外の場合は存在しません。呼び出しの消費クレジットが 5 か 10 かを決定します。
defenses object present はページの読み込み中に認識されたすべてのベンダーを一覧表示し、cleared は最終ページでクリアランスを保持しているベンダーを一覧表示します。ベンダーは present に現れても cleared に現れない場合があります。サイトチェックを参照してください。
proxy string request が経由した proxy のエンコードされた ID（request で proxy が指定された場合のみ）。後続の呼び出しでこれを再利用して同じイグジットを維持します。
error string request が失敗した場合のエラーメッセージ

イグジットの固定

Single または Browser request の proxy 値は、前の呼び出しで使用されたイグジットを固定します。proxy アドレスではなく、受け取ったままの不透明な ID をそのまま渡してください。

次の 3 つの値は拒否され、すべて 400 が返されます:

エラー 意味
Invalid proxy format 値が FourA によって発行された ID ではありません。生の proxy アドレスはここに該当します。
Proxy not found ID はデコードされましたが、有効なイグジットに解決されなくなりました。新しい呼び出しから新しい ID を取得してください。
Managed exit: this proxy id cannot be pinned to a request イグジットは存在しますが、指定された request に対して FourA が維持するものではありません。プランに使用可能なプレミアムトラフィックが残っていない場合、プレミアムイグジットの ID はここに該当します。返されたセッションを再利用するか、POST /api/proxy/ 経由で呼び出しを実行して自動選択されたイグジットを使用してください。

固定されたプレミアムイグジットはプレミアムトラフィックとして計測されます。レスポンスには X-FourA-Exit-Class: premium が含まれるため request ごとに確認でき、サイトが目的のページを返したかどうかに関係なく、イグジットが転送したトラフィックは 使用量と制限 ページのプレミアムトラフィックおよび合計帯域幅にカウントされます。固定にはプラン内のプレミアムイグジットと残りの許容量が必要です。そうでない場合、ID は上記のマネージドイグジットの 400 エラーで拒否されます。

HTTP ステータスコード

コード 意味
200 リクエスト完了 (ターゲットのレスポンスについては内部の status を確認)
400 無効なリクエストボディ、パラメータ、プライベート/予約範囲のターゲットIP、または固定できないプロキシID
401 APIキーがないか無効
403 エンドポイントまたはパラメータがプランに含まれていません。X-FourA-Limit に記載: plan_limit_feature または plan_limit_premium。
404 Not Found: そのパスにエンドポイントが存在しません。
413 JSONリクエストボディが 100 KB を超えています。応答は JSON ではなく、X-FourA-Request-Id も含まれません。
429 プランの上限 (X-FourA-Limit が設定されている場合) またはプラットフォーム共有の1分あたりの許容量 (ヘッダーなしの場合)
500 内部サーバーエラー
502 Upstream unavailable。FourA はエンジンに到達しましたが、応答が使用不可でした。再試行してください。
503 サービスが一時的に無効化されているか容量上限に達している、またはエンジンの再起動中に Backend service unavailable が発生
504 Upstream timeout。エンジンがこのリクエストの制限時間内に完了しませんでした。timeout_ms を増やすか再試行してください。

次のステップ

最終更新日: 2026年9月30日
APIエラー →