Docs › Guías › Smart Fetch (Auto)

Smart Fetch (Auto)

Le pasas a FourA una URL y una regla validate sobre lo que debe contener la página real. FourA hace el resto: recorre una escala consciente de los costos, se detiene en el primer peldaño que devuelve una response que tus reglas aceptan y recuerda lo que funcionó por host para que la próxima llamada en el mismo sitio sea económica.

Esta guía explica qué hace auto internamente, cuándo usarlo y cómo leer su response. Para la referencia de parámetros, consulta API Endpoints.

La idea

La mayoría de las configuraciones de scraping te obligan a elegir el motor por adelantado. Single es el más rápido, proxy añade rotación, browser maneja JavaScript. Si adivinas mal, desperdicias créditos o te bloquean.

Auto le da la vuelta. 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. Single con proxy rotativo
  3. Browser, con JavaScript y un solucionador si el sitio presenta desafíos
  4. Browser a través de proxy para los objetivos más difíciles

Auto se detiene tan pronto como un peldaño devuelve una response que tu regla validate acepta.

forceProxy tiene como valor predeterminado true, por lo que el peldaño 1 se omite y el objetivo nunca ve la propia dirección de FourA. La mayoría de las llamadas terminan entonces en el peldaño 2, o en una sesión cálida reproducida. Establece forceProxy: false cuando sepas que un objetivo trata mejor a una dirección limpia que a una rotativa, y el peldaño 1 regresa.

Qué envías

El mínimo es una URL más una subcadena validate. Sin validate.data.accept, auto no puede distinguir una página real de un intersticial de desafío devuelto con HTTP 200, y puede devolver el desafío como éxito.

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 para ver todos los detalles):

  • returnSession (por defecto true): devuelve el ganador { proxy, cookies, userAgent } para que puedas repetirlo.
  • forceProxy (por defecto true): omite los niveles de salida directa. Usa false solo si sabes que el sitio acepta mejor una IP limpia que los proxies rotativos gratuitos.
  • timeout_ms (por defecto 120000): presupuesto total para toda la llamada. La escalera lo distribuye entre los niveles.
  • ignoreProxies: IDs de proxy a evitar en cada subintento.
  • followRedirects (por defecto 5): redirecciones máximas en los niveles baratos.

Qué obtienes como respuesta

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

Tres cosas para leer:

  • status y data: la misma estructura que devolvió el motor subyacente. status es el estado HTTP del destino, 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 browser, headers es un objeto plano.
  • meta: la traza de lo que hizo el ladder, presente en cada response. meta.rung nombra el paso que entregó el response, meta.attempts cuenta los intentos de subllamadas, meta.solved indica si se resolvió un desafío de bot y meta.credits es el gasto total de la llamada (el mismo número que el header X-FourA-Credits).
  • session: la tripleta { proxy, cookies, userAgent } que logró entrar al destino. Úsala para repetir la petición contra el mismo host mediante /api/single/ o /api/browser/.

Auto responde con HTTP 200 siempre que el ladder se haya ejecutado, incluso cuando fallaron todos los peldaños. Lee status y error en el body para averiguar qué pasó, no el código de estado del transporte. Un valor distinto a 200 de /api/auto/ significa que FourA rechazó la llamada antes de que iniciara el ladder: 401 por una clave incorrecta, 400 por un body incorrecto o un destino privado, 429 o 503 por los rate limits.

Repetir peticiones con la sesión

Después de que auto devuelve una sesión, puedes pasar directamente a Single o Browser para las páginas de seguimiento en el mismo host. Sin nuevos ascensos en el ladder, sin nuevas pruebas.

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["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# 2) Follow-up pages: replay through single with the same proxy + UA.
for sku in ("43", "44", "45"):
    r = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, r["status"])

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

Cuándo usar Auto

Usar auto Usar single, proxy o browser manualmente
Apuntas a un sitio nuevo y no sabes qué necesita Ya conoces el motor que funciona
Quieres una llamada que maneje las alternativas direct, proxy y browser por ti Quieres control total sobre los reintentos y tiempos de espera por llamada
No te importa pagar unos segundos de prueba en la primera llamada La latencia de la primera llamada importa más que el descubrimiento
Quieres una sesión aprendida que puedas repetir a bajo costo Estás optimizando un bucle ajustado en un objetivo conocido

Auto no siempre es la opción más barata. 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 escalera, lo cual puede ser más si el sitio requiere escalamiento.

Validate le dice a Auto qué significa "éxito"

El parámetro más importante es validate. Sin él, auto no puede distinguir una página 200 real de un desafío intersticial 200 disfrazado de contenido.

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

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

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

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

Para sitios que devuelven estados distintos a 200 de forma legítima (bloqueos geográficos que quieres ignorar, códigos 403 intencionales en endpoints sin sesión iniciada), permítelos a través de validate.status.accept:

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

Sin validate, auto recurre a "HTTP 200 = success" y no detectará un desafío intersticial de Cloudflare que el WAF devuelva con un 200.

Leer meta.rung para entender qué ocurrió

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

  • probe: resuelto en un request directo económico. La ruta más barata.
  • proxy: necesitó rotación de proxy para pasar.
  • browser: necesitó un renderizado completo en el navegador, posiblemente con la resolución de un desafío.
  • cache: reprodujo una sesión activa de una llamada auto anterior. La ruta más barata en llamadas repetidas.
  • fail: ningún peldaño produjo un response que tus reglas aceptaran.

meta.solved: true significa que se detectó y superó un desafío de bot durante la llamada. meta.attempts es el recuento de intentos de sub-llamadas antes del éxito. Para conocer los detalles del proveedor detrás de una resolución, lee el campo defense que devuelven los peldaños single y proxy: consulta Defensas Anti-Bot.

Si un sitio sigue terminando en browser cuando esperabas probe, considera si una regla validate más estricta (o una menos estricta) permitiría pasar un peldaño más barato. Recuerda que forceProxy tiene como valor predeterminado true, por lo que la prueba de salida directa se omite a menos que la desactives.

Errores y casos extremos

Cuando auto falla, el response incluye status (generalmente el estado del último peldaño fallido) y una cadena error:

{
  "status": 0,
  "error": "all attempts failed",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status: 0 significa que ningún nivel produjo un response en absoluto (cada intento excedió el tiempo de espera o fue rechazado). Un status distinto de cero más error significa que el último intento obtuvo un response, pero auto lo rechazó (validación u otro motivo).

Revisa meta.attempts y meta.credits para ver en qué se gastó el presupuesto. Si meta.attempts es alto y meta.rung es fail después del nivel del navegador, es posible que el objetivo necesite un timeout_ms más largo, una regla validate más estricta, o simplemente no sea accesible a través de rotating proxies en este momento.

Lo que Auto no hace

  • No elude restricciones legales. Si un sitio está bloqueado por región y rechaza cada salida a la que FourA puede acceder, auto devuelve el bloqueo.
  • No almacena contenido en caché. Cada llamada sigue llegando al objetivo. La "warm session" es el proxy y las cookies, no el response.
  • No escribe en el Activity Log como una fila separada de las sub-llamadas. Las sub-llamadas Single / Proxy / Browser que auto hace en tu nombre aparecen en Activity; la llamada /api/auto/ externa es un coordinador.

Relacionado

Actualizado: 12 de agosto de 2026
← Gestión de protección contra bots