Referência de Endpoints da API

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 sua chave de API no header X-API-Key:

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. As chaves usam o prefixo pk_live_.

Response Headers

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

Header	Value	Description
`X-FourA-Request-Id`	UUID	ID exclusivo atribuído à request. Retornado em todas as responses, 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 da atribuição de um ID. Registre isso em seus logs.
`X-FourA-Credits`	integer	Créditos gastos nesta request. Retornado em todas as responses que atingiram um engine, seja com sucesso ou falha (o trabalho foi executado em ambos os casos). Uma chamada recusada pelo FourA antes da execução de qualquer engine (chave ausente ou inválida, limite de plano ou plataforma, destino ou proxy ID recusado) não contém créditos. Consulte Request Outcomes para saber quais resultados são faturáveis.

O mesmo request ID serve como chave para a pré-visualização do payload de request e response no Activity Log do Dashboard (mantido por 24 horas, últimas 200 por chave). Assim, você pode consultar a request exata mais tarde e reproduzi-la a partir de Activity direto no Playground. Inclua-o ao entrar em contato com o suporte para identificar a request em segundos.

$ 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 para a lista completa e dicas de uso.

Endpoints

Usando esses endpoints via MCP? O servidor @fouradata/mcp encapsula todos os quatro endpoints como ferramentas nativas do MCP (foura_auto, foura_single, foura_proxy, foura_browser) com os mesmos formatos de entrada, além de uma opção offload_large para tratamento de respostas grandes otimizado para tokens.

A FourA fornece quatro endpoints de request, cada um otimizado para um cenário diferente:

Endpoint	Melhor para
`POST /auto/`	Smart fetch. Você envia uma URL, a FourA escolhe o caminho mais barato que funciona (direto, proxy rotativo ou navegador) e memoriza o que funciona por host.
`POST /single/`	Requests HTTP rápidos, páginas estáticas, APIs
`POST /proxy/`	Sites protegidos com rotação automática de proxy, definição opcional de país visível ao alvo
`POST /browser/`	Páginas renderizadas em JavaScript, SPAs
`GET /profiles`	O catálogo de perfis de navegador para `single` e `proxy`. Público, sem chave de API.

Para uma explicação mais detalhada sobre quando escolher cada um, consulte Escolhendo o Endpoint Correto e o Guia de Smart Fetch.

Restrições de URL de Destino

Destinos que resolvem para faixas de IP privadas, de loopback ou reservadas (RFC 5735, RFC 6598, blocos reservados de IPv6) são recusados com um erro 400 antes que o request saia da FourA. Apenas hostnames e IPs públicos são encaminhados.

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

Smart Fetch (Auto)

POST /api/auto/

Você passa uma URL e regras validate opcionais. O FourA percorre uma escala com foco em custo (sonda direta econômica, proxy rotativo, navegador completo) e para no primeiro nível que retornar uma resposta aceita pelas suas regras. Em chamadas repetidas para o mesmo host, uma sessão ativa é reutilizada, tornando a segunda requisição econômica.

Você não precisa ajustar retentativas, tamanhos de pool ou contagens de proxy. 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 personalizados como pares [nome, valor]
`data`	any	Não	-	Corpo da requisição para requisições que não sejam GET
`validate`	object	Não	-	Critérios de sucesso, mesmo formato do `validate` de Single Request (veja abaixo). Informe ao modo auto como é uma página real para que ele consiga diferenciar o conteúdo de uma página de desafio.
`returnSession`	boolean	Não	`true`	Inclui a sessão bem-sucedida (`proxy`, `cookies`, `userAgent`) na resposta 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 o caminho direto mais econômico quando o destino permitir (algumas defesas são mais rígidas com tráfego de proxy).
`timeout_ms`	integer	Não	`120000`	Limite de tempo total para toda a chamada, em milissegundos. Todas as subtentativas são executadas dentro desse limite. Mínimo `5000`, máximo `180000`.
`ignoreProxies`	string[]	Não	-	IDs de proxy para evitar em cada subtentativa. Use os IDs retornados por respostas anteriores de `/api/auto/` ou `/api/proxy/`.
`followRedirects`	integer	Não	`5`	Máximo de redirecionamentos a seguir nos níveis econômicos da escala. `0` para desativar. Máximo `20`.

Response

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

Campo	Tipo	Descrição
`status`	number	Status HTTP retornado pelo destino.
`data`	string	Corpo da response como texto, independentemente do degrau que a entregou. Uma página JSON retorna como texto JSON, portanto faça o parse manualmente.
`headers`	array or object	Headers da response de destino. Degraus Single e proxy retornam um array de objetos de header por salto; degraus de browser retornam um objeto simples.
`meta.rung`	string	Qual degrau da escada entregou a response. Um de: `probe` (request direta e econômica), `proxy` (proxy rotativo), `browser` (renderização completa em browser), `cache` (sessão ativa reproduzida), `warmup` (a página inicial do site foi acessada primeiro e seus cookies abriram a URL profunda) ou `fail` (nenhum degrau produziu uma response aceita).
`meta.solved`	boolean	Indica se a página exigiu uma etapa extra (uma página de desafio) e ela foi concluída durante esta chamada.
`meta.attempts`	number	Subtentativas feitas antes do sucesso.
`meta.credits`	number	Total de créditos gastos nesta chamada. Corresponde a `X-FourA-Credits`.
`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 da tentativa vencedora. Presente quando `returnSession` for `true`.
`session.userAgent`	string	User-Agent utilizado na tentativa vencedora. Presente quando `returnSession` for `true`.
`error`	string	Mensagem de erro caso a chamada tenha falhado.

Exemplo

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

Observações

O Auto funciona como um coordenador. Ele chama Single, Proxy ou Browser internamente e encaminha sua chave de API para cada subchamada. A chamada Auto conta como uma única request no seu Activity Log e na sua Overview, somando os créditos das suas subchamadas; as subchamadas são listadas abaixo dela como tentativas e nunca contam como requests 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 uma página intermediária de desafio retornada com status 200.
timeout_ms limita a chamada completa. Um primeiro acesso a frio em um site protegido pode levar dezenas de segundos; sessões ativas reutilizadas geralmente terminam em menos de um segundo.

Single Request

POST /api/single/

Envia uma HTTP request 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 cache-busting.
`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` para enviar uma assinatura de cliente simples.
`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 pelo aceite 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	disabled	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 buffer bruto em vez de 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. Devolva 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 Pinning an exit.
`browser`	string	Não	Chrome	Navegador a apresentar: Chrome, Edge, Safari, Firefox ou Tor. Veja Browser profiles.
`os`	string	Não	-	Sistema operacional a apresentar: Windows, macOS, Android ou iOS. Um nome de 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 se aplicarem.
`profile`	string	Não	-	ID exato do perfil 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, então browser, os e version refinam um catálogo de perfis medidos, e profile seleciona um por ID.

{
  "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 correspondem, a versão mais recente vence.
Uma combinação que o catálogo não pode apresentar retorna um erro indicando o que está disponível. 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 API key:

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

osFamily é o valor para filtrar ao criar um seletor; os mantém o nome do lançamento para exibição.

Regras de validação

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

{
  "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	Pares chave-valor de header que devem estar presentes
`validate.headers.fail`	object	Pares chave-valor de header que causam falha
`validate.data.accept`	string[]	Strings que devem aparecer no corpo da resposta
`validate.data.fail`	string[]	Strings no corpo da resposta que causam falha

Exemplo

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:

{
  "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,
  "proxy": "A1B2C3"
}

Quando o destino executa uma verificação de bot a caminho do body, a response também traz um objeto defense indicando o fornecedor e se a verificação foi superada:

{
  "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 e todos os headers de resposta. Headers com 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 pelo qual 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 cookies do próprio site gerou o corpo. `defense.solved` indica se a verificação foi superada, `defense.retry` indica se uma nova tentativa obteve o conteúdo para você. Consulte 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 por proxies rotativos com repetição automática em caso de falha. Opcionalmente, restrinja a seleção a um conjunto de países de saída visíveis pelo destino.

Request Body

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`request`	object	Sim	-	Um corpo de request único (mesmos campos de Single Request acima)
`timeout_ms`	number	Não	45000	Tempo limite geral para todas as tentativas em ms (máx.: 120000)
`maxTries`	number	Não	5	Máximo de tentativas de rotação de proxy (máx.: 90)
`ignoreProxies`	string[]	Não	-	IDs de proxy a serem excluídos da rotação (use IDs retornados por respostas anteriores)
`exitCountries`	string[]	Não	-	Lista de permissões estrita de códigos de país de duas letras visíveis pelo destino (ex.: `["CZ", "GB"]`). Os valores têm espaços removidos, são convertidos para maiúsculas e deduplicados. Proxies com saídas desconhecidas são excluídos e a request nunca recorre a um país não solicitado.
`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 com dificuldades em um destino protegido. Exige um plano que inclua saídas premium.

Escopo de exitCountries

A seleção usa os metadados mais recentes disponíveis de países visíveis pelo destino, 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, a resposta retorna HTTP 200 com um envelope de erro:

{
  "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 apenas quando a exigência de país do seu fluxo de trabalho mudar explicitamente.

Exemplo

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:

{
  "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 utilizado. 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 ao destino referente ao proxy que atendeu à requisição. Presente apenas quando a requisição definiu `exitCountries`. 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 atendeu a nada, portanto não contém `exitClass`; leia seu `attemptReport` para saber o que as tentativas encontraram.
`total`	number	Duração total de tempo de relógio em segundos (float). Inclui a seleção de proxy, retentativas 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 que você solicitou. Ausente significa 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 escopo não encontrado, `code` é `no_eligible_proxy` e `details.exitCountries` reflete o escopo normalizado.
`attemptReport`	object	Presente em toda chamada Proxy com falha. Contabiliza o que as tentativas encontraram, evitando que um pool bloqueado, um pool inativo e uma regra `validate` que nunca correspondeu apareçam todos como o mesmo erro. Veja abaixo.

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

Por que uma chamada Proxy falhou

Download maxTry limit reached mantém a mesma leitura independentemente de como foram as tentativas, portanto toda resposta Proxy com falha inclui um attemptReport ao lado do erro:

{
  "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	A saída 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 que a tarefa enviou, na ordem do primeiro uso. `default` significa que sua request foi enviada sem alterações.
`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 nela continua funcionando. O que fazer sobre cada contagem: Por que uma Proxy Request esgotou as tentativas.

exitClass

Alguns alvos recusam as saídas no pool padrão, não importa quantas sejam tentadas. exitClass: premium informa ao Proxy que ele pode escalar essa request para uma premium exit além do pool padrão, em vez de apenas rotacionar dentro dele.

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

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

É uma permissão, não uma instrução. O pool padrão ainda compete para responder, e geralmente ele vence. Uma saída premium só entra em ação quando o pool esgota um curto orçamento na requisição ou quando o destino a recusa abertamente. Uma requisição respondida pelo pool padrão antes de qualquer tentativa com saída premium é um sucesso normal e não consome tráfego premium. Uma vez tentada uma saída premium, o tráfego dela é contabilizado, conforme descrito abaixo.

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

{
  "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 também é a resposta que você recebe 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 adicional comprada) foi esgotado 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 response X-FourA-Exit-Class (consulte Response Headers).

O tráfego premium é medido na rede. Uma tentativa premium contabiliza o que enviou e recebeu ao trafegar pela rede, compactado e criptografado durante o trajeto, quer tenha retornado sua página ou não. Uma tentativa que ainda estava em execução quando outra saída respondeu é interrompida imediatamente e não é contabilizada. O tráfego premium conta para o seu limite premium e também dentro da sua largura de banda total: os mesmos bytes, reportados duas vezes, nunca somados. Quando uma saída premium entrega a página, o tráfego dela é todo o tráfego do request, portanto a página não é contabilizada novamente como tráfego padrão. Sua página Usage & Limits mostra o tráfego total, a parcela premium dele e o limite premium usado como referência.

Omitir o campo não é o mesmo que enviar standard. Omiti-lo deixa a decisão indefinida; enviar standard diz explicitamente que este request nunca deve escalar, que é a forma de manter um job específico totalmente fora do tráfego premium.

Ficar sem saldo não é um erro. Um request que especifica premium após o término da franquia continua funcionando: o pool padrão o atende e a response informa standard. Nenhum job é interrompido por franquia esgotada.

exitClass: premium precisa de um plano que inclua saídas premium. Em um plano sem elas, o request nunca consome uma saída premium: ele é recusado com um 403 contendo X-FourA-Limit: plan_limit_premium (consulte Rate Limits) ou atendido pelo pool padrão com exitClass: standard na response. Trate ambos.

Browser Profile Rotation

O Proxy faz a rotação de saídas. Quando um site recusa o navegador apresentado pelo FourA em vez da saída de onde ele veio, o Proxy também alterna para outra família de navegadores do catálogo. Isso não adiciona nenhuma tentativa: a rotação altera o que uma nova tentativa envia, nunca se ela acontece.

O Proxy também memoriza, por algum tempo, a família aceita pela última vez por um site, para que uma chamada posterior ao mesmo site possa começar nessa família em vez da padrão. A response informa o nome dela em profile, como faz para qualquer família escolhida pela rotação.

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

Browser Request

POST /api/browser/

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

Request Body

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 pela página antes do carregamento (uma página de desafio ou barreira semelhante). Ativado por padrão. Defina `false` para renderizar o que a página retornar, incluindo uma página de desafio, exatamente como veio.
`proxy`	string	Não	-	ID do proxy de uma response anterior, para fixar a mesma saída. Envie a string opaca de volta exatamente igual. Um endereço de proxy bruto é rejeitado com `400 Invalid proxy format`.
`exitCountry`	string	Não	-	Código de país de duas letras (ISO 3166-1 alpha-2) do país por onde a request sai. Define o relógio do navegador para um fuso horário correspondente. Veja Como sincronizar o relógio do navegador com a saída.
`timeout_ms`	number	Não	30000	Timeout de carregamento da página em ms (máx: 120000)
`checkStatus`	number	Não	-	Status HTTP esperado (a request falha se for diferente)
`checkText`	string	Não	-	Texto que deve aparecer na página renderizada

Como sincronizar o relógio do navegador com a 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 que um detector de bots usa, e não custa nada eliminá-la.

Defina exitCountry para o país por onde seu tráfego sai e o navegador informará um fuso horário correspondente:

{
  "url": "https://example.com",
  "proxy": "A1B2C3",
  "exitCountry": "BR"
}

Regras:

O valor é o país de saída, ou seja, o país que o destino vê, não onde o proxy está hospedado. Os dois divergem com frequência suficiente para importar.
Omita-o e o FourA usará o país de saída quando souber de um, caso contrário deixará o relógio do navegador inalterado em vez de tentar adivinhar.
Um código de país que o FourA não reconhece é tratado da mesma forma que omitir o campo. Não é um erro.
Apenas o relógio segue o país. O Accept-Language e o conteúdo que o site fornece permanecem intactos, portanto uma página não mudará de idioma inesperadamente para você.

O parâmetro `userAgent`

Envie userAgent e essa string exata será o que a página, seus workers e o destino verão. 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 que um detector solicita por nome), para que a request não declare um navegador no header e outro no JavaScript.

O userAgent na response é aquele que foi apresentado. Isso é importante quando você reproduz uma liberação: um cookie cf_clearance está vinculado à saída e ao User-Agent que o obteve, portanto envie de volta a string informada na response, não a que você acha que foi usada. Consulte 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

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:

{
  "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"]},
  "proxy": "A1B2C3"
}

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 autenticamente superada nesta chamada. Ausente 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 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 usada por uma chamada anterior. Envie de volta o ID opaco exatamente como foi recebido, nunca um endereço de proxy.

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 cai aqui.
`Proxy not found`	O ID foi decodificado, mas não resolve mais para uma saída ativa. Obtenha um novo ID em 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 cai aqui quando seu plano não tem mais tráfego premium restante para gastar. Reutilize a sessão em que ele retornou ou execute a chamada por meio de `POST /api/proxy/` e use a saída que ela escolher.

Uma saída premium fixada é tarifada como tráfego premium. A response traz 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 Usage & Limits, bem como para 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 limite disponível; caso contrário, o ID é recusado com o erro 400 de saída gerenciada acima.

Códigos de status HTTP

Código	Significado
200	Request concluída (verifique `status` interno para a resposta de destino)
400	Corpo da request inválido, parâmetros inválidos, IP de destino em faixa privada/reservada ou um proxy ID que não pode ser fixado
401	API key ausente ou inválida
403	O endpoint ou um parâmetro não está no seu plano. `X-FourA-Limit` especifica: `plan_limit_feature` ou `plan_limit_premium`.
404	`Not Found`: não há nenhum endpoint nesse caminho.
413	O corpo da request JSON 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 a franquia compartilhada por minuto da plataforma (sem header)
500	Erro interno do servidor
502	`Upstream unavailable`. FourA alcançou seu motor, mas a resposta estava inutilizável. Tente novamente.
503	Serviço temporariamente desativado ou na capacidade máxima, ou `Backend service unavailable` enquanto um motor reinicia
504	`Upstream timeout`. O motor não concluiu dentro do tempo limite para esta request. Aumente `timeout_ms` ou tente novamente.

Próximos passos

Smart Fetch (Auto): Quando deixar FourA escolher o caminho para você
Escolhendo o endpoint correto: Quando escolher Single, Proxy ou Browser manualmente
Autenticação: Gerencie suas API keys
Tratamento de erros: Trate erros de forma adequada
Verificações de site: Leia o campo defense e reproduza uma liberação
Por que uma request via proxy esgotou as tentativas: Leia attemptReport e tome providências
Rate limits: Entenda os limites de requests
Início rápido: Sua primeira request em 30 segundos

Atualizado em: 30 de setembro de 2026

Referência de Endpoints da API

Base URL

Autenticação

Response Headers

Endpoints

Restrições de URL de Destino

Smart Fetch (Auto)

Request Body

Response

Exemplo

Observações

Single Request

Request Body

Perfis de navegador

Regras de validação

Exemplo

Proxy Request

Request Body

Escopo de exitCountries

Exemplo

Por que uma chamada Proxy falhou

exitClass

Browser Profile Rotation

Browser Request

Request Body

Como sincronizar o relógio do navegador com a saída

O parâmetro userAgent

Exemplo

Fixando uma saída

Códigos de status HTTP

Próximos passos

O parâmetro `userAgent`