# API endpoint リファレンス

> URL: https://foura.ai/ja/docs/api/endpoints
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

リクエストパラメータおよびレスポンス形式を含む、すべてのFourA API endpointのリファレンスです。

## ベースURL

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

## 認証

すべてのリクエストにおいて、`X-API-Key`ヘッダーにAPIキーを指定する必要があります:

```bash
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](https://foura.ai/dashboard) で行います。キーには `pk_live_` プレフィックスが付きます。

## レスポンスヘッダー

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

| Header | Value | Description |
|--------|-------|-------------|
| `X-FourA-Request-Id` | UUID | リクエストに割り当てられた一意の ID。FourA が本文をまったく読み取れない場合を除き、4xx および 5xx を含むすべてのレスポンスで返されます。`400 Invalid JSON in request body` および `413` は ID が割り当てられる前に拒否されます。クライアント側でログに記録してください。 |
| `X-FourA-Credits` | integer | このリクエストで消費されたクレジット。成否にかかわらず、エンジンに到達したすべてのレスポンスで返されます (いずれの場合も処理が実行されたため)。エンジンが実行される前に FourA が拒否した呼び出し (キーの不足や無効、プランまたはプラットフォームの制限、拒否されたターゲットまたはプロキシ ID) には付与されません。課金対象となる結果については [Request Outcomes](https://foura.ai/docs/api/outcomes) を参照してください。 |

同じリクエスト ID により、Dashboard の [Activity Log](https://foura.ai/docs/dashboard/activity-log) (24時間保持、キーごとに直近200件) でリクエストとレスポンスのペイロードプレビューが識別されるため、後から正確なリクエストを確認し、Activity から [Playground](https://foura.ai/docs/dashboard/playground) へ直接リプレイできます。サポートへの問い合わせ時にこれを含めると、対象のリクエストを数秒で特定できます。

```bash
$ 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](https://foura.ai/docs/api/response-headers)を参照してください。

## エンドポイント

> **MCP経由でこれらのエンドポイントを使用しますか?** [`@fouradata/mcp`サーバー](https://foura.ai/docs/mcp/server)は、4つのエンドポイントすべてをネイティブMCPツール（`foura_auto`、`foura_single`、`foura_proxy`、`foura_browser`）としてラップしており、同じ入力形式に加え、トークン効率の良い大規模レスポンス処理のための`offload_large`オプトインを提供します。相違点: `foura_browser`には`lean`フィールドがなく、`foura_proxy`はまだ[exit location](#exit-location)フィールドを受け付けません。

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

| エンドポイント | 最適な用途 |
|----------|----------|
| `POST /auto/` | スマートフェッチ。URLを渡すと、FourAが機能する最も低コストなパス（ローテーションプロキシまたはブラウザ、加えて`forceProxy: false`を使用した直接リクエスト）を選択し、ホストごとに機能したパスを記憶します。 |
| `POST /single/` | 高速なHTTPリクエスト、静的ページ、API |
| `POST /proxy/` | 自動プロキシローテーション、オプションのターゲットから見える国指定を備えた保護されたサイト |
| `POST /browser/` | JavaScriptレンダリングが必要なページ、SPA |
| `GET /profiles` | `single`および`proxy`用のブラウザプロファイルカタログ。公開されており、APIキーは不要です。 |

それぞれの使い分けの詳細については、[Choosing the Right Endpoint](https://foura.ai/docs/guides/choosing-task-type)および[Smart Fetch guide](https://foura.ai/docs/guides/smart-fetch)を参照してください。

## ターゲットURLの制限

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

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

FourA自身のAPIホスト（`eu.api.foura.ai`または`api.foura.ai`）を対象とするターゲットも、フェッチや課金が行われる前に、4つのendpointすべてで400エラーとなり拒否されます。スペースや制御文字を含むURLも同様に、Single、Proxy、Autoで400エラーとなり拒否されます。スペースは`%20`としてエンコードしてください（BrowserはChromeと同じ方法でフェッチします）。FourAがフェッチする唯一のページは[`/inspect`](https://foura.ai/docs/api/inspect)です。

```json
{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }
```

---

## Smart Fetch (Auto)

`POST /api/auto/`

URLと任意の`validate`ルールを渡します。FourAはコストを考慮したラダー（ローテーションproxy、次にフルブラウザ）を順に実行し、設定したルールを満たすレスポンスを返した最初の段階で停止します。`forceProxy: false`を使用すると、まず低コストな直接プローブが実行されます。同一ホストへのリピート呼び出しではウォームセッションが再生されるため、2回目以降のリクエストは低コストになります。

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

### リクエストボディ

| パラメータ | タイプ | 必須 | デフォルト値 | 説明 |
|-----------|------|----------|---------|-------------|
| `url` | string | はい | - | ターゲットURL |
| `method` | string | いいえ | `"GET"` | HTTPメソッド |
| `headers` | [string, string][] | いいえ | - | [name, value] のペアとしてターゲットに送信するheader。ブラウザ段階を除くすべての段階で送信されます。送信した`Cookie`は変更されずにサイトへ届き、保存済みセッションのcookieは未送信の名前に対してのみ追加されます。保存済みセッションの`userAgent`は指定の`User-Agent`を上書きします。proxy段階では、`validate.status.accept`に`304`が含まれていない限り、`If-None-Match`などの条件付きheaderは除外されます。 |
| `data` | any | いいえ | - | GET以外のリクエスト用のリクエストボディ |
| `validate` | object | いいえ | - | 成功判定基準。Single Requestの`validate`と同じ形式です（下記参照）。コンテンツとチャレンジページを識別できるよう、正常なページの条件をautoに指定します。 |
| `returnSession` | boolean | いいえ | `true` | 成功したセッション情報（`proxy`、`cookies`、`userAgent`）をレスポンスに含めます。`/api/single/`または`/api/browser/`で再利用可能です。 |
| `forceProxy` | boolean | いいえ | `true` | 常にローテーションproxyを経由します。ターゲットが許可する場合に、より低コストな直接アクセスを許可するには`false`を設定します（一部の防御機構はproxyトラフィックに対してより厳格です）。 |
| `timeout_ms` | integer | いいえ | `120000` | 呼び出し全体の合計制限時間（ミリ秒）。すべての内部試行はこの制限時間内で実行されます。最小値は`5000`、最大値は`180000`です。 |
| `ignoreProxies` | string[] | いいえ | - | すべての内部試行で除外するproxy IDのリスト。以前の`/api/auto/`または`/api/proxy/`レスポンスから返されたIDを使用します。 |
| `followRedirects` | integer | いいえ | `5` | 低コストなラダー段階で追跡する最大リダイレクト数。`0`で無効化。最大値は`20`です。 |
| `exitClass` | string | いいえ | - | [Proxy Request](#exitclass)と同様に、`standard`または`premium`を指定します。`premium`を使用すると、標準プールでページにアクセスできない場合にプレミアムexitへエスカレーションできます。プレミアムexitを含むプランが必要です。詳細は[Smart FetchでのexitClass](#exitclass-on-smart-fetch)を参照してください。 |

### レスポンス

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

| フィールド | 型 | 説明 |
|-------|------|-------------|
| `status` | number | ターゲットからの HTTP ステータス。 |
| `data` | string | 応答した階層を問わず、テキスト形式のレスポンスボディ。JSON ページは JSON テキストとして返されるため、自身でパースします。 |
| `headers` | array or object | ターゲットのレスポンスヘッダー。Single および proxy 階層はホップごとのヘッダーオブジェクトの配列を返し、browser 階層はフラットなオブジェクトを返します。 |
| `meta.rung` | string | レスポンスを配信したラダー階層。次のいずれか: `probe` (低コストな直接リクエスト、`forceProxy: false` を指定した場合のみ)、`proxy` (ローテーションプロキシ)、`browser` (完全なブラウザレンダリング)、`cache` (ウォームセッションの再実行)、`warmup` (サイトのエントリページを先に取得し、そのクッキーでディープ URL を開いた場合)、または `fail` (どの階層も承認されたレスポンスを生成しなかった場合)。 |
| `meta.solved` | boolean | ページに追加のステップ (チャレンジページ) が必要であり、この呼び出し中にそれが完了したかどうか。 |
| `meta.attempts` | number | 成功までに実行されたサブ試行回数。 |
| `meta.credits` | number | この呼び出しで消費された合計クレジット。`X-FourA-Credits` と一致します。 |
| `meta.attemptsByEngine` | object | `single`、`proxy`、および `browser` に送信されたリクエスト。プランによって拒否されたブラウザリクエストも、送信されたためカウントされます。 |
| `meta.browserRequests` | number | 1 日の許容量のスロットを消費したブラウザリクエスト数。プランによって拒否されたブラウザリクエストは消費しません。 |
| `meta.exitClass` | string | 配信したエグジットのクラス。リクエストで `exitClass` が指定された場合に存在: `premium` または `standard`。同じ値が `X-FourA-Exit-Class` レスポンスヘッダーにも設定されます。 |
| `session.proxy` | string | レスポンスを配信したプロキシのエンコード済み ID。Single または Browser リクエストで再利用します。`returnSession` が `true` の場合に存在します。 |
| `session.cookies` | array | 再利用するクッキー。それぞれ少なくとも `name` と `value` を含みます。browser 階層はブラウザの cookie jar を返します。proxy 階層または直接プローブは、ページを開くのに必要だったクッキー (サイトのチェックページで設定されたものなど) のみを返し、ページが設定したすべてのクッキーを返すわけではないため、リストが空になることがあります。`returnSession` が `true` の場合に存在します。 |
| `session.userAgent` | string | 成功した試行で使用された User-Agent。`returnSession` が `true` の場合に存在します。 |
| `error` | string | 呼び出しが失敗した場合のエラーメッセージ。 |
| `attemptReport` | object | 呼び出し失敗時: ページを取得できずに戻ったエンジンリクエストの原因別内訳。[Smart Fetch](https://foura.ai/docs/guides/smart-fetch) を参照してください。 |

### 例

```bash
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キーを転送します。Autoの呼び出しは、[アクティビティログ](https://foura.ai/docs/dashboard/activity-log)および概要画面上で1件のリクエストとしてカウントされ、サブコールのクレジットの合計が記録されます。サブコールはその試行（attempts）として下に一覧表示され、単体でリクエストとしてカウントされることはありません。
- 実際のページにのみ含まれる部分文字列を指定して`validate.data.accept`を渡してください。これがない場合、Autoは実際の200応答と、ステータス200で返されるチャレンジ画面（interstitial）を判別できません。
- 削除されたページはサイトによる正当な応答であり、拒絶ではありません。2つの出口から同一の`404`または`410`が返され、指定した`validate`がそれを受け入れない場合、呼び出しはその`status`と、`the site answered`で始まる`error`を返して終了します。`validate.status.accept`にそのステータスを指定すると、Autoは残りの`validate`の条件を満たすそのステータスの最初のレスポンスを返します。サイトがチャレンジページと併せて返すことのある`403`、`429`、`503`、`202`を除き、そこに指定した他の任意のステータスでも同様に動作します。
- `timeout_ms`は呼び出し全体の上限時間を制限します。保護されたサイトへの初回のコールドアクセスには数十秒かかる場合がありますが、再利用されたウォームセッションは通常1秒未満で完了します。

### Smart FetchにおけるexitClass

`exitClass`は、[Proxy Request](#exitclass)と同様にSmart Fetchでも機能します。これは許可であり、強制的な指示ではありません。Autoはまず標準プールを試行します。標準プールでページにアクセスできず、リクエストで`premium`が指定されている場合、Autoはプレミアム出口経由のブラウザでページを開きます。そこで構築されたセッションは、同じく`premium`を指定する同一サイトへの以降の呼び出しに利用されます。これを指定しない呼び出しがそのセッションを使用することはありません。

使い切ってもエラーにはなりません。請求期間内のプランのプレミアムトラフィックを使い切ると、呼び出しは標準プールで継続され、`meta.exitClass`には`standard`と表示されます。プレミアム出口を含まないプランでは、`exitClass: premium`を送信した呼び出しは処理が行われる前に`X-FourA-Limit: plan_limit_premium`を含む`403`で拒否されます。

プレミアムトラフィックの計測方法はProxy Requestと同様です。ブラウザで開かれたページはページ単体よりも多くのリソースを読み込むため、プレミアムSmart Fetchによるページ取得は、Proxy Requestで同じページを取得する場合よりも多くのプレミアムトラフィックを消費します。トラフィック消費を抑えるため、プレミアムSmart Fetchページは画像、フォント、メディア、および既知の広告、アナリティクス、同意管理プロバイダーのスクリプトを読み込まずに動作します。

---

## 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` に設定すると、FourA はブラウザーヘッダーを追加せず、渡されたヘッダーのみを送信します。 |
| `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 | いいえ | 無効 | 追跡する最大リダイレクト数（0-20）。無効にするには省略します。 |
| `tryJsonData` | boolean | いいえ | false | 可能な場合、レスポンスボディをJSONとしてパースする |
| `returnBuffer` | boolean | いいえ | false | デコードされた文字列の代わりに生のバッファを返す |
| `data` | any | いいえ | - | リクエストボディ（文字列またはオブジェクト、JSONに自動シリアライズ） |
| `proxy` | string | いいえ | - | 同じイグジットを固定するための、以前のレスポンスのプロキシID。不透明な文字列をそのまま渡してください。生のプロキシアドレスは `400 Invalid proxy format` で拒絶されます。固定できないIDもあります。[イグジットの固定](#pinning-an-exit)を参照してください。 |
| `browser` | string | いいえ | Chrome | 提示するブラウザー: Chrome、Edge、Safari、Firefox、Tor。[ブラウザープロファイル](#browser-profiles)を参照してください。 |
| `os` | string | いいえ | - | 提示するOS: Windows、macOS、Android、iOS。ファミリー名を指定すると、その全バージョンが対象になります。 |
| `version` | string | いいえ | newest | カタログに記載されている提示対象のブラウザーバージョン。複数該当する場合は最新の一致が優先されます。 |
| `profile` | string | いいえ | - | 上記3フィールドの代わりに使用する、`GET /api/profiles` からの正確なプロファイルID。 |
| `validate` | object | いいえ | - | レスポンス検証ルール（以下を参照） |

### ブラウザープロファイル

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

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

ルール:

- 選択には`unblocker`が必要です（デフォルトで有効）。`unblocker`が無効の場合、ブラウザheaderが送信されないため、不完全に適用されるのではなくrequestが拒否されます。
- 複数のプロファイルが一致する場合、最新バージョンが優先されます。
- カタログに存在しない組み合わせの場合は利用可能な内容を示すエラーが返され、不明な`profile` IDの場合は`unknown profile '<id>'`が返されます。requestが別のブラウザとして送信されることはありません。
- 同じ4つのフィールドは`POST /proxy/`の`request`オブジェクト内でも利用可能です。

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

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

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

### バリデーションルール

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

```json
{
  "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 | いずれかのリダイレクトホップで少なくとも1つのペアが一致した場合にレスポンスが通過します。名前と値は大文字小文字を区別せず、部分一致で判定されます。 |
| `validate.headers.fail` | object | 失敗をトリガーするヘッダーのキーと値のペア |
| `validate.data.accept` | string[] | レスポンスボディにこれらの文字列が少なくとも1つ含まれている場合に通過します |
| `validate.data.fail` | string[] | 失敗をトリガーするレスポンスボディ内の文字列 |

### 例

```bash
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:

```json
{
  "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
}
```

ターゲットが本文の取得前にBotチェックを実行した場合、responseにはベンダー名とチェックをクリアしたかどうかを示す`defense`オブジェクトも含まれます:

```json
{
  "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 | リクエストが経由したプロキシのエンコード済み ID (リクエストで `proxy` が指定された場合のみ)。後続の呼び出しでこれを再利用することで、同じ出口を固定できます。 |
| `defense` | object | ターゲットがこのリクエストで Bot チェックを実行した場合、またはサイト独自の Cookie による再試行でボディが生成された場合に存在します。`defense.solved` はチェックがクリアされたかどうかを示し、`defense.retry` は再試行によってコンテンツが取得できたかどうかを示します。すべてのフィールドおよびシステムの完全なリストについては [サイトチェック](https://foura.ai/docs/api/site-checks) を参照してください。 |
| `error` | string | リクエストが失敗した場合のエラーメッセージ |

---

## Proxy Request

`POST /api/proxy/`

失敗時の自動再試行を備えたローテーションプロキシ経由でリクエストをルーティングします。オプションで、選択対象をターゲットから認識可能な特定の出口国に限定できます。

### リクエストボディ

| パラメータ | 型 | 必須 | デフォルト | 説明 |
|-----------|------|----------|---------|-------------|
| `request` | object | はい | - | 単一のリクエストボディ (上記のSingle Requestと同じフィールド) |
| `timeout_ms` | number | いいえ | 45000 | 全ての試行に対する合計タイムアウト (ミリ秒単位、最大: 120000) |
| `maxTries` | number | いいえ | 5 | 失敗数がこの値に達すると、FourAは新しい試行の開始を停止します (最大: 90)。試行は並列で実行されるため、完了する試行数がこの値をわずかに上回る場合があります。 |
| `ignoreProxies` | string[] | いいえ | - | ローテーションから除外するプロキシID (以前のレスポンスで返されたIDを使用) |
| `exitCountries` | string[] | いいえ | - | ターゲットから認識される2文字の国コードの厳密な許可リスト (例: `["CZ", "GB"]`)。値はトリミングされ、大文字に変換され、重複排除されます。国が不明なスタンダードプールの出口は除外され、スタンダードプールが要求されていない国へフォールバックすることはありません。プレミアム出口も指定された国のいずれかから送信されます。 |
| `exitClass` | string | いいえ | - | `standard` または `premium`。`premium` を指定すると、保護されたターゲットに対してスタンダードプールが対応しきれない場合、リクエストをプレミアム出口へエスカレーションできます。プレミアム出口を含むプランが必要です。 |
| `exitState` | string | いいえ | - | 出口の送信元地域。`exitClass: premium`、および `exitCountries` で正確に1つの国を指定する必要があります。[Exit location](#exit-location) を参照してください。 |
| `exitCity` | string | いいえ | - | 出口の送信元都市。`exitClass: premium`、および `exitCountries` で正確に1つの国を指定する必要があります。 |
| `exitAsn` | string | いいえ | - | 出口の送信元ネットワーク (AS番号指定、例: `8866`)。`exitClass: premium`、および `exitCountries` で正確に1つの国を指定する必要があります。 |
| `exitOs` | string | いいえ | - | `windows`、`android`、`ios`、または `mac`: アドレスが属するデバイスの種類。`exitClass: premium` が必要です。 |
| `exitLifetimeMin` | integer | いいえ | - | 出口がアドレスを保持する分数 (`3` から `1440`)。`exitClass: premium` が必要です。 |

### exitCountries のスコープ

選択には、ターゲットから認識される最新の国メタデータが使用されます (通常は約10分以内に更新)。リクエスト中のリアルタイムな地理位置情報ルックアップではありません。プロキシホストのアドレスから提供元の国を推測しないでください。

現在のプールに要求された国と一致するものがなく、リクエストで `exitClass: premium` が指定されていない場合、レスポンスはエラーエンベロープを含む HTTP 200 を返します。

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

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

### 例

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

レスポンス:

```json
{
  "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 リクエストで再利用するか、`ignoreProxies` を使用して次の Proxy リクエストでスキップします。 |
| `exitCountry` | string | リクエストを処理したプロキシの、ターゲットから認識可能な2文字の国コード。処理した出口クラスに関わらず、リクエストに `exitCountries` が設定されていた場合にのみ存在します。レスポンスを信頼する前に、要求したコードのいずれかであることを必ず確認してください。 |
| `exitClass` | string | このリクエストを処理した出口のクラス。リクエストで指定された場合の成功レスポンスに含まれます。`premium` はプレミアム出口が本文を返したことを示し、`standard` は標準プールが返したことを示します。失敗した呼び出しは何も処理しなかったため、`exitClass` は含まれません。試行結果については `attemptReport` を確認してください。 |
| `total` | number | 秒単位の外部実経過時間（浮動小数点数）。プロキシの選択、再試行、成功した試行を含みます。`total_time` は内部リクエストのみを対象とします。`total` は常に `total_time` 以上になります。 |
| `profile` | string | ローテーションによって選択されたブラウザプロファイル。要求したものと異なる場合に**のみ**存在します。存在しない場合は、リクエストが記述どおりに送信されたことを意味します。動作したブラウザを維持するには、後続の呼び出しでこの ID を `profile` として返してください。 |
| `error` | string | リクエストが失敗した場合のエラーメッセージ。スコープ不一致の場合、`code` は `no_eligible_proxy` となり、`details.exitCountries` に正規化されたスコープが反映されます。 |
| `attemptReport` | object | 失敗した**すべての** Proxy 呼び出しに存在します。ブロックされたプール、停止したプール、一度も一致しなかった `validate` ルールがすべて同じエラーとして表示されないよう、試行が直面した事象をカウントします。詳細は以下を参照してください。 |
| `request` | object | 失敗した Proxy 呼び出しに含まれます。デフォルト値が補完され、送信されたままの `ignoreProxies` を含む、FourA が実行したリクエストです。 |

すべての Single Request レスポンスフィールドも含まれます（`defense` を含む）。Bot チェックに遭遇したプロキシの試行は、Single と同じ方法でそれを報告します。

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

試行がどのように進行したかに関わらず `Download maxTry limit reached` は同一に読み取れるため、失敗したすべての Proxy レスポンスにはエラーとともに `attemptReport` が含まれます。

```json
{
  "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 | サイトは応答しましたが、その応答でボットチェックが検出されました |
| `contentRejected` | integer | HTTP 200、ボットチェックなし、お客様の `validate.data` のみによって拒絶されました |
| `statusRejected` | integer | サイトは応答し、ボットチェックはありませんでしたが、お客様の `validate.status` によって拒絶されました |
| `other` | integer | 応答があり、上記のいずれにも該当しません |
| `vendors` | string[] | タスク内で検出されたボットチェックベンダー |
| `profilesTried` | string[] | タスクが送信したブラウザプロファイル（初回使用順）。`default` はリクエストが変更されずに送信されたことを示します。 |
| `summary` | string | 各カウントから生成された1文（ログ記録可能） |

`error` 文字列は変更されないため、これにマッチングするクライアントはそのまま動作します。各カウントへの対処方法: [Proxy リクエストの試行回数が上限に達した理由](https://foura.ai/docs/troubleshooting/proxy-attempt-report)。

### exitClass

ターゲットによっては、標準プール内のイグジットを何度試行しても拒否される場合があります。`exitClass: premium` は、標準プール内のみでローテーションする代わりに、このようなリクエストを標準プールに加えて**プレミアムイグジット**にエスカレーションしてよいことを Proxy に伝えます。

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

送信前に把握しておくべき点が3つあります。

**これは許容設定であり、強制的な指示ではありません。** 標準プールが引き続き応答を競合し、通常は標準プールが優先されます。プレミアム出口は、標準プールがリクエストに短いバジェットを費やしたか、ターゲットが明確に拒否した場合にのみ参加します。プレミアム出口を試行する前に標準プールが応答したリクエストは通常通りの成功となり、プレミアムトラフィックは消費されません。一度プレミアム出口が試行されると、後述のとおりそのトラフィックがカウントされます。

**プレミアム出口は`exitCountries`の範囲内に留まります。** 国リストが指定されている場合、プレミアム出口はそれらのいずれかの国からルーティングされ、標準プールと同様に応答内の`exitCountry`にその国名が示されます。

**応答には、実際に処理を行った対象が示されます。** クラスを指定した場合、応答には`exitClass`が含まれて返されます。

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

`premium` は、プレミアムイグジットがレスポンスボディを返したことを示します。`standard` は標準プールが返したことを意味し、これはプレミアムイグジットを取得できなかった場合や、プランに含まれるプレミアムトラフィック（および追加購入分）を請求期間内で使い切った場合にも返される値です。どちらもエラーではなく、月次の合計値ではなくリクエストごとにプレミアムトラフィックを照合できます。同じ値が `X-FourA-Exit-Class` レスポンスヘッダーでも返されます（[Response Headers](https://foura.ai/docs/api/response-headers#x-foura-exit-class) を参照してください）。

**プレミアムトラフィックはネットワーク上で計測されます。** プレミアムの試行では、ページが返されたかどうかに関わらず、ネットワークを通過した際の圧縮および暗号化された送受信データ量がカウントされます。別のイグジットが先に応答して途中で停止された試行についても、その時点までに発生したトラフィックがカウント対象となります。プレミアムトラフィックはプレミアム許容量と合計帯域幅の両方にカウントされます。同一のバイト数が2か所に記録されますが、合算されることはありません。プレミアムイグジットがページを返した場合、そのトラフィックがリクエスト全体のトラフィックとなるため、標準トラフィックとして二重にカウントされることはありません。[Usage & Limits](https://foura.ai/docs/dashboard/quota) ページには、合計トラフィック、そのうちのプレミアムの割合、および計測基準となるプレミアム許容量が表示されます。

フィールドを省略した場合と `standard` を送信した場合は、いずれもリクエストが標準プールに留まります。`premium` のみを指定した場合にプレミアムイグジットが許可されます。クラスを指定した成功リクエストにはレスポンスに `exitClass` が含まれ、フィールドを省略したリクエストには含まれません。

**許容量の超過はエラーではありません。** 許容量を使い切った後に `premium` を指定したリクエストも処理は継続されます。標準プールがリクエストを処理し、レスポンスには `standard` と表示されます。唯一の例外は [exit location](#exit-location) を指定したリクエストです。標準プールでは対応できないため拒絶されます。

`exitClass: premium` を使用するには、プレミアムイグジットを含むプランが必要です。含まれないプランの場合、リクエストがプレミアムイグジットを消費することはなく、処理が開始される前に `X-FourA-Limit: plan_limit_premium` を伴う 403 で拒絶されます（[Rate Limits](https://foura.ai/docs/api/rate-limits#plan-limits) を参照してください）。


### イグジットロケーション

プレミアムイグジットは国境内の特定の場所から発信でき、必要な期間そのアドレスを保持できます。

```json
{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}
```

レスポンスには、出口と送信元の国名が含まれます:

```json
{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}
```

その`proxy` IDは、これらすべてを保持します。これをSingleまたはBrowserに渡すと、リクエストは他のフィールドなしで同じ場所から送信されます。[Pinning an Exit](#pinning-an-exit)を参照してください。

ルール:

- `exitState`、`exitCity`、`exitAsn`、`exitOs`、`exitLifetimeMin`のいずれかを指定すると、リクエストはプレミアム出口経由でのみ送信されます。標準プールではこれらを処理できないため、試行は行われません。
- これらには`exitClass: premium`が必要です。これがない場合、リクエストは該当フィールド名を明記した400エラーで拒否されます。
- `exitState`、`exitCity`、`exitAsn`は1つの国内に存在するため、`exitCountries`には厳密に1つの国が必要です。`exitOs`および`exitLifetimeMin`には複数の国を指定できます。出口にはそのうちの1つが採用され、レスポンス内の`exitCountry`に該当の国が示されます。
- `exitState`、`exitCity`、`exitAsn`、`exitOs`には、プレミアム出口に加えて地域ターゲティングを含むプランが必要です。
- プレミアムトラフィックの残量がない場合、標準プールでは処理できないため、リクエストは`X-FourA-Limit: plan_limit_premium`を含む403エラーで拒否されます。
- その場所で応答するプレミアム出口がない場合、レスポンスは[exitCountries scoping](#exitcountries-scoping)に記載されているようなエラーエンベロープとなり、エラー`No premium exit answered for this request`および`code: no_eligible_proxy`が含まれます。国のリストを送信した場合は`details.exitCountries`が含まれます。

これらは、[プロキシポート](https://foura.ai/docs/api/proxy-port)が`state`、`city`、`asn`、`os`に受け付ける値です。

### ブラウザプロファイルのローテーション

Proxyは出口をローテーションします。サイトが出口そのものではなく、FourAが提示したブラウザを拒否した場合、Proxyはカタログから別のブラウザファミリーにも切り替えます。試行回数は追加されません。ローテーションはリトライで送信する内容を変更するのみであり、リトライ自体の実行有無を変更することはありません。

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

内部の`request`で明示的に指定された`profile`、`browser`、`os`、または`version`が上書きされることはありません。また、独自の`User-Agent`または`Cookie`ヘッダーを含むリクエストも上書きされません。これはクリアランスがそれを取得したシグネチャに紐づいているためです。

---

## Browser Request

`POST /api/browser/`

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

### リクエストボディ

| パラメータ | 型 | 必須 | デフォルト | 説明 |
|-----------|------|----------|---------|-------------|
| `url` | string | はい | - | ターゲットURL |
| `headers` | object | いいえ | - | キーと値のペア形式のカスタムヘッダー |
| `cookies` | array | いいえ | - | 設定するCookie: `[{name, value, domain?}]` |
| `userAgent` | string | いいえ | - | カスタムUser-Agent文字列 |
| `unblocker` | boolean | いいえ | `true` | ページ読み込み前に要求される検証（チャレンジページなど）を自動完了します。デフォルトで有効です。`false` を指定すると、チャレンジページを含め、ページから返された内容をそのままレンダリングします。 |
| `proxy` | string | いいえ | - | 以前のレスポンスから取得したプロキシID。同一の出口を固定するために使用します。取得した不透明な文字列をそのまま渡してください。直接のプロキシアドレスは `400 Invalid proxy format` で拒否されます。 |
| `timeout_ms` | number | いいえ | 30000 | ページ読み込みタイムアウト（ミリ秒、最大: 120000） |
| `checkStatus` | number | いいえ | - | 期待されるHTTPステータス（異なる場合はリクエストが失敗します） |
| `checkText` | string | いいえ | - | レンダリングされたページ内に存在する必要があるテキスト |
| `lean` | boolean | いいえ | `false` | 画像、フォント、メディア、および既知の広告、アナリティクス、同意管理、ソーシャルサービスへのリクエストを除外します。ページ自体、独自のスクリプトやスタイル、および検証ステップに必要なリソースは引き続き読み込まれます。固定されたプレミアム出口などを通じたトラフィック消費を抑えるために使用します。 |

### ブラウザの時計を出口に合わせる

ページはブラウザのタイムゾーンを読み取り、認識したIPの国情報と照合できます。この不一致はボット検出ツールにとって最も低コストで検知できるシグナルの1つであり、簡単に対処できます。

特別な操作は不要です。FourA が `proxy` IDから国を読み取り、ブラウザはその国に属するタイムゾーンを報告します。

- これは**出口**の国、つまりプロキシがホストされている場所ではなく、ターゲットから見える国を指します。両者が異なるケースは無視できない頻度で発生します。
- FourA は出口の国が不明な場合、推測せずブラウザの時計をそのまま維持します。[Proxy Request](#exit-location) で `exitCountries` を指定した場合、プレミアム出口の国は判明しています。
- 追従するのは時計のみです。`Accept-Language` やサイトが配信するコンテンツは変更されないため、ページ言語が勝手に切り替わることはありません。

### `userAgent` パラメータ

`userAgent` を送信すると、ページ、そのワーカー、およびターゲットのすべてにその正確な文字列が渡されます。FourA はそこから対応する Client Hints（`sec-ch-ua`、`sec-ch-ua-platform`、`navigator.platform`、および検出ツールが名前で要求する高エントロピー値）も導出するため、リクエストのヘッダーとJavaScriptの間で異なるブラウザ情報が報告されることはありません。

レスポンス内の `userAgent` は、実際に提示された値です。これはクリアランスを再利用する際に重要となります。`cf_clearance` Cookieは、それを取得した出口および User-Agent に紐づいているため、使用したと推測される文字列ではなく、レスポンスで報告された文字列をそのまま送り返してください。詳細は [Site checks](https://foura.ai/docs/api/site-checks) を参照してください。

Chromium系以外の文字列（FirefoxのUser-Agentなど）を送信すると、Chromiumブランドリストは付加されず、そのまま提示されます。

### 例

```bash
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:

```json
{
  "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"]}
}
```

| フィールド | 型 | 説明 |
|-------|------|-------------|
| `status` | number | ターゲットからの HTTP ステータスコード |
| `headers` | object | レスポンスヘッダー |
| `body` | string または object | 完全にレンダリングされたページコンテンツ。content-type が HTML の場合は文字列の HTML、ページが JSON を返して自動パースされた場合はオブジェクト。 |
| `cookies` | array | ページからの完全な Cookie オブジェクト。各 Cookie には `name`、`value`、`domain`、`path`、`expires`、`httpOnly`、`secure`、`sameSite`、およびその他の Cookie プロパティが含まれます。 |
| `userAgent` | string | 使用されたブラウザの User-Agent |
| `defenseSolved` | boolean | この呼び出しで bot 防御に遭遇し、正常にクリアされた場合は `true`、それ以外の場合は `false`。呼び出しコストが 5 クレジットか 10 クレジットかを決定します。 |
| `defenses` | object | `present` はページ読み込み中に認識されたすべてのベンダーを一覧表示し、`cleared` は最終ページがクリアランスを保持しているベンダーを一覧表示します。ベンダーは `present` に現れても `cleared` には一切現れないことがあります。[サイトチェック](https://foura.ai/docs/api/site-checks)を参照してください。 |
| `proxy` | string | リクエストが経由したプロキシのエンコード済み ID（リクエストで `proxy` が指定された場合のみ）。同じ出口を維持するために、後続の呼び出しでこれを再利用します。 |
| `error` | string | リクエストが失敗した場合のエラーメッセージ |

---

## 出口の固定

Single または Browser リクエストで `proxy` の値を指定すると、以前の呼び出しで使用された出口が固定されます。受け取ったままの不透明な ID をそのまま返し、プロキシアドレスは絶対に渡さないでください。国、場所、または有効期間を指定した Proxy リクエストからの ID はそれらを保持するため、固定されたリクエストには他のフィールドは不要です。

3 つの値は拒絶され、すべて 400 が返されます。

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

固定されたプレミアム出口はプレミアムトラフィックとして計測されます。リクエストごとに確認できるようにレスポンスには `X-FourA-Exit-Class: premium` が含まれ、サイトが意図したページを返したかどうかに関係なく、その出口が伝送したトラフィックは [利用状況と制限](https://foura.ai/docs/dashboard/quota) ページのプレミアムトラフィックおよび合計帯域幅にカウントされます。固定にはプラン内のプレミアム出口と残りの許容量が必要です。そうでない場合、ID は上記のマネージド出口の 400 で拒絶されます。

## HTTP ステータスコード

| コード | 意味 |
|------|---------|
| 200 | リクエスト完了（ターゲットのレスポンスについては内部の `status` を確認） |
| 400 | 無効なリクエストボディ、パラメータ、プライベート/予約済み範囲のターゲットIP、FourA 自体の API ホスト上のターゲット、エンコードされていないスペースを含む URL（Single、Proxy、Auto）、または固定できないプロキシ ID。Single、Proxy、Browser では、バリデーションに失敗したフィールドが指定されます: `Invalid request: <field>: <reason>`（最大5フィールドまで）。請求対象外。Auto は同じエラーに対して HTTP 200 とボディ内の `status: 400` で応答します。 |
| 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 がエンジンに接続できませんでした。`Malformed JSON from backend`: エンジンは応答しましたが、FourA がその応答を読み取れませんでした。再試行してください。 |
| 503 | サービスが一時的に無効または過負荷、一時的にキーを確認できなかった場合の `API key check temporarily unavailable`（`Retry-After` 後に再試行）、またはエンジンの再起動中の `Backend service unavailable`。Browser では、すべてのブラウザがビジー状態の場合、ページは空きブラウザを最大10秒間待機し、その時間内に解放されない場合は `Backend service unavailable` が返されます。 |
| 504 | `Upstream timeout`。エンジンがこのリクエストの時間制限内に終了しませんでした。`timeout_ms` を増やすか、再試行してください。 |

## 次のステップ

- [スマートフェッチ (Auto)](https://foura.ai/docs/guides/smart-fetch): FourA にパスの選択を任せるタイミング
- [適切なエンドポイントの選択](https://foura.ai/docs/guides/choosing-task-type): 手動で Single、Proxy、または Browser を選択するタイミング
- [認証](https://foura.ai/docs/getting-started/authentication): API キーの管理
- [エラーハンドリング](https://foura.ai/docs/api/errors): エラーの適切な処理
- [サイトチェック](https://foura.ai/docs/api/site-checks): `defense` フィールドの読み取りとクリアランスの再適用
- [Proxy リクエストの試行回数が上限に達した理由](https://foura.ai/docs/troubleshooting/proxy-attempt-report): `attemptReport` を読み取って対処する
- [レート制限](https://foura.ai/docs/api/rate-limits): リクエスト制限の理解
- [クイックスタート](https://foura.ai/docs/getting-started/quick-start): 30秒で最初のリクエストを実行
