# Smart Fetch (Auto)

> URL: https://foura.ai/pt/docs/guides/smart-fetch
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

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](https://foura.ai/docs/api/endpoints#smart-fetch-auto).

## 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.

```bash
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](https://foura.ai/docs/api/endpoints#smart-fetch-auto) 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](https://foura.ai/docs/api/endpoints#exitclass-on-smart-fetch).

## O que você recebe de volta

```json
{
  "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](#what-a-call-spent). 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](#when-your-plans-limits-meet-the-ladder)).

## 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.

```python
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:

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

Para APIs JSON, aceite o nome de campo esperado:

```json
{
  "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`:

```json
{
  "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](https://foura.ai/docs/api/site-checks).

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](https://foura.ai/docs/dashboard/overview). `meta.browserRequests` contabiliza as que consumiram um espaço da sua franquia diária de navegador.

```json
"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](https://foura.ai/docs/api/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`:

```json
{
  "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](https://foura.ai/docs/troubleshooting/proxy-attempt-report), 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](https://foura.ai/docs/api/rate-limits) 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:

```json
{
  "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](https://foura.ai/docs/how-to/run-requests-in-parallel) 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](https://foura.ai/docs/dashboard/activity-log), 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.

## Relacionado

- [Endpoints da API](https://foura.ai/docs/api/endpoints#smart-fetch-auto): Referência completa de parâmetros
- [Escolhendo o Endpoint Correto](https://foura.ai/docs/guides/choosing-task-type): Quando escolher auto vs single, proxy ou browser
- [Resultados de Request](https://foura.ai/docs/api/outcomes): Quais resultados são faturáveis
- [Sites protegidos](https://foura.ai/docs/guides/protected-sites): O que o FourA faz em sites que verificam quem está solicitando
- [Verificações de site](https://foura.ai/docs/api/site-checks): O campo `defense` por trás de `meta.solved`
- [Receitas MCP](https://foura.ai/docs/mcp/recipes): Os mesmos padrões como chamadas de ferramentas MCP
- [Rate Limits](https://foura.ai/docs/api/rate-limits): Os limites do plano contra os quais as subchamadas do auto são medidas
