# Referência do endpoint de pesquisa: POST e GET /search > Referência do endpoint de pesquisa: todos os parâmetros de POST e GET /search, de read e max_chars a topic, time_range e filtros de domínio. Sem KYC, cripto. - URL: https://llmwebsearch.com/pt/docs/search/ - Última atualização: 2026-10-22 - Editor: LLMWebSearch (https://llmwebsearch.com) `/search` executa uma pesquisa na web em tempo real, classifica até 20 resultados e lê as páginas por trás dos primeiros. Esta página lista todos os parâmetros, seu padrão, seus limites e o que cada um faz com o preço. **Resposta rápida — Quais parâmetros o endpoint de pesquisa do LLMWebSearch aceita?** O endpoint `/search` do **LLMWebSearch** precisa apenas de `q`. Parâmetros opcionais definem quantos resultados retornam (`max_results`), quantas páginas são lidas (`read`), o formato e o comprimento do conteúdo, notícias ou web, um intervalo de tempo, o país e o idioma, e domínios a manter ou descartar. Ler até 3 páginas custa 1 crédito, a partir de US$ 1,20/1K pesquisas em outubro de 2026. Sem KYC; pague com cripto. ## /search at a glance | Atributo | Valor | | --- | --- | | Métodos | `POST` com um corpo JSON, ou `GET` com os mesmos nomes na query string | | URL | `https://llmwebsearch.com/api/v1/search` | | Obrigatório | `q`: 1 a 400 caracteres; operadores de pesquisa são passados como escritos | | Padrões | 5 resultados, os 3 primeiros lidos, Markdown de até 6.000 caracteres por página | | Cobrança | Um crédito paga uma pesquisa: até 20 resultados classificados, com as páginas dos 3 primeiros lidas e devolvidas em Markdown. Ler de 4 a 10 páginas custa 2 créditos. Uma chamada que termina em erro não custa nada | | Resultados | Os resultados vêm de uma pesquisa na web ao vivo, executada no momento da sua chamada, na ordem em que o mecanismo de pesquisa os classifica; nada é servido de um índice antigo | | Filtros | Escolha o país e o idioma dos resultados, um intervalo de tempo (último dia, semana, mês ou ano), resultados da web ou de notícias, e domínios para incluir ou excluir | | Leitor de páginas | `LLMWebSearch/1.0 (+https://llmwebsearch.com/bot/)` | ## Pesquisar na web e ler os principais resultados (POST) `POST /api/v1/search` Executa uma pesquisa na web em tempo real e retorna resultados classificados. As páginas dos primeiros `read` resultados são buscadas em paralelo e seu conteúdo principal é retornado em `content`. O exemplo pergunta como rotacionar chaves de API; títulos, datas e valores são ilustrativos. Autenticação: chave de API no header `Authorization: Bearer API_KEY`. **Corpo da requisição** | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `q` | string | Sim | A consulta de pesquisa, de 1 a 400 caracteres. Aspas e operadores como `site:` são mantidos como escritos. | | `max_results` | integer | Não | Número de resultados classificados, de 1 a 20. Padrão 5. | | `read` | integer | Não | Quantos dos primeiros resultados são lidos e retornados com seu conteúdo, de 0 a 10. Padrão 3. A partir de 4, a chamada custa 2 créditos. | | `format` | string | Não | `markdown` (padrão) ou `text` para o conteúdo da página. | | `max_chars` | integer | Não | Limite de tamanho do conteúdo de cada página, de 500 a 50.000 caracteres. Padrão 6.000. | | `topic` | string | Não | `web` (padrão) ou `news`. | | `time_range` | string | Não | `day`, `week`, `month` ou `year`. Sem padrão: qualquer data. | | `country` | string | Não | Código de país de duas letras (ISO 3166-1 alpha-2) para onde a pesquisa é executada. Padrão `us`. | | `language` | string | Não | Idioma dos resultados, como `en`, `de` ou `pt-BR`. Padrão `en`. | | `include_domains` | string[] | Não | Até 20 domínios; apenas resultados desses domínios e de seus subdomínios são mantidos. | | `exclude_domains` | string[] | Não | Até 20 domínios cujos resultados são descartados. | *Exemplo: five results, the top three read as Markdown* ```json { "q": "how to rotate api keys without downtime", "max_results": 5, "read": 3, "max_chars": 6000 } ``` *Exemplo: news of the past week from two sites, nothing read* ```json { "q": "open source license change", "topic": "news", "time_range": "week", "include_domains": [ "news.example.com", "example.org" ], "read": 0 } ``` **Resposta** `200` ```json { "query": "how to rotate api keys without downtime", "created_at": "2026-10-22T10:15:04Z", "credits_used": 1, "results": [ { "position": 1, "title": "Rotating API keys", "url": "https://docs.example.com/security/key-rotation", "host": "docs.example.com", "snippet": "Create a second key, deploy it everywhere, then revoke the first one.", "published_at": "2026-09-30", "content_status": "ok", "content": "# Rotating API keys\n\n## Zero-downtime rotation\n\n1. Create a second key.\n2. Deploy it to every service.\n3. Revoke the old key.", "word_count": 948 }, { "position": 2, "title": "Key rotation checklist", "url": "https://blog.example.org/key-rotation-checklist", "host": "blog.example.org", "snippet": "Keep two keys active during the switch and alert on the old one.", "content_status": "blocked_by_robots" }, { "position": 3, "title": "Secrets management basics", "url": "https://security.example.net/secrets-basics", "host": "security.example.net", "snippet": "Never commit keys to a repository.", "published_at": "2026-06-12", "content_status": "ok", "content": "# Secrets management basics\n\n**Never** commit keys to a repository...", "word_count": 1310 }, { "position": 4, "title": "API key best practices", "url": "https://dev.example.com/api-key-best-practices", "host": "dev.example.com", "snippet": "Scope each key to one service and one environment.", "content_status": "not_requested" } ] } ``` *curl* ```bash curl -s "https://llmwebsearch.com/api/v1/search" \ -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \ -H "Content-Type: application/json" \ -d '{"q": "how to rotate api keys without downtime", "max_results": 5, "read": 3}' ``` *Python* ```python import os import requests resp = requests.post( "https://llmwebsearch.com/api/v1/search", headers={"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]}, json={"q": "how to rotate api keys without downtime", "max_results": 5, "read": 3}, timeout=60, ) resp.raise_for_status() for r in resp.json()["results"]: print(r["position"], r["content_status"], r["url"]) ``` *Node.js* ```javascript const res = await fetch('https://llmwebsearch.com/api/v1/search', { method: 'POST', headers: { Authorization: `Bearer ${process.env.LLMWEBSEARCH_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ q: 'how to rotate api keys without downtime', max_results: 5, read: 3 }), }); const { results } = await res.json(); for (const r of results) console.log(r.position, r.content_status, r.url); ``` ## Pesquisar na web (GET) `GET /api/v1/search` A mesma pesquisa com os parâmetros na query string, codificados em URL. Listas como `include_domains` são escritas como um único valor separado por vírgulas. Útil para um teste rápido ou para ferramentas que só enviam requisições GET. O exemplo pede apenas resultados (`read=0`). Autenticação: chave de API no header `Authorization: Bearer API_KEY`. **Parâmetros** | Nome | Em | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | --- | | `q` | query | string | Sim | A consulta de pesquisa, codificada em URL, de 1 a 400 caracteres. | | `max_results` | query | integer | Não | De 1 a 20. Padrão 5. | | `read` | query | integer | Não | De 0 a 10. Padrão 3; 4 ou mais custa 2 créditos. | | `format` | query | string | Não | `markdown` (padrão) ou `text`. | | `max_chars` | query | integer | Não | De 500 a 50.000 por página. Padrão 6.000. | | `topic` | query | string | Não | `web` (padrão) ou `news`. | | `time_range` | query | string | Não | `day`, `week`, `month` ou `year`. | | `country` | query | string | Não | Código ISO 3166-1 alpha-2. Padrão `us`. | | `language` | query | string | Não | Código de idioma. Padrão `en`. | | `include_domains` | query | string | Não | Lista separada por vírgulas, com até 20 domínios. | | `exclude_domains` | query | string | Não | Lista separada por vírgulas, com até 20 domínios. | | `api_key` | query | string | Não | Sua chave, quando você não envia o header `Authorization`. | **Resposta** `200` ```json { "query": "postgres connection pooling", "created_at": "2026-10-22T10:21:47Z", "credits_used": 1, "results": [ { "position": 1, "title": "Connection pooling explained", "url": "https://docs.example.com/db/pooling", "host": "docs.example.com", "snippet": "A pool keeps a few database connections open and lends them to requests.", "content_status": "not_requested" }, { "position": 2, "title": "Sizing a connection pool", "url": "https://blog.example.org/pool-size", "host": "blog.example.org", "snippet": "Start small: the right size depends on cores and disk, not on traffic.", "published_at": "2026-03-04", "content_status": "not_requested" } ] } ``` *curl* ```bash curl -sG "https://llmwebsearch.com/api/v1/search" \ -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \ --data-urlencode "q=postgres connection pooling" \ -d max_results=10 -d read=0 ``` *Python* ```python import os import requests resp = requests.get( "https://llmwebsearch.com/api/v1/search", headers={"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]}, params={"q": "postgres connection pooling", "max_results": 10, "read": 0}, timeout=60, ) print([r["url"] for r in resp.json()["results"]]) ``` *Node.js* ```javascript const params = new URLSearchParams({ q: 'postgres connection pooling', max_results: '10', read: '0' }); const res = await fetch(`https://llmwebsearch.com/api/v1/search?${params}`, { headers: { Authorization: `Bearer ${process.env.LLMWEBSEARCH_API_KEY}` }, }); console.log((await res.json()).results.map((r) => r.url)); ``` ## Como faço para obter resultados sem nenhum conteúdo de página? Defina `read` como `0`. Cada resultado volta então com seu título, URL, host, snippet e data, e `content_status: "not_requested"`. A resposta fica bem menor, o que ajuda quando o agente só precisa escolher quais links importam. O preço continua em 1 crédito, o mesmo de ler até 3 páginas. Um padrão comum é uma pesquisa `read=0` para fazer a pré-seleção e depois uma [chamada de extração](https://llmwebsearch.com/pt/docs/extract/) nas duas ou três URLs que o modelo escolheu. ## Quando uma pesquisa custa 2 créditos? Quando `read` está entre 4 e 10. Ler mais páginas dá mais trabalho do nosso lado, então o preço dobra uma vez e fica em 2 créditos até o máximo de 10 páginas. `credits_used` em cada resposta mostra quanto custou a chamada. Uma página que não pôde ser lida, por uma regra do robots.txt ou por uma recusa, não reduz nem aumenta esse preço. Se na maior parte das vezes você só precisa de algumas páginas completas, mantenha `read` em 3 e chame `/extract` para a página extra ocasional. ## Como pesquisar notícias recentes? Envie `topic: "news"` e um `time_range`. Os resultados passam então a vir de artigos de notícias, e `time_range` mantém apenas os dos últimos `day`, `week`, `month` ou `year`. `published_at` é preenchido quando o artigo ou o resultado de pesquisa informa uma data. O mesmo filtro de atualidade funciona com `topic: "web"`. Ele é útil para perguntas como lançamentos recentes ou mudanças de preço, em que uma página antiga enganaria o modelo. *Notícias da última semana, 3 principais artigos lidos* ```bash curl -s "https://llmwebsearch.com/api/v1/search" \ -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \ -H "Content-Type: application/json" \ -d '{"q": "database release security fix", "topic": "news", "time_range": "week", "read": 3}' ``` ## Como mantenho os resultados restritos a certos sites? Liste-os em `include_domains`, com até 20 entradas. Só são mantidos os resultados cujo host seja um desses domínios, ou um de seus subdomínios: `example.com` também corresponde a `docs.example.com`. Use `exclude_domains` no sentido inverso, por exemplo para tirar seu próprio site dos resultados. No corpo de um POST, ambos os campos são arrays JSON. Em uma requisição GET, escreva-os como um único valor separado por vírgulas. A própria consulta também pode conter um operador `site:`; ele é repassado à pesquisa como está. ## O que país e idioma mudam? `country` define onde a pesquisa é executada, com um código de duas letras como `us`, `de` ou `br`. Os rankings variam por país, especialmente para serviços locais, preços e regulamentações. `language` define o idioma dos resultados, como `en`, `fr` ou `pt-BR`. Ambos vêm por padrão como Estados Unidos e inglês. Defina os dois juntos quando o agente atende usuários de um único mercado: um usuário alemão perguntando sobre regras tributárias quer `country: "de"` e `language: "de"`. ## Quanto texto de página volta? Até `max_chars` caracteres por página, 6.000 por padrão e de 500 a 50.000. O limite protege a janela de contexto do modelo: três páginas com 6.000 caracteres dão aproximadamente 4.500 tokens de inglês. `word_count` conta todo o texto extraído, antes do corte, para você saber quando uma página foi truncada. Quando uma resposta precisa de um documento longo, pesquise primeiro com um limite baixo e depois busque só essa página via `/extract` com um limite maior. Uma página lenta não é aguardada indefinidamente: após 15 segundos ela volta como `fetch_timeout`, sem conteúdo. ## Endpoint de pesquisa: perguntas frequentes ### Devo usar POST ou GET? POST no código, porque arrays JSON e consultas longas são mais simples em um corpo. GET serve para um teste rápido no terminal ou para uma ferramenta que só envia query strings. Ambos retornam a mesma resposta e custam o mesmo. ### Posso pedir mais de 20 resultados? Não. 20 é o máximo por chamada. Os agentes raramente precisam de mais: uma segunda pesquisa com a consulta reformulada costuma trazer fontes melhores do que uma lista longa. ### As páginas são lidas uma após a outra? Não, em paralelo. Uma página que não responde em 15 segundos é retornada sem conteúdo, como `fetch_timeout`, para que um site lento não segure a resposta inteira. ### Qual mecanismo de pesquisa produz os resultados? Os resultados vêm de uma pesquisa na web ao vivo, executada no momento da sua chamada, na ordem em que o mecanismo de pesquisa os classifica; nada é servido de um índice antigo. Não divulgamos quais provedores upstream executam a pesquisa. --- LLMWebSearch: O LLMWebSearch é uma API de pesquisa na web para agentes de IA que retorna resultados classificados com o conteúdo das principais páginas em Markdown, pago com cripto sem envio de documentos. Os créditos pré-pagos a partir de US$ 1,20/1K pesquisas nunca expiram. Sem KYC — sem documento, sem selfie, sem comprovantes. Pague com cripto.