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/mcpencapsula 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çãooffload_largepara lidar com respostas grandes de forma econômica em tokens. As diferenças:foura_browsernão tem o campolean, efoura_proxyainda 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.acceptcom 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
404ou410e o seuvalidatenão o aceita, a chamada termina com essestatuse umerrorque começa comthe site answered. Liste o status emvalidate.status.accepte o Auto entrega a primeira resposta com esse status que passe pelo restante do seuvalidate. O mesmo vale para qualquer outro status listado ali, exceto403,429,503e202, que os sites também enviam com uma página de desafio. timeout_mslimita 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). Comunblockerdesativado, 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
profiledesconhecido retornaunknown profile '<id>'. A request nunca é enviada como um navegador diferente. - Os mesmos quatro campos estão disponíveis dentro do objeto
requestdePOST /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,exitOseexitLifetimeMinenvia 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,exitCityeexitAsnexistem dentro de um único país, portanto exigem exatamente um país emexitCountries.exitOseexitLifetimeMinfuncionam com vários: o exit seleciona um deles, e oexitCountryna response indica qual foi.exitState,exitCity,exitAsneexitOsexigem 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 requestecode: no_eligible_proxy.details.exitCountriesestará 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
exitCountriesno Proxy Request. - Apenas o relógio acompanha o país. O
Accept-Languagee 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
- Smart Fetch (Auto): Quando deixar o 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 eficiente
- Verificações de site: Leia o campo
defensee repita uma liberação - Por que uma request de Proxy esgotou as tentativas: Leia
attemptReporte tome medidas - Rate limits: Entenda os limites de requests
- Início rápido: Sua primeira request em 30 segundos