Reutilizar um proxy entre requisições

Saiba como manter a mesma saída de proxy em requisições de acompanhamento, garantindo que renderizações JavaScript, chamadas de API e buscas paginadas saiam do mesmo IP.

Por que reutilizar um proxy

Quando você acessa um destino pela primeira vez, o FourA escolhe um proxy funcional para você. Cada resposta inclui o ID do proxy utilizado. Envie esse ID de volta em requisições posteriores e:

Páginas de acompanhamento passam pela mesma saída, mantendo cookies de sessão e rate limits coerentes com o destino.
Uma busca com escopo de país permanece dentro da sua allowlist sem uma nova seleção.
O endpoint POST /api/single/, mais barato, repete o envio através de um proxy que você já pagou para descobrir, pelo custo do Single em vez do Proxy.

O ID do proxy é uma string base36 opaca (algo como A1B2C3). Nunca um IP bruto.

Onde o ID fica na resposta

Endpoint	Campo	Quando está presente
`POST /api/auto/`	`session.proxy`	Quando `returnSession` for `true` (o padrão)
`POST /api/single/`	`proxy` (nível superior)	Apenas quando a requisição forneceu um campo `proxy`
`POST /api/proxy/`	`proxy` (nível superior)	Sempre, em caso de sucesso
`POST /api/browser/`	`proxy` (nível superior)	Apenas quando a requisição forneceu um campo `proxy`

Para obter uma saída nova sem fixar uma, comece com Auto ou Proxy. Ambos descobrem uma saída funcional e retornam seu ID para você.

Padrão 1: Auto descobre, Single repete

Ideal quando você tem um destino que ainda não conhece. O Auto percorre a sequência uma vez, e depois o Single reutiliza a sessão bem-sucedida para cada página seguinte.

import requests

API = "https://eu.api.foura.ai"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

# Step 1: discover a working exit with Auto.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# Step 2: paginate with Single, reusing the same exit and User-Agent.
for sku in ("43", "44", "45"):
    p = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, p["status"])

A chamada Auto custa o que sua ladder gastar. Cada chamada Single seguinte custa 2 créditos (Single com unblocker, o padrão).

Padrão 2: Proxy descobre, Browser renderiza pela mesma saída

Use isso quando o destino precisar ver um país de saída específico e o conteúdo final exigir JavaScript.

# Step 1: pick a country-scoped exit with Proxy.
curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "exitCountries": ["FR", "GB"],
    "request": {"method": "GET", "url": "https://example.com/pricing"}
  }'
# Response includes: "proxy": "A1B2C3", "exitCountry": "FR"

# Step 2: render the JS-heavy page through THAT exit.
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/pricing",
    "proxy": "A1B2C3",
    "timeout_ms": 20000
  }'

Não chame /api/proxy/ novamente para atualizar a seleção. Uma nova chamada pode escolher uma saída diferente e anular o propósito da fixação (pinning). Se a saída fixada parar de funcionar, execute uma nova chamada /api/proxy/ para escolher uma nova e continue com ela.

Pattern 3: Pular uma saída queimada

Se uma saída que costumava funcionar começar a retornar recusas ou páginas de verificação, instrua o FourA a evitá-la na próxima seleção.

{
  "maxTries": 5,
  "ignoreProxies": ["A1B2C3"],
  "request": { "method": "GET", "url": "https://example.com/data" }
}

ignoreProxies aceita uma lista de IDs de proxy de respostas anteriores. Funciona em /api/proxy/ e /api/auto/. A lista é respeitada em cada retry interno, portanto, uma única chamada com ignoreProxies nunca seleciona os exits queimados.

Por quanto tempo uma sessão fixada permanece ativa

O exit em si permanece ativo enquanto o proxy subjacente estiver saudável, normalmente de minutos a horas. Se um replay começar a retornar desafios, bloqueios ou redirecionamentos inesperados, o exit provavelmente foi rotacionado ou o destino atualizou a autorização.

Duas opções quando isso acontecer:

Uma nova chamada /api/auto/ para a mesma URL. O Auto descobrirá uma nova sessão funcional; descarte os IDs anteriores.
Uma nova chamada /api/proxy/ com ignoreProxies: ["<burned-id>"] se você quiser continuar fixando manualmente.

Os cookies de sessão de uma resposta do Auto também expiram de acordo com o cronograma do próprio destino. Alguns sites vinculam a autorização por horas; outros por minutos. Trate a sessão como um cache, não como um token duradouro.

Quando um ID não fixa

Três erros 400 podem retornar de um valor proxy, e eles significam coisas diferentes:

Erro	O que aconteceu	O que fazer
`Invalid proxy format`	O valor não é um ID emitido pela FourA. Um endereço de proxy bruto cai aqui.	Envie a string opaca de uma resposta, exatamente como recebida.
`Proxy not found`	O ID foi decodificado, mas não resolve mais para um exit ativo.	Obtenha um novo exit a partir de uma nova chamada Auto ou Proxy.
`Managed exit: this proxy id cannot be pinned to a request`	O ID é um exit premium e o tráfego premium do seu plano para este período acabou, ou o seu plano não inclui exits premium.	Execute a chamada via `POST /api/proxy/` e use o exit que ele escolher, ou adicione tráfego premium e fixe-o novamente.

O terceiro erro retorna de um ID fornecido por uma chamada bem-sucedida, portanto você pode recebê-lo sem ter feito nada de errado. Trate-o da mesma forma que trataria uma sessão expirada: recorra a uma nova chamada de descoberta em vez de tentar o mesmo ID novamente.

Erros comuns

Reutilizar um ID de proxy entre contas. Nao compartilhe IDs entre contas: um ID que uma conta pode fixar pode ser recusado para outra, por exemplo uma saida premium em um plano sem trafego premium.
Tentar decodificar o ID. A string base36 e opaca. Nao faca parse dela, nao remova caracteres, nao converta para minusculas. Envie-a de volta exatamente como recebida.
Fixar atraves de uma saida com rate limit. Se o destino aplica rate limit por IP, direcionar muitas requests atraves de uma unica saida vai disparar bloqueios mais rapidamente. Para cargas de trabalho de alto volume, deixe o Auto ou o Proxy alternar entre muitas saidas e fixe apenas onde o destino realmente exigir.
Fixar uma saida premium sem intencao. Um ID de uma chamada atendida por uma saida premium (exitClass: "premium" no Proxy) fixa essa saida premium. Cada repeticao atraves dela consome seu trafego premium, e a response inclui X-FourA-Exit-Class: premium.
Enviar exitCountries em um plano sem direcionamento geografico. O escopo por pais esta incluido a partir do plano Startup. Em um plano sem esse recurso, uma chamada que envia exitCountries e recusada com 403 e X-FourA-Limit: plan_limit_feature.
Ignorar exitCountries na chamada seguinte. Se voce fixar uma saida com escopo definido e depois chamar o Proxy novamente sem exitCountries, a continuacao pode passar por um pais diferente. Mantenha o escopo em todas as chamadas que precisarem dele.

Relacionados

Endpoints de API: Referencia completa de parametros e responses
Smart Fetch (Auto): Como o Auto cria a sessao que voce repete
Sites protegidos: Quando a fixacao ajuda e quando a rotacao e melhor
Problemas comuns: no_eligible_proxy e outros erros de proxy
Por que uma request de Proxy esgotou as tentativas: Interpretando attemptReport quando uma chamada de Proxy desiste

Atualizado em: 27 de setembro de 2026