Playground
O Playground (barra lateral > Playground) permite que você execute requests de API reais com a sua chave ativa sem escrever código. É a forma mais rápida de testar um novo site de destino, depurar uma response complexa ou comparar Auto, Single, Proxy e Browser lado a lado.
Acesse em foura.ai/dashboard#playground.
O que ele faz
Um formulário. Quatro motores. Tráfego real.
- Auto: busca inteligente. Você envia uma URL com uma regra
validatee o FourA escolhe o caminho mais barato e funcional. - Single: busca HTTP direta com características de rede idênticas às de navegadores reais
- Proxy: busca gerenciada com proxy rotativo, com suporte opcional a países visíveis no destino
- Browser: abre a URL em uma instância do Chrome para sites renderizados com JS
Os requests são executados usando a chave de API que você selecionar no topo da página. O consumo é debitado da cota dessa chave exatamente como uma chamada de produção; portanto, evite esgotar seu plano durante os testes.
Selecionando uma chave
O menu suspenso de chave de API lista todas as chaves ativas disponíveis: as suas próprias em My Keys e um grupo para cada organização à qual você pertence. Qualquer membro pode usar a chave de uma organização, e o consumo do request é cobrado no plano do proprietário da organização. Selecione a chave que deve receber a cobrança do request. Se você ainda não tiver chaves ativas, um link direto direciona para a página API Keys para criar uma.
Escolhendo um modo
A linha superior Mode alterna entre Auto e os motores manuais. Ao selecionar Auto, o formulário muda para a interface simplificada do Auto (URL, validate e alguns ajustes). Ambas as linhas são exibidas continuamente: Mode: Auto, e Endpoint: Single, Proxy, Browser. Ao selecionar uma opção, a outra é desmarcada. A troca de endpoints altera os campos visíveis e o motor acionado pelo request. A seleção atual é mantida se você recarregar a página.
| Mode | Quando usar |
|---|---|
| Auto | Novo destino ou site com proteções variadas. O Auto escolhe o caminho mais econômico e memoriza o que funciona. |
| Single | Busca HTTP rápida. Primeira opção recomendada para hosts conhecidos. |
| Proxy | A mesma busca com rotação automática de proxy. Defina exitCountries se precisar de um país visível no destino. |
| Browser | Carrega a página em uma instância do Chrome. Use quando os dados dependerem da execução de JavaScript. |
Montando o request
Linha de URL
A linha superior contém o método HTTP (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), a URL de destino e o botão Send. Single, Proxy e Auto aceitam todos os métodos. Browser ignora o método (o Chrome sempre envia GET para navegação) e o body.
Abas do request
Abaixo da linha de URL, cinco abas permitem preencher os demais parâmetros:
| Aba | O que controla |
|---|---|
| UI | Campos de formulário para timeouts, redirecionamentos, flags, proxy, opções específicas do navegador e regras de validação |
| Body | Corpo em formato livre para requests POST / PUT / PATCH |
| Headers | Headers customizados da request como pares chave-valor |
| Cookies | Um cookie jar mantido por host neste navegador. Use jar anexa cookies correspondentes à request e Save response cookies armazena os cookies definidos por uma resposta. Ambos vêm ativados por padrão, e a aba exibe uma prévia do que esta request enviará |
| Raw | O payload JSON exato que será enviado, como uma prévia somente leitura com Copy JSON, além do reprodutor cURL logo abaixo |
Qualquer alteração feita em UI / Body / Headers / Cookies é refletida em Raw. Não é possível digitar em Raw: modifique a request nas outras abas. Um ponto vermelho aparece em qualquer aba ou seção recolhível que contenha um valor diferente dos padrões do engine, permitindo identificar rapidamente o que você personalizou.
Seções do Painel de UI
A aba UI agrupa as configurações em seções recolhíveis. Campos vazios utilizam o valor padrão do schema da engine. Seções que não se aplicam ao Mode atual permanecem ocultas.
- Timeouts:
timeout_ms,connect_timeout_ms,accept_timeout_ms,server_response_timeout_ms,dns_cache_timeout_sec. Browser e Auto expõem apenastimeout_ms(no Auto, o orçamento total). - Redirecionamentos: ative e defina
followRedirects(0-20). Single e Proxy. O Browser segue redirecionamentos por conta própria. - Flags:
unblockerpara Single, Proxy e Browser (unblockerno Browser conclui as verificações solicitadas pela página);tryJsonDataereturnBufferpara Single e Proxy. O Auto expõeforceProxyereturnSession. - Proxy: escolha um ID de proxy específico para Single ou Browser, ou defina
maxTries, o timeout externo do Proxy,exitCountries,exitClasseignoreProxiespara o mecanismo Proxy. O Auto também expõeignoreProxieseexitClass. A seleçãoexitClasstem três estados: não definido não envia nenhum campo,standarddefine o pool padrão epremiumpermite que a request faça escalonamento para uma saída premium quando o pool padrão apresentar instabilidade. Não definido estandardpermanecem no pool padrão; uma request bem-sucedida que especifica uma classe recebeexitClassde volta. O Premium exige um plano que inclua saídas premium: consulte exitClass. - Browser profile: três menus suspensos em cascata, os, browser e version, listando o que o FourA pode realmente emular. Eles aparecem no modo Single e Proxy. Deixe-os vazios para usar o Chrome mais recente. Cada seleção restringe as outras duas, garantindo que combinações inválidas não apareçam. A seção exige
unblockerativado: se estiver desativado, nenhum header de navegador será enviado, o perfil será aplicado apenas pela metade e a API recusará a request. - Browser: opções exclusivas do Browser, como
checkStatusecheckText. - Validar: status accept e status fail aceitam códigos de status separados por vírgula (
validate.status), e body accept e body fail aceitam substrings com alternativas separadas por|(validate.data). Disponível para Single, Proxy e Auto. O Browser usacheckStatusecheckText. O formulário não possui campo para regras de header (validate.headers).
Assim que uma execução retorna um proxy funcional, a seção Working proxies aparece no final da aba da interface. Ela lista até 20 IDs de proxy, do mais recente ao mais antigo, cada um com seu país de saída e horário. O botão use insere um proxy no campo proxy no Single ou Browser (o mecanismo Proxy localiza o seu próprio), e × o remove da lista.
Escopo de País de Saída (Modo Proxy)
O campo exitCountries em Proxy aceita uma lista separada por vírgulas de códigos de país de duas letras visíveis ao destino (CZ, GB). Os valores têm espaços removidos, são convertidos para maiúsculas e deduplicados no envio. A seleção a partir do pool padrão é uma allowlist rigorosa: proxies com saídas desconhecidas são excluídos e o pool nunca faz fallback para outro país. Uma saída premium também segue a lista. Com exitClass definido como premium, uma saída premium parte de um dos países listados, e um país no qual o pool padrão não tem disponibilidade é direcionado para saídas premium locais. Sem premium, um pool sem correspondências retorna code: "no_eligible_proxy" com o escopo solicitado retornado em details.exitCountries. Mantenha o escopo e tente novamente mais tarde.
Quando uma chamada de proxy é bem-sucedida sob escopo definido, a faixa de resposta exibe exit <CODE> ao lado do ID do proxy para que você possa verificar se o país atendido corresponde ao solicitado.
Local de Saída (Modo Proxy)
O grupo Exit location em Proxy escolhe de onde parte uma saída premium: região, cidade, rede, dispositivo e por quanto tempo mantém seu endereço. As listas de região, cidade e rede são preenchidas quando exitCountries especifica exatamente um país. Defina exitClass como premium, pois qualquer uma dessas opções envia a request apenas por saídas premium. O ID do proxy na resposta preserva o local, portanto basta transferi-lo para Single ou Browser. Consulte Exit location.
Redefinição da Barra de Ferramentas
O botão Reset na barra de ferramentas (ao lado de History e Saved) redefine o playground para o estado inicial limpo. Como é uma ação destrutiva, ela abre uma caixa de diálogo de confirmação listando exatamente o que será apagado: todas as abas de request, todos os cookies salvos no jar, todos os proxies transferidos e a response atual. As predefinições salvas e a chave de API selecionada são mantidas. Clique em Reset everything para confirmar; qualquer outra ação cancela.
Enviando e Cancelando
Clique em Send para disparar a request. A coluna direita muda para um estado de carregamento com um spinner e um botão Cancel enquanto a chamada está em andamento. Clique em Cancel (ou toque no botão novamente no celular) para abortar. Uma request cancelada restaura o placeholder ocioso com "Request canceled." em vez de exibir um erro.
O card de response muda para o resultado no momento em que a request é concluída (ou falha). Em um celular, ou em qualquer janela estreita o suficiente para posicionar a response abaixo do formulário, a página rola o card de response para a visualização quando ele chega na parte inferior da tela. Execuções em Auto podem demorar mais do que com os mecanismos manuais porque a sequência de escalonamento pode avançar várias etapas em um destino frio.
Lendo a Resposta
A coluna de response reflete o layout da request com suas próprias abas:
| Aba | O que mostra |
|---|---|
| Body | Corpo analisado. Alterna entre visualizações JSON, HTML e Texto dependendo do retorno recebido. |
| Headers | Headers de resposta, um por linha. |
| Cookies | Cookies retornados pelo destino, tanto na visualização analisada (agrupada por host) quanto na bruta (texto de Set-Cookie). A visualização analisada exibe um selo HO em cookies restritos ao host; cookies de domínio ficam sem marcação. |
| Raw | O envelope JSON completo retornado pela API. |
A barra de ferramentas de resposta tem Copiar e Baixar para a resposta inteira, além de Localizar na resposta (Ctrl+K ou Cmd+K) para pesquisar na aba aberta, usando Enter e Shift+Enter para navegar pelas correspondências. Body, Headers e Cookies também contam com opções próprias de Copiar e Baixar exclusivas para a aba em exibição.
Uma barra de metadados acima das abas mostra o status HTTP upstream, o tempo total, o ID do proxy que processou a chamada e (para uma chamada Proxy com escopo) o código de duas letras exit <CODE>. A faixa também mostra o tamanho da resposta e, quando a API os reporta, os créditos que a requisição consumiu. Para execuções Auto, o nível e as tentativas aparecem na frase abaixo da barra.
O que a chamada exigiu
Uma frase abaixo da faixa de metadados descreve em texto o que carregou a página. Para uma execução Auto, ela especifica o nível (uma sessão que o FourA já mantinha para o host, uma requisição simples, um proxy rotativo, um navegador real ou um navegador inicial seguido por uma repetição econômica), se um desafio foi resolvido, quantas tentativas foram necessárias e o custo envolvido. Quando a requisição definiu exitClass, ela também informa se a entrega ocorreu por uma saída premium ou pelo pool padrão.
Quando um dos limites do seu plano recusa a chamada, a frase informa isso primeiro: "Interrompido pelo seu plano, não pelo site", seguido por qual limite (requisições de navegador esgotadas hoje, excesso de requisições em andamento, créditos consumidos neste período, entre outros) e um link para Uso e Limites. A linha é gerada a partir do código X-FourA-Limit retornado pela API, portanto, uma página complexa com falha indica se o bloqueio ocorreu pelo site ou pelo plano.
Transportar valores entre execuções
Após qualquer execução que retorne dados de sessão reutilizáveis, um pequeno controle Transportar na barra de ferramentas de resposta exibe o que está disponível:
- Execuções Auto feitas com
returnSessionoferecem ouserAgente oproxyda sessão. Os cookies da sessão aparecem na aba Cookies da resposta e são adicionados ao repositório de cookies quando Salvar cookies de resposta estiver ativado. - Execuções Browser oferecem o
userAgentde resposta, além do ID do proxy, caso algum tenha sido utilizado. - Execuções Proxy oferecem o ID do proxy retornado e o perfil de navegador quando a rotação seleciona uma opção que você não solicitou.
Clique em Transportar e escolha onde aplicar cada valor com apenas um clique: userAgent torna-se um header User-Agent em Single ou Proxy, e o ID do proxy é inserido no campo proxy em Single ou Browser. Os campos que recebem um valor transportado exibem o ponto vermelho de "modificado" para que você possa identificar as alterações.
Um browser profile transferido preenche as três seleções de os, browser e version e ativa unblocker, a mesma regra aplicada quando você escolhe um perfil manualmente. Ele é oferecido apenas após o catálogo de perfis carregar, já que o formulário é composto por três seleções e não por um campo de id.
O perfil é o único valor que indica que a request que funcionou não foi a request digitada por você: o Proxy reporta profile apenas quando mudou para uma família de browser que você não solicitou. Repita sem ele e você repetirá a versão que falhou. Consulte Why a Proxy Request Ran Out of Tries.
Expandir para Tela Cheia
O ícone de expansão na barra de ferramentas de resposta destaca o card de resposta do layout dividido e o exibe em uma sobreposição em tela cheia. Use isso para árvores JSON profundas, dumps longos de Set-Cookie ou corpos HTML largos onde a coluna de meia largura fica apertada. A própria página para de rolar enquanto a sobreposição estiver aberta. Clique no ícone novamente (ou pressione Escape) para recolher.
O Reprodutor curl
Na aba Raw da request, abaixo do JSON, um bloco curl mostra o comando de linha de comando exato equivalente à request que você está criando, com um botão Copy curl. Copie para reproduzir a request a partir de um terminal, compartilhar com um colega de equipe ou colar em um relatório de bug.
Para chaves reveláveis, um botão Reveal key ao lado do snippet insere a chave real em texto simples diretamente no curl para que você possa copiar e executar diretamente. Clique novamente para ocultar. Chaves legadas (criadas antes do lançamento do recurso de revelação) mantêm um placeholder PASTE_PLAINTEXT_FOR_<key-name>; gere a chave novamente na página API Keys para torná-la revelável.
A revelação é registrada em log de auditoria no servidor a cada execução, e a chave em texto simples permanece na memória apenas durante a sessão atual da página.
Salvando Presets
Se você precisa reconfigurar o mesmo destino repetidamente, salve-o. Clique em Save na linha de abas de request para armazenar a configuração atual como um preset nomeado.
Abra Saved na barra de ferramentas para ver seus presets. Clique em Load para preencher o formulário ou em Delete para remover um.
Uma request aberta a partir da aba DevTools da extensão FourA Chrome carrega com a chave da extensão selecionada quando essa chave estiver na sua conta, e a página informará isso. Caso contrário, ela solicitará que você escolha uma chave. Uma request repetida que não define unblocker é executada com ele ativado, exatamente como a API faz.
| Preset field | What it stores |
|---|---|
| Name | Um rótulo curto (até 100 caracteres) |
| Description | Notas opcionais (até 500 caracteres) |
| Endpoint | Para qual engine o preset serve (auto / single / proxy / browser) |
| Config | O payload completo da request, incluindo campos de UI, headers, cookies e body |
Os presets são restritos à sua conta de usuário e não são compartilhados com membros da equipe.
Repetindo a partir do Histórico
Cada request executada por você é registrada. Abra History na barra de ferramentas para ver suas últimas 20 execuções, ordenadas da mais recente para a mais antiga.
Cada linha mostra o endpoint, a URL de destino, o status e o horário. Clique em Replay em qualquer linha para carregar essa request de volta no formulário e depois em Send para executá-la novamente.
O histórico é limitado automaticamente à sua conta: você vê apenas as suas próprias execuções.
Abrindo a partir de Activity
A caixa de diálogo de detalhes do Activity Log tem um botão Open in Playground. Clique nele e o Playground será carregado tanto com a request arquivada quanto com a response arquivada. O formulário é preenchido a partir do payload armazenado, e o card de response exibe o que a API retornou naquele momento com uma badge "archived" na barra de metadados do proxy ("archived
A partir daí, você pode alterar um parâmetro e clicar em Send para executar uma nova request na API ativa, ou apenas inspecionar o payload arquivado sem executá-lo novamente. Os payloads são mantidos por 24 horas, portanto, linhas mais antigas do Activity não terão uma response recarregável.
Dicas
- Comece no Playground antes de escrever código para um novo destino. Com o Auto ativado, você saberá em segundos se uma requisição fetch simples é suficiente ou se o site exige resolução por navegador.
- Para alvos com bloqueio geográfico, execute uma chamada Proxy com
exitCountriesdefinido e passe o ID de proxy retornado para uma chamada Browser, garantindo que a renderização de JavaScript ocorra pela mesma saída. - Salve um preset para cada alvo que você coleta regularmente. Executar novamente um preset salvo leva um clique; reconstruir a request de cabeça leva mais tempo.
- Use a aba Cookies para depurar scraping baseado em sessão. A visualização Set-Cookie bruta mostra exatamente o que o destino enviou.
- Quando um alvo recusar a requisição, teste outra opção nos seletores de perfil de Browser antes de recorrer a um mecanismo mais pesado. Alternar o navegador apresentado não tem custo adicional; uma renderização de navegador tem.
- As requests do Playground são cobradas na chave selecionada. Use uma chave dedicada de cota baixa para exploração informal se quiser manter o uso de produção isolado.
Relacionado
- Endpoints da API: Referência completa de parâmetros para todos os quatro mecanismos, incluindo
exitCountriese os campos de perfil do navegador - Smart Fetch (Auto): O que o Auto faz nos bastidores
- Escolhendo o Endpoint Correto: Quando escolher Auto vs Single vs Proxy vs Browser
- Chaves de API: Gerencie as chaves usadas para autenticar requests no Playground
- Activity Log: Abra uma request anterior diretamente no Playground
- Visão Geral do Dashboard: Todas as seções da barra lateral