スマートフェッチ (Auto)

FourAにURLと、実際のページに含まれるべき内容を定義するvalidateルールを渡します。残りはFourAが処理します。コストを考慮したラダー（段階的なフォールバック手順）を実行し、ルールが受け入れるレスポンスを返した最初の段階で停止します。また、ホストごとに成功した方法を記憶するため、同じサイトへの次の呼び出しは低コストになります。

本ガイドでは、autoの内部動作、使用すべき場面、およびレスポンスの解釈方法について説明します。パラメータのリファレンスについては、API Endpointsを参照してください。

コンセプト

多くのスクレイピング環境では、事前にエンジンを選択する必要があります。Singleは最速であり、Proxyはローテーションを追加し、BrowserはJavaScriptを処理します。推測を誤ると、クレジットを浪費するか、ブロックされることになります。

Autoはこのアプローチを逆転させます。手法ではなく、成功条件（validate）を宣言します。FourAは、いずれかの段階が成功するまでラダーを進めます。

低コストなプローブ（single、FourA自身のネットワークから直接実行）
Browser（FourA自身のネットワークから直接実行、サイトからチャレンジを受けた場合はJavaScriptとソルバーを使用）
ローテーションプロキシ single
プロキシ経由のBrowser（最も難易度の高いターゲット向け）

Autoは、validateルールが受け入れるレスポンスがいずれかの段階で返された時点で即座に停止します。

この順序の外にある段階が1つあります。出口IPがサイトに到達したものの、要求したディープURLへのアクセスをサイトが拒否した場合、autoは同じ出口を経由してサイトのエントリページを取得し、エントリページから付与されたcookieを保持した上で、それらを付加して再度URLを要求します。これがwarmupの段階です。これはサイトルートより深いURLに対してのみ、かつ直接の試行がすでに失敗した後にのみ実行され、結果を追加することのみが可能で、結果を損なうことはありません。

forceProxyはデフォルトでtrueに設定されているため、段階1と段階2はスキップされ、ターゲットにFourA自身のアドレスが表示されることはありません。そのため、ほとんどの呼び出しは段階3、または再利用されたウォームセッションで完了します。ターゲットがローテーションアドレスよりもクリーンなアドレスを優遇することが分かっている場合はforceProxy: falseを設定すると、段階1と段階2が再び有効になります。

送信内容

最小構成は、URLとvalidateの部分文字列です。Autoは一般的なチャレンジページを独自に認識しますが、validate.data.acceptがない場合、未知のチェックページや目的のコンテンツが読み込まれなかったページと実際のページを区別できず、それらを成功として返してしまう可能性があります。

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

オプション設定（詳細はendpoint referenceを参照）:

returnSession (デフォルト true): 再生できるように成功した{ proxy, cookies, userAgent }を返します。
forceProxy (デフォルト true): 直接下り（direct-egress）の段階をスキップします。サイトが無料のローテーションproxyよりもクリーンなIPに適していることがわかっている場合にのみfalseを設定してください。
timeout_ms (デフォルト 120000): 呼び出し全体の合計予算。ラダーが各段階に配分します。
ignoreProxies: すべてのサブ試行で回避するproxy ID。
followRedirects (デフォルト 5): 低コストな段階での最大リダイレクト数。

レスポンス内容

{
  "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..."
  }
}

確認すべき3つの項目:

statusおよびdata: ターゲットの応答。dataはすべての段階でテキスト形式です。ブラウザ経由で取得された場合でもJSONページはJSON文字列として返されるため、クライアント側でパースしてください。statusはターゲットのHTTPステータスであり、FourAへの呼び出し自体の転送ステータスではありません。SingleおよびProxyの段階では、headersはホップごとの配列になります。Browserの段階では、headersはフラットなオブジェクトになります。
meta: ラダーの実行トレース。ラダーの開始後はすべてのレスポンスに含まれます。meta.rungはレスポンスを返したステップ名、meta.attemptsはサブコールの試行回数、meta.solvedはチャレンジページを完了したかどうかのフラグ、meta.creditsは呼び出しの合計コスト（X-FourA-Creditsヘッダーと同じ数値）です。
session: ターゲットの突破に成功した{ proxy, cookies, userAgent }の3要素。/api/single/または/api/browser/を経由して同じホストへリプレイするために使用します。

Autoは、すべての段階が失敗した場合を含め、ラダーが実行された場合は常にHTTP 200を返します。何が起きたかを確認するには、転送ステータスコードではなく、ボディ内のstatusおよびerrorを確認してください。/api/auto/からの200以外のレスポンスは、呼び出しがラダーに到達しなかったことを意味します。無効なキーの場合は401、ボディが有効なJSONでない場合やプライベートネットワーク上のターゲットの場合は400、サービスが呼び出しを処理できなかった場合やタイムアウトした場合は502、503、または504になります。Autoはゲートウェイのスロットを消費しないため、プラットフォームの共有制限によって呼び出し自体が拒否されることはありません。ラダーが行った呼び出しが制限された場合、応答はHTTP 200となり、ボディにstatus: 429または503およびretryAfterが含まれます。バリデーションに失敗したフィールドも、status: 400とともにHTTP 200として返されます。ラダー内でプラン制限に達した場合もHTTP 200となり、ボディ内に拒否理由が含まれます（プランの制限がラダーに適用される場合を参照）。

セッションを使用したリプレイ

Autoがセッションを返した後は、同じホスト上の後続ページに対してSingleまたはBrowserを直接実行できます。ラダーを最初からやり直す必要も、新たなプローブも不要です。

import requests

API = "https://eu.api.foura.ai"
KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1) First call: let auto figure it out.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}},
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# 2) Follow-up pages: replay through single with the same proxy + UA.
for sku in ("43", "44", "45"):
    r = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, r["status"])

セッションの持続期間はターゲット側の仕様に依存します。クリアランスを数時間 cookie jar にバインドするサイトもあれば、数分ごとにローテーションするサイトもあります。リプレイで再びチャレンジが返されるようになった場合は、/api/auto/ をもう一度呼び出して更新してください。

Auto を使用すべきケース

auto を使用する場合	手動で single、proxy、または browser を使用する場合
新しいサイトが対象で、必要な構成が不明な場合	動作するエンジンがすでに判明している場合
1回の呼び出しで direct、proxy、browser へのフォールバックを自動処理させたい場合	呼び出しごとのリトライやタイムアウトを完全に制御したい場合
初回呼び出し時に数秒のプローブ処理を許容できる場合	探索よりも初回呼び出しのレイテンシを重視する場合
低コストでリプレイ可能な学習済みセッションが必要な場合	動作確認済みのターゲットでタイトなループを最適化する場合

Auto が常に最も低コストな選択肢とは限りません。ターゲットが single + unblocker で動作することがわかっている場合、Single を直接呼び出せば予測可能なレイテンシで 2 クレジットです。同じターゲットで Auto を使用すると、そのラダーで消費された分だけコストが発生し、サイトでエスカレーションが必要な場合はコストが増加する可能性があります。

Validate による Auto の「成功」条件の定義

最も重要なパラメータは validate です。これを設定しない場合、auto は認識可能なチャレンジページのみを拒絶するため、未知のチェックページや HTTP 200 で返される空のシェルが有効なコンテンツとして通過してしまいます。

実際のページにのみ含まれる部分文字列を指定して validate.data.accept を使用してください:

{
  "validate": {
    "data": {
      "accept": ["sku-42-add-to-cart", "Customer reviews"]
    }
  }
}

JSON APIの場合、予期されるフィールド名を指定します。

{
  "validate": {
    "data": { "accept": ["\"products\":["] },
    "status": { "accept": [200] }
  }
}

正常に200以外を返すサイト (無視したい国制限や、未ログインエンドポイントでの意図的な403など) の場合、validate.status.accept でそれらを許可します:

{
  "validate": {
    "status": { "accept": [200, 451] }
  }
}

validate がない場合、auto はチャレンジとして認識しないすべてのページに対して「HTTP 200 = 成功」へとフォールバックするため、サイトが 200 で返す未知のチェックページを検出できません。

実行内容を把握するための `meta.rung` の確認

meta.rung は最も有用なデバッグシグナルです。値:

probe: コストの低い direct request で解決。最も低コストなパス。
proxy: 通過に proxy ローテーションが必要だった。
browser: フルブラウザレンダリングが必要だった (チャレンジ解決を含む場合あり)。
cache: 以前の auto 呼び出しからのウォームセッションを再利用。リピート呼び出しで最も低コストなパス。
warmup: サイトがエントリページを返しディープ URL を制限したため、auto がまずエントリページを取得し、発行された cookie を保持してそれらを使って再リクエストした。このステップで保存されるセッションは単一のエグジットに縛られないため、後続の呼び出しは低コストなステップで処理される。
fail: 設定したルールを受け入れるレスポンスを返したステップがなかった。

meta.solved: true は、呼び出し中にチャレンジページに遭遇し完了したことを意味します。meta.attempts は成功までのサブコール試行回数です。その詳細については、single ステップおよび proxy ステップが返す defense フィールドを確認してください (Site checks を参照)。

probe を期待していたサイトが browser で終了し続ける場合は、validate ルールをより厳密 (またはより緩やか) にすることで、より低コストなステップを通過させられないか検討してください。forceProxy のデフォルトは true であるため、無効化しない限り direct-egress プローブはスキップされます。

エラーとエッジケース

auto が失敗した場合、レスポンスには status (通常は最後に失敗したステップのステータス) と error 文字列が含まれます:

{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status は、403 などの auto が拒否した最後の試行におけるサイトの応答です。サイトから全く応答が得られなかった場合は通常 502 または 504 となり、error は動作する出口が見つからなかったか、timeout_ms 予算が不足したかを示します。status: 0 はターゲットのホスト名が解決できなかったことのみを意味し、ラダーが開始されなかったためその応答には meta が含まれません。

予算の消費先を確認するには、meta.attempts と meta.credits を確認してください。meta.attempts が高く、browser 段階の後に meta.rung が fail である場合、ターゲットにはより長い timeout_ms、より厳格な validate ルールが必要か、現在ローテーション proxy 経由では単にアクセスできない可能性があります。

プランの制限がラダーに達した場合

auto のサブコールは API キー下の通常の Single、Proxy、Browser request であるため、プランの制限が適用されます。ラダーは拒否時の X-FourA-Limit コードを読み取り、2種類のエラーを区別して処理します。

1つの段階が停止しても、残りのラダーは引き続き使用可能です。 plan_limit_browser_daily (その日の Browser request を使い切った場合) および plan_limit_concurrency (その endpoint でプランの上限まで request が既に実行されている場合) は、該当する1つの段階を閉じます。auto は他の段階の処理を継続するため、ローテーション出口やウォームセッションがコンテンツを返す限りページを取得できます。また、試行された出口はプラン制限に起因する拒否の責任を負いません。BAN されることも、セッションが破棄されることもありません。

アカウントが無効な場合はラダーが停止します。 plan_limit_credits、plan_limit_bandwidth、plan_limit_rate、plan_limit_feature、plan_limit_premium は他の段階でも解決できないため、auto は無駄にクレジットを消費して検証を続けることなく直ちに制御を返します。拒否の詳細は、サブコールのステータスおよび直接 endpoint と同じ reason フィールドとともに body で返されます。

{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}

サブコールの拒否ボディ全体が、statusおよびmetaとともに出力されます。トランスポートステータスではなくボディからstatusを読み取ってください。ラダーが実行されたため、autoはHTTP 200を返します。plan_limit_featureまたはplan_limit_premiumの拒否も同様にstatus: 403で届きます。拒否されたサブコールはクレジットを消費しないため、meta.creditsにはターゲットに到達した段階のみがカウントされます。

1つのautoコールがラダーの進行中に複数のスロットを保持する可能性があるため、autoコールの並列バッチは想定より少ないコール数で同時実行上限に達します。バッチサイズの調整についてはリクエストの並列実行を参照してください。

Autoが対応しない処理

法的制限の変更は行いません。FourAが到達可能なすべての出口をサイトが拒否した場合、autoはその拒否を返します。
コンテンツのキャッシュは行いません。すべてのコールはターゲットへ直接送信されます。「ウォームセッション」はproxyとcookieを指し、responseではありません。
受信したリクエストIDのもとで、サブコールのクレジット合計とともにアクティビティログに1行として記録されます。ログを開くと、autoが代理実行したSingle / Proxy / Browserサブコールが試行として一覧表示され、それぞれに結果が記録されます。これらはSingle、Proxy、Browserの上限にカウントされ、リクエスト数や成功率にはカウントされません。