Smart Fetch (Auto)

Você fornece à FourA uma URL e uma regra validate para o que a página real deve conter. A FourA faz o resto: ela percorre uma escala que otimiza custos, para no primeiro degrau que retornar uma resposta aceita por 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.

O Conceito

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ê adivinhar errado, desperdiça créditos ou é bloqueado.

O auto inverte isso. Você define o sucesso (validate), não o método. A FourA sobe uma escala até que um degrau tenha sucesso:

  1. Sondagem econômica (single, direto da própria rede da FourA)
  2. Browser, direto da própria rede da 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 degrau retorna uma resposta que sua regra validate aceita.

Um degrau fica 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 meio dessa mesma saída, mantém os cookies fornecidos por ela e solicita sua URL novamente enviando esses cookies. Esse é o degrau warmup. Ele só é executado em URLs mais profundas que a raiz do site, apenas depois que a tentativa direta já falhou, e só pode somar um resultado, nunca remover um.

forceProxy tem como padrão true, portanto os degraus 1 e 2 são ignorados e o alvo nunca vê o endereço da própria FourA. A maioria das chamadas termina no degrau 3 ou em uma sessão quente reutilizada. Defina forceProxy: false quando você souber que o alvo lida melhor com um endereço limpo do que com um rotativo, e os degraus 1 e 2 voltam a ser considerados.

O Que Você Envia

O mínimo necessário é uma URL e uma substring validate. O auto reconhece sozinho as páginas de desafio mais comuns, mas sem o 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 que carregou 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"]}}
  }'

Ajustes opcionais (consulte a referência de endpoints para obter detalhes completos):

  • returnSession (padrão true): retorna a { proxy, cookies, userAgent } vencedora para que você possa repeti-la.
  • forceProxy (padrão true): pula as etapas de saída direta. Defina false apenas se você souber que o site aceita melhor um IP limpo do que saídas rotativas.
  • timeout_ms (padrão 120000): orçamento total para a chamada inteira. O fluxo o distribui entre as etapas.
  • ignoreProxies: IDs de proxy a evitar em cada sub-tentativa.
  • followRedirects (padrão 5): máximo de redirecionamentos nas etapas de baixo custo.
  • headers: headers a serem enviados para o site, como pares [name, value]. Eles são enviados nas requisições Single e Proxy, incluindo a busca por uma saída funcional, e as etapas de navegador não os enviam. Seu próprio Cookie chega ao site sem alterações, e os cookies de uma sessão ativa são adicionados junto a ele apenas sob nomes que você não enviou. Quando uma sessão ativa carrega um userAgent, ele substitui seu User-Agent. Headers condicionais como If-None-Match e If-Modified-Since ficam de fora da busca de saída, a menos que seu validate.status.accept liste 304.
  • exitClass: premium permite que o Auto escale para uma saída premium quando o pool padrão não conseguir alcançar a página; standard indica que ele nunca escala. Requer um plano que inclua saídas premium. Consulte exitClass no Smart Fetch.

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,
    "attemptsByEngine": {"single": 1, "proxy": 0, "browser": 0},
    "browserRequests": 0
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}

Três coisas para ler:

  • status e data: a resposta do destino. data é texto qualquer que seja o degrau que serviu a página, portanto uma página JSON chega como texto JSON e você mesmo faz o parse. 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 simples.
  • meta: o rastreamento do que a escada fez, presente em todas as respostas assim que a escada é iniciada. meta.rung indica a etapa que entregou a resposta, 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 valor do cabeçalho X-FourA-Credits). meta.attemptsByEngine e meta.browserRequests informam o que a chamada consumiu: consulte O que uma chamada gastou. Quando a requisição indicou um exitClass, meta.exitClass diz qual classe de saída fez a entrega.
  • session: o trio { proxy, cookies, userAgent } que superou o destino. Use-o para repetir contra o mesmo host via /api/single/ ou /api/browser/. Um campo pode estar ausente: uma sessão obtida por uma busca simples via proxy tem proxy, mas não userAgent, e sua lista cookies contém apenas os cookies definidos por uma página de verificação antes de o site servir a página, de modo que frequentemente está vazia. Uma resposta da sondagem direta econômica traz uma session apenas quando essa página de verificação definir cookies, contendo apenas cookies. Um status listado no seu validate.status.accept retornado por uma saída (como o 404 de uma página removida) não tem session.

O Auto responde com HTTP 200 sempre que a escada for executada, mesmo se todos os degraus falharem. Leia status e error no corpo para saber o que ocorreu, e não o código de status de transporte. Um retorno diferente de 200 de /api/auto/ significa que a chamada nunca alcançou a escada: 401 para chave inválida, 400 para corpo que não seja JSON válido, destino em rede privada, destino no próprio host de API do FourA ou uma URL contendo espaço não codificado, 403 com X-FourA-Limit: plan_limit_premium para exitClass: premium em planos sem saídas premium, e 502, 503 ou 504 quando o serviço não pôde receber a chamada ou excedeu o tempo limite. O Auto não consome slot no gateway, de modo que os limites compartilhados da plataforma não recusam a chamada em si: quando um deles recusa uma chamada feita pela escada, a resposta é HTTP 200 com status: 429 ou 503 e retryAfter no corpo. Um campo que falhar na validação também retorna como HTTP 200, com status: 400. Um limite de plano atingido dentro da escada também retorna como HTTP 200, trazendo a recusa no corpo (consulte Quando os limites do seu plano encontram a escada).

Repetindo com a sessão

Depois que o auto retorna uma sessão, você pode ir direto para Single ou Browser para páginas seguintes no mesmo host. Sem nova subida na escada, 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.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"])

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

Quando usar Auto

Use auto Use single, proxy ou browser manualmente
Você tem como alvo um novo site e não sabe do que ele precisa Você já conhece o mecanismo que funciona
Você quer uma única chamada que gerencie o fallback de proxy e browser para você Você quer controle total sobre retries e timeouts por chamada
Para você, tudo bem aguardar 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 reproduzir com baixo custo Você está otimizando um loop restrito em um alvo sabidamente funcional

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

O Validate informa ao Auto o que "Sucesso" significa

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 não familiar ou uma estrutura vazia enviada com HTTP 200 passa como conteúdo válido.

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 o nome de campo esperado:

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

Para sites que legitimamente retornam status diferente de 200 (uma restrição de país que você deseja ignorar, o 404 ou 410 de uma página removida), permita-os via validate.status.accept:

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

O auto retorna um status listado por você em validate.status.accept assim que uma saída o traz de volta e ele passa no restante da sua regra. Quatro status são a exceção: 202, 403, 429 e 503. O auto interpreta esses códigos como o site verificando quem está fazendo a solicitação, portanto, uma saída que retorna um deles não encerra a busca, e a sequência continua subindo.

Sem validate, o auto recorre ao padrão "HTTP 200 = sucesso" para cada página que não reconhece como um desafio, portanto não detectará uma página de verificação desconhecida retornada pelo site com status 200.

Lendo meta.rung para entender o que aconteceu

meta.rung é o sinal de depuração mais útil. Valores:

  • probe: resolvido em uma request direta de baixo custo. O caminho mais econômico.
  • proxy: precisou de rotação de proxy para passar.
  • browser: precisou de uma renderização completa em navegador, possivelmente com resolução de desafio.
  • cache: reproduziu uma sessão ativa de uma chamada auto anterior. O caminho mais econômico em chamadas repetidas.
  • warmup: o site exibiu a página inicial, mas bloqueou a URL profunda, então o auto buscou primeiro a página inicial, manteve os cookies fornecidos e tentou novamente com eles. A sessão armazenada a partir desta etapa não fica vinculada a uma única saída, portanto as chamadas seguintes chegam às etapas mais econômicas.
  • fail: nenhuma etapa produziu uma resposta aceita pelas suas regras.

meta.solved: true indica que uma página de desafio foi encontrada e concluída durante a chamada. meta.attempts é a contagem de tentativas de subchamadas antes do sucesso. Para ver os detalhes por trás disso, leia o campo defense retornado pelas etapas direta e de proxy: consulte Verificações de site.

Se um site continuar terminando em browser quando você esperava probe, avalie se uma regra de validate mais restrita (ou menos restrita) permitiria a aprovação de uma etapa mais econômica. Lembre-se de que forceProxy tem como padrão true, portanto a sondagem de saída direta é ignorada, a menos que você a desative.

O que uma chamada consumiu

meta.attemptsByEngine contabiliza as requests enviadas pela chamada a cada mecanismo, as mesmas requests mostradas no painel Auto attempts em sua Visão geral. meta.browserRequests contabiliza as que consumiram um espaço da sua franquia diária de navegador.

"meta": {
  "rung": "browser",
  "solved": true,
  "attempts": 7,
  "credits": 47,
  "attemptsByEngine": {"single": 1, "proxy": 4, "browser": 3},
  "browserRequests": 2
}
Campo Tipo Descrição
meta.attemptsByEngine object Requests enviadas para single, proxy e browser. Uma browser request recusada pelo seu plano é contabilizada aqui, pois foi enviada.
meta.browserRequests number Browser requests que consumiram um slot do seu limite diário. Uma browser request recusada pelo seu plano não consome nada.

meta.attempts conta as etapas da sequência, portanto nem sempre é igual à soma de meta.attemptsByEngine. Uma etapa pode enviar uma Single request e depois uma Proxy request, e uma etapa cujo browser já esteja encerrado para o dia não envia nada.

A sua contagem atual para o dia é enviada nos headers X-FourA-Browser-Used-Today e X-FourA-Browser-Limit-Per-Day: consulte Response Headers.

Erros e Casos Limite

Quando o auto falha, a resposta traz status (geralmente o status da última etapa que falhou) e uma string error:

{
  "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 é a resposta do site na última tentativa rejeitada pelo Auto, como um 403. Quando nenhuma tentativa obteve resposta do site, normalmente é 502 ou 504, e error indica 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 possui meta porque a ladder nunca foi iniciada.

O Auto também é interrompido antecipadamente quando o navegador continua encontrando uma verificação que não consegue concluir. Após duas saídas recusarem o navegador dessa forma e uma busca por uma saída cujo fetch simples passe pela sua regra validate retornar vazia, ou após três saídas desse tipo, a chamada termina. status contém a última resposta do site e error começa com the browser was refused by, seguido pelo nome do sistema de verificação.

O Auto também é interrompido quando o próprio site informa que a página não existe. Quando duas saídas retornam o mesmo 404 ou 410 e as suas regras não o aceitam, a chamada termina com esse status, e error começa com the site answered. Se uma página removida for uma resposta aceitável para você, liste 404 ou 410 em validate.status.accept: o Auto a retornará como entregue assim que uma saída a trouxer de volta.

Após quatro chamadas consecutivas do Auto com a sua API key terminarem sem a página porque o site continuou recusando, o Auto para de tentar esse site para a sua chave por 120 segundos. Uma chamada feita durante esse período responde imediatamente com status: 503, error: "target temporarily unservable, retry later" e retryAfter em segundos, sem nenhum custo. A contagem é feita por API key: outras chaves chamando o mesmo site não são afetadas, e qualquer chamada que obtenha a página reinicia a contagem. Uma chamada com exitClass: premium não é interrompida por isso.

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

Por que uma chamada do Auto falhou

Toda resposta com falha de uma ladder executada traz um attemptReport. Ele conta as requisições da engine que retornaram sem a página, cada uma contada uma vez, de acordo com o que foi encontrado.

Campo Tipo Descrição
total integer Requests que retornaram sem a página. No máximo a soma de meta.attemptsByEngine, porque uma request de browser recusada pelo seu plano nunca tentou o destino.
noResponse integer Não obteve resposta do site
defense integer O site recusou a request: uma verificação de bot foi detectada, a página era um desafio ou o site respondeu 401, 403, 429 ou 503
contentRejected integer A página foi obtida e apenas a sua regra validate a rejeitou
statusRejected integer O site respondeu com um status que sua request não aceita, como 404 para uma página removida
other integer Falhou por outro motivo, como um erro no servidor
vendors string[] Provedores de verificação de bot identificados nas recusas encontradas pela chamada
summary string Uma frase gerada a partir das contagens, segura para registrar em logs. Ela indica o status HTTP retornado pelo site quando nenhum provedor foi identificado e informa quando o seu limite diário de browser foi esgotado, impedindo a abertura de novos browsers.

Os campos correspondem ao relatório de uma chamada Proxy com falha, sem profilesTried. Duas coisas diferem. O Proxy contabiliza cada saída que tentou, até o limite de maxTries definido por você, enquanto o Auto contabiliza suas próprias requests. O Auto também lê a página e o respectivo status, portanto uma recusa é contabilizada em defense mesmo quando nenhum provedor foi identificado. A contagem em contentRejected é a única que você mesmo pode corrigir: a página retornou e a sua regra não correspondeu a ela.

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 limites do seu plano se aplicam a elas. A ladder lê o código X-FourA-Limit em caso de recusa e trata os dois tipos de forma diferente.

Um degrau fechado mantém o restante da ladder utilizável. plan_limit_browser_daily (suas requests de Browser do dia foram esgotadas) e plan_limit_concurrency (esse endpoint já atingiu o limite de requests simultâneas permitido pelo seu plano) fecham um degrau. O Auto continua operando os outros degraus, permitindo que você ainda obtenha a página sempre que uma saída rotativa ou uma sessão ativa entregar o conteúdo, sem penalizar as saídas testadas por uma recusa originada do seu próprio plano. Nada é bloqueado e nenhuma sessão é descartada.

Uma conta sem saldo interrompe a ladder. plan_limit_credits, plan_limit_bandwidth, plan_limit_rate, plan_limit_feature e plan_limit_premium não são resolvidos por outro degrau, portanto o Auto retorna imediatamente em vez de gastar mais dos seus créditos tentando provar isso. A recusa retorna no body com o status da subchamada e o mesmo campo reason usado pelos endpoints diretos:

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

Todo o body de recusa da subchamada é retornado, além de status, attemptReport e meta. Leia status a partir do body e não do status de transporte: o auto ainda responde HTTP 200 aqui, porque a sequência foi executada. Uma recusa de plan_limit_feature ou plan_limit_premium chega da mesma forma com status: 403. Uma subchamada recusada não consome nada, portanto meta.credits contabiliza apenas as etapas que chegaram até o destino.

Uma chamada auto pode ocupar vários slots enquanto sua sequência avança, de modo que um lote paralelo de chamadas auto atinge o limite de concorrência 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 armazena conteúdo em cache. Cada chamada ainda atinge o destino. A "sessão quente" consiste no proxy e cookies, não na response.
  • É registrado como uma única linha no Log de Atividades, sob o request id que você recebeu, com a soma dos créditos das suas subchamadas. Ao abri-lo, as subchamadas Single / Proxy / Browser que o auto fez em seu nome são listadas como tentativas, cada uma com seu próprio resultado. Elas contam para os seus limites de Single, Proxy e Browser, nunca para a sua contagem de requests ou taxa de sucesso.
Atualizado em: 13 de novembro de 2026