# Smart Fetch (Auto)

> URL: https://foura.ai/es/docs/guides/smart-fetch
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Le pasas a FourA una URL y una regla `validate` sobre lo que la página real debería contener. FourA hace el resto: recorre una escala según el costo, se detiene en el primer peldaño que devuelve una respuesta aceptada por tus reglas y recuerda qué funcionó por host para que la siguiente llamada al mismo sitio sea económica.

Esta guía explica qué hace auto por debajo, cuándo usarlo y cómo interpretar su respuesta. Para consultar los parámetros, consulta [API Endpoints](https://foura.ai/docs/api/endpoints#smart-fetch-auto).

## La idea

La mayoría de las configuraciones de scraping te obligan a elegir el motor de antemano. Single es el más rápido, Proxy añade rotación, Browser gestiona JavaScript. Si te equivocas, malgastas créditos o te bloquean.

Auto cambia las reglas. Tú declaras el éxito (`validate`), no el método. FourA sube una escala hasta que un peldaño tiene éxito:

1. **Sondeo económico** (single, directamente desde la propia red de FourA)
2. **Browser**, directamente desde la propia red de FourA, con JavaScript y un solver si el sitio presenta un desafío
3. **Proxy rotado single**
4. **Browser a través de proxy** para los objetivos más complejos

Auto se detiene en cuanto un peldaño devuelve una respuesta que tu regla `validate` acepta.

Hay un peldaño que queda fuera de ese orden. Cuando una salida llega al sitio pero este rechaza la URL profunda que solicitaste, auto obtiene la página de entrada del sitio mediante esa misma salida, conserva las cookies que dicha página entrega y vuelve a solicitar tu URL incluyéndolas. Ese es el peldaño `warmup`. Solo se ejecuta en una URL más profunda que la raíz del sitio, solo después de que el intento directo ya haya fallado, y solo puede añadir un resultado, nunca descartar uno.

`forceProxy` tiene el valor predeterminado `true`, por lo que los peldaños 1 y 2 se omiten y el objetivo nunca ve la dirección propia de FourA. La mayoría de las llamadas terminan entonces en el peldaño 3 o en una sesión previa reutilizada. Establece `forceProxy: false` cuando sepas que un objetivo responde mejor a una dirección limpia que a una rotativa, y los peldaños 1 y 2 volverán a activarse.

## Lo que envías

El mínimo es una URL más una subcadena `validate`. Auto reconoce por sí mismo las páginas de desafío comunes, pero sin `validate.data.accept` no puede distinguir entre una página real y una página de comprobación desconocida, o una página que cargó sin tu contenido, por lo que podría devolver cualquiera de ellas como éxito.

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

Ajustes opcionales (consulta la [referencia del endpoint](https://foura.ai/docs/api/endpoints#smart-fetch-auto) para ver todos los detalles):

- `returnSession` (por defecto `true`): devuelve la `{ proxy, cookies, userAgent }` ganadora para que puedas reproducirla.
- `forceProxy` (por defecto `true`): omite los niveles de salida directa. Establece `false` solo si sabes que el sitio responde mejor a una IP limpia que a salidas rotativas.
- `timeout_ms` (por defecto `120000`): presupuesto total para toda la llamada. La escala lo distribuye entre los niveles.
- `ignoreProxies`: IDs de proxy que se deben evitar en cada subintento.
- `followRedirects` (por defecto `5`): cantidad máxima de redirecciones en los niveles económicos.
- `headers`: headers que se envían al sitio, como pares `[name, value]`. Se envían en las requests Single y Proxy, incluida la búsqueda de una salida funcional, y los niveles con navegador no los envían. Tu propio `Cookie` llega al sitio sin cambios, y las cookies de una sesión activa se agregan junto a él solo bajo nombres que no hayas enviado. Cuando una sesión activa incluye un `userAgent`, este reemplaza a tu `User-Agent`. Los headers condicionales como `If-None-Match` y `If-Modified-Since` se excluyen de la búsqueda de salida a menos que tu `validate.status.accept` incluya `304`.
- `exitClass`: `premium` permite que Auto escale a una salida premium una vez que el grupo estándar no pueda acceder a la página; `standard` indica que nunca escala. Requiere un plan que incluya salidas premium. Consulta [exitClass en Smart Fetch](https://foura.ai/docs/api/endpoints#exitclass-on-smart-fetch).

## Qué recibes como respuesta

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

Tres cosas a leer:

- **`status` y `data`**: la respuesta del objetivo. `data` es texto sin importar qué peldaño sirvió la página, por lo que una página JSON llega como texto JSON y tú mismo la parseas. `status` es el estado HTTP del objetivo, no el estado de transporte de tu llamada a FourA. Para los peldaños single y proxy, `headers` es un array por salto. Para los peldaños de navegador, `headers` es un objeto plano.
- **`meta`**: la traza de lo que hizo la escalera, presente en cada respuesta una vez que la escalera ha iniciado. `meta.rung` nombra el paso que entregó la respuesta, `meta.attempts` cuenta los reintentos de subllamadas, `meta.solved` indica si se completó una página de desafío y `meta.credits` es el gasto total de la llamada (el mismo número que el encabezado `X-FourA-Credits`). `meta.attemptsByEngine` y `meta.browserRequests` indican lo que envió la llamada: consulta [Lo que gastó una llamada](#what-a-call-spent). Cuando la solicitud nombró un `exitClass`, `meta.exitClass` indica qué clase de salida entregó.
- **`session`**: la terna `{ proxy, cookies, userAgent }` que descifró el objetivo. Úsala para reproducir contra el mismo host mediante `/api/single/` o `/api/browser/`. Puede faltar un campo: una sesión obtenida mediante una extracción con proxy simple tiene `proxy` pero no `userAgent`, y su lista `cookies` contiene solo las cookies que la página de verificación de un sitio configuró antes de que el sitio sirviera la página, por lo que a menudo está vacía. Una respuesta del sondeo directo económico incluye un `session` solo cuando dicha página de verificación configuró cookies, y luego contiene únicamente `cookies`. Un estado que liste tu `validate.status.accept` y que una salida haya devuelto (como el `404` de una página eliminada) no tiene ningún `session`.

Auto responde con HTTP 200 siempre que la escalera se haya ejecutado, incluso cuando fallaron todos los peldaños. Lee `status` y `error` en el cuerpo para descubrir qué sucedió, no el código de estado de transporte. Un código distinto de 200 de `/api/auto/` significa que la llamada nunca llegó a la escalera: 401 para una clave incorrecta, 400 para un cuerpo que no es JSON válido, un objetivo en una red privada, un objetivo en el propio host de API de FourA o una URL con un espacio sin codificar en su interior, 403 con `X-FourA-Limit: plan_limit_premium` para `exitClass: premium` en un plan sin salidas premium, y 502, 503 o 504 cuando el servicio no pudo aceptar la llamada o se quedó sin tiempo. Auto no ocupa ningún slot en la pasarela, por lo que los límites compartidos de la plataforma no rechazan la llamada en sí: cuando uno de ellos rechaza una llamada realizada por la escalera, la respuesta es HTTP 200 con `status: 429` o `503` y `retryAfter` en el cuerpo. Un campo que no supera la validación también se devuelve como HTTP 200, con `status: 400`. Si se alcanza un límite del plan dentro de la escalera, también se devuelve como HTTP 200, con el rechazo en el cuerpo (consulta [Cuando los límites de tu plan se cruzan con la escalera](#when-your-plans-limits-meet-the-ladder)).

## Reproducir con la sesión

Después de que auto devuelve una sesión, puedes pasar directamente a Single o Browser para páginas de seguimiento en el mismo host. Sin subir una nueva escalera, sin un nuevo sondeo.

```python
import requests

API = "https://eu.api.foura.ai"
KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1) First call: let auto figure it out.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}},
}).json()

session = r.get("session") or {}
proxy = session.get("proxy")
user_agent = session.get("userAgent")

# 2) Follow-up pages: replay through single with the same proxy, UA and cookies.
for sku in ("43", "44", "45"):
    body = {"method": "GET", "url": f"https://example.com/product/{sku}"}
    if proxy:
        body["proxy"] = proxy
    headers = []
    if user_agent:
        headers.append(["User-Agent", user_agent])
    if session.get("cookies"):
        headers.append(["Cookie", "; ".join(f"{c['name']}={c['value']}" for c in session["cookies"])])
    if headers:
        body["headers"] = headers
    r = requests.post(f"{API}/api/single/", headers=H, json=body).json()
    print(sku, r["status"])
```

La sesión solo es tan duradera como el objetivo lo permita. Algunos sitios vinculan la autorización al cookie jar durante horas; otros la rotan cada pocos minutos. Si una repetición vuelve a devolver desafíos, llama a `/api/auto/` una vez más para actualizarla.

## Cuándo usar Auto

| Usa auto | Usa single, proxy o browser manualmente |
|----------|----------------------------------------|
| Te diriges a un nuevo sitio y no sabes qué necesita | Ya conoces el motor que funciona |
| Quieres una sola llamada que gestione el fallback de proxy y browser por ti | Quieres control total sobre los reintentos y timeouts por llamada |
| Aceptas unos segundos de sondeo en la primera llamada | La latencia de la primera llamada importa más que el descubrimiento |
| Quieres una sesión aprendida que puedas repetir de forma económica | Estás optimizando un bucle ajustado en un objetivo que ya sabes que funciona |

Auto no siempre es la opción más económica. Si sabes que un objetivo funciona con `single` + `unblocker`, llamar a Single directamente cuesta 2 créditos con latencia predecible. Auto en el mismo objetivo cuesta lo que gaste su escala, lo cual puede ser más si el sitio requiere escalación.

## Validate le indica a Auto qué significa "éxito"

El parámetro más importante es `validate`. Sin él, auto solo rechaza las páginas de desafío que reconoce, por lo que una página de verificación desconocida o una estructura vacía servida con HTTP 200 pasa como contenido.

Usa `validate.data.accept` con una subcadena que solo contenga la página real:

```json
{
  "validate": {
    "data": {
      "accept": ["sku-42-add-to-cart", "Customer reviews"]
    }
  }
}
```

Para las API de JSON, acepta un nombre de campo que esperes:

```json
{
  "validate": {
    "data": { "accept": ["\"products\":["] },
    "status": { "accept": [200] }
  }
}
```

Para sitios que legítimamente devuelven un código distinto de 200 (una restricción por país que quieres ignorar, un `404` o `410` de una página eliminada), permítelos mediante `validate.status.accept`:

```json
{
  "validate": {
    "status": { "accept": [200, 451] }
  }
}
```

Auto devuelve un estado que incluyas en `validate.status.accept` tan pronto como una salida lo retorne y cumpla el resto de tu regla. Cuatro estados son la excepción: `202`, `403`, `429` y `503`. Auto los interpreta como que el sitio está verificando quién pregunta, por lo que una salida que devuelva uno de ellos no termina la búsqueda y la escala continúa subiendo.

Sin `validate`, auto recurre por defecto a "HTTP 200 = éxito" para cualquier página que no reconozca como un desafío, por lo que no detectará una página de verificación desconocida que un sitio devuelva con un 200.

## Cómo leer `meta.rung` para entender qué sucedió

`meta.rung` es la señal de depuración más útil. Valores:

- `probe`: resuelto en una request directa económica. La ruta más barata.
- `proxy`: requirió rotación de proxy para completarse.
- `browser`: necesitó un renderizado completo en navegador, posiblemente resolviendo un desafío.
- `cache`: reutilizó una sesión activa de una llamada auto previa. La ruta más económica en llamadas repetidas.
- `warmup`: el sitio sirvió su página de entrada pero restringió la URL profunda, por lo que auto obtuvo primero la página de entrada, conservó las cookies devueltas y volvió a realizar la petición con ellas. La sesión almacenada a partir de este peldaño no está vinculada a una sola salida, por lo que las llamadas siguientes llegan a los peldaños económicos.
- `fail`: ningún peldaño produjo una respuesta aceptada por tus reglas.

`meta.solved: true` indica que se encontró y completó una página de desafío durante la llamada. `meta.attempts` es la cantidad de intentos de subllamadas antes del éxito. Para conocer los detalles detrás de esto, consulta el campo `defense` que devuelven los peldaños individuales y de proxy: consulta [Verificaciones del sitio](https://foura.ai/docs/api/site-checks).

Si un sitio sigue terminando en `browser` cuando esperabas `probe`, evalúa si una regla `validate` más estricta (o menos estricta) permitiría que un peldaño más económico sea válido. Recuerda que `forceProxy` tiene el valor predeterminado `true`, por lo que el sondeo de salida directa se omite a menos que lo desactives.

## Qué consumió una llamada

`meta.attemptsByEngine` cuenta las requests que la llamada envió a cada motor, las mismas requests que el panel de intentos de Auto muestra en tu [Visión general](https://foura.ai/docs/dashboard/overview). `meta.browserRequests` cuenta aquellas que consumieron un cupo de tu límite diario de navegador.

```json
"meta": {
  "rung": "browser",
  "solved": true,
  "attempts": 7,
  "credits": 47,
  "attemptsByEngine": {"single": 1, "proxy": 4, "browser": 3},
  "browserRequests": 2
}
```

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `meta.attemptsByEngine` | object | Requests enviadas a `single`, `proxy` y `browser`. Una browser request que tu plan haya rechazado cuenta aquí, ya que fue enviada. |
| `meta.browserRequests` | number | Browser requests que consumieron un slot de tu cuota diaria. Una browser request que tu plan haya rechazado no consume nada. |

`meta.attempts` cuenta los pasos de la escala, por lo que no siempre coincide con la suma de `meta.attemptsByEngine`. Un paso puede enviar una Single request y luego una Proxy request, y un paso cuyo navegador ya está cerrado por el día no envía nada.

Tu recuento acumulado del día viaja en los headers `X-FourA-Browser-Used-Today` y `X-FourA-Browser-Limit-Per-Day`: consulta [Response Headers](https://foura.ai/docs/api/response-headers).

## Errores y Casos Límite

Cuando auto falla, la response incluye `status` (generalmente el status del último peldaño fallido) y un string `error`:

```json
{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "attemptReport": {
    "total": 7,
    "noResponse": 5,
    "defense": 2,
    "contentRejected": 0,
    "statusRejected": 0,
    "other": 0,
    "vendors": ["datadome"],
    "summary": "7 attempt(s): 5 got no answer from the site; 2 refused by the site (datadome)"
  },
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47,
    "attemptsByEngine": {"single": 0, "proxy": 4, "browser": 3},
    "browserRequests": 3
  }
}
```

`status` es la respuesta del sitio en el último intento que Auto rechazó, como un `403`. Cuando ningún intento obtuvo respuesta alguna del sitio, suele ser `502` o `504`, y `error` indica si no se encontró una salida operativa o si se agotó el presupuesto de `timeout_ms`. `status: 0` solo significa que el nombre de host del objetivo no se resolvió, y esa respuesta no tiene `meta` porque el ladder nunca comenzó.

Auto también se detiene antes de tiempo cuando su navegador encuentra continuamente una comprobación que no puede completar. Tras dos salidas que rechazan el navegador de esa manera y una búsqueda vacía de una salida cuya solicitud simple pase tu regla `validate`, o tras tres salidas de este tipo, la llamada finaliza. `status` contiene la última respuesta del sitio y `error` comienza con `the browser was refused by`, seguido del nombre del sistema de comprobación.

Auto también se detiene cuando el propio sitio indica que la página no existe. Cuando dos salidas devuelven el mismo `404` o `410` y tus reglas no lo aceptan, la llamada termina con ese `status`, y `error` comienza con `the site answered`. Si una página eliminada es una respuesta que buscas, incluye `404` o `410` en `validate.status.accept`: Auto la devolverá como entregada en cuanto una salida la recupere.

Después de que cuatro llamadas consecutivas de Auto con tu API key terminen sin la página porque el sitio siguió rechazando los intentos, Auto deja de intentar acceder a ese sitio con tu clave durante 120 segundos. Una llamada dentro de ese intervalo responde de inmediato con `status: 503`, `error: "target temporarily unservable, retry later"` y `retryAfter` en segundos, y no tiene coste. Se contabiliza por API key: otras claves que llamen al mismo sitio no se ven afectadas, y cualquier llamada que obtenga la página reinicia el contador. Una llamada con `exitClass: premium` no se ve interrumpida por este bloqueo.

Revisa `attemptReport`, `meta.attemptsByEngine` y `meta.credits` para ver dónde se consumió el presupuesto. Si `meta.attempts` es alto y `meta.rung` es `fail` tras el nivel del navegador, es posible que el objetivo requiera un `timeout_ms` más largo, una regla `validate` más estricta o simplemente no sea accesible mediante proxies rotativos en este momento.

### Por qué falló una llamada de Auto

Cada respuesta fallida de un ladder ejecutado incluye un `attemptReport`. Registra las solicitudes del motor devueltas sin la página, cada una contada una sola vez, según lo que encontraron.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `total` | integer | Requests que regresaron sin la página. Como máximo la suma de `meta.attemptsByEngine`, ya que una request de browser que tu plan rechazó nunca intentó acceder al destino. |
| `noResponse` | integer | No se obtuvo respuesta del sitio |
| `defense` | integer | El sitio rechazó la request: se reconoció una verificación de bots, la página era un challenge o el sitio respondió con 401, 403, 429 o 503 |
| `contentRejected` | integer | La página se descargó y solo tu regla `validate` la rechazó |
| `statusRejected` | integer | El sitio respondió con un status que tu request no acepta, como 404 para una página eliminada |
| `other` | integer | Falló por otra razón, como un error de servidor |
| `vendors` | string[] | Proveedores de verificación de bots reconocidos en los rechazos que encontró la llamada |
| `summary` | string | Una sola frase armada a partir de los conteos, segura para registrar en logs. Indica el HTTP status con el que respondió el sitio cuando no se reconoció ningún proveedor, y señala cuándo se agotó tu cupo diario de browser, por lo que no se pudo abrir ningún browser. |

Los campos coinciden con el reporte de una [llamada fallida a Proxy](https://foura.ai/docs/troubleshooting/proxy-attempt-report), sin `profilesTried`. Dos aspectos difieren. Proxy cuenta cada salida que intentó, hasta el `maxTries` que configuraste, y Auto cuenta sus propias requests. Auto también lee la página y su status, por lo que un rechazo cuenta en `defense` incluso cuando no se reconoció ningún proveedor. Un conteo bajo `contentRejected` es el que puedes solucionar tú mismo: la página regresó y tu regla no coincidió con ella.

### Cuando los límites de tu plan se encuentran con la escala

Las subllamadas de Auto son requests comunes de Single, Proxy y Browser bajo tu key, por lo que los [límites de tu plan](https://foura.ai/docs/api/rate-limits) se aplican a ellas. La escala lee el código `X-FourA-Limit` ante un rechazo y trata los dos tipos de forma diferente.

**Un peldaño cerrado deja utilizable el resto de la escala.** `plan_limit_browser_daily` (se agotaron tus requests de Browser para el día) y `plan_limit_concurrency` (ese endpoint ya tiene tantas de tus requests ejecutándose como permite el plan) cierran un peldaño. Auto sigue operando en los demás peldaños, por lo que aún obtienes una página siempre que una salida rotativa o una sesión activa sirva el contenido, y las salidas que intentó no se consideran responsables de un rechazo originado en tu propio plan. Nada se bloquea y ninguna sesión se descarta.

**Una cuenta sin saldo detiene la escala.** `plan_limit_credits`, `plan_limit_bandwidth`, `plan_limit_rate`, `plan_limit_feature` y `plan_limit_premium` no pueden resolverse con otro peldaño, por lo que Auto responde de inmediato en lugar de gastar más de tus créditos comprobándolo. El rechazo se devuelve en el body con el status de la subllamada y el mismo campo `reason` que utilizan los endpoints directos:

```json
{
  "status": 429,
  "error": "Credit limit reached: 300,000 of 300,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 300000,
  "hard_stop": 300000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}
```

Llega el cuerpo completo de rechazo de la subllamada, más `status`, `attemptReport` y `meta`. Lee `status` desde el cuerpo y no desde el estado de transporte: auto todavía responde HTTP 200 aquí, porque la escala se ejecutó. Un rechazo `plan_limit_feature` o `plan_limit_premium` llega de la misma manera con `status: 403`. Una subllamada rechazada no gasta nada, por lo que `meta.credits` solo cuenta los niveles que llegaron hasta el destino.

Una llamada auto puede ocupar varios slots mientras su escala avanza, por lo que un lote paralelo de llamadas auto alcanza un límite de concurrencia con menos llamadas de las que esperarías. [Ejecutar solicitudes en paralelo](https://foura.ai/docs/how-to/run-requests-in-parallel) explica cómo dimensionar el lote.

## Lo que Auto no hace

- No cambia las restricciones legales. Si un sitio rechaza cada salida a la que FourA puede acceder, auto devuelve ese rechazo.
- No almacena contenido en caché. Cada llamada sigue consultando el destino. La "sesión activa" corresponde al proxy y a las cookies, no a la response.
- Es una sola fila en el [Registro de actividad](https://foura.ai/docs/dashboard/activity-log), bajo el request id que recibiste, con la suma de los créditos de sus subllamadas. Ábrelo y las subllamadas Single / Proxy / Browser que auto realizó en tu nombre aparecerán como sus intentos, cada una con su propio resultado. Cuentan para tus límites de Single, Proxy y Browser, nunca para tu recuento de requests o tasa de éxito.

## Relacionado

- [Endpoints de la API](https://foura.ai/docs/api/endpoints#smart-fetch-auto): Referencia completa de parámetros
- [Elegir el endpoint correcto](https://foura.ai/docs/guides/choosing-task-type): Cuándo elegir auto frente a single, proxy o browser
- [Resultados de solicitudes](https://foura.ai/docs/api/outcomes): Qué resultados son facturables
- [Sitios protegidos](https://foura.ai/docs/guides/protected-sites): Qué hace FourA en sitios que verifican quién consulta
- [Comprobaciones del sitio](https://foura.ai/docs/api/site-checks): El campo `defense` detrás de `meta.solved`
- [Recetas MCP](https://foura.ai/docs/mcp/recipes): Los mismos patrones como llamadas a herramientas MCP
- [Límites de tasa](https://foura.ai/docs/api/rate-limits): Los límites del plan con los que se miden las subllamadas de auto
