FourA - HTTP request via rotating proxies
foura_proxyRoutes HTTP requests through rotating proxies, retrying on different exits until one delivers. Use it when a single proxy is blocked or the request must originate from a specific exit country.
Instructions
Route an HTTP request through rotating proxies, retrying on another exit until one delivers. Use it when foura_single is blocked, and whenever the exit itself matters: this is the only tool that takes a strict exit-country allowlist (exitCountries, which never falls back to another country), presents a named browser family per attempt, excludes exits you already know are dead (ignoreProxies), and may escalate to a premium exit (exitClass, an allowance rather than an instruction). maxTries bounds how many exits are tried and timeout_ms bounds the whole rotation, so a short timeout can end it before maxTries is reached; protected targets often need 25 to 30. validate decides what counts as delivered, and an attempt it rejects is retried on the next exit. The response returns the id of the exit that succeeded: pass that returned id to foura_single.proxy or foura_browser.proxy to send the next request from the same exit. A failed rotation returns attemptReport, which separates exits that never answered from exits a bot check refused from pages your own rule threw away. Use foura_browser when the page needs JavaScript. Rotation costs several times a single request. One FourA API key authenticates every call, the result reports the credits it spent, and a refusal by your own plan arrives as a plan_limit_ code with retryAfter rather than as a block by the target.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes | The inner HTTP request to send through each proxy attempt. Validation rules here determine when a proxy is treated as failed and retried. | |
| maxTries | No | Maximum rotation attempts before giving up (default 5, max 90). Difficult protected targets may need 25-30. Use exitCountries for country scope. | |
| exitClass | No | Allow escalation to a premium exit for a target the standard pool cannot deliver. An allowance, not an instruction: the pool still races and usually wins, and the response reports which class served. `standard` forbids escalation. Without premium exits in the plan the call is refused with code plan_limit_premium. | |
| timeout_ms | No | Overall timeout across all rotation attempts in ms (default 45000, max 120000). Must be positive. | |
| exitCountries | No | Optional target-visible proxy countries as two-letter provider codes, for example ["CZ", "GB"]. Use codes supplied by the user or target requirements. When geography matters, do not guess codes or substitute unscoped rotation. Values are trimmed, uppercased, and deduplicated. Unknown exits are excluded and the request never falls back to another country. | |
| ignoreProxies | No | Encoded proxy IDs (base36 strings like "4DZ3VE") or proxy URLs to exclude from rotation. | |
| offload_large | No | If true, response bodies of 50 KB or more are returned as a resource_link instead of inlined. Default false. Read the returned offloaded_resource_uri with resources/read. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Stable error code for retry classification. auth_failed means the FourA API key was rejected; verify that key, not target-site credentials. no_eligible_proxy means the strict exitCountries scope had no match. Keep that scope and retry later; do not propose or perform an unscoped fallback. A plan_limit_* code is the caller's own FourA plan refusing (credits, bandwidth, rate, concurrency, browser_daily, premium, feature), not the target: wait out retryAfter or change the plan, never retry the same work through another tool. | |
| data | No | Decoded response body. Omitted when offloaded. | |
| error | No | Human-readable error message | |
| proxy | No | Base36 ID of the exit that succeeded (e.g. `4DZ3VE`). Pass it to foura_single.proxy or foura_browser.proxy to reuse that exit, or to foura_proxy.ignoreProxies to skip it on future rotations. | |
| total | No | Outer total time in seconds (proxy selection + retries + the successful inner attempt). Float. | |
| limits | No | ||
| status | No | HTTP status code from the target (from the succeeding proxy attempt). `0` indicates every attempt failed before any HTTP response (DNS / connection refused / timeout) - check the `error` field for the underlying reason. | |
| credits | No | Credits this call spent. Reported on failures too: the work was done either way. | |
| current | No | ||
| defense | No | Present when the target ran a bot check. When solved is false the body may be a challenge page: retry with a different browser, os, or version, or move to foura_browser. | |
| details | No | Structured no_eligible_proxy context containing the normalized requested country scope. Preserve this scope and retry later. Do not propose or perform an unscoped fallback; change it only after the user explicitly changes the requirement. | |
| headers | No | Response headers per redirect hop, as an array of objects. Each entry has `result.{version, code, reason}` plus arbitrary header-name keys whose values are strings (or arrays of strings for multi-value headers like Set-Cookie / Link). | |
| profile | No | The catalogue profile id the rotation moved to after the target refused the browser this request sent. Absent means it went out as written; when present, pass it as `profile` to present the same browser on the next call. | |
| request | No | Echoed PrRequest from upstream PrResponseError | |
| service | No | ||
| exitClass | No | Which class delivered, when the request named exitClass. `standard` means the standard pool answered first, which is also the answer once the premium allowance is spent. Neither is an error. | |
| request_id | No | FourA's id for this call, for a support request. | |
| retryAfter | No | ||
| size_bytes | No | Total offloaded body size in bytes | |
| total_time | No | Per-attempt wall-clock duration of the succeeding inner request | |
| exitCountry | No | Latest available two-letter target-visible exit-country code used for selection. Present on successful requests that use exitCountries. | |
| attemptReport | No | Why a failed rotation ran out of tries. Read `summary` first. Counts over `total` attempts: noResponse (the exit never answered), defense (a bot check was recognised, named in `vendors`), contentRejected (HTTP 200, no bot check, rejected only by your validate.data), statusRejected (rejected by your validate.status), other. `profilesTried` lists the browsers sent, `default` meaning the request went out as written. High contentRejected means the pages arrived and your own rule threw them away: fetch once with foura_single and no validate, then rewrite it. | |
| offloaded_resource_uri | No | foura-mcp://payload/<uuid>. Pass this URI to resources/read to retrieve the offloaded body. |