Docs › Guias › Smart Fetch (Auto)

Smart Fetch (Auto)

Você fornece ao FourA uma URL e uma regra validate definindo o que a página real deve conter. O FourA faz o resto: ele percorre uma escala com base em custo, para no primeiro nível que retorna uma resposta aceita pelas suas regras e memoriza o que funcionou por host para que a próxima chamada no mesmo site seja econômica.

Este guia explica o que o auto faz nos bastidores, quando usá-lo e como interpretar sua resposta. Para a referência de parâmetros, consulte API Endpoints.

A ideia

A maioria das configurações de scraping exige que você escolha o mecanismo antecipadamente. Single é o mais rápido, Proxy adiciona rotação, Browser processa JavaScript. Se você errar na escolha, desperdiça créditos ou é bloqueado.

O Auto inverte isso. Você declara o sucesso (validate), não o método. O FourA sobe uma escala até que um nível funcione:

  1. Sondagem econômica (single, diretamente da rede do FourA)
  2. Browser, diretamente da rede do FourA, com JavaScript e um solver se o site apresentar desafios
  3. Single com proxy rotativo
  4. Browser via proxy para os alvos mais difíceis

O Auto para assim que um nível retorna uma resposta aceita pela sua regra validate.

Um nível opera fora dessa ordem. Quando uma saída alcança o site mas o site recusa a URL profunda solicitada, o auto busca a página inicial do site por essa mesma saída, mantém os cookies fornecidos por ela e solicita sua URL novamente enviando esses cookies. Esse é o nível warmup. Ele roda apenas em URLs mais profundas que a raiz do site, somente após a tentativa direta ter falhado, e pode apenas adicionar um resultado positivo, nunca remover um.

forceProxy tem como padrão true, portanto os níveis 1 e 2 são ignorados e o alvo nunca vê o endereço do FourA. A maioria das chamadas termina no nível 3 ou em uma sessão reutilizada em cache. Defina forceProxy: false quando você souber que um alvo lida melhor com um endereço limpo do que com um rotativo, e os níveis 1 e 2 voltam a operar.

O que você envia

O mínimo é uma URL e uma substring validate. O Auto reconhece as páginas de desafio comuns por conta própria, mas sem validate.data.accept ele não consegue diferenciar uma página real de uma página de verificação desconhecida, ou de uma página carregada sem o seu conteúdo, podendo retornar qualquer uma delas 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"]}}
  }'

Parâmetros opcionais (consulte a referência do endpoint para obter todos os detalhes):

  • returnSession (padrão true): retorna o { proxy, cookies, userAgent } vencedor para você poder reproduzi-lo.
  • forceProxy (padrão true): pula etapas de saída direta. Defina false apenas se você souber que o site aceita melhor um IP limpo do que proxies rotativos gratuitos.
  • timeout_ms (padrão 120000): orçamento total para toda a chamada. A estratégia divide isso entre as etapas.
  • ignoreProxies: IDs de proxy a serem evitados em cada subtentativa.
  • followRedirects (padrão 5): máximo de redirecionamentos nas etapas de baixo custo.

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 itens para ler:

  • status e data: a resposta do destino. data é texto em cada degrau: uma página JSON retorna como uma string JSON mesmo quando servida por um navegador, portanto faça o parse do seu lado. status é o status HTTP do destino, não o status de transporte da sua chamada para o FourA. Para degraus single e proxy, headers é um array por salto. Para degraus de navegador, headers é um objeto plano.
  • meta: o rastro do que a ladder executou, presente em cada response após o início da ladder. meta.rung indica a etapa que entregou a response, meta.attempts conta as tentativas de subchamadas, meta.solved sinaliza se uma página de desafio foi concluída e meta.credits é o gasto total da chamada (o mesmo número do header X-FourA-Credits).
  • session: a trinca { proxy, cookies, userAgent } que superou o destino. Use-a para repetir requisições contra o mesmo host via /api/single/ ou /api/browser/.

O Auto responde com HTTP 200 sempre que a ladder for executada, mesmo quando todos os degraus falharem. Leia status e error no body para saber o que aconteceu, não o código de status de transporte. Um status diferente de 200 vindo de /api/auto/ significa que a chamada nunca alcançou a ladder: 401 para uma chave inválida, 400 para um body que não seja JSON válido ou um destino em rede privada, e 502, 503 ou 504 quando o serviço não pôde receber a chamada ou esgotou o tempo limite. O Auto não ocupa slot no gateway, portanto os limites compartilhados da plataforma não recusam a chamada em si: quando um limite recusa uma chamada feita pela ladder, a resposta é HTTP 200 com status: 429 ou 503 e retryAfter no body. Um campo que falha na validação também retorna como HTTP 200, com status: 400. Um limite de plano atingido dentro da ladder também retorna como HTTP 200, com a recusa no body (veja Quando os limites do seu plano encontram a Ladder).

Reproduzindo com a Session

Depois que o auto retornar uma session, você pode ir direto para Single ou Browser para as próximas páginas 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 é tão durável quanto o site de destino permitir. Alguns sites vinculam a autorizaçã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á acessando um novo site e não sabe o que ele exige Você já conhece o engine que funciona
Você quer uma única chamada que gerencie fallback direto, proxy e browser para você Você quer controle total sobre retries e timeouts por chamada
Você aceita esperar alguns segundos de sondagem na primeira chamada A latência da primeira chamada importa mais do que a descoberta
Você quer uma sessão aprendida que possa reutilizar de forma econômica Você está otimizando um loop rápido em um destino comprovadamente funcional

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

Validate Informa ao Auto o Que Significa "Sucesso"

O parâmetro mais importante é validate. Sem ele, o auto rejeita apenas as páginas de desafio que reconhece, portanto, uma página de verificação desconhecida ou uma casca vazia retornada com HTTP 200 passa como conteúdo.

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

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

Para APIs JSON, aceite um nome de campo esperado:

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

Para sites que legitimamente retornam códigos diferentes de 200 (uma restrição de país que você deseja ignorar, um 403 intencional em endpoints desconectados), permita-os via validate.status.accept:

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

Sem validate, o modo auto recorre a "HTTP 200 = sucesso" para cada pagina que nao reconhece como um desafio, portanto nao detectara uma pagina de verificacao desconhecida que um site retorne com status 200.

Lendo meta.rung para entender o que aconteceu

meta.rung e o sinal de debug mais util. Valores:

  • probe: resolvido em uma request direta e economica. O caminho mais barato.
  • proxy: precisou de rotacao de proxy para passar.
  • browser: precisou de renderizacao completa em browser, possivelmente com resolucao de desafio.
  • cache: reutilizou uma sessao ativa de uma chamada auto anterior. Caminho mais economico em chamadas repetidas.
  • warmup: o site exibiu a pagina inicial, mas bloqueou a URL profunda, entao o modo auto buscou a pagina inicial primeiro, manteve os cookies fornecidos e tentou novamente com eles. A sessao armazenada deste nivel nao fica vinculada a uma unica saida, permitindo que as chamadas seguintes usem niveis mais baratos.
  • fail: nenhum nivel gerou uma response aceita pelas suas regras.

meta.solved: true significa que uma pagina de desafio foi encontrada e concluida durante a chamada. meta.attempts e a contagem de tentativas de subchamadas antes do sucesso. Para ver os detalhes correspondentes, leia o campo defense retornado pelos niveis single e proxy: consulte Site checks.

Se um site continuar terminando em browser quando voce esperava probe, avalie se uma regra validate mais restrita (ou menos restrita) permitiria a aprovacao de um nivel mais barato. Lembre-se de que forceProxy padroniza para true, portanto a verificacao de saida direta e ignorada, a menos que voce a desative.

Erros e casos extremos

Quando o modo auto falha, a response contem status (geralmente o status do ultimo nivel que falhou) e uma string 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 é a resposta do site na última tentativa rejeitada pelo modo auto, como um 403. Quando nenhuma tentativa obteve qualquer resposta do site, geralmente é 502 ou 504, e error informa se nenhuma saída funcional foi encontrada ou se o orçamento de timeout_ms se esgotou. status: 0 significa apenas que o nome do host de destino não foi resolvido, e essa resposta não tem meta porque a sequência de tentativas (ladder) nunca foi iniciada.

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

Quando os limites do seu plano encontram a ladder

As subchamadas do Auto são requests comuns de Single, Proxy e Browser sob a sua chave, portanto os seus limites de plano se aplicam a elas. A ladder lê o código X-FourA-Limit em uma recusa e trata os dois tipos de forma diferente.

Uma etapa fechada deixa o restante da ladder utilizável. plan_limit_browser_daily (seus requests de Browser do dia acabaram) e plan_limit_concurrency (aquele endpoint já tem tantos requests seus em execução quanto o plano permite) fecham uma etapa. O modo Auto continua executando as outras etapas, para que você ainda receba uma página sempre que uma saída rotativa ou uma sessão ativa entregar o conteúdo, e as saídas testadas não são penalizadas por uma recusa originada no seu próprio plano. Nada é banido e nenhuma sessão é descartada.

Uma conta esgotada interrompe a ladder. plan_limit_credits, plan_limit_bandwidth, plan_limit_rate, plan_limit_feature e plan_limit_premium não podem ser resolvidos por outra etapa, então o modo Auto retorna imediatamente em vez de gastar mais dos seus créditos tentando confirmar isso. A recusa retorna no corpo com o status da subchamada e o mesmo campo reason usado pelos endpoints diretos:

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

Todo o corpo de recusa da sub-call é retornado, além de status e meta. Leia status a partir do corpo e não do status de transporte: o auto ainda responde HTTP 200 aqui, porque a escada foi executada. Uma recusa de plan_limit_feature ou plan_limit_premium chega da mesma forma com status: 403. Uma sub-call recusada não consome nada, portanto meta.credits conta apenas os degraus que chegaram até o destino.

Uma chamada auto pode ocupar vários slots enquanto sua escada progride, portanto um lote paralelo de chamadas auto atinge o teto de simultaneidade com menos chamadas do que você esperaria. Executar Requests em Paralelo aborda o dimensionamento do lote.

O que o Auto não faz

  • Não altera restrições legais. Se um site recusar todas as saídas que o FourA consegue alcançar, o auto retorna essa recusa.
  • Não faz cache de conteúdo. Cada chamada ainda atinge o destino. A "sessão quente" refere-se ao proxy e aos cookies, não à response.
  • É uma única linha no Log de Atividades, sob o request id que você recebeu, com a soma dos créditos de suas sub-calls. Abra-o e as sub-calls de Single / Proxy / Browser que o auto fez em seu nome serão listadas como suas tentativas, cada uma com seu próprio resultado. Elas contam contra seus limites de Single, Proxy e Browser, nunca contra sua contagem de requests ou taxa de sucesso.

Relacionado

Atualizado em: 30 de setembro de 2026
← Como Seu Plano É Medido