Smart Fetch (Auto)

Você fornece ao FourA uma URL e uma regra validate sobre o que a página real deve conter. O FourA faz o resto: ele sobe uma escada sensível a custos, para no primeiro degrau que retorna uma response que suas regras aceitam e lembra o que funcionou por host para que a próxima chamada no mesmo site seja barata.

Este guia explica o que o auto faz por trás dos panos, quando usá-lo e como ler sua response. Para a referência de parâmetros, consulte API Endpoints.

A Ideia

A maioria das configurações de scraping faz você escolher o motor de antemão. Single é mais rápido, Proxy adiciona rotação, Browser lida com JavaScript. Se você adivinhar errado, você desperdiça créditos ou é bloqueado.

O Auto inverte isso. Você declara o sucesso (validate), não o método. O FourA sobe uma escada até que um degrau tenha sucesso:

Sondagem barata (single, direto da própria rede do FourA)
Proxy single rotacionado
Browser, com JavaScript e um solver se o site apresentar desafios
Browser through proxy para os alvos mais difíceis

O Auto para assim que um degrau retorna uma response que sua regra validate aceita.

forceProxy tem o padrão true, então o degrau 1 é ignorado e o alvo nunca vê o próprio endereço do FourA. A maioria das chamadas então termina no degrau 2, ou em uma sessão quente repetida. Defina forceProxy: false quando você souber que um alvo trata um endereço limpo melhor do que um rotativo, e o degrau 1 retorna.

O Que Você Envia

O mínimo é uma URL mais uma substring validate. Sem validate.data.accept, o auto não consegue diferenciar uma página real de um intersticial de desafio retornado com HTTP 200, e ele pode retornar o desafio como sucesso.

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

Configurações opcionais (veja a referência do endpoint para obter todos os detalhes):

returnSession (padrão true): retorna o { proxy, cookies, userAgent } vencedor para que você possa repeti-lo.
forceProxy (padrão true): ignora níveis de saída direta. Defina false apenas se você souber que o site é mais tolerante a um IP limpo do que a proxies rotativos gratuitos.
timeout_ms (padrão 120000): orçamento total para toda a chamada. A escada o distribui entre os níveis.
ignoreProxies: IDs de proxy para evitar em cada subtentativa.
followRedirects (padrão 5): máximo de redirecionamentos nos níveis mais baratos.

O Que Você Recebe de Volta

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

Três coisas para ler:

status e data: o mesmo formato que o motor subjacente retornou. status é o status HTTP do alvo, não o status de transporte da sua chamada para a FourA. Para etapas single e proxy, headers é um array por salto. Para etapas de browser, headers é um objeto plano.
meta: o rastro do que a ladder fez, presente em cada response. meta.rung nomeia o passo que entregou a response, meta.attempts conta as tentativas de sub-chamadas, meta.solved sinaliza se um desafio de bot foi superado, e meta.credits é o gasto total da chamada (o mesmo número do header X-FourA-Credits).
session: a tripla { proxy, cookies, userAgent } que quebrou o alvo. Use-a para fazer replay contra o mesmo host via /api/single/ ou /api/browser/.

Auto responde com HTTP 200 sempre que a ladder for executada, mesmo quando todas as etapas falharem. Leia status e error no corpo para descobrir o que aconteceu, não o código de status de transporte. Um valor diferente de 200 de /api/auto/ significa que a FourA rejeitou a chamada antes de a ladder começar: 401 para uma chave inválida, 400 para um corpo inválido ou um alvo privado, 429 ou 503 para rate limits.

Fazendo replay com a Sessão

Depois que auto retornar uma sessão, você pode ir direto para Single ou Browser para as páginas subsequentes no mesmo host. Sem nova subida na ladder, sem nova sondagem.

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"])

A sessão é apenas tão durável quanto o alvo permite. Alguns sites vinculam a liberação ao cookie jar por horas; outros rotacionam a cada poucos minutos. Se um replay começar a retornar desafios novamente, chame /api/auto/ mais uma vez para atualizar.

Quando usar Auto

Usar Auto	Usar single, proxy ou browser manualmente
Você está buscando um site novo e não sabe do que ele precisa	Você já sabe o motor que funciona
Você quer uma chamada que gerencie o fallback direto, de proxy e browser para você	Você quer controle total sobre retentativas e timeouts por chamada
Você aceita pagar alguns segundos de investigação na primeira chamada	A latência da primeira chamada importa mais do que a descoberta
Você quer uma sessão aprendida que possa fazer replay com baixo custo	Você está otimizando um loop ajustado em um alvo conhecido e funcional

O Auto nem sempre é a escolha mais barata. Se você sabe que um alvo funciona com single + unblocker, chamar Single diretamente custa 2 créditos com latência previsível. O Auto no mesmo alvo custa o que a sua escalada gastar, o que pode ser mais se o site exigir escalonamento.

Validate diz ao Auto o que "Sucesso" significa

O parâmetro mais importante é validate. Sem ele, o Auto não consegue distinguir uma página 200 real de um intersticial de desafio 200 disfarçado de conteúdo.

Use validate.data.accept com uma substring que apenas a página real contenha:

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

Para APIs JSON, aceite um nome de campo que você espera:

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

Para sites que legitimamente retornam não-200 (bloqueios geográficos que você deseja ignorar, 403 intencional em endpoints sem login), permita-os via validate.status.accept:

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

Sem validate, o auto usa o fallback para "HTTP 200 = sucesso" e não irá capturar um desafio intersticial do Cloudflare que o WAF retorna com um 200.

Lendo `meta.rung` para Entender o Que Aconteceu

meta.rung é o sinal de debug mais útil. Valores:

probe - resolvido em uma requisição direta barata. O caminho mais barato.
proxy - precisou de rotação de proxy para passar.
browser - precisou de uma renderização completa de navegador, possivelmente com resolução de desafio.
cache - repetiu uma sessão quente de uma chamada auto anterior. O caminho mais barato em chamadas repetidas.
fail - nenhum nível produziu uma resposta que suas regras aceitaram.

meta.solved: true significa que um desafio de bot foi detectado e resolvido durante a chamada. meta.attempts é a contagem de tentativas de subchamada antes do sucesso. Para os detalhes do fornecedor por trás de uma resolução, leia o campo defense que os níveis single e proxy retornam: veja Anti-Bot Defenses.

Se um site continua terminando em browser quando você esperava probe, considere se uma regra validate mais restrita (ou menos restrita) deixaria um nível mais barato passar. Lembre-se que forceProxy tem o padrão true, então o probe de egress direto é ignorado a menos que você o desative.

Erros e Edge Cases

Quando o auto falha, a resposta traz status (geralmente o status do último nível que falhou) e uma string error:

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

status: 0 significa que nenhum nível produziu uma response (todas as tentativas esgotaram o tempo limite ou foram rejeitadas). Um status diferente de zero mais error significa que a última tentativa obteve uma response, mas o auto a rejeitou (por validação ou outro motivo).

Verifique meta.attempts e meta.credits para ver onde o orçamento foi gasto. Se meta.attempts estiver alto e meta.rung for fail após o nível do browser, o alvo pode precisar de um timeout_ms maior, de uma regra validate mais rígida ou simplesmente não está acessível através de proxies rotativos no momento.

O que o Auto não faz

Ele não ignora restrições legais. Se um site possui bloqueio geográfico e rejeita todas as saídas que o FourA pode alcançar, o auto retorna o bloqueio.
Ele não faz cache de conteúdo. Cada chamada ainda atinge o alvo. A "sessão quente" é o proxy e os cookies, não a response.
Ele não grava no Activity Log como uma linha separada das subchamadas. As subchamadas Single / Proxy / Browser que o auto faz em seu nome aparecem no Activity; a chamada /api/auto/ externa atua como um coordenador.

Relacionado

API Endpoints: Referência completa de parâmetros
Choosing the Right Endpoint: Quando escolher auto vs single, proxy ou browser
Request Outcomes: Quais resultados são faturáveis
Anti-Bot Protection: O que o FourA faz sobre Cloudflare, DataDome e similares
Anti-Bot Defenses: O campo defense por trás de meta.solved
MCP Recipes: Os mesmos padrões das chamadas de ferramentas MCP

Atualizado em: 12 de agosto de 2026