Referencia de endpoints de la API
Una referencia para todos los endpoints de la API de FourA con parámetros de request y formatos de response.
URL base
https://eu.api.foura.ai/api
Autenticación
Cada request requiere tu API key en el header X-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"}'
Crea y administra claves de API en el Dashboard. Las claves usan el prefijo pk_live_.
Headers de respuesta
Las respuestas de /api/* incluyen dos headers de correlación:
| Header | Value | Description |
|---|---|---|
X-FourA-Request-Id |
UUID | ID único asignado a la request. Se devuelve en cada respuesta, incluyendo 4xx y 5xx, excepto si FourA no puede leer el cuerpo en absoluto: 400 Invalid JSON in request body y 413 se rechazan antes de asignar un ID. Regístralo en tus logs. |
X-FourA-Credits |
integer | Créditos gastados en esta request. Se devuelve en cada respuesta que llegó a un motor, sea éxito o fallo (el trabajo se realizó de todos modos). Una llamada que FourA rechazó antes de que cualquier motor la ejecutara (una clave faltante o no válida, un límite de plan o plataforma, un target o proxy ID rechazado) no incluye ninguno. Consulta Resultados de request para ver qué resultados son facturables. |
El mismo ID de request indexa la vista previa de la carga útil de request y response en el Activity Log del Dashboard (conservado durante 24 horas, las últimas 200 por clave), para que puedas buscar la request exacta más tarde y reproducirla desde Activity directamente en el Playground. Inclúyelo cuando contactes a soporte para identificar la request en segundos.
$ 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
...
Consulta Response Headers para ver la lista completa y consejos de uso.
Endpoints
¿Usas estos endpoints mediante MCP? El servidor
@fouradata/mcpenvuelve los cuatro endpoints como herramientas nativas de MCP (foura_auto,foura_single,foura_proxy,foura_browser) con las mismas estructuras de entrada, más una opciónoffload_largepara gestionar respuestas grandes optimizando tokens. Las diferencias:foura_browserno tiene el campolean, yfoura_proxyaún no admite los campos de ubicación de salida.
FourA ofrece cuatro endpoints de request, cada uno optimizado para un escenario distinto:
| Endpoint | Ideal para |
|---|---|
POST /auto/ |
Smart fetch. Envías una URL, FourA elige la ruta más económica que funcione (proxy rotado o browser, además de una request directa con forceProxy: false) y recuerda lo que funciona para cada host. |
POST /single/ |
HTTP requests rápidas, páginas estáticas, APIs |
POST /proxy/ |
Sitios protegidos con rotación automática de proxy, alcance opcional por país visible para el destino |
POST /browser/ |
Páginas renderizadas con JavaScript, SPAs |
GET /profiles |
El catálogo de perfiles de browser para single y proxy. Público, sin API key. |
Para un análisis más detallado sobre cuándo elegir cada uno, consulta Cómo elegir el endpoint correcto y la guía de Smart Fetch.
Restricciones de URL de destino
Los destinos que resuelven a rangos de IP privadas, de loopback o reservadas (RFC 5735, RFC 6598, bloques reservados de IPv6) se rechazan con un error 400 antes de que la request salga de FourA. Solo se reenvían hostnames e IPs públicos.
{ "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." }
Un destino en el propio host de la API de FourA (eu.api.foura.ai o api.foura.ai) también se rechaza con un 400, en los cuatro endpoints, antes de que se obtenga nada o se realice cualquier cobro. Una URL que contenga un espacio o un carácter de control se rechaza de la misma manera con un 400 en Single, Proxy y Auto; codifica el espacio como %20 (Browser lo obtiene de la misma forma que Chrome). La única página allí que FourA obtiene es /inspect.
{ "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/
Envías una URL junto con reglas validate opcionales. FourA recorre una escala según el costo (proxy rotativo y luego navegador completo) y se detiene en el primer nivel que devuelva una response que tus reglas acepten. Con forceProxy: false, primero se ejecuta una prueba directa económica. En llamadas repetidas al mismo host, se reutiliza una sesión activa, por lo que el segundo acceso resulta económico.
No necesitas configurar reintentos, tamaños de grupos ni cantidad de proxies. FourA los aprende por host.
Request Body
| Parámetro | Tipo | Obligatorio | Valor predeterminado | Descripción |
|---|---|---|---|---|
url |
string | Sí | - | URL de destino |
method |
string | No | "GET" |
Método HTTP |
headers |
[string, string][] | No | - | Headers para enviar al destino, como pares [name, value]. Cada nivel los envía, excepto el nivel de navegador. El Cookie que envíes llega al sitio sin cambios, y las cookies de una sesión guardada se agregan junto a él solo con los nombres que no hayas enviado. El userAgent de una sesión guardada reemplaza tu User-Agent. El nivel de proxy omite headers condicionales como If-None-Match, a menos que tu validate.status.accept incluya 304. |
data |
any | No | - | Request body para requests que no sean GET |
validate |
object | No | - | Criterios de éxito, con la misma estructura que validate de Single Request (ver abajo). Indica a auto cómo se ve una página real para que distinga el contenido de una página de desafío. |
returnSession |
boolean | No | true |
Incluye la sesión ganadora (proxy, cookies, userAgent) en la response para que puedas reutilizarla mediante /api/single/ o /api/browser/. |
forceProxy |
boolean | No | true |
Enrutar siempre mediante un proxy rotativo. Establece false para permitir la ruta directa más económica cuando el destino lo permita (algunas defensas son más estrictas con el tráfico de proxies). |
timeout_ms |
integer | No | 120000 |
Presupuesto de tiempo total para toda la llamada, en milisegundos. Todos los subintentos se ejecutan dentro de este presupuesto. Mínimo 5000, máximo 180000. |
ignoreProxies |
string[] | No | - | IDs de proxy que se deben evitar en cada subintento. Usa los IDs devueltos por responses previas de /api/auto/ o /api/proxy/. |
followRedirects |
integer | No | 5 |
Cantidad máxima de redirecciones a seguir en los niveles económicos de la escala. 0 para deshabilitar. Máximo 20. |
exitClass |
string | No | - | standard o premium, igual que en Proxy Request. premium permite que la llamada escale a una salida premium una vez que el grupo estándar no pueda acceder a la página. Requiere un plan que incluya salidas premium. Consulta exitClass en Smart Fetch. |
Response
{
"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..."
}
}
| Campo | Tipo | Descripción |
|---|---|---|
status |
number | Estado HTTP del objetivo. |
data |
string | Cuerpo de la respuesta como texto, sin importar qué nivel lo haya servido. Una página JSON se devuelve como texto JSON, por lo que debes analizarlo tú mismo. |
headers |
array or object | Headers de respuesta del objetivo. Los niveles Single y proxy devuelven un array de objetos de headers por salto; los niveles de navegador devuelven un objeto plano. |
meta.rung |
string | Qué nivel de la escala entregó la respuesta. Uno de: probe (request directa económica, solo con forceProxy: false), proxy (proxy rotativo), browser (renderizado completo en navegador), cache (sesión activa reproducida), warmup (se obtuvo primero la página de entrada del sitio y sus cookies abrieron la URL profunda) o fail (ningún nivel produjo una respuesta aceptada). |
meta.solved |
boolean | Indica si la página necesitó un paso adicional (una página de desafío) y este se completó durante esta llamada. |
meta.attempts |
number | Subintentos realizados antes de tener éxito. |
meta.credits |
number | Créditos totales consumidos en esta llamada. Coincide con X-FourA-Credits. |
meta.attemptsByEngine |
object | Requests enviadas a single, proxy y browser. Una request de navegador rechazada por tu plan cuenta, ya que fue enviada. |
meta.browserRequests |
number | Requests de navegador que consumieron un espacio de tu límite diario. Una request de navegador rechazada por tu plan no consume nada. |
meta.exitClass |
string | Qué clase de salida entregó la respuesta, presente cuando la request indicó un exitClass: premium o standard. El mismo valor se envía en el header de respuesta X-FourA-Exit-Class. |
session.proxy |
string | ID codificado del proxy que entregó la respuesta. Reutilízalo en una request Single o Browser. Presente cuando returnSession es true. |
session.cookies |
array | Cookies para reproducir, cada una con al menos name y value. Un nivel de navegador devuelve el almacén de cookies del navegador. Un nivel de proxy, o la sonda directa, devuelve solo las cookies que abrieron la página (como las establecidas por una página de verificación del sitio), nunca todas las cookies establecidas por la página, por lo que la lista puede estar vacía. Presente cuando returnSession es true. |
session.userAgent |
string | User-Agent utilizado en el intento exitoso. Presente cuando returnSession es true. |
error |
string | Mensaje de error si la llamada falló. |
attemptReport |
object | En una llamada fallida: las requests del motor que regresaron sin la página, clasificadas por causa. Consulta Smart Fetch. |
Ejemplo
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"]}}
}'
Notas
- Auto es un coordinador. Llama a Single, Proxy o Browser internamente y reenvía tu API key a cada sub-llamada. La llamada de Auto es un request en tu Activity Log y en tu Overview, con la suma de los créditos de sus sub-llamadas; las sub-llamadas se listan debajo como sus intentos y nunca cuentan como requests independientes.
- Pasa
validate.data.acceptcon una subcadena que solo la página real contenga. Sin ella, Auto no puede distinguir un 200 real de una pantalla intermedia de challenge devuelta con estado 200. - Una página eliminada es la respuesta del sitio, no un rechazo. Cuando dos salidas devuelven el mismo
404o410y tuvalidateno lo acepta, la llamada termina con esestatusy unerrorque comienza conthe site answered. Incluye el estado envalidate.status.accepty Auto entrega la primera respuesta con ese estado que supere el resto de tuvalidate. Lo mismo aplica para cualquier otro estado que listes allí, excepto403,429,503y202, que los sitios también envían junto con una página de challenge. timeout_mslimita toda la llamada. Un primer intento en frío hacia un sitio protegido puede tardar decenas de segundos; las sesiones activas reutilizadas suelen completarse en menos de un segundo.
exitClass en Smart Fetch
exitClass funciona en Smart Fetch igual que en Proxy Request: es un permiso, no una instrucción. Auto prueba primero el pool estándar. Cuando el pool estándar no puede acceder a la página y el request especifica premium, Auto abre la página en un browser a través de una salida premium. La sesión que crea allí sirve para tus llamadas posteriores al mismo sitio que también especifiquen premium; las llamadas que no lo indiquen nunca la usan.
Agotar la cuota no es un error. Una vez que el tráfico premium de tu plan se consume durante el período de facturación, la llamada continúa en el pool estándar y meta.exitClass indica standard. En un plan sin salidas premium, una llamada que envía exitClass: premium se rechaza con un 403 que incluye X-FourA-Limit: plan_limit_premium, antes de realizar cualquier trabajo.
El tráfico premium se mide igual que en Proxy Request. Una página abierta en un browser carga más elementos que la página en sí, por lo que una página premium en Smart Fetch consume más tráfico premium que la misma página obtenida mediante Proxy Request. Para reducir ese consumo, una página premium en Smart Fetch se carga sin imágenes, fuentes ni medios, y sin scripts de proveedores conocidos de publicidad, analítica y consentimiento.
Single Request
POST /api/single/
Envía un HTTP request con características de red realistas similares a las de un browser, sin iniciar un browser real. Este es el endpoint más rápido.
Request Body
| Parámetro | Tipo | Requerido | Por defecto | Descripción |
|---|---|---|---|---|
method |
string | Sí | - | Método HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
url |
string | Sí | - | URL de destino. Usa {ts} en cualquier parte de la URL para insertar la marca de tiempo actual para invalidar la caché. |
headers |
[string, string][] | No | - | Headers personalizados como pares [nombre, valor] |
unblocker |
boolean | No | true |
Envía headers de navegador realistas (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Activado por defecto. Define false y FourA no añadirá headers de navegador, solo los que pases. |
timeout_ms |
number | No | 15000 | Timeout total en ms (máx: 120000) |
connect_timeout_ms |
number | No | 5000 | Timeout de conexión en ms |
accept_timeout_ms |
number | No | 5000 | Timeout de aceptación en ms (tiempo de espera para aceptar la conexión) |
server_response_timeout_ms |
number | No | 15000 | Timeout de respuesta del servidor en ms (tiempo de espera para el primer byte) |
dns_cache_timeout_sec |
number | No | 120 | TTL de la caché DNS en segundos (máx: 240) |
followRedirects |
number | No | disabled | Redirecciones máximas a seguir (0-20). Omite para desactivar. |
tryJsonData |
boolean | No | false | Parsea el cuerpo de la respuesta como JSON si es posible |
returnBuffer |
boolean | No | false | Devuelve un buffer sin procesar en lugar de una cadena decodificada |
data |
any | No | - | Cuerpo de la request (string u objeto, serializado automáticamente a JSON) |
proxy |
string | No | - | ID de proxy de una respuesta anterior, para fijar la misma salida. Devuelve la cadena opaca tal cual. Una dirección de proxy sin procesar se rechaza con 400 Invalid proxy format. Algunos ID no se pueden fijar: consulta Fijar una salida. |
browser |
string | No | Chrome | Navegador a presentar: Chrome, Edge, Safari, Firefox o Tor. Consulta Perfiles de navegador. |
os |
string | No | - | Sistema operativo a presentar: Windows, macOS, Android o iOS. Un nombre de familia acepta cualquiera de sus versiones. |
version |
string | No | newest | Versión del navegador a presentar, tal como figura en el catálogo. La coincidencia más reciente tiene prioridad cuando varias encajan. |
profile |
string | No | - | ID exacto del perfil desde GET /api/profiles, en lugar de los tres campos anteriores. |
validate |
object | No | - | Reglas de validación de respuesta (ver más abajo) |
Perfiles de navegador
Por defecto, una request presenta la última versión de Google Chrome. Algunos destinos aceptan un navegador y rechazan otro, por lo que browser, os y version acotan un catálogo de perfiles medidos, y profile selecciona uno por su ID.
{
"method": "GET",
"url": "https://example.com",
"browser": "Firefox",
"os": "Windows"
}
Reglas:
- La selección requiere
unblocker(activado por defecto). Conunblockerdesactivado no se envían headers de navegador, por lo que la request se rechaza en lugar de aplicarse a medias. - Cuando varios perfiles coinciden, se utiliza la versión más reciente.
- Una combinación que el catálogo no pueda ofrecer devuelve un error indicando lo que está disponible, y un id de
profiledesconocido devuelveunknown profile '<id>'. La request nunca se envía como un navegador diferente. - Los mismos cuatro campos están disponibles dentro del objeto
requestdePOST /proxy/.
GET /api/profiles devuelve el catálogo completo y no requiere API key:
{
"profiles": [
{ "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
],
"default": "..."
}
osFamily es el valor por el que filtrar al crear un selector; os conserva el nombre de la versión para mostrarlo.
Reglas de validación
El objeto validate te permite definir condiciones de éxito y fallo. Si una condición de fail coincide, la request se procesa como fallida. Si se establecen condiciones de accept, solo las respuestas que coincidan se procesan como exitosas.
{
"validate": {
"status": { "accept": [200, 201], "fail": [403, 503] },
"headers": { "accept": {"content-type": "application/json"} },
"data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
}
}
| Campo | Tipo | Descripción |
|---|---|---|
validate.status.accept |
number[] | Códigos de estado HTTP para aceptar |
validate.status.fail |
number[] | Códigos de estado HTTP para rechazar |
validate.headers.accept |
object | La respuesta se aprueba cuando al menos un par coincide en cualquier salto de redirección. Los nombres y valores coinciden sin distinguir mayúsculas de minúsculas, sobre parte del texto. |
validate.headers.fail |
object | Pares clave-valor de cabecera que activan un error |
validate.data.accept |
string[] | La respuesta se aprueba cuando el cuerpo contiene al menos una de estas cadenas |
validate.data.fail |
string[] | Cadenas en el cuerpo de la respuesta que activan un error |
Ejemplo
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
}
Cuando el objetivo ejecuta una comprobación de bots de camino al body, la respuesta también incluye un objeto defense que indica el proveedor y si se superó la comprobación:
{
"status": 200,
"data": "<!doctype html>...",
"total_time": 3.61,
"defense": {
"vendor": "sgcaptcha",
"solved": true,
"present": ["sgcaptcha"],
"ms": 3412,
"cookie": "_I_=<clearance>"
}
}
| Campo | Tipo | Descripción |
|---|---|---|
status |
number | Código de estado HTTP del destino |
headers |
array | Un objeto por cada salto de redirección. Cada uno tiene un campo result con la línea de estado más cada header de respuesta. Los headers con múltiples valores (Set-Cookie, Link, WWW-Authenticate) se devuelven como arrays de strings. |
data |
string/object | Cuerpo de la respuesta (JSON si tryJsonData es true) |
total_time |
number | Tiempo total de la request en segundos |
proxy |
string | ID codificado del proxy a través del cual pasó la request (solo cuando se proporcionó un proxy en la request). Reutilízalo en una llamada posterior para fijar la misma salida. |
defense |
object | Presente cuando el destino ejecutó una verificación de bots en esta request, o cuando un reintento con las cookies del propio sitio produjo el cuerpo. defense.solved indica si se superó una verificación, defense.retry indica si un reintento te obtuvo el contenido. Consulta Site checks para ver cada campo y la lista completa de sistemas. |
error |
string | Mensaje de error si la request falló |
Proxy Request
POST /api/proxy/
Enruta tu request a través de proxies rotativos con reintento automático en caso de fallo. Opcionalmente, limita la selección a un conjunto de países de salida visibles para el destino.
Request Body
| Parámetro | Tipo | Obligatorio | Valor predeterminado | Descripción |
|---|---|---|---|---|
request |
object | Sí | - | Un único cuerpo de request (los mismos campos que Single Request arriba) |
timeout_ms |
number | No | 45000 | Timeout global para todos los intentos en ms (máx: 120000) |
maxTries |
number | No | 5 | FourA deja de iniciar nuevos intentos cuando esta cantidad ha fallado (máx: 90). Los intentos se ejecutan en paralelo, por lo que pueden terminar unos pocos más que este número. |
ignoreProxies |
string[] | No | - | IDs de proxy que se deben excluir de la rotación (usa los IDs devueltos por responses anteriores) |
exitCountries |
string[] | No | - | Lista de permitidos estricta con códigos de país de dos letras visibles para el destino (por ejemplo, ["CZ", "GB"]). Los valores se limpian de espacios, se pasan a mayúsculas y se desduplican. Las salidas del pool estándar con un país desconocido quedan excluidas, y el pool estándar nunca recurre a un país no solicitado. Una salida premium también sale desde uno de los países listados. |
exitClass |
string | No | - | standard o premium. premium permite que el request escale a una salida premium cuando el pool estándar tiene dificultades con un destino protegido. Requiere un plan que incluya salidas premium. |
exitState |
string | No | - | Región desde la que sale la conexión. Requiere exitClass: premium y exactamente un país en exitCountries. Consulta Exit location. |
exitCity |
string | No | - | Ciudad desde la que sale la conexión. Requiere exitClass: premium y exactamente un país en exitCountries. |
exitAsn |
string | No | - | Red desde la que sale la conexión, por número de AS, por ejemplo 8866. Requiere exitClass: premium y exactamente un país en exitCountries. |
exitOs |
string | No | - | windows, android, ios o mac: el tipo de dispositivo al que pertenece la dirección. Requiere exitClass: premium. |
exitLifetimeMin |
integer | No | - | Minutos durante los cuales la salida conserva su dirección, de 3 a 1440. Requiere exitClass: premium. |
Alcance de exitCountries
La selección utiliza los metadatos más recientes disponibles sobre el país visible para el destino, normalmente actualizados en unos diez minutos. No es una búsqueda de geolocalización en tiempo real durante el request. No deduzcas el país de servicio a partir de la dirección del host del proxy.
Si el pool actual no tiene coincidencias para los países solicitados y el request no especificó exitClass: premium, la response devuelve HTTP 200 con un contenedor de error:
{
"error": "No eligible proxy found for exit countries: CZ, GB",
"code": "no_eligible_proxy",
"details": { "exitCountries": ["CZ", "GB"] },
"total": 0.084
}
Conserva el scope solicitado y reintenta más tarde. Cámbialo o amplíalo solo cuando el requisito de país de tu flujo de trabajo cambie de forma explícita.
Ejemplo
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
}
| Campo | Tipo | Descripción |
|---|---|---|
proxy |
string | Identificador codificado del proxy utilizado. Reutilízalo en una solicitud Single o Browser pasándolo como el campo proxy, u omítelo en la siguiente solicitud Proxy mediante ignoreProxies. |
exitCountry |
string | Código de país de dos letras, visible para el destino, del proxy que atendió la solicitud. Presente solo cuando la solicitud definió exitCountries, sin importar qué clase de salida la atendió. Verifica siempre que sea uno de los códigos que solicitaste antes de confiar en la respuesta. |
exitClass |
string | Qué clase de salida atendió esta solicitud, presente en una respuesta exitosa cuando la solicitud especificó una. premium significa que una salida premium devolvió el cuerpo; standard significa que lo hizo el pool estándar. Una llamada fallida no atendió nada, por lo que no incluye exitClass; consulta su attemptReport para ver qué encontraron los intentos. |
total |
number | Duración total transcurrida (wall-clock) en segundos (float). Incluye la selección de proxy, los reintentos y el intento exitoso. total_time corresponde únicamente a la solicitud interna; total es siempre >= total_time. |
profile |
string | El perfil de navegador que eligió la rotación, presente solo cuando no fue el que solicitaste. Si está ausente, significa que la solicitud se envió exactamente como se escribió. Pasa el id de vuelta como profile en las llamadas siguientes para conservar el navegador que funcionó. |
error |
string | Mensaje de error si la solicitud falló. En un fallo de alcance (scope miss), code es no_eligible_proxy y details.exitCountries repite el scope normalizado. |
attemptReport |
object | Presente en cada llamada de Proxy fallida. Cuenta lo que encontraron los intentos, de modo que un pool bloqueado, un pool inactivo y una regla validate que nunca coincidió no se interpreten como el mismo error. Consulta más abajo. |
request |
object | Presente en una llamada de Proxy fallida: la solicitud que FourA ejecutó, con los valores predeterminados completados y tus ignoreProxies tal como los enviaste. |
También se incluyen todos los campos de respuesta de Single Request, defense entre ellos: un intento de proxy que encontró una verificación de bots lo reporta de la misma manera que Single.
Por qué falló una llamada de Proxy
Download maxTry limit reached se lee igual independientemente del resultado de los intentos, por lo que cada respuesta fallida de Proxy incluye un attemptReport junto al error:
{
"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
}
| Campo | Tipo | Descripción |
|---|---|---|
total |
integer | Intentos realizados |
noResponse |
integer | La salida nunca respondió, por lo que nunca se alcanzó el sitio |
defense |
integer | El sitio respondió y se reconoció una verificación de bots en esa respuesta |
contentRejected |
integer | HTTP 200, sin verificación de bots, rechazado solo por tu validate.data |
statusRejected |
integer | El sitio respondió, sin verificación de bots, rechazado por tu validate.status |
other |
integer | Respondió, y ninguno de los casos anteriores |
vendors |
string[] | Proveedores de verificación de bots reconocidos en cualquier parte de la tarea |
profilesTried |
string[] | Perfiles de navegador enviados por la tarea, en orden de primer uso. default significa que tu request se envió sin cambios. |
summary |
string | Una frase construida a partir de los conteos, segura para registrar |
La cadena error no ha cambiado, por lo que un cliente que coincida con ella sigue funcionando. Qué hacer con cada conteo: Por qué un Proxy Request se quedó sin intentos.
exitClass
Algunos objetivos rechazan las salidas del grupo estándar sin importar cuántas se intenten. exitClass: premium le indica a Proxy que puede escalar dicha request a una salida premium además del grupo estándar, en lugar de limitarse a rotar dentro de él.
{
"exitClass": "premium",
"request": { "method": "GET", "url": "https://example.com/report" }
}
Vale la pena saber tres cosas antes de enviarlo.
Es una concesión, no una instrucción. El pool estándar sigue compitiendo por la respuesta y suele ganar. Una salida premium solo se une cuando el pool ha consumido un breve presupuesto en la request o el destino la ha rechazado visiblemente. Una request que el pool estándar responde antes de que se intente cualquier salida premium es un éxito normal y no te cuesta tráfico premium. Una vez que se prueba una salida premium, su tráfico cuenta, como se describe a continuación.
Una salida premium se mantiene dentro de exitCountries. Con una lista de países, una salida premium sale desde uno de esos países y exitCountry en la response lo nombra, al igual que para el pool estándar.
La response te indica qué te atendió en realidad. Cuando especificas una clase, la response devuelve exitClass:
{
"status": 200,
"exitClass": "premium",
"proxy": "Y2QXVK",
"data": "..."
}
premium significa que una salida premium devolvió el cuerpo. standard significa que lo hizo el pool estándar, que es la respuesta que también obtienes cuando no se pudo conseguir una salida premium, y cuando el tráfico premium incluido en tu plan (más lo que hayas comprado adicionalmente) se ha agotado durante el periodo de facturación. Ninguno es un error, y puedes conciliar tu tráfico premium con estos valores por request en lugar de hacerlo contra una cifra mensual. El mismo valor viaja en el header de respuesta X-FourA-Exit-Class (consulta Response Headers).
El tráfico premium se mide en la red. Un intento premium contabiliza lo que envió y recibió al cruzar la red, comprimido y cifrado sobre la marcha, devuelva o no tu página. Un intento que seguía ejecutándose cuando otra salida respondió se detiene de inmediato, y el tráfico que transmitió hasta ese momento también cuenta. El tráfico premium cuenta para tu cuota premium y también dentro de tu ancho de banda total: los mismos bytes, reportados dos veces, nunca sumados entre sí. Cuando una salida premium entregó la página, su tráfico representa todo el tráfico de la request, por lo que la página no se vuelve a contar como tráfico estándar. Tu página Usage & Limits muestra el tráfico total, la porción premium del mismo y la cuota premium contra la que se te mide.
Omitir el campo y enviar standard mantienen la request en el pool estándar: solo premium permite una salida premium. Una request exitosa que especifica una clase recibe exitClass en la respuesta, y una request que omite el campo no lo recibe.
Agotar la cuota no es un error. Una request que especifica premium después de haber consumido la cuota sigue funcionando: el pool estándar la atiende y la respuesta indica standard. La única excepción es una request que especifica una exit location: el pool estándar no puede cumplirla, por lo que se rechaza.
exitClass: premium requiere un plan que incluya salidas premium. En un plan sin ellas, la request nunca consume una salida premium: se rechaza con un 403 que incluye X-FourA-Limit: plan_limit_premium (consulta Rate Limits), antes de realizar cualquier trabajo.
Ubicación de salida
Una salida premium puede originarse desde un lugar dentro de un país y mantener su dirección durante el tiempo que la necesites:
{
"exitClass": "premium",
"exitCountries": ["BG"],
"exitCity": "sofia",
"exitLifetimeMin": 15,
"request": { "method": "GET", "url": "https://example.com/" }
}
La response indica la salida y el país desde el que salió:
{
"status": 200,
"exitClass": "premium",
"exitCountry": "BG",
"proxy": "1EM4GZY",
"data": "..."
}
Ese ID proxy conserva todo. Pásalo a Single o Browser y la request saldrá desde el mismo lugar, sin ningún otro campo junto a él. Consulta Fijar una salida.
Reglas:
- Cualquiera de
exitState,exitCity,exitAsn,exitOsyexitLifetimeMinenvía la request únicamente a través de salidas premium. El grupo estándar no recibe ningún intento, ya que no puede aplicarlas. - Requieren
exitClass: premium. Sin él, la request se rechaza con un 400 que especifica el campo. exitState,exitCityyexitAsnexisten dentro de un solo país, por lo que necesitan exactamente un país enexitCountries.exitOsyexitLifetimeMinadmiten varios: la salida toma uno de ellos, yexitCountryen la response indica cuál.exitState,exitCity,exitAsnyexitOsrequieren un plan con segmentación geográfica además de salidas premium.- Si no queda tráfico premium, la request se rechaza con un 403 que incluye
X-FourA-Limit: plan_limit_premium, ya que el grupo estándar no puede atenderla. - Si ninguna salida premium responde para esa ubicación, la response es un contenedor de error como el de alcance de exitCountries, con el error
No premium exit answered for this requestycode: no_eligible_proxy.details.exitCountriesaparece cuando enviaste una lista de países.
Los términos coinciden con los que acepta el puerto proxy para state, city, asn y os.
Rotación del perfil del navegador
Proxy rota las salidas. Cuando un sitio rechaza el navegador presentado por FourA y no la salida de origen, Proxy también pasa a otra familia de navegadores del catálogo. Esto no añade intentos adicionales: la rotación modifica lo que envía un reintento, nunca si este se ejecuta o no.
Proxy también recuerda temporalmente la última familia que aceptó un sitio, de modo que una llamada posterior al mismo sitio pueda comenzar con esa familia en lugar de la predeterminada. La response la nombra en profile, tal como lo hace para cualquier familia elegida por la rotación.
Un valor explícito de profile, browser, os o version en tu request interno nunca se sobrescribe, al igual que una request que incluya su propio header User-Agent o Cookie, ya que una autorización está vinculada a la firma que la obtuvo.
Browser Request
POST /api/browser/
Abre tu URL en una instancia del navegador Chrome. La página carga, JavaScript se ejecuta y obtienes el HTML completamente renderizado junto con las cookies.
Request Body
| Parámetro | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
url |
string | Sí | - | URL de destino |
headers |
object | No | - | Headers personalizados como pares clave-valor |
cookies |
array | No | - | Cookies para configurar: [{name, value, domain?}] |
userAgent |
string | No | - | Cadena de User-Agent personalizada |
unblocker |
boolean | No | true |
Completa la comprobación que solicita una página antes de cargar (una página de desafío o un filtro similar). Activado por defecto. Establece false para renderizar lo que devuelva la página, incluida una página de desafío, tal como llegó. |
proxy |
string | No | - | ID de proxy de una respuesta anterior, para fijar la misma salida. Devuelve la cadena opaca sin cambios. Una dirección de proxy sin procesar se rechaza con 400 Invalid proxy format. |
timeout_ms |
number | No | 30000 | Tiempo de espera de carga de página en ms (máx: 120000) |
checkStatus |
number | No | - | Estado HTTP esperado (la solicitud falla si es diferente) |
checkText |
string | No | - | Texto que debe aparecer en la página renderizada |
lean |
boolean | No | false |
Omite imágenes, fuentes y medios, así como solicitudes a servicios conocidos de publicidad, analítica, consentimiento y redes sociales. La página en sí, sus propios scripts y estilos, y todo lo que requiera un paso de verificación se siguen cargando. Úsalo para reducir el tráfico que consume una página, por ejemplo a través de una salida premium fijada. |
Sincronización del reloj del navegador con la salida
Una página puede leer la zona horaria del navegador y compararla con el país de la IP que detecta. Una discrepancia es una de las señales más fáciles de detectar para un sistema antibot, y no te cuesta nada eliminarla.
No necesitas hacer nada. FourA lee el país a partir del ID de proxy y el navegador reporta una zona horaria que le corresponde.
- Es el país de salida, es decir, el país que ve el destino, no el lugar donde está alojado el proxy. Ambos discrepan con la frecuencia suficiente como para importar.
- Cuando FourA no conoce el país de salida, no modifica el reloj del navegador en lugar de adivinarlo. Una salida premium tiene un país conocido cuando solicitaste uno con
exitCountriesen Proxy Request. - Solo el reloj se ajusta al país.
Accept-Languagey el contenido que sirve el sitio permanecen intactos, por lo que la página no cambiará de idioma inesperadamente.
El parámetro userAgent
Envía userAgent y esa cadena exacta será la que vean la página, sus workers y el destino. FourA también deduce a partir de ella los client hints correspondientes (sec-ch-ua, sec-ch-ua-platform, navigator.platform y los valores de alta entropía que un detector solicita por nombre), evitando que la request declare un navegador en el header y otro en JavaScript.
El userAgent en la respuesta es el que se presentó. Esto es importante al reutilizar una autorización: una cookie cf_clearance está vinculada a la salida y al User-Agent que la obtuvo, así que devuelve la cadena que reportó la respuesta, no la que crees que se utilizó. Consulta Site checks.
Envía una cadena que no sea de Chromium (por ejemplo, un User-Agent de Firefox) y se presentará tal cual, sin ninguna lista de marcas de Chromium adjunta.
Ejemplo
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"]}
}
| Campo | Tipo | Descripción |
|---|---|---|
status |
number | Código de estado HTTP del destino |
headers |
object | Headers de la respuesta |
body |
string u object | Contenido de la página totalmente renderizado. String HTML cuando content-type es HTML; object cuando la página devolvió JSON y fue analizado automáticamente. |
cookies |
array | Objetos cookie completos de la página. Cada cookie incluye name, value, domain, path, expires, httpOnly, secure, sameSite y otras propiedades de cookies. |
userAgent |
string | User-Agent del navegador utilizado |
defenseSolved |
boolean | true si se encontró y superó genuinamente una defensa contra bots en esta llamada, false en caso contrario. Determina si la llamada cuesta 5 o 10 créditos. |
defenses |
object | present lista cada proveedor reconocido durante la carga de la página, cleared lista aquellos cuya autorización mantiene la página final. Un proveedor puede aparecer en present y nunca en cleared. Consulta Comprobaciones del sitio. |
proxy |
string | ID codificado del proxy a través del cual pasó la solicitud (solo cuando se proporcionó un proxy en la solicitud). Reutilízalo en llamadas posteriores para mantener la misma salida. |
error |
string | Mensaje de error si la solicitud falló |
Fijar una salida
Un valor proxy en una solicitud Single o Browser fija la salida que utilizó una llamada anterior. Devuelve el ID opaco exactamente como llegó, nunca una dirección de proxy. Un ID de una solicitud Proxy que especificó un país, una ubicación o una duración los conserva, por lo que la solicitud fijada no necesita ningún otro campo.
Se rechazan tres valores, todos con un 400:
| Error | Significado |
|---|---|
Invalid proxy format |
El valor no es un ID emitido por FourA. Una dirección de proxy sin procesar termina aquí. |
Proxy not found |
El ID se decodificó, pero ya no resuelve a una salida activa. Obtén una nueva mediante otra llamada. |
Managed exit: this proxy id cannot be pinned to a request |
La salida existe, pero no es una que FourA mantendrá abierta para una solicitud específica. El ID de una salida premium termina aquí cuando a tu plan no le queda tráfico premium disponible. Reutiliza la sesión en la que se devolvió o ejecuta la llamada a través de POST /api/proxy/ y toma la salida que elija. |
Una salida premium fijada se mide como tráfico premium. La respuesta incluye X-FourA-Exit-Class: premium para que puedas verlo por solicitud, y el tráfico que transportó la salida cuenta para el tráfico premium en tu página Uso y límites así como para tu ancho de banda total, independientemente de si el sitio devolvió la página deseada o no. Fijar requiere salidas premium en tu plan y saldo disponible; de lo contrario, el ID se rechaza con el 400 de salida gestionada indicado arriba.
Códigos de estado HTTP
| Código | Significado |
|---|---|
| 200 | Solicitud completada (revisa el status interno para ver la respuesta del destino) |
| 400 | Cuerpo de la solicitud no válido, parámetros no válidos, IP de destino en un rango privado/reservado, destino en el propio host de la API de FourA, una URL con un espacio sin codificar en su interior (Single, Proxy, Auto), o un ID de proxy que no se puede fijar. En Single, Proxy y Browser se indica el campo que falla la validación: Invalid request: <field>: <reason>, hasta cinco campos. No facturado. Auto responde al mismo error con HTTP 200 y status: 400 en el cuerpo. |
| 401 | Clave de API ausente o no válida |
| 403 | El endpoint o un parámetro no está en tu plan. X-FourA-Limit lo especifica: plan_limit_feature o plan_limit_premium. |
| 404 | Not Found: no hay ningún endpoint en esa ruta. |
| 413 | El cuerpo JSON de la solicitud supera los 100 KB. La respuesta no es JSON y no incluye X-FourA-Request-Id. |
| 429 | Límite del plan (X-FourA-Limit establecido) o límite compartido por minuto de la plataforma (sin header) |
| 500 | Error interno del servidor |
| 502 | Upstream unavailable: FourA no pudo conectarse a su motor. Malformed JSON from backend: el motor respondió pero FourA no pudo leer la respuesta. Reintenta. |
| 503 | Servicio temporalmente deshabilitado o al máximo de su capacidad, API key check temporarily unavailable cuando FourA no pudo confirmar tu clave momentáneamente (reintenta tras Retry-After), o Backend service unavailable mientras se reinicia un motor. En Browser, una página espera hasta 10 segundos por un navegador libre cuando todos están ocupados, y recibe Backend service unavailable si ninguno se libera en ese tiempo. |
| 504 | Upstream timeout. El motor no terminó dentro del tiempo límite asignado para esta solicitud. Aumenta timeout_ms o reintenta. |
Próximos pasos
- Smart Fetch (Auto): Cuándo dejar que FourA elija la ruta por ti
- Elegir el endpoint adecuado: Cuándo seleccionar manualmente Single, Proxy o Browser
- Autenticación: Administra tus claves de API
- Gestión de errores: Gestiona errores de forma controlada
- Comprobaciones de sitio: Lee el campo
defensey reproduce una autorización - Por qué una solicitud de Proxy agotó los intentos: Lee
attemptReporty actúa en consecuencia - Límites de tasa: Comprende los límites de solicitudes
- Inicio rápido: Tu primera solicitud en 30 segundos