# Referencia de endpoints de la API

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

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

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

Crea y administra claves de API en el [Dashboard](https://foura.ai/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](https://foura.ai/docs/api/outcomes) 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](https://foura.ai/docs/dashboard/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](https://foura.ai/docs/dashboard/playground). Inclúyelo cuando contactes a soporte para identificar la request en segundos.

```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
...
```

Consulta [Response Headers](https://foura.ai/docs/api/response-headers) para ver la lista completa y consejos de uso.

## Endpoints

> **¿Usas estos endpoints mediante MCP?** El servidor [`@fouradata/mcp`](https://foura.ai/docs/mcp/server) envuelve 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ón `offload_large` para gestionar respuestas grandes optimizando tokens. Las diferencias: `foura_browser` no tiene el campo `lean`, y `foura_proxy` aún no admite los campos de [ubicación de salida](#exit-location).

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](https://foura.ai/docs/guides/choosing-task-type) y la [guía de Smart Fetch](https://foura.ai/docs/guides/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.

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

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`](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/`

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](#exitclass). `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](#exitclass-on-smart-fetch). |

### Response

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

| 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](https://foura.ai/docs/guides/smart-fetch). |

### Ejemplo

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

### 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](https://foura.ai/docs/dashboard/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.accept` con 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 `404` o `410` y tu `validate` no lo acepta, la llamada termina con ese `status` y un `error` que comienza con `the site answered`. Incluye el estado en `validate.status.accept` y Auto entrega la primera respuesta con ese estado que supere el resto de tu `validate`. Lo mismo aplica para cualquier otro estado que listes allí, excepto `403`, `429`, `503` y `202`, que los sitios también envían junto con una página de challenge.
- `timeout_ms` limita 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](#exitclass): 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](#pinning-an-exit). |
| `browser` | string | No | Chrome | Navegador a presentar: Chrome, Edge, Safari, Firefox o Tor. Consulta [Perfiles de navegador](#browser-profiles). |
| `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.

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

Reglas:

- La selección requiere `unblocker` (activado por defecto). Con `unblocker` desactivado 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 `profile` desconocido devuelve `unknown profile '<id>'`. 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 requiere API key:

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

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

```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
}
```

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:

```json
{
  "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](https://foura.ai/docs/api/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](#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:

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

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

Response:

```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
}
```

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

```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
}
```

| 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](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### 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.

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

```json
{
  "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](https://foura.ai/docs/api/response-headers#x-foura-exit-class)).

**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](https://foura.ai/docs/dashboard/quota) 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](#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](https://foura.ai/docs/api/rate-limits#plan-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:

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

```json
{
  "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](#pinning-an-exit).

Reglas:

- Cualquiera de `exitState`, `exitCity`, `exitAsn`, `exitOs` y `exitLifetimeMin` enví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`, `exitCity` y `exitAsn` existen dentro de un solo país, por lo que necesitan exactamente un país en `exitCountries`. `exitOs` y `exitLifetimeMin` admiten varios: la salida toma uno de ellos, y `exitCountry` en la response indica cuál.
- `exitState`, `exitCity`, `exitAsn` y `exitOs` requieren 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](#exitcountries-scoping), con el error `No premium exit answered for this request` y `code: no_eligible_proxy`. `details.exitCountries` aparece cuando enviaste una lista de países.

Los términos coinciden con los que acepta el [puerto proxy](https://foura.ai/docs/api/proxy-port) 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 `exitCountries` en [Proxy Request](#exit-location).
- Solo el reloj se ajusta al país. `Accept-Language` y 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](https://foura.ai/docs/api/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

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

| 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](https://foura.ai/docs/api/site-checks). |
| `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](https://foura.ai/docs/dashboard/quota) 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)](https://foura.ai/docs/guides/smart-fetch): Cuándo dejar que FourA elija la ruta por ti
- [Elegir el endpoint adecuado](https://foura.ai/docs/guides/choosing-task-type): Cuándo seleccionar manualmente Single, Proxy o Browser
- [Autenticación](https://foura.ai/docs/getting-started/authentication): Administra tus claves de API
- [Gestión de errores](https://foura.ai/docs/api/errors): Gestiona errores de forma controlada
- [Comprobaciones de sitio](https://foura.ai/docs/api/site-checks): Lee el campo `defense` y reproduce una autorización
- [Por qué una solicitud de Proxy agotó los intentos](https://foura.ai/docs/troubleshooting/proxy-attempt-report): Lee `attemptReport` y actúa en consecuencia
- [Límites de tasa](https://foura.ai/docs/api/rate-limits): Comprende los límites de solicitudes
- [Inicio rápido](https://foura.ai/docs/getting-started/quick-start): Tu primera solicitud en 30 segundos
