Docs › Guías › Smart Fetch (Auto)

Smart Fetch (Auto)

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

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

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 al elegir, gastas créditos o te bloquean.

Auto cambia el enfoque. Declaras el éxito (validate), no el método. FourA sube una escala hasta que un peldaño tiene éxito:

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

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

Hay un peldaño 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 a través de esa misma salida, conserva las cookies que la página de entrada 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 haya fallado, y únicamente puede añadir un resultado, nunca restarlo.

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 activa reutilizada. Configura forceProxy: false cuando sepas que un objetivo trata mejor una dirección limpia que una rotativa, y los peldaños 1 y 2 volverán a estar activos.

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 una página real de una página de verificación desconocida, o de una página que cargó sin tu contenido, y podría devolver cualquiera de ellas 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"]}}
  }'

Parámetros opcionales (consulta la referencia del endpoint para ver todos los detalles):

  • returnSession (por defecto true): devuelve el { proxy, cookies, userAgent } ganador para que puedas reproducirlo.
  • forceProxy (por defecto true): omite los niveles de salida directa. Configura false solo si sabes que el sitio es más tolerante con una IP limpia que con 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): máximo de redirecciones en los niveles económicos.

Lo que recibes

{
  "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 elementos para leer:

  • status y data: la respuesta del objetivo. data es texto en cada peldaño: una página JSON se devuelve como una cadena JSON incluso cuando la sirvió un navegador, así que procésala en tu lado. status es el estado HTTP del objetivo, no el estado de transporte de tu llamada a FourA. Para peldaños single y proxy, headers es un array por salto. Para peldaños de navegador, headers es un objeto plano.
  • meta: la traza de lo que hizo la escala, presente en cada response una vez que la escala ha comenzado. meta.rung nombra el paso que entregó la response, meta.attempts cuenta los intentos 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 header X-FourA-Credits).
  • session: la terna { proxy, cookies, userAgent } que superó el objetivo. Úsala para reproducir peticiones contra el mismo host mediante /api/single/ o /api/browser/.

Auto responde con HTTP 200 siempre que la escala se haya ejecutado, incluso si fallaron todos los peldaños. Lee status y error en el body para saber qué ocurrió, no el código de estado de transporte. Un estado distinto de 200 de /api/auto/ significa que la llamada nunca llegó a la escala: 401 por una clave incorrecta, 400 por un body que no es JSON válido o un objetivo en una red privada, y 502, 503 o 504 cuando el servicio no pudo aceptar la llamada o agotó el tiempo de espera. Auto no ocupa un slot en el gateway, por lo que los límites compartidos de la plataforma no rechazan la llamada en sí: cuando uno rechaza una llamada realizada por la escala, la respuesta es HTTP 200 con status: 429 o 503 y retryAfter en el body. Un campo que no pasa la validación también se devuelve como HTTP 200, con status: 400. Un límite de plan alcanzado dentro de la escala también se devuelve como HTTP 200, con el rechazo en el body (consulta When Your Plan's Limits Meet the Ladder).

Reproducción con la Session

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 una nueva ejecución de la escala, sin un nuevo sondeo.

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 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 comienza a devolver desafíos nuevamente, 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 sitio nuevo y no sabes qué necesita Ya conoces el motor que funciona
Quieres una sola llamada que gestione direct, proxy y fallback a browser por ti Quieres control total sobre los reintentos y tiempos de espera 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 a bajo costo 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 se aceptará como contenido válido.

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

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

Para APIs JSON, acepta un nombre de campo que esperes:

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

Para sitios que devuelven legítimamente respuestas distintas de 200 (una restricción de país que deseas ignorar, un 403 intencional en endpoints sin sesión iniciada), permítelos mediante validate.status.accept:

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

Sin validate, auto recurre a "HTTP 200 = éxito" para cada página que no reconozca como un challenge, por lo que no detectará una página de verificación desconocida que un sitio 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 una request directa económica. La ruta más barata.
  • proxy: necesitó rotación de proxy para completarse.
  • browser: necesitó un renderizado de navegador completo, posiblemente resolviendo un challenge.
  • cache: reutilizó una sesión activa de una llamada auto previa. La ruta más económica en llamadas repetidas.
  • warmup: el sitio entregó su página de entrada pero bloqueó la URL profunda, por lo que auto obtuvo primero la página de entrada, conservó las cookies recibidas y volvió a solicitar con ellas. La sesión almacenada en este nivel no está vinculada a una sola salida, por lo que las siguientes llamadas aprovechan los niveles económicos.
  • fail: ningún nivel produjo una response aceptada por tus reglas.

meta.solved: true indica que se encontró y completó una página de challenge durante la llamada. meta.attempts es el número de intentos de sub-llamadas antes del éxito. Para conocer los detalles, consulta el campo defense devuelto por los niveles directos y con proxy: consulta Verificaciones del sitio.

Si un sitio continúa terminando en browser cuando esperabas probe, evalúa si una regla validate más estricta (o menos estricta) permitiría validar un nivel más económico. Recuerda que forceProxy tiene como valor predeterminado true, por lo que la comprobación de salida directa se omite a menos que la desactives.

Errores y casos límite

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

{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status es la respuesta del sitio en el último intento rechazado automáticamente, como un 403. Cuando ningún intento obtuvo respuesta del sitio, suele ser 502 o 504, y error indica si no se encontró una salida funcional o si se agotó el presupuesto de timeout_ms. status: 0 solo significa que el nombre de host del destino no se resolvió, y esa respuesta no tiene meta porque la escala nunca se inició.

Revisa meta.attempts y meta.credits para ver a dónde se fue el presupuesto. Si meta.attempts es alto y meta.rung es fail después del nivel de navegador, el destino podría necesitar un timeout_ms más largo, una regla validate más estricta o simplemente no es accesible a través de proxies rotativos en este momento.

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

Las subllamadas de Auto son requests ordinarias de Single, Proxy y Browser bajo tu key, por lo que los límites de tu plan se aplican a ellas. La escala lee el código X-FourA-Limit en 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 (tus requests de Browser para el día se han agotado) y plan_limit_concurrency (ese endpoint ya tiene tantas de tus requests en ejecución como permite el plan) cierran un peldaño. Auto sigue procesando los otros peldaños, por lo que aún obtienes una página siempre que una salida rotativa o una sesión activa entregue el contenido, y las salidas que intentó no se consideran responsables de un rechazo originado en tu propio plan. No se banea nada y no se descarta ninguna sesión.

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

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

El cuerpo de rechazo completo de la subllamada se incluye, además de status y meta. Lee status desde el cuerpo y no desde el estado de transporte: auto sigue respondiendo 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 consume nada, por lo que meta.credits solo cuenta los peldaños que llegaron hasta el destino.

Una llamada auto puede ocupar varios slots mientras su escala sube, por lo que un lote paralelo de llamadas auto alcanza un límite de concurrencia con menos llamadas de las que esperarías. Ejecutar requests en paralelo 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 impactando en el destino. La "sesión activa" corresponde al proxy y las cookies, no a la response.
  • Es una sola fila en el Registro de actividad, bajo el ID de request 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 listadas 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

Actualizado: 30 de septiembre de 2026
← Cómo se mide el consumo de tu plan