# Referência de Endpoints da API

> URL: https://foura.ai/pt/docs/api/endpoints
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

Uma referência para todos os endpoints da API FourA com parâmetros de request e formatos de response.

## Base URL

```
https://eu.api.foura.ai/api
```

## Autenticação

Toda request exige a sua chave de API no header `X-API-Key`:

```bash
curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'
```

Crie e gerencie chaves de API no [Dashboard](https://foura.ai/dashboard). As chaves usam o prefixo `pk_live_`.

## Headers de resposta

As respostas do `/api/*` contêm dois headers de correlação:

| Header | Valor | Descrição |
|--------|-------|-------------|
| `X-FourA-Request-Id` | UUID | ID exclusivo atribuído à requisição. Retornado em todas as respostas, incluindo 4xx e 5xx, exceto quando o FourA não consegue ler o body: `400 Invalid JSON in request body` e `413` são recusados antes que um ID seja atribuído. Registre-o em seus logs. |
| `X-FourA-Credits` | integer | Créditos gastos nesta requisição. Retornado em todas as respostas que alcançaram uma engine, com sucesso ou falha (o processamento foi feito em ambos os casos). Uma chamada que o FourA recusou antes de qualquer engine executá-la (uma chave ausente ou inválida, um limite do plano ou da plataforma, um destino ou ID de proxy recusado) não contém o header. Consulte [Resultados de Requisições](https://foura.ai/docs/api/outcomes) para verificar quais resultados são cobrados. |

O mesmo ID de requisição indexa a pré-visualização do payload da requisição e da resposta no [Registro de Atividades](https://foura.ai/docs/dashboard/activity-log) do Dashboard (mantido por 24 horas, últimas 200 por chave), para que você possa consultar a requisição exata mais tarde e reproduzi-la diretamente no [Playground](https://foura.ai/docs/dashboard/playground). Inclua-o ao entrar em contato com o suporte para identificar a requisição em segundos.

```bash
$ curl -i -X POST https://eu.api.foura.ai/api/single/ \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"method": "GET", "url": "https://example.com"}'

HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
x-foura-credits: 2
...
```

Consulte [Response Headers](https://foura.ai/docs/api/response-headers) para obter a lista completa e dicas de uso.

## Endpoints

> **Usando estes endpoints via MCP?** O [servidor `@fouradata/mcp`](https://foura.ai/docs/mcp/server) encapsula todos os quatro endpoints como ferramentas MCP nativas (`foura_auto`, `foura_single`, `foura_proxy`, `foura_browser`) com os mesmos formatos de entrada, além de uma opção `offload_large` para lidar com respostas grandes de forma econômica em tokens. As diferenças: `foura_browser` não tem o campo `lean`, e `foura_proxy` ainda não aceita os campos de [localização de saída](#exit-location).

A FourA fornece quatro endpoints de requisição, cada um otimizado para um cenário diferente:

| Endpoint | Ideal para |
|----------|----------|
| `POST /auto/` | Busca inteligente. Você envia uma URL, a FourA escolhe o caminho mais econômico que funciona (proxy rotativo ou navegador, além de uma requisição direta com `forceProxy: false`) e memoriza o que funciona por host. |
| `POST /single/` | Requisições HTTP rápidas, páginas estáticas, APIs |
| `POST /proxy/` | Sites protegidos com rotação automática de proxy, delimitação opcional de país visível ao destino |
| `POST /browser/` | Páginas renderizadas em JavaScript, SPAs |
| `GET /profiles` | O catálogo de perfis de navegador para `single` e `proxy`. Público, sem API key. |

Para um guia detalhado sobre quando escolher cada um, consulte [Escolhendo o Endpoint Correto](https://foura.ai/docs/guides/choosing-task-type) e o [guia do Smart Fetch](https://foura.ai/docs/guides/smart-fetch).

## Restrições de URL de Destino

Destinos que resolvem para intervalos de IP privados, de loopback ou reservados (RFC 5735, RFC 6598, blocos reservados de IPv6) são recusados com um 400 antes que a requisição saia da FourA. Apenas nomes de host e IPs públicos são encaminhados.

```json
{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }
```

Um destino no próprio host de API da FourA (`eu.api.foura.ai` ou `api.foura.ai`) também é recusado com um 400, em todos os quatro endpoints, antes que qualquer item seja buscado ou cobrado. Uma URL com um espaço ou um caractere de controle dentro dela é recusada com um 400 no Single, Proxy e Auto da mesma forma; codifique o espaço como `%20` (o Browser faz a busca da mesma forma que o Chrome). A única página ali que a FourA busca é [`/inspect`](https://foura.ai/docs/api/inspect).

```json
{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }
```

---

## Smart Fetch (Auto)

`POST /api/auto/`

Você passa uma URL e regras opcionais de `validate`. O FourA percorre uma escala que otimiza custos (proxy rotativo, depois browser completo) e para no primeiro nível que retornar uma response aceita pelas suas regras. Com `forceProxy: false`, uma sondagem direta e econômica é executada primeiro. Em chamadas repetidas para o mesmo host, uma sessão ativa é reutilizada, tornando a segunda requisição mais barata.

Você não precisa ajustar retries, tamanhos de pool ou quantidade de proxies. O FourA aprende esses parâmetros por host.

### Request Body

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|-----------|------|----------|---------|-------------|
| `url` | string | Sim | - | URL de destino |
| `method` | string | Não | `"GET"` | Método HTTP |
| `headers` | [string, string][] | Não | - | Headers a serem enviados ao destino, como pares [nome, valor]. Todos os níveis os enviam, exceto o nível de browser. Um `Cookie` enviado por você chega ao site inalterado, e os cookies de uma sessão armazenada são adicionados ao lado dele apenas com os nomes que você não enviou. O `userAgent` de uma sessão armazenada substitui o seu `User-Agent`. O nível de proxy omite headers condicionais como `If-None-Match`, a menos que o seu `validate.status.accept` inclua `304`. |
| `data` | any | Não | - | Request body para requisições diferentes de GET |
| `validate` | object | Não | - | Critérios de sucesso, no mesmo formato do `validate` de Single Request (veja abaixo). Informe ao auto como é uma página real para que ele diferencie o conteúdo de uma página de desafio. |
| `returnSession` | boolean | Não | `true` | Inclui a sessão bem-sucedida (`proxy`, `cookies`, `userAgent`) na response para que você possa reutilizá-la via `/api/single/` ou `/api/browser/`. |
| `forceProxy` | boolean | Não | `true` | Sempre roteia por meio de um proxy rotativo. Defina como `false` para permitir a rota direta e mais barata quando o destino permitir (algumas defesas são mais rigorosas com tráfego de proxy). |
| `timeout_ms` | integer | Não | `120000` | Tempo total limite para toda a chamada, em milissegundos. Todas as subtentativas rodam dentro desse limite. Mínimo `5000`, máximo `180000`. |
| `ignoreProxies` | string[] | Não | - | IDs de proxy a serem evitados em cada subtentativa. Use os IDs retornados por responses anteriores de `/api/auto/` ou `/api/proxy/`. |
| `followRedirects` | integer | Não | `5` | Limite máximo de redirecionamentos nos níveis de menor custo da escala. `0` para desativar. Máximo de `20`. |
| `exitClass` | string | Não | - | `standard` ou `premium`, conforme documentado em [Proxy Request](#exitclass). `premium` permite que a chamada escale para uma saída premium quando o pool padrão não conseguir alcançar a página. Requer um plano que inclua saídas premium. Consulte [exitClass on Smart Fetch](#exitclass-on-smart-fetch). |

### Response

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

| Campo | Tipo | Descrição |
|-------|------|-------------|
| `status` | number | Status HTTP retornado pelo destino. |
| `data` | string | Corpo da response como texto, independentemente do degrau que o entregou. Uma página JSON retorna como texto JSON, portanto você mesmo faz o parse. |
| `headers` | array or object | Headers da response do destino. Degraus direct e proxy retornam um array de objetos de headers por salto; degraus browser retornam um objeto simples. |
| `meta.rung` | string | Qual degrau da escada entregou a response. Um de: `probe` (request direta econômica, apenas com `forceProxy: false`), `proxy` (proxy rotativo), `browser` (renderização completa em browser), `cache` (sessão ativa reutilizada), `warmup` (a página inicial do site foi acessada primeiro e seus cookies liberaram a URL profunda) ou `fail` (nenhum degrau gerou uma response aceita). |
| `meta.solved` | boolean | Se a página precisou de uma etapa extra (uma página de desafio) e ela foi concluída durante esta chamada. |
| `meta.attempts` | number | Subtentativas realizadas antes do sucesso. |
| `meta.credits` | number | Total de créditos gastos nesta chamada. Corresponde a `X-FourA-Credits`. |
| `meta.attemptsByEngine` | object | Requests enviadas para `single`, `proxy` e `browser`. Uma request de browser recusada pelo seu plano é contabilizada, pois foi enviada. |
| `meta.browserRequests` | number | Requests de browser que consumiram um slot do seu limite diário. Uma request de browser recusada pelo seu plano não consome nada. |
| `meta.exitClass` | string | Qual classe de saída entregou a resposta, presente quando a request especificou um `exitClass`: `premium` ou `standard`. O mesmo valor trafega no header de response `X-FourA-Exit-Class`. |
| `session.proxy` | string | ID codificado do proxy que entregou a response. Reutilize-o em uma request Single ou Browser. Presente quando `returnSession` for `true`. |
| `session.cookies` | array | Cookies para reproduzir, cada um com pelo menos `name` e `value`. Um degrau de browser retorna o cookie jar do browser. Um degrau de proxy, ou a sonda direta, retorna apenas os cookies que liberaram a página (como aqueles definidos pela página de verificação do site), nunca todos os cookies definidos pela página, portanto a lista pode estar vazia. Presente quando `returnSession` for `true`. |
| `session.userAgent` | string | User-Agent utilizado na tentativa bem-sucedida. Presente quando `returnSession` for `true`. |
| `error` | string | Mensagem de erro caso a chamada tenha falhado. |
| `attemptReport` | object | Em uma chamada com falha: as requests do mecanismo que retornaram sem a página, por causa. Consulte [Smart Fetch](https://foura.ai/docs/guides/smart-fetch). |

### Exemplo

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

### Notas

- O Auto é um coordenador. Ele chama Single, Proxy ou Browser internamente e encaminha sua chave de API para cada subchamada. A chamada Auto é uma única requisição no seu [Activity Log](https://foura.ai/docs/dashboard/activity-log) e na sua Overview, com a soma dos créditos das subchamadas; as subchamadas são listadas abaixo dela como tentativas e nunca contam como requisições próprias.
- Passe `validate.data.accept` com uma substring que apenas a página real contenha. Sem isso, o auto não consegue diferenciar um 200 real de um interstitial de desafio retornado com status 200.
- Uma página removida é a resposta do site, não uma recusa. Quando duas saídas retornam o mesmo `404` ou `410` e o seu `validate` não o aceita, a chamada termina com esse `status` e um `error` que começa com `the site answered`. Liste o status em `validate.status.accept` e o Auto entrega a primeira resposta com esse status que passe pelo restante do seu `validate`. O mesmo vale para qualquer outro status listado ali, exceto `403`, `429`, `503` e `202`, que os sites também enviam com uma página de desafio.
- `timeout_ms` limita a chamada inteira. Um primeiro acesso frio a um site protegido pode levar dezenas de segundos; sessões ativas reutilizadas geralmente terminam em menos de um segundo.

### exitClass no Smart Fetch

`exitClass` funciona no Smart Fetch como funciona no [Proxy Request](#exitclass): uma permissão, não uma instrução. O Auto tenta primeiro o pool padrão. Quando o pool padrão não consegue acessar a página e a requisição especifica `premium`, o Auto abre a página em um navegador por meio de uma saída premium. A sessão criada ali atende às suas chamadas posteriores para o mesmo site que também especifiquem `premium`; chamadas que não o especificam nunca a utilizam.

Ficar sem saldo não é um erro. Quando o tráfego premium do seu plano se esgota no período de faturamento, a chamada continua no pool padrão e `meta.exitClass` indica `standard`. Em um plano sem saídas premium, uma chamada que envia `exitClass: premium` é recusada com um `403` contendo `X-FourA-Limit: plan_limit_premium`, antes que qualquer trabalho seja executado.

O tráfego premium é medido da mesma forma que no Proxy Request. Uma página aberta em um navegador carrega mais elementos do que a página em si, portanto, uma página premium do Smart Fetch consome mais tráfego premium do que a mesma página obtida via Proxy Request. Para reduzir isso, uma página premium do Smart Fetch é carregada sem imagens, fontes e mídias, e sem scripts de provedores conhecidos de publicidade, analytics e consentimento.

---

## Single Request

`POST /api/single/`

Envia uma requisição HTTP com características de rede realistas semelhantes às de um navegador, sem iniciar um navegador real. Este é o endpoint mais rápido.

### Request Body

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|-----------|------|----------|---------|-------------|
| `method` | string | Sim | - | Método HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| `url` | string | Sim | - | URL de destino. Use `{ts}` em qualquer parte da URL para inserir o timestamp atual para quebra de cache. |
| `headers` | [string, string][] | Não | - | Headers personalizados como pares [nome, valor] |
| `unblocker` | boolean | Não | `true` | Envia headers realistas de navegador (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). Ativo por padrão. Defina `false` e o FourA não adicionará headers de navegador, apenas os que você fornecer. |
| `timeout_ms` | number | Não | 15000 | Timeout geral em ms (máx: 120000) |
| `connect_timeout_ms` | number | Não | 5000 | Timeout de conexão em ms |
| `accept_timeout_ms` | number | Não | 5000 | Timeout de aceite em ms (tempo de espera para aceitação da conexão) |
| `server_response_timeout_ms` | number | Não | 15000 | Timeout de resposta do servidor em ms (tempo de espera pelo primeiro byte) |
| `dns_cache_timeout_sec` | number | Não | 120 | TTL do cache DNS em segundos (máx: 240) |
| `followRedirects` | number | Não | desativado | Máximo de redirecionamentos a seguir (0-20). Omita para desativar. |
| `tryJsonData` | boolean | Não | false | Faz o parse do corpo da resposta como JSON, se possível |
| `returnBuffer` | boolean | Não | false | Retorna o buffer bruto em vez da string decodificada |
| `data` | any | Não | - | Corpo da requisição (string ou objeto, serializado automaticamente para JSON) |
| `proxy` | string | Não | - | ID de proxy de uma resposta anterior, para fixar a mesma saída. Repasse a string opaca exatamente como recebida. Um endereço de proxy bruto é rejeitado com `400 Invalid proxy format`. Alguns IDs não podem ser fixados: veja [Fixando uma saída](#pinning-an-exit). |
| `browser` | string | Não | Chrome | Navegador a apresentar: Chrome, Edge, Safari, Firefox ou Tor. Veja [Perfis de navegador](#browser-profiles). |
| `os` | string | Não | - | Sistema operacional a apresentar: Windows, macOS, Android ou iOS. O nome de uma família aceita qualquer uma de suas versões. |
| `version` | string | Não | newest | Versão do navegador a apresentar, conforme listada no catálogo. A correspondência mais recente vence quando várias forem compatíveis. |
| `profile` | string | Não | - | ID de perfil exato de `GET /api/profiles`, em vez dos três campos acima. |
| `validate` | object | Não | - | Regras de validação de resposta (veja abaixo) |

### Perfis de navegador

Por padrão, uma requisição apresenta o Google Chrome mais recente. Alguns destinos aceitam um navegador e recusam outro; portanto, `browser`, `os` e `version` refinam um catálogo de perfis medidos, e `profile` seleciona um por ID.

```json
{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}
```

Regras:

- A seleção requer `unblocker` (ativado por padrão). Com `unblocker` desativado, nenhum header de navegador é enviado, portanto a request é recusada em vez de ser aplicada pela metade.
- Quando vários perfis coincidem, a versão mais recente prevalece.
- Uma combinação que o catálogo não puder apresentar retorna um erro indicando o que está disponível, e um id `profile` desconhecido retorna `unknown profile '<id>'`. A request nunca é enviada como um navegador diferente.
- Os mesmos quatro campos estão disponíveis dentro do objeto `request` de `POST /proxy/`.

`GET /api/profiles` retorna o catálogo completo e não precisa de chave de API:

```json
{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}
```

`osFamily` é o valor para filtrar ao criar um seletor; `os` mantém o nome da versão para exibição.

### Regras de validação

O objeto `validate` permite definir condições de sucesso e falha. Se uma condição `fail` corresponder, a request será tratada como com falha. Se condições `accept` forem definidas, apenas as responses correspondentes serão tratadas como bem-sucedidas.

```json
{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}
```

| Campo | Tipo | Descrição |
|-------|------|-------------|
| `validate.status.accept` | number[] | Códigos de status HTTP a aceitar |
| `validate.status.fail` | number[] | Códigos de status HTTP a rejeitar |
| `validate.headers.accept` | object | A response passa quando pelo menos um par coincide em qualquer salto de redirecionamento. Nomes e valores coincidem sem diferenciar maiúsculas de minúsculas, em parte do texto. |
| `validate.headers.fail` | object | Pares chave-valor de header que acionam falha |
| `validate.data.accept` | string[] | A response passa quando o body contém pelo menos uma dessas strings |
| `validate.data.fail` | string[] | Strings no body da response que acionam falha |

### Exemplo

```bash
curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://example.com/products",
    "timeout_ms": 10000
  }'
```

Response:

```json
{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "...", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342
}
```

Quando o destino executa uma verificação de bot a caminho do corpo, a response também inclui um objeto `defense` informando o fornecedor e se a verificação foi superada:

```json
{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "cookie": "_I_=<clearance>"
  }
}
```

| Campo | Tipo | Descrição |
|-------|------|-------------|
| `status` | number | Código de status HTTP do destino |
| `headers` | array | Um objeto por salto de redirecionamento. Cada um possui um campo `result` com a linha de status mais todos os headers de resposta. Headers de múltiplos valores (`Set-Cookie`, `Link`, `WWW-Authenticate`) retornam como arrays de strings. |
| `data` | string/object | Corpo da resposta (JSON se `tryJsonData` for true) |
| `total_time` | number | Tempo total da request em segundos |
| `proxy` | string | ID codificado do proxy por onde a request passou (apenas quando um `proxy` foi fornecido na request). Reutilize-o em uma chamada seguinte para fixar a mesma saída. |
| `defense` | object | Presente quando o destino executou uma verificação de bot nesta request, ou quando uma nova tentativa com os próprios cookies do site produziu o corpo. `defense.solved` informa se uma verificação foi superada, `defense.retry` informa se uma nova tentativa obteve o conteúdo para você. Consulte [Site checks](https://foura.ai/docs/api/site-checks) para ver todos os campos e a lista completa de sistemas. |
| `error` | string | Mensagem de erro se a request falhar |

---

## Proxy Request

`POST /api/proxy/`

Encaminha sua request através de proxies rotativos com nova tentativa automática em caso de falha. Opcionalmente, restrinja a seleção a um conjunto de países de saída visíveis ao destino.

### Request Body

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|-----------|------|----------|---------|-------------|
| `request` | object | Sim | - | O corpo de uma única request (mesmos campos que Single Request acima) |
| `timeout_ms` | number | Não | 45000 | Timeout geral para todas as tentativas em ms (máx.: 120000) |
| `maxTries` | number | Não | 5 | O FourA para de iniciar novas tentativas assim que esse número falhar (máx.: 90). As tentativas rodam em paralelo, então algumas a mais podem ser concluídas além desse número. |
| `ignoreProxies` | string[] | Não | - | IDs de proxy para excluir da rotação (use IDs retornados por responses anteriores) |
| `exitCountries` | string[] | Não | - | Lista de permissão estrita de códigos de país de duas letras visíveis ao destino (ex.: `["CZ", "GB"]`). Os valores são formatados sem espaços extras, convertidos para maiúsculas e deduplicados. Saídas do pool padrão com país desconhecido são excluídas, e o pool padrão nunca recorre a um país não solicitado. Uma saída premium também sai de um dos países listados. |
| `exitClass` | string | Não | - | `standard` ou `premium`. `premium` permite que a request faça escalonamento para uma saída premium quando o pool padrão estiver enfrentando dificuldades em um destino protegido. Exige um plano que inclua saídas premium. |
| `exitState` | string | Não | - | Região de onde a saída parte. Requer `exitClass: premium` e exatamente um país em `exitCountries`. Consulte [Exit location](#exit-location). |
| `exitCity` | string | Não | - | Cidade de onde a saída parte. Requer `exitClass: premium` e exatamente um país em `exitCountries`. |
| `exitAsn` | string | Não | - | Rede de onde a saída parte, por número de AS, por exemplo `8866`. Requer `exitClass: premium` e exatamente um país em `exitCountries`. |
| `exitOs` | string | Não | - | `windows`, `android`, `ios` ou `mac`: o tipo de dispositivo ao qual o endereço pertence. Requer `exitClass: premium`. |
| `exitLifetimeMin` | integer | Não | - | Minutos durante os quais a saída mantém seu endereço, `3` a `1440`. Requer `exitClass: premium`. |

### Escopo de exitCountries

A seleção usa os metadados de país visíveis ao destino mais recentes disponíveis, normalmente atualizados em cerca de dez minutos. Não é uma consulta de geolocalização em tempo real durante a request. Não deduza o país de atendimento a partir do endereço de host do proxy.

Se o pool atual não tiver correspondência para os países solicitados e a request não tiver especificado `exitClass: premium`, a response retorna HTTP 200 com um envelope de erro:

```json
{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}
```

Mantenha o escopo solicitado e tente novamente mais tarde. Altere ou amplie o escopo apenas quando a exigência de país do seu fluxo de trabalho mudar explicitamente.

### Exemplo

```bash
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 3,
    "exitCountries": ["CZ", "GB"],
    "request": {
      "method": "GET",
      "url": "https://example.com/prices"
    }
  }'
```

Response:

```json
{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "A1B2C3",
  "exitCountry": "CZ",
  "total": 2.341
}
```

| Campo | Tipo | Descrição |
|-------|------|-------------|
| `proxy` | string | Identificador codificado do proxy usado. Reutilize-o em uma requisição Single ou Browser passando-o como o campo `proxy`, ou ignore-o na próxima requisição Proxy via `ignoreProxies`. |
| `exitCountry` | string | Código de país de duas letras visível pelo destino do proxy que atendeu à requisição. Presente apenas quando a requisição definiu `exitCountries`, independentemente da classe de saída que a atendeu. Sempre verifique se é um dos códigos solicitados antes de confiar na resposta. |
| `exitClass` | string | Qual classe de saída atendeu a esta requisição, presente em uma resposta bem-sucedida quando a requisição especificou uma. `premium` significa que uma saída premium retornou o corpo; `standard` significa que o pool padrão o fez. Uma chamada que falhou não entregou nada, portanto não contém `exitClass`; leia seu `attemptReport` para saber o que as tentativas encontraram. |
| `total` | number | Duração total de relógio externo em segundos (float). Inclui a seleção de proxy, novas tentativas e a tentativa bem-sucedida. `total_time` é apenas a requisição interna; `total` é sempre >= `total_time`. |
| `profile` | string | O perfil de navegador escolhido pela rotação, presente **apenas** quando não foi o solicitado por você. A ausência indica que a requisição foi enviada exatamente como escrita. Passe o id de volta como `profile` em chamadas seguintes para manter o navegador que funcionou. |
| `error` | string | Mensagem de erro caso a requisição tenha falhado. Em caso de não correspondência de escopo, `code` é `no_eligible_proxy` e `details.exitCountries` reflete o escopo normalizado. |
| `attemptReport` | object | Presente em **toda** chamada de Proxy com falha. Contabiliza o que as tentativas encontraram, para que um pool bloqueado, um pool inativo e uma regra `validate` que nunca correspondeu não pareçam o mesmo erro. Veja abaixo. |
| `request` | object | Presente em uma chamada de Proxy com falha: a requisição que o FourA executou, com padrões preenchidos e seus `ignoreProxies` conforme você os enviou. |

Todos os campos de resposta de Single Request também estão incluídos, com `defense` entre eles: uma tentativa de proxy que encontrou uma verificação de bot a relata da mesma forma que o Single.

### Por que uma Chamada de Proxy Falhou

`Download maxTry limit reached` tem a mesma leitura independentemente de como as tentativas ocorreram, portanto toda resposta de Proxy com falha traz um `attemptReport` ao lado do erro:

```json
{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
```

| Campo | Tipo | Descrição |
|-------|------|-------------|
| `total` | integer | Tentativas realizadas |
| `noResponse` | integer | O exit nunca respondeu, portanto o site nunca foi alcançado |
| `defense` | integer | O site respondeu e uma verificação de bot foi detectada nessa resposta |
| `contentRejected` | integer | HTTP 200, sem verificação de bot, rejeitado apenas pelo seu `validate.data` |
| `statusRejected` | integer | O site respondeu, sem verificação de bot, rejeitado pelo seu `validate.status` |
| `other` | integer | Respondeu, e nenhum dos casos acima |
| `vendors` | string[] | Provedores de verificação de bot detectados em qualquer parte da tarefa |
| `profilesTried` | string[] | Perfis de navegador enviados pela tarefa, em ordem de primeiro uso. `default` significa que sua request saiu intacta. |
| `summary` | string | Uma frase gerada a partir das contagens, segura para log |

A string `error` não foi alterada, portanto um cliente que faz correspondência com ela continua funcionando. O que fazer sobre cada contagem: [Por Que uma Proxy Request Esgotou as Tentativas](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### exitClass

Alguns alvos recusam os exits no pool padrão, não importa quantos sejam tentados. `exitClass: premium` informa ao Proxy que ele pode escalar tal request para um **exit premium** além do pool padrão, em vez de apenas rotacionar dentro dele.

```json
{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}
```

Três pontos são importantes antes de enviar a requisição.

**É uma permissão, não uma instrução.** O pool padrão ainda concorre pela resposta e geralmente vence. Uma saída premium entra apenas quando o pool esgota um limite curto na requisição ou o alvo a recusa visivelmente. Uma requisição atendida pelo pool padrão antes de qualquer tentativa com saída premium é um sucesso normal e não consome tráfego premium. Quando uma saída premium é tentada, seu tráfego é contabilizado, conforme descrito abaixo.

**Uma saída premium permanece dentro de `exitCountries`.** Com uma lista de países, a saída premium parte de um desses países e `exitCountry` na resposta informa qual foi, assim como no pool padrão.

**A resposta informa o que realmente atendeu você.** Ao especificar uma classe, a resposta retorna `exitClass`:

```json
{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}
```

`premium` significa que uma saída premium retornou o corpo. `standard` significa que o pool padrão retornou, que é a mesma resposta obtida quando uma saída premium não pôde ser obtida e quando o tráfego premium incluído no seu plano (mais qualquer quantidade adquirida adicionalmente) for consumido no período de faturamento. Nenhum dos dois é um erro, e você pode reconciliar seu tráfego premium com base nesses valores por request, em vez de usar um valor mensal. O mesmo valor é enviado no header de resposta `X-FourA-Exit-Class` (consulte [Response Headers](https://foura.ai/docs/api/response-headers#x-foura-exit-class)).

**O tráfego premium é medido na rede.** Uma tentativa premium contabiliza o que enviou e recebeu ao trafegar pela rede, comprimido e criptografado durante o trajeto, quer tenha retornado a sua página ou não. Uma tentativa que ainda estava em execução quando outra saída respondeu é interrompida imediatamente, e o tráfego transferido até esse momento também é contabilizado. O tráfego premium é contabilizado na sua franquia premium e também dentro da sua largura de banda total: são os mesmos bytes, reportados duas vezes, nunca somados. Quando uma saída premium entrega a página, o tráfego dela corresponde a todo o tráfego da request, portanto a página não é contabilizada novamente como tráfego padrão. Sua página [Usage & Limits](https://foura.ai/docs/dashboard/quota) mostra o tráfego total, a parcela premium dele e a franquia premium usada como referência de medição.

Omitir o campo e enviar `standard` mantêm a request no pool padrão: apenas `premium` permite uma saída premium. Uma request bem-sucedida que especifica uma classe recebe `exitClass` de volta na resposta, e uma request que omite o campo não o recebe.

**Ficar sem franquia não é um erro.** Uma request que especifica `premium` após a franquia ter sido consumida continua funcionando: o pool padrão a processa e a resposta indica `standard`. A única exceção é uma request que especifica uma [exit location](#exit-location): o pool padrão não pode atendê-la, portanto ela é recusada.

`exitClass: premium` exige um plano que inclua saídas premium. Em um plano sem elas, a request nunca consome uma saída premium: ela é recusada com um erro 403 contendo `X-FourA-Limit: plan_limit_premium` (consulte [Rate Limits](https://foura.ai/docs/api/rate-limits#plan-limits)), antes que qualquer ação seja executada.


### Localização de saída

Uma saída premium pode partir de um local dentro de um país e manter o endereço dela pelo tempo que você precisar:

```json
{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}
```

A response informa a saída e o país de onde ela partiu:

```json
{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}
```

Esse ID `proxy` mantém tudo isso. Passe-o para Single ou Browser e a request sairá do mesmo local, sem nenhum outro campo ao lado. Veja [Fixando um Exit](#pinning-an-exit).

Regras:

- Qualquer um entre `exitState`, `exitCity`, `exitAsn`, `exitOs` e `exitLifetimeMin` envia a request apenas por exits premium. O pool padrão não recebe nenhuma tentativa, pois não pode atendê-los.
- Eles exigem `exitClass: premium`. Sem isso, a request é recusada com um 400 que informa o campo.
- `exitState`, `exitCity` e `exitAsn` existem dentro de um único país, portanto exigem exatamente um país em `exitCountries`. `exitOs` e `exitLifetimeMin` funcionam com vários: o exit seleciona um deles, e o `exitCountry` na response indica qual foi.
- `exitState`, `exitCity`, `exitAsn` e `exitOs` exigem um plano com segmentação geográfica além de exits premium.
- Sem tráfego premium restante, a request é recusada com um 403 contendo `X-FourA-Limit: plan_limit_premium`, pois o pool padrão não pode atendê-la.
- Se nenhum exit premium responder para esse local, a response será um envelope de erro como o apresentado em [escopo de exitCountries](#exitcountries-scoping), com o erro `No premium exit answered for this request` e `code: no_eligible_proxy`. `details.exitCountries` estará presente caso você tenha enviado uma lista de países.

Os termos são os mesmos aceitos pela [porta de proxy](https://foura.ai/docs/api/proxy-port) para `state`, `city`, `asn` e `os`.

### Rotação de Perfil de Navegador

O Proxy faz a rotação de exits. Quando um site recusa o navegador apresentado pela FourA em vez do exit de onde ele partiu, o Proxy também alterna para outra família de navegadores do catálogo. Ele não adiciona tentativas: a rotação altera o que uma nova tentativa envia, nunca se ela acontece ou não.

O Proxy também memoriza, temporariamente, a família que um site aceitou por último, permitindo que uma chamada posterior ao mesmo site comece nessa família em vez da padrão. A response informa isso em `profile`, assim como faz para qualquer família escolhida pela rotação.

Um `profile`, `browser`, `os` ou `version` explícito no seu `request` interno nunca é sobrescrito, assim como uma request que contenha seu próprio header `User-Agent` ou `Cookie`, pois uma autorização está vinculada à assinatura que a obteve.

---

## Request do Browser

`POST /api/browser/`

Abre a sua URL em uma instância do navegador Chrome. A página carrega, o JavaScript executa e você recebe o HTML totalmente renderizado, além do cookie jar.

### Corpo da Request

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|-----------|------|----------|---------|-------------|
| `url` | string | Sim | - | URL de destino |
| `headers` | object | Não | - | Headers personalizados como pares chave-valor |
| `cookies` | array | Não | - | Cookies para definir: `[{name, value, domain?}]` |
| `userAgent` | string | Não | - | String de User-Agent personalizada |
| `unblocker` | boolean | Não | `true` | Conclui a verificação solicitada por uma página antes de carregar (uma página de desafio ou barreira similar). Ativado por padrão. Defina `false` para renderizar exatamente o que a página retornar, incluindo uma página de desafio. |
| `proxy` | string | Não | - | ID do proxy de uma resposta anterior, para fixar a mesma saída. Reenvie a string opaca exatamente como recebida. Um endereço de proxy bruto é rejeitado com `400 Invalid proxy format`. |
| `timeout_ms` | number | Não | 30000 | Tempo limite de carregamento da página em ms (máx: 120000) |
| `checkStatus` | number | Não | - | Status HTTP esperado (a requisição falha se for diferente) |
| `checkText` | string | Não | - | Texto que deve aparecer na página renderizada |
| `lean` | boolean | Não | `false` | Omite imagens, fontes e mídias, além de requisições para serviços conhecidos de publicidade, analytics, consentimento e redes sociais. A página em si, seus scripts e estilos próprios e tudo o que uma etapa de verificação precisa continuam carregando. Use para reduzir o tráfego consumido pela página, por exemplo, por meio de uma saída premium fixada. |

### Alinhando o relógio do navegador à saída

Uma página pode ler o fuso horário do navegador e compará-lo com o país do IP que ela detecta. Uma divergência é um dos sinais mais simples para um detector de bots identificar, e não custa nada para você remover.

Você não precisa fazer nada. O FourA lê o país a partir do ID `proxy` e o navegador informa o fuso horário correspondente a ele.

- Trata-se do país de **saída**, ou seja, o país que o destino enxerga, e não onde o proxy está hospedado. Os dois divergem com frequência suficiente para fazer diferença.
- Quando o FourA não sabe o país de saída, ele mantém o relógio original do navegador em vez de tentar adivinhar. Uma saída premium tem país conhecido quando você solicita um via `exitCountries` no [Proxy Request](#exit-location).
- Apenas o relógio acompanha o país. O `Accept-Language` e o conteúdo servido pelo site permanecem intocados, evitando que a página mude de idioma inesperadamente.

### O parâmetro `userAgent`

Envie `userAgent` e essa string exata será vista pela página, por seus workers e pelo destino. O FourA também deriva os client hints correspondentes a partir dela (`sec-ch-ua`, `sec-ch-ua-platform`, `navigator.platform` e os valores de alta entropia solicitados nominalmente por um detector), para que a requisição não aponte um navegador no header e outro no JavaScript.

O `userAgent` retornado na resposta é aquele que foi apresentado. Isso é importante ao reutilizar uma liberação: um cookie `cf_clearance` fica vinculado à saída e ao User-Agent que o obteve, portanto envie de volta a string informada na resposta, e não a que você supõe ter sido usada. Consulte [Site checks](https://foura.ai/docs/api/site-checks).

Envie uma string que não seja Chromium (um User-Agent do Firefox, por exemplo) e ela será apresentada como está, sem nenhuma lista de marcas Chromium anexada.

### Exemplo

```bash
curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'
```

Response:

```json
{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]}
}
```

| Campo | Tipo | Descrição |
|-------|------|-------------|
| `status` | number | Código de status HTTP do destino |
| `headers` | object | Headers da response |
| `body` | string or object | Conteúdo da página totalmente renderizado. String HTML quando o content-type for HTML; object quando a página retornou JSON e foi analisada automaticamente. |
| `cookies` | array | Objetos completos de cookie da página. Cada cookie inclui `name`, `value`, `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite` e outras propriedades de cookie. |
| `userAgent` | string | User-Agent do navegador utilizado |
| `defenseSolved` | boolean | `true` se uma defesa contra bots foi encontrada e genuinamente superada nesta chamada, `false` caso contrário. Define se a chamada custa 5 ou 10 créditos. |
| `defenses` | object | `present` lista todos os provedores reconhecidos durante o carregamento da página, `cleared` lista aqueles cuja liberação a página final mantém. Um provedor pode aparecer em `present` e nunca em `cleared`. Consulte [Verificações de sites](https://foura.ai/docs/api/site-checks). |
| `proxy` | string | ID codificado do proxy pelo qual a request passou (apenas quando um `proxy` foi fornecido na request). Reutilize-o em chamadas seguintes para manter a mesma saída. |
| `error` | string | Mensagem de erro se a request falhar |

---

## Fixando uma Saída

Um valor `proxy` em uma request Single ou Browser fixa a saída utilizada por uma chamada anterior. Envie de volta o ID opaco exatamente como recebido, nunca um endereço de proxy. Um ID de uma request de Proxy que especificou um país, um local ou uma duração mantém essas definições, de modo que a request fixada não precisa de nenhum outro campo.

Três valores são recusados, todos com 400:

| Erro | Significado |
|-------|---------|
| `Invalid proxy format` | O valor não é um ID emitido pela FourA. Um endereço de proxy bruto se enquadra aqui. |
| `Proxy not found` | O ID foi decodificado, mas não resolve mais para uma saída ativa. Obtenha um novo a partir de uma nova chamada. |
| `Managed exit: this proxy id cannot be pinned to a request` | A saída existe, mas não é uma que a FourA manterá aberta para uma request nomeada. O ID de uma saída premium se enquadra aqui quando o seu plano não tiver mais tráfego premium disponível. Reutilize a sessão em que ele foi retornado ou execute a chamada por meio de `POST /api/proxy/` e utilize a saída que ele escolher. |

Uma saída premium fixada é contabilizada como tráfego premium. A response inclui `X-FourA-Exit-Class: premium` para que você possa visualizá-lo por request, e o tráfego transportado pela saída conta para o tráfego premium na sua página de [Uso e Limites](https://foura.ai/docs/dashboard/quota), bem como para a sua largura de banda total, quer o site tenha retornado a página desejada ou não. A fixação exige saídas premium no seu plano e franquia disponível; caso contrário, o ID será recusado com o erro 400 de saída gerenciada acima.

## Códigos de Status HTTP

| Código | Significado |
|------|---------|
| 200 | Request concluída (verifique o `status` interno para a resposta de destino) |
| 400 | Corpo de request inválido, parâmetros inválidos, IP de destino em faixa privada/reservada, destino no próprio host de API do FourA, URL com espaço não codificado (Single, Proxy, Auto) ou ID de proxy que não pode ser fixado. No Single, Proxy e Browser, um campo que falha na validação é identificado em: `Invalid request: <field>: <reason>`, até cinco campos. Não cobrado. O Auto responde ao mesmo erro com HTTP 200 e `status: 400` no corpo. |
| 401 | API key ausente ou inválida |
| 403 | O endpoint ou um parâmetro não faz parte do seu plano. `X-FourA-Limit` indica: `plan_limit_feature` ou `plan_limit_premium`. |
| 404 | `Not Found`: não há endpoint nesse caminho. |
| 413 | O corpo JSON da request tem mais de 100 KB. A resposta não é JSON e não contém `X-FourA-Request-Id`. |
| 429 | Limite do plano (`X-FourA-Limit` definido) ou limite compartilhado por minuto da plataforma (sem header) |
| 500 | Erro interno do servidor |
| 502 | `Upstream unavailable`: o FourA não conseguiu conectar ao engine. `Malformed JSON from backend`: o engine respondeu, mas o FourA não conseguiu ler a resposta. Tente novamente. |
| 503 | Serviço temporariamente desativado ou com capacidade esgotada, `API key check temporarily unavailable` quando o FourA não pôde validar sua chave momentaneamente (tente novamente após `Retry-After`), ou `Backend service unavailable` durante o reinício de um engine. No Browser, uma página aguarda até 10 segundos por um browser livre quando todos estiverem ocupados, retornando `Backend service unavailable` se nenhum for liberado a tempo. |
| 504 | `Upstream timeout`. O engine não concluiu o processamento dentro do tempo limite desta request. Aumente `timeout_ms` ou tente novamente. |

## Próximos passos

- [Smart Fetch (Auto)](https://foura.ai/docs/guides/smart-fetch): Quando deixar o FourA escolher o caminho para você
- [Escolhendo o endpoint correto](https://foura.ai/docs/guides/choosing-task-type): Quando escolher Single, Proxy ou Browser manualmente
- [Autenticação](https://foura.ai/docs/getting-started/authentication): Gerencie suas API keys
- [Tratamento de erros](https://foura.ai/docs/api/errors): Trate erros de forma eficiente
- [Verificações de site](https://foura.ai/docs/api/site-checks): Leia o campo `defense` e repita uma liberação
- [Por que uma request de Proxy esgotou as tentativas](https://foura.ai/docs/troubleshooting/proxy-attempt-report): Leia `attemptReport` e tome medidas
- [Rate limits](https://foura.ai/docs/api/rate-limits): Entenda os limites de requests
- [Início rápido](https://foura.ai/docs/getting-started/quick-start): Sua primeira request em 30 segundos
