Docs › Referencia API › Referencia de endpoints de la API

Referencia de endpoints de la API

Una referencia de 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 gestiona API keys en el Dashboard. Las keys usan el prefijo pk_live_.

Headers de respuesta

Cada response de /api/* incluye dos headers de correlación:

Header Valor Descripción
X-FourA-Request-Id UUID ID único asignado a la request. Se devuelve en cada response, incluyendo 4xx y 5xx. Regístralo de tu lado.
X-FourA-Credits entero Créditos gastados en esta request. Se devuelve en caso de éxito o de fallo (el trabajo se realizó de todos modos). Consulta Request Outcomes para saber qué resultados son facturables.

El mismo ID de la request identifica la request y la vista previa del payload de la response en el Activity Log del Dashboard (se conserva 24 horas, las últimas 200 por key), por lo que puedes buscar la request exacta más tarde y volver a ejecutarla desde Activity directamente en el Playground. Inclúyelo cuando te comuniques con el equipo de soporte y localizará 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 los Response Headers para ver la lista completa y consejos de uso.

Endpoints

¿Usas estos endpoints a través de MCP? El @fouradata/mcp server envuelve los cuatro endpoints como herramientas MCP nativas (foura_auto, foura_single, foura_proxy, foura_browser) con los mismos formatos de entrada, más una opción offload_large para el manejo de large-responses optimizado para tokens.

FourA proporciona cuatro request endpoints, cada uno optimizado para un escenario diferente:

Endpoint Ideal para
POST /auto/ Búsqueda inteligente. Pasas una URL, FourA elige la ruta más barata que funcione (directa, proxy rotativo o navegador) y recuerda qué funciona por host.
POST /single/ Request HTTP rápidos, páginas estáticas, APIs
POST /proxy/ Sitios protegidos con rotación automática de proxy, alcance de país visible para el destino opcional
POST /browser/ Páginas renderizadas con JavaScript, SPAs
GET /profiles El catálogo de perfiles de navegador para single y proxy. Público, sin API key.

Para ver una guía detallada sobre cuándo elegir cada uno, consulta Choosing the Right Endpoint y la guía de Smart Fetch.

Restricciones de la URL de destino

Los destinos que se resuelven en rangos de direcciones IP privados, loopback o reservados (RFC 5735, RFC 6598, bloques reservados de IPv6) se rechazan con un error 400 antes de que el request salga de FourA. Solo se reenvían los nombres de host e IPs públicos.

{ "error": "Target <ip> resolves to a private/reserved IP" }

Smart Fetch (Auto)

POST /api/auto/

Pasas una URL y reglas opcionales de validate. FourA recorre una escalera sensible a los costos (sonda directa económica, proxy rotativo, navegador completo) y se detiene en el primer escalón que devuelve un response que tus reglas aceptan. En llamadas repetidas al mismo host, se reproduce una sesión cálida en su lugar, por lo que el segundo intento es económico.

No ajustas reintentos, tamaños de pools ni recuentos de proxy. FourA los aprende por cada host.

Cuerpo del request

Parámetro Tipo Requerido Por defecto Descripción
url string Sí - URL de destino
method string No "GET" Método HTTP
headers [string, string][] No - Headers personalizados como pares [nombre, valor]
data any No - Cuerpo del request para requests que no son GET
validate object No - Criterios de éxito, con la misma estructura que validate de Single Request (ver abajo). Indícale a auto cómo se ve una página real para que pueda distinguir el contenido de una página de desafío.
returnSession boolean No true Incluye la sesión ganadora (proxy, cookies, userAgent) en el response para que puedas reproducirla a través de /api/single/ o /api/browser/.
forceProxy boolean No true Siempre enruta a través de un proxy rotativo. Configura 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 proxy).
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 a evitar en cada subintento. Usa los IDs devueltos por responses previas de /api/auto/ o /api/proxy/.
followRedirects integer No 5 Máximo de redirecciones a seguir en los escalones económicos. 0 para deshabilitar. Máximo 20.

Response

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}
Campo Tipo Descripción
status number Estado HTTP del objetivo.
data string u object Cuerpo de la response.
headers array u object Headers de la response del objetivo. Los niveles single y proxy devuelven un array de objetos header por salto; los niveles de navegador devuelven un objeto plano.
meta.rung string Qué nivel de la escalera entregó la response. Uno de: probe (request directa económica), proxy (proxy rotativo), browser (renderizado de navegador completo), cache (sesión cálida reproducida), o fail (ningún nivel produjo una response aceptada).
meta.solved boolean Indica si se resolvió un desafío de bot durante esta llamada.
meta.attempts number Subintentos realizados antes del éxito.
meta.credits number Créditos totales gastados en esta llamada. Coincide con X-FourA-Credits.
session.proxy string ID codificado del proxy que entregó la response. Reutilízalo en una request Single o de navegador. Presente cuando returnSession es true.
session.cookies array Cookies del intento ganador. Presente cuando returnSession es true.
session.userAgent string User-Agent utilizado en el intento ganador. Presente cuando returnSession es true.
error string Mensaje de error si la llamada falló.

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 internamente a Single, Proxy o Browser y reenvía tu clave de API a cada subllamada. Cada subllamada aparece en tu registro de actividad; la llamada externa /api/auto/ no añade una fila facturable independiente.
  • Pasa validate.data.accept con una subcadena que solo contenga la página real. Sin ella, auto no puede distinguir un 200 real de un desafío intersticial devuelto con el estado 200.
  • timeout_ms limita toda la llamada. Un primer intento en frío a un sitio protegido puede tardar decenas de segundos; las sesiones cálidas reutilizadas normalmente terminan en menos de un segundo.

Solicitud única

POST /api/single/

Envía una solicitud HTTP con características de red realistas similares a las de un navegador, sin arrancar un navegador real. Este es el endpoint más rápido.

Cuerpo de la solicitud

Parámetro Tipo Requerido Predeterminado 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 lugar de la URL para insertar la marca de tiempo actual y evitar 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. Establece false para enviar una firma de cliente simple.
timeout_ms number No 15000 Timeout general 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 caché DNS en segundos (máx: 240)
followRedirects number No desactivado Máximo de redirecciones a seguir (0-20). Omítelo para desactivar.
tryJsonData boolean No false Analiza el body de la respuesta como JSON si es posible
returnBuffer boolean No false Devuelve un buffer en bruto en lugar de un string decodificado
data any No - Body de la solicitud (string u objeto, se serializa automáticamente a JSON)
proxy string No - ID del proxy de una respuesta anterior, para fijar la misma salida. Devuelve el string opaco textualmente. Una dirección de proxy en bruto se rechaza con 400 Invalid proxy format.
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 más reciente Versión del navegador a presentar, como aparece en el catálogo. La coincidencia más reciente gana cuando encajan varias.
profile string No - ID exacto del perfil de 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 solicitud presenta el último Google Chrome. Algunos objetivos aceptan un navegador y rechazan otro, por lo que browser, os y version reducen un catálogo de perfiles medidos, y profile selecciona uno por ID.

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

Reglas:

  • La selección requiere unblocker (activado por defecto). Con el desbloqueador apagado no se envían headers del navegador, por lo que la request es rechazada en lugar de aplicarse a medias.
  • Cuando varios perfiles coinciden, gana la versión más reciente.
  • Una combinación que el catálogo no puede presentar devuelve un error que indica lo que está disponible. La request nunca se envía como un navegador diferente.
  • Los mismos cuatro campos están disponibles dentro del objeto request de POST /proxy/.

GET /api/profiles devuelve el catálogo completo y no necesita API key:

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

osFamily es el valor por el cual 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 se cumple una condición fail, la request se considera fallida. Si se establecen condiciones accept, solo las response que coincidan se consideran 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 a aceptar
validate.status.fail number[] Códigos de estado HTTP a rechazar
validate.headers.accept object Pares clave-valor de header que deben estar presentes
validate.headers.fail object Pares clave-valor de header que provocan un error
validate.data.accept string[] Cadenas que deben aparecer en el response body
validate.data.fail string[] Cadenas en el response body que provocan 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
  }'

Respuesta:

{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "nginx", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342,
  "proxy": "A1B2C3"
}

Cuando el objetivo ejecuta una verificación de bots en el camino hacia el body, la respuesta también incluye un objeto defense que indica el proveedor y si la verificación fue superada:

{
  "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 número 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 cadenas.
data cadena/objeto Cuerpo de la respuesta (JSON si tryJsonData es true)
total_time número Tiempo total de la request en segundos
proxy cadena ID codificado del proxy por el que pasó la request (solo cuando se proporcionó un proxy en la request). Reutilízalo en una llamada posterior para fijar la misma salida.
defense objeto Presente solo cuando el destino ejecutó una comprobación de bots en esta request. defense.solved indica si la comprobación se superó. Consulta Defensas Anti-Bot para ver cada campo y la lista completa de proveedores.
error cadena 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, puedes limitar la selección a un conjunto de países de salida visibles para el destino.

Cuerpo de la Request

Parámetro Tipo Obligatorio Por defecto Descripción
request objeto Sí - Un único cuerpo de request (mismos campos que Single Request arriba)
timeout_ms número No 45000 Tiempo de espera general para todos los intentos en ms (máx: 120000)
maxTries número No 5 Máximos intentos de rotación de proxy (máx: 90)
ignoreProxies cadena[] No - IDs de proxy a excluir de la rotación (usa los IDs devueltos en respuestas anteriores)
exitCountries cadena[] No - Lista de permisos estricta de códigos de país de dos letras visibles para el destino (ej. ["CZ", "GB"]). Los valores se recortan, se pasan a mayúsculas y se eliminan duplicados. Los proxies con salidas desconocidas se excluyen y la request nunca recurre a un país no solicitado.

Scoping de exitCountries

La selección utiliza los últimos metadatos de países visibles para el destino disponibles, que normalmente se actualizan en unos diez minutos. No es una búsqueda de geolocalización en vivo durante la request. No deduzcas el país servidor de la dirección del host del proxy.

Si el pool actual no tiene coincidencias con los países solicitados, la respuesta devuelve HTTP 200 con un sobre 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 alcance solicitado y vuelve a intentarlo 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"
    }
  }'

Respuesta:

{
  "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. Reútilízalo en una request de tipo Single o Browser pasándolo como el campo proxy, u omítelo en la siguiente request de Proxy a través de ignoreProxies.
exitCountry string Código de país de dos letras visible para el destino del proxy que atendió la request. Solo está presente cuando la request establece exitCountries. Verifica siempre que sea uno de los códigos que solicitaste antes de confiar en la response.
total number Duración externa real en segundos (float). Incluye la selección de proxy, los reintentos y el intento exitoso. total_time es solo la request interna; total siempre es >= total_time.
error string Mensaje de error si la request falló. En un fallo de alcance (scope miss), code es no_eligible_proxy y details.exitCountries devuelve el scope normalizado.

También se incluyen todos los campos de response de Single Request, defense entre ellos: un intento de proxy que encontró un control de bots lo reporta de la misma manera que Single.

Browser Request

POST /api/browser/

Abre tu URL en una instancia del navegador Chrome. La página se carga, JavaScript se ejecuta y obtienes el HTML completamente renderizado más el cookie jar.

Cuerpo de la request

Parámetro Tipo Requerido Por defecto Descripción
url string Sí - URL de destino
headers object No - Headers personalizados como pares clave-valor
cookies array No - Cookies a establecer: [{name, value, domain?}]
userAgent string No - Cadena de User-Agent personalizada
unblocker boolean No true Resuelve automáticamente los desafíos comunes de bots (Cloudflare clearance, accesos similares) durante la carga de la página. Activado por defecto. Establece false para renderizar lo que devuelva la página, incluida una página de desafío, sin resolverla.
proxy string No - ID del proxy de una response anterior, para fijar la misma salida. Pasa la cadena opaca de vuelta tal cual. Una dirección de proxy directa es rechazada con 400 Invalid proxy format.
timeout_ms number No 30000 Tiempo de espera de carga de la página en ms (máx: 120000)
checkStatus number No - Estado HTTP esperado (la request falla si es diferente)
checkText string No - Texto que debe aparecer en la página renderizada

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

Respuesta:

{
  "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"]},
  "proxy": "A1B2C3"
}
Campo Tipo Descripción
status número Código de estado HTTP del objetivo
headers objeto Encabezados de respuesta
body string u objeto Contenido de la página completamente renderizado. String HTML cuando el content-type es HTML; objeto cuando la página devolvió JSON y se analizó automáticamente.
cookies array Objetos de cookie completos de la página. Cada cookie incluye name, value, domain, path, expires, httpOnly, secure, sameSite, y otras propiedades de cookie.
userAgent string User-Agent del navegador utilizado
defenseSolved booleano true si se encontró una defensa contra bots y se superó genuinamente en esta llamada. Ausente en caso contrario. Determina el costo de 15 o 30 créditos.
defenses objeto present enumera cada proveedor reconocido durante la carga de la página, cleared enumera aquellos cuya autorización mantiene la página final. Un proveedor puede aparecer en present y nunca en cleared. Consulta Defensas Anti-Bot.
proxy string ID codificado del proxy por el que pasó la solicitud (solo cuando se proporcionó un proxy en la solicitud). Reutilízalo en llamadas de seguimiento para mantener la misma salida.
error string Mensaje de error si la solicitud falló

Códigos de estado HTTP

Código Significado
200 Solicitud completada (revisa el status interno para ver la respuesta del objetivo)
400 Cuerpo de solicitud inválido, parámetros o IP objetivo en un rango privado o reservado
401 Clave de API faltante o inválida
429 Límite de tasa excedido
500 Error interno del servidor
502 Upstream unavailable. FourA alcanzó su motor pero la respuesta era inutilizable. Reintenta.
503 Servicio deshabilitado temporalmente o a capacidad máxima, o Backend service unavailable mientras un motor se reinicia
504 Upstream timeout. El motor no terminó dentro del tiempo asignado para esta solicitud. Aumenta timeout_ms o reintenta.

Próximos pasos

Actualizado: 12 de agosto de 2026
Errores de la API →