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 a 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_.

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 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 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. Inclua-o ao entrar em contato com o suporte para identificar a requisição 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 obter a lista completa e dicas de uso.

Endpoints

Usando estes endpoints via MCP? O servidor @fouradata/mcp 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.

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 e o guia do 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.

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

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

Response

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

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

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 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: 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.
browser string Não Chrome Navegador a apresentar: Chrome, Edge, Safari, Firefox ou Tor. Veja Perfis de navegador.
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.

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

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

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

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
}

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:

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

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

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

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

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.

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

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

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 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: 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), 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:

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

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

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, 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 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.
  • 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.

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"]}
}
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.
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, 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

Atualizado em: 13 de novembro de 2026