Smart Fetch (自動)
FourA に URL と、実際のページに含まれるべき内容を示す validate ルールを渡します。残りは FourA が処理します。コストを考慮したラダーを順に実行し、ルールが受け入れ可能なレスポンスを返した最初の段階で停止します。さらにホストごとに成功した手法を記憶するため、同じサイトへの次の呼び出しを低コストに抑えられます。
本ガイドでは、auto が内部で実行する処理、使用すべきケース、レスポンスの読み方を説明します。パラメータのリファレンスについては、API Endpoints を参照してください。
基本コンセプト
一般的なスクレイピング環境では、エンジンの事前選択が必要です。Single は最速、Proxy はローテーションを追加、Browser は JavaScript を処理します。選択を誤ると、クレジットが無駄になるかブロックされます。
Auto はこのアプローチを逆転させます。手法ではなく、成功条件(validate)を宣言します。FourA はいずれかの段階が成功するまでラダーを進めます。
- 低コストプローブ(single、FourA 独自のネットワークから直接実行)
- Browser(FourA 独自のネットワークから直接実行、サイトからチャレンジを受けた場合は JavaScript およびソルバーを使用)
- ローテーションプロキシ single
- プロキシ経由の Browser(最も難易度の高いターゲット向け)
Auto は、validate ルールが受け入れ可能なレスポンスを返した段階で即座に停止します。
この順序の外にある段階が1つ存在します。出口がサイトに到達したものの、要求した詳細 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): 直接送信のステップをスキップします。ローテーション出口よりもクリーンなIPに対して親和性が高いサイトであると分かっている場合にのみfalseを設定してください。timeout_ms(デフォルト:120000): 呼び出し全体の上限予算。ラダーが各ステップに配分します。ignoreProxies: すべてのサブ試行で回避するproxy ID。followRedirects(デフォルト:5): 低コストなステップでの最大リダイレクト数。headers: サイトに送信するheader([name, value]のペア)。これらは機能する出口の探索を含むSingleおよびProxy requestで送信され、ブラウザステップでは送信されません。指定したCookieはそのままサイトに到達し、ウォームセッションのcookieは送信されなかった名前の横にのみ追加されます。ウォームセッションがuserAgentを持つ場合、指定したUser-Agentが置き換えられます。If-None-MatchやIf-Modified-Sinceなどの条件付きheaderは、validate.status.acceptに304が含まれていない限り、出口探索から除外されます。exitClass:premiumを指定すると、標準プールでページにアクセスできない場合にAutoがプレミアム出口へエスカレーションできるようにします。standardはエスカレーションを行わないことを指定します。プレミアム出口を含むプランが必要です。exitClass on Smart Fetchを参照してください。
レスポンス内容
{
"status": 200,
"data": "<!doctype html>...",
"headers": [{"content-type": "text/html"}],
"meta": {
"rung": "cache",
"solved": false,
"attempts": 1,
"credits": 2,
"attemptsByEngine": {"single": 1, "proxy": 0, "browser": 0},
"browserRequests": 0
},
"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ヘッダーと同じ数値)です。meta.attemptsByEngineとmeta.browserRequestsは呼び出しが消費した内容を示します。呼び出しが消費したクレジットを参照してください。リクエストでexitClassが指定されている場合、meta.exitClassは配信したイグジット(出口)のクラスを示します。session: ターゲットの突破に成功した{ proxy, cookies, userAgent }の3要素。これを使用して、/api/single/または/api/browser/経由で同じホストに対してリプレイを実行します。フィールドが存在しない場合もあります。通常のプロキシ取得で確立されたセッションにはproxyが含まれますがuserAgentはなく、そのcookiesリストにはサイトがページを提供する前にチェックページが設定したCookieのみが含まれるため、通常は空です。低コストの直接プローブからの応答にsessionが含まれるのは、そのようなチェックページがCookieを設定した場合のみであり、その場合はcookiesのみが保持されます。validate.status.acceptにリストされたステータスをイグジットが返した場合(削除されたページの404など)、sessionは一切含まれません。
Autoは、すべてのラングが失敗した場合も含め、ラダーが実行された場合は常にHTTP 200で応答します。何が発生したかを確認するには、トランスポートステータスコードではなく、ボディ内のstatusおよびerrorを確認してください。/api/auto/からの200以外のステータスは、呼び出しがラダーに到達しなかったことを意味します。無効なキーの場合は401、無効なJSONボディ、プライベートネットワーク上のターゲット、FourA自体のAPIホスト上のターゲット、またはエンコードされていないスペースを含むURLの場合は400、プレミアムイグジットのないプランでのexitClass: premiumリクエストに対するX-FourA-Limit: plan_limit_premium付きの403、サービスが呼び出しを受け付けられなかったかタイムアウトした場合は502、503、または504が返されます。Autoはゲートウェイのスロットを消費しないため、プラットフォームの共有制限によって呼び出し自体が拒絶されることはありません。共有制限によってラダーによる呼び出しが拒絶された場合、応答はボディにstatus: 429または503とretryAfterを含むHTTP 200になります。検証に失敗したフィールドも、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.get("session") or {}
proxy = session.get("proxy")
user_agent = session.get("userAgent")
# 2) Follow-up pages: replay through single with the same proxy, UA and cookies.
for sku in ("43", "44", "45"):
body = {"method": "GET", "url": f"https://example.com/product/{sku}"}
if proxy:
body["proxy"] = proxy
headers = []
if user_agent:
headers.append(["User-Agent", user_agent])
if session.get("cookies"):
headers.append(["Cookie", "; ".join(f"{c['name']}={c['value']}" for c in session["cookies"])])
if headers:
body["headers"] = headers
r = requests.post(f"{API}/api/single/", headers=H, json=body).json()
print(sku, r["status"])
セッションの持続性はターゲット側の仕様に依存します。Cookie jarにクリアランスを数時間紐付けるサイトもあれば、数分ごとにローテーションするサイトもあります。リプレイで再びチャレンジが返されるようになった場合は、/api/auto/ をもう一度呼び出して更新してください。
Autoの使いどころ
| Autoを使用するケース | single、proxy、またはbrowserを手動で使用するケース |
|---|---|
| 初めてアクセスするサイトで、必要な設定が不明な場合 | 正常に動作するエンジンをすでに把握している場合 |
| プロキシおよびブラウザへのフォールバックを1回の呼び出しで処理したい場合 | 呼び出しごとのリトライやタイムアウトを完全に制御したい場合 |
| 初回呼び出し時の数秒のプロービングを許容できる場合 | 調査の自動化よりも初回のレイテンシを重視する場合 |
| 低コストでリプレイ可能な学習済みセッションが必要な場合 | 動作確認済みのターゲットに対してタイトなループ処理を最適化する場合 |
Autoが常に最も低コストな選択肢とは限りません。ターゲットが single + unblocker で動作することが分かっている場合、Singleを直接呼び出せば予測可能なレイテンシかつ2クレジットで済みます。同じターゲットでAutoを使用すると、ラダーで消費された分のコストがかかり、エスカレーションが必要なサイトではより高額になる可能性があります。
Validateによる「成功」の定義
最も重要なパラメータは 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以外を返すサイト(無視したい国制限、削除されたページの404や410など)の場合、validate.status.acceptで許可します:
{
"validate": {
"status": { "accept": [200, 451] }
}
}
Auto は、イグジットがステータスを返し、かつルールの残りの条件を満たした時点で、validate.status.accept に指定されたステータスを即座に返します。ただし、202、403、429、503 の 4 つのステータスは例外です。Auto はこれらをサイトによる身元確認と解釈するため、これらを返すイグジットがあっても探索を終了せず、ラダーの昇格を継続します。
validate が設定されていない場合、auto はチャレンジとして認識されないすべてのページに対して「HTTP 200 = 成功」へとフォールバックします。そのため、サイトが 200 で返す未知の確認ページを検知できません。
何が起きたかを把握するための meta.rung の確認
meta.rung は最も有用なデバッグシグナルです。値は以下の通りです。
probe: コストの低い直接リクエストで解決。最も安価なパスです。proxy: 通過のためにプロキシローテーションが必要でした。browser: 完全なブラウザレンダリングが必要でした(チャレンジ解決を伴う場合があります)。cache: 以前の auto 呼び出しのウォームセッションを再利用。リピート呼び出しにおける最も安価なパスです。warmup: サイトがエントリページを提供したものの詳細 URL を制限したため、auto がまずエントリページを取得し、発行された cookie を保持して再リクエストを実行しました。この段階で保存されるセッションは単一のイグジットに紐付けられないため、後続の呼び出しは安価な段階で処理されます。fail: ルールに合致するレスポンスを返したいずれの段階もありませんでした。
meta.solved: true は、呼び出し中にチャレンジページに遭遇し、それが完了したことを示します。meta.attempts は成功までのサブリクエスト試行回数です。その詳細については、単一およびプロキシの各段階が返す defense フィールドを確認してください。サイトチェック を参照してください。
サイトへのリクエストが probe を想定しているにもかかわらず browser で終了し続ける場合は、validate ルールをより厳格に(またはより緩やかに)設定することで、より安価な段階を通過できないか検討してください。forceProxy のデフォルトは true であるため、無効化しない限りダイレクトイグレスのプローブはスキップされる点に留意してください。
呼び出しで消費されたリソース
meta.attemptsByEngine は呼び出しが各エンジンに送信したリクエスト数をカウントします。これは Overview の Auto attempts パネルに表示されるリクエストと同じです。meta.browserRequests は、1 日のブラウザ割り当て枠を消費したリクエスト数をカウントします。
"meta": {
"rung": "browser",
"solved": true,
"attempts": 7,
"credits": 47,
"attemptsByEngine": {"single": 1, "proxy": 4, "browser": 3},
"browserRequests": 2
}
| フィールド | 型 | 説明 |
|---|---|---|
meta.attemptsByEngine |
object | single、proxy、および browser に送信された request。プランによって拒否された browser request も、送信されたためここにカウントされます。 |
meta.browserRequests |
number | 1日の許容量のスロットを消費した browser request。プランによって拒否された browser request は消費しません。 |
meta.attempts はラダーのステップ数をカウントするため、必ずしも meta.attemptsByEngine の合計と一致するとは限りません。1つのステップで Single request を送信した後に Proxy request を送信する場合があり、その日の browser がすでに停止しているステップでは何も送信されません。
当日の累積カウントは X-FourA-Browser-Used-Today および X-FourA-Browser-Limit-Per-Day header に含まれます。Response Headers を参照してください。
エラーとエッジケース
auto が失敗した場合、response には status(通常は最後に失敗した段階の status)と error 文字列が含まれます。
{
"status": 502,
"error": "could not find a working exit for the target",
"attempts": 7,
"attemptReport": {
"total": 7,
"noResponse": 5,
"defense": 2,
"contentRejected": 0,
"statusRejected": 0,
"other": 0,
"vendors": ["datadome"],
"summary": "7 attempt(s): 5 got no answer from the site; 2 refused by the site (datadome)"
},
"meta": {
"rung": "fail",
"solved": false,
"attempts": 7,
"credits": 47,
"attemptsByEngine": {"single": 0, "proxy": 4, "browser": 3},
"browserRequests": 3
}
}
status は、403 など、自動で拒否された最後の試行におけるサイトの応答です。サイトから全く応答が得られなかった試行の場合、通常は 502 または 504 となり、error には有効な出口が見つからなかったのか、timeout_ms バジェットを使い果たしたのかが示されます。status: 0 はターゲットのホスト名が解決できなかったことのみを意味し、ラダーが開始されなかったため、その応答には meta が含まれません。
Auto は、ブラウザが完了できないチェックに遭遇し続ける場合にも早期停止します。その方法で2つの出口がブラウザを拒否し、通常の取得が validate ルールをパスする出口の検索が空で返った場合、またはそのような出口が3つ続いた後、呼び出しは終了します。status にはサイトの最後の応答が保持され、error は the browser was refused by で始まり、その後にチェックシステムの名前が続きます。
Auto は、サイト自体がページが存在しないと応答した場合にも停止します。2つの出口が同じ 404 または 410 を返し、ルールでそれが許可されていない場合、呼び出しはその status で終了し、error は the site answered で始まります。削除されたページが必要な応答である場合は、validate.status.accept に 404 または 410 を指定してください。出口がそれを返した時点で、Auto は配信済みとして返します。
サイトによる拒否が続いたためにAPIキーでの Auto 呼び出しが連続して4回ページを取得できずに終了した場合、Auto はそのキーによるそのサイトへの試行を120秒間停止します。その間の呼び出しには即座に status: 503、error: "target temporarily unservable, retry later"、および秒単位の retryAfter が返され、コストは発生しません。これはAPIキー単位でカウントされます。同じサイトを呼び出す他のキーには影響せず、ページを取得できた呼び出しがあればカウントはリセットされます。exitClass: premium を指定した呼び出しは、これによって停止されません。
バジェットがどこで消費されたかを確認するには、attemptReport、meta.attemptsByEngine、および meta.credits を確認してください。ブラウザステップの後に meta.attempts が高く meta.rung が fail の場合、ターゲットにはより長い timeout_ms、より厳格な validate ルールが必要か、あるいはローテーション proxy 経由では現在到達できない可能性があります。
Auto 呼び出しが失敗した理由
実行されたラダーからの失敗応答には、すべて attemptReport が含まれます。ページを取得できずに返されたエンジン request を、遭遇した状況ごとに1回ずつカウントします。
| フィールド | 型 | 説明 |
|---|---|---|
total |
integer | ページを取得できずに返されたリクエスト数。プランによって拒否されたブラウザリクエストはターゲットへの試行を行わないため、最大でも meta.attemptsByEngine の合計となります。 |
noResponse |
integer | サイトから応答がなかった回数 |
defense |
integer | サイトがリクエストを拒否した回数: bot チェックが検出された、ページがチャレンジであった、またはサイトが 401、403、429、503 を返したケース |
contentRejected |
integer | ページは取得されたが、設定した validate ルールのみによって拒否された回数 |
statusRejected |
integer | 削除されたページに対する 404 など、リクエストが許容しないステータスをサイトが返した回数 |
other |
integer | サーバーエラーなど、その他の理由で失敗した回数 |
vendors |
string[] | コールが遭遇した拒否において検出された bot チェックベンダー |
summary |
string | カウントから生成された、ログ出力に適した1文。ベンダーが検出されなかった場合にサイトが返した HTTP ステータスを示し、1日のブラウザ許容量を使い切ってブラウザを開けなかったタイミングを通知します。 |
これらのフィールドは、profilesTried を除き、失敗した Proxy 呼び出しのレポートと一致します。異なる点は2点あります。Proxy は設定された maxTries を上限として試行した各出口をカウントしますが、Auto は自身のリクエストをカウントします。また、Auto はページとそのステータスも読み取るため、ベンダーが検出されなかった場合でも拒否は defense にカウントされます。contentRejected のカウントはユーザー自身で対処可能なものです。ページは返されたものの、ルールに一致しませんでした。
プランの上限とラダーの競合
Auto のサブコールは API キー配下の通常の Single、Proxy、Browser リクエストであるため、プランの上限が適用されます。ラダーは拒否時の X-FourA-Limit コードを読み取り、2種類のエラーを区別して処理します。
一部の段が閉鎖されても、ラダーの他の段は引き続き利用可能です。 plan_limit_browser_daily (当日の Browser リクエストを使い果たした) および plan_limit_concurrency (該当 endpoint でプランの上限に達する数のリクエストがすでに実行中) は1つの段を閉じます。Auto は他の段での処理を継続するため、ローテーション出口またはウォームセッションがコンテンツを提供できる限りページを取得できます。また、試行した出口は、ユーザー自身のプランに起因する拒否の責任を問われません。アクセス禁止になることはなく、セッションが破棄されることもありません。
アカウントの上限枯渇はラダーを停止させます。 plan_limit_credits、plan_limit_bandwidth、plan_limit_rate、plan_limit_feature、および plan_limit_premium は他の段でも解決できないため、Auto はクレジットをそれ以上消費して検証することなく即座に復帰します。拒否の詳細は、サブコールのステータスおよび直接エンドポイントと同じ reason フィールドとともに body に返されます。
{
"status": 429,
"error": "Credit limit reached: 300,000 of 300,000 credits used this billing period. Upgrade your plan or wait for the reset.",
"reason": "plan_limit_credits",
"documentation": "https://foura.ai/prices",
"used": 300000,
"hard_stop": 300000,
"retry_after_seconds": 86400,
"resets_at": "2026-10-01T00:00:00.000Z",
"meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
サブコールからの拒否レスポンスボディ全体がそのまま返され、さらに status、attemptReport、meta も含まれます。トランスポートステータスではなくボディから status を読み取ってください。ラダーが実行されたため、auto はここでも HTTP 200 を返します。plan_limit_feature または plan_limit_premium の拒否も、同様に status: 403 を伴って到達します。拒否されたサブコールはクレジットを消費しないため、meta.credits はターゲットに到達した段階のみをカウントします。
1つの auto 呼び出しがラダーを昇格する間、複数のスロットを保持することがあるため、auto 呼び出しの並行バッチは予想よりも少ない呼び出し数で並行処理数の上限に達します。バッチサイズの調整については リクエストの並行実行 で説明しています。
Auto が行わないこと
- 法的な制限を変更することはありません。サイトが FourA の到達可能なすべての出口を拒否する場合、auto はその拒否を返します。
- コンテンツをキャッシュすることはありません。すべての呼び出しは依然としてターゲットにアクセスします。「ウォームセッション」とはプロキシと cookie のことであり、レスポンスではありません。
- 受信した request id のもと、サブコールのクレジット合計とともに、アクティビティログ に1行として記録されます。それを開くと、auto が代理で実行した Single、Proxy、Browser のサブコールが試行として一覧表示され、それぞれに独自の結果が示されます。これらは Single、Proxy、Browser の制限に対してカウントされ、リクエスト数や成功率に対してカウントされることはありません。
関連資料
- API エンドポイント: 完全なパラメータリファレンス
- 適切なエンドポイントの選択: auto と single、proxy、browser の使い分け
- リクエストの結果: 請求対象となる結果の一覧
- 保護されたサイト: クライアントを検証するサイトに対して FourA が行う処理
- サイトチェック:
meta.solvedの背後にあるdefenseフィールド - MCP レシピ: MCP ツール呼び出しとしての同一パターン
- レート制限: auto のサブコールが照合されるプラン制限