Search API

Visão geral

O Search API é uma solução de SERP API em tempo real que gerencia proxies, CAPTCHAs e parsing de JSON para extração de dados da web de forma transparente. Com a integração no SquadOS, seus agentes podem realizar buscas em mais de 40 motores de pesquisa — incluindo Google, Bing, Yahoo, DuckDuckGo, YouTube, Amazon e muito mais — obtendo resultados estruturados com orgânicos, anúncios, knowledge graphs, listagens locais, imagens, vídeos e buscas relacionadas.

• Site oficial: https://www.searchapi.io/
• Documentação na Composio: docs.composio.dev/toolkits/search_api

Autenticação

Esta ferramenta utiliza chave de API (API_KEY) para conectar.

Você vai precisar dos seguintes campos:

Campo	Obrigatório	Descrição
api_key	Sim	Chave de API da sua conta Search API, usada para autenticar todas as requisições.

Como obter a credencial

1. Acesse searchapi.io e clique em Sign up.
2. Conclua o cadastro — não é necessário cartão de crédito.
3. Após o login, acesse o painel da sua conta.
4. Copie a chave de API exibida no dashboard — esse é o valor a usar no campo api_key ao conectar no SquadOS.

Dica

Novos usuários recebem 100 requisições gratuitas para testar a integração antes de escolher um plano.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por Search API.
3. Clique no card para abrir o modal de detalhes e em Conectar.
4. Você é levado para a página de conexão segura hospedada pela Composio, onde informa a chave de API obtida acima.
5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

Ações disponíveis

Obter informações da conta

SEARCH_API_GET_ACCOUNT_INFO

Recupera estatísticas de uso da conta, incluindo uso mensal, créditos restantes, limites por hora e informações do período de assinatura. Use quando precisar verificar o status atual da conta ou os limites de uso.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
zero_retention	boolean	Não	Funcionalidade exclusiva para Enterprise. Quando definido como true, desabilita todos os logs e armazenamento persistente para esta requisição.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter busca em cache por ID

SEARCH_API_GET_CACHED_SEARCH_BY_ID

Recupera resultados de busca em cache pelo ID da busca, no formato JSON. Use quando precisar acessar resultados de uma busca executada anteriormente sem reexecutar a consulta. O ID da busca está nos campos search_metadata.id ou search_metadata.json_url das respostas iniciais. Resultados em cache ficam disponíveis por 90 dias.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
search_id	string	Sim	Identificador único de uma busca executada anteriormente, no formato search_[alfanumérico]. Este ID está no campo id ou json_url do search_metadata das respostas iniciais.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter HTML de busca em cache por ID

SEARCH_API_GET_CACHED_SEARCH_HTML_BY_ID

Recupera resultados de busca em cache pelo ID da busca, no formato HTML. Use quando precisar acessar o snapshot HTML bruto de uma busca executada anteriormente. O ID da busca está nos campos search_metadata.id ou search_metadata.html_url das respostas iniciais.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
search_id	string	Sim	Identificador único de uma busca executada anteriormente. Este ID está no campo id ou html_url do search_metadata das respostas iniciais.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter localizações

SEARCH_API_GET_LOCATIONS

Retorna as localizações disponíveis para consultas de busca geolocalizadas. Use quando precisar encontrar identificadores de localização para direcionar buscas no Google a áreas geográficas específicas. Retorna metadados de localização incluindo identificadores, nomes, coordenadas e alcance populacional.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
q	string	Sim	Consulta de busca para localização. O nome do local que deseja pesquisar (ex.: new york, london, tokyo).
limit	integer	Não	Número máximo de resultados a retornar. Padrão: 10; máximo permitido: 100.
zero_retention	boolean	Não	Funcionalidade exclusiva para Enterprise. Quando definido como true, desabilita o registro da requisição. Disponível apenas para contas Enterprise.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Buscar

SEARCH_API_SEARCH

Realiza buscas unificadas em mais de 40 motores de pesquisa, incluindo Google, Bing, Yahoo, DuckDuckGo, YouTube, Amazon e outros. Use quando precisar obter resultados de busca com dados estruturados e ricos, incluindo resultados orgânicos, anúncios, knowledge graphs, listagens locais, imagens, vídeos e buscas relacionadas. Suporta filtragem avançada por localização, idioma, data, tipo de dispositivo e configurações de SafeSearch.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
q	string	Sim	Termos da consulta de busca com suporte a operadores e filtros avançados.
cr	string	Não	Restringe resultados por país via TLD ou geolocalização de IP.
gl	string	Não	Código de país para os resultados (padrão: us). Código de país de duas letras.
hl	string	Não	Código de idioma da interface (padrão: en). Código de idioma de duas letras.
lr	string	Não	Restringe resultados pelo idioma do documento (formato: lang_xx).
num	integer	Não	Número de resultados por página. Nota: o Google atualmente retorna sempre 10 resultados independentemente deste parâmetro.
nfpr	integer	Não	Defina como 1 para excluir resultados com autocorreção.
page	integer	Não	Número da página de resultados para paginação (padrão: 1).
safe	string	Não	Configuração do SafeSearch: active para filtrar conteúdo explícito ou off para desabilitar (padrão: off).
uule	string	Não	Parâmetro de localização codificado pelo Google. Não pode ser usado junto com o parâmetro location.
kgmid	string	Não	Identificador do Knowledge Graph para buscas específicas de entidades.
device	string	Não	Tipo de dispositivo para os resultados: desktop, mobile ou tablet (padrão: desktop).
engine	string	Sim	Especifica o motor de busca a usar. Motores suportados: google, bing, yahoo, duckduckgo, youtube, google_maps, google_shopping, google_jobs, google_hotels, amazon_search, ebay_search, walmart_search, apple_app_store, baidu, yandex, naver, entre outros.
filter	integer	Não	Habilita (1) ou desabilita (0) filtros de conteúdo duplicado (padrão: 1).
location	string	Não	Localização canônica para resultados geolocalizados (ex.: United States, London,England,United Kingdom).
time_period	string	Não	Filtra resultados por data: last_hour, last_day, last_week, last_month ou last_year.
google_domain	string	Não	Domínio do Google a usar na busca (padrão: google.com).
zero_retention	boolean	Não	Funcionalidade exclusiva para Enterprise. Quando definido como true, desabilita todos os logs e armazenamento persistente para esta requisição.
time_period_max	string	Não	Data de fim do intervalo personalizado no formato MM/DD/YYYY.
time_period_min	string	Não	Data de início do intervalo personalizado no formato MM/DD/YYYY.
optimization_strategy	string	Não	Estratégia de otimização da busca: performance ou ads (padrão: performance).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.