# Riferimento dell'endpoint di ricerca: POST e GET /search > Riferimento dell'endpoint di ricerca: parametri di POST e GET /search, da read e max_chars a topic, time_range e filtri di dominio. Senza KYC, in criptovalute. - URL: https://llmwebsearch.com/it/docs/search/ - Ultimo aggiornamento: 2026-10-22 - Editore: LLMWebSearch (https://llmwebsearch.com) `/search` esegue una ricerca web in tempo reale, classifica fino a 20 risultati e legge le pagine dietro ai primi. Questa pagina elenca ogni parametro, il suo valore predefinito, i suoi limiti e cosa comporta per il prezzo. **Risposta rapida — Quali parametri accetta l'endpoint di ricerca di LLMWebSearch?** L'endpoint `/search` di **LLMWebSearch** richiede solo `q`. I parametri opzionali impostano quanti risultati tornano (`max_results`), quante pagine vengono lette (`read`), il formato e la lunghezza del contenuto, news o web, un intervallo di tempo, il paese e la lingua, e i domini da mantenere o scartare. Leggere fino a 3 pagine costa 1 credito, a partire da 1,20 USD/1K ricerche a ottobre 2026. Senza KYC; paghi in criptovalute. ## /search at a glance | Attributo | Valore | | --- | --- | | Metodi | `POST` con un body JSON, oppure `GET` con gli stessi nomi nella query string | | URL | `https://llmwebsearch.com/api/v1/search` | | Obbligatorio | `q`: da 1 a 400 caratteri; gli operatori di ricerca vengono passati così come sono scritti | | Valori predefiniti | 5 risultati, i primi 3 letti, Markdown fino a 6.000 caratteri per pagina | | Fatturazione | Un credito paga una ricerca: fino a 20 risultati classificati, con le pagine dei primi 3 lette e restituite come Markdown. Leggere da 4 a 10 pagine costa 2 crediti. Una chiamata che termina in errore non costa nulla | | Risultati | I risultati provengono da una ricerca web live eseguita al momento della tua chiamata, nell'ordine in cui il motore di ricerca li classifica; nulla viene servito da un vecchio indice | | Filtri | Scegli il paese e la lingua dei risultati, un intervallo di tempo (ultimo giorno, settimana, mese o anno), risultati web o news, e i domini da includere o escludere | | Page reader | `LLMWebSearch/1.0 (+https://llmwebsearch.com/bot/)` | ## Cerca sul web e leggi i risultati principali (POST) `POST /api/v1/search` Esegue una ricerca web in tempo reale e restituisce risultati classificati. Le pagine dei primi `read` risultati vengono recuperate in parallelo e il loro contenuto principale viene restituito in `content`. L'esempio chiede come ruotare le chiavi API; titoli, date e valori sono illustrativi. Autenticazione: chiave API nell'header `Authorization: Bearer API_KEY`. **Body della richiesta** | Campo | Tipo | Obbligatorio | Descrizione | | --- | --- | --- | --- | | `q` | string | Sì | La query di ricerca, da 1 a 400 caratteri. Le virgolette e gli operatori come `site:` vengono mantenuti così come sono scritti. | | `max_results` | integer | No | Numero di risultati classificati, da 1 a 20. Predefinito 5. | | `read` | integer | No | Quanti dei primi risultati vengono letti e restituiti con il loro contenuto, da 0 a 10. Predefinito 3. Da 4 in su la chiamata costa 2 crediti. | | `format` | string | No | `markdown` (predefinito) oppure `text` per il contenuto della pagina. | | `max_chars` | integer | No | Limite di lunghezza del contenuto di ogni pagina, da 500 a 50.000 caratteri. Predefinito 6.000. | | `topic` | string | No | `web` (predefinito) oppure `news`. | | `time_range` | string | No | `day`, `week`, `month` oppure `year`. Nessun valore predefinito: qualsiasi data. | | `country` | string | No | Codice paese a due lettere (ISO 3166-1 alpha-2) per il luogo in cui viene eseguita la ricerca. Predefinito `us`. | | `language` | string | No | Lingua dei risultati, come `en`, `de` oppure `pt-BR`. Predefinito `en`. | | `include_domains` | string[] | No | Fino a 20 domini; vengono mantenuti solo i risultati da questi domini e dai loro sottodomini. | | `exclude_domains` | string[] | No | Fino a 20 domini i cui risultati vengono scartati. | *Esempio: 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 } ``` *Esempio: 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 } ``` **Risposta** `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); ``` ## Cerca sul web (GET) `GET /api/v1/search` La stessa ricerca con i parametri nella query string, codificati URL. Le liste come `include_domains` si scrivono come un unico valore separato da virgole. Comodo per un test rapido o per strumenti che inviano solo richieste GET. L'esempio richiede solo i risultati (`read=0`). Autenticazione: chiave API nell'header `Authorization: Bearer API_KEY`. **Parametri** | Nome | In | Tipo | Obbligatorio | Descrizione | | --- | --- | --- | --- | --- | | `q` | query | string | Sì | La query di ricerca, codificata per URL, da 1 a 400 caratteri. | | `max_results` | query | integer | No | Da 1 a 20. Default 5. | | `read` | query | integer | No | Da 0 a 10. Default 3; 4 o più costano 2 crediti. | | `format` | query | string | No | `markdown` (predefinito) o `text`. | | `max_chars` | query | integer | No | Da 500 a 50.000 per pagina. Default 6.000. | | `topic` | query | string | No | `web` (predefinito) oppure `news`. | | `time_range` | query | string | No | `day`, `week`, `month` o `year`. | | `country` | query | string | No | Codice ISO 3166-1 alpha-2. Default `us`. | | `language` | query | string | No | Codice lingua. Default `en`. | | `include_domains` | query | string | No | Elenco separato da virgole, fino a 20 domini. | | `exclude_domains` | query | string | No | Elenco separato da virgole, fino a 20 domini. | | `api_key` | query | string | No | La tua chiave, quando non invii l'header `Authorization`. | **Risposta** `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)); ``` ## Come ottengo risultati senza alcun contenuto della pagina? Imposta `read` su `0`. Ogni risultato torna allora con titolo, URL, host, snippet e data, e `content_status: "not_requested"`. La risposta è molto più piccola, il che aiuta quando l'agente deve solo scegliere quali link contano. Il prezzo resta di 1 credito, lo stesso della lettura di un massimo di 3 pagine. Uno schema comune è una ricerca `read=0` per fare una shortlist, poi una [chiamata extract](https://llmwebsearch.com/it/docs/extract/) sui due o tre URL scelti dal modello. ## Quando una ricerca costa 2 crediti? Quando `read` è tra 4 e 10. Leggere più pagine richiede più lavoro da parte nostra, quindi il prezzo raddoppia una volta sola e resta a 2 crediti fino al massimo di 10 pagine. `credits_used` in ogni risposta mostra quanto è costata la chiamata. Una pagina che non è stato possibile leggere, per una regola di robots.txt o per un rifiuto, non abbassa né alza quel prezzo. Se la maggior parte delle volte ti servono solo poche pagine complete, tieni `read` a 3 e chiama `/extract` per la rara pagina in più. ## Come cerco notizie recenti? Invia `topic: "news"` e un `time_range`. I risultati provengono allora da articoli di notizie, e `time_range` mantiene solo quelli degli ultimi `day`, `week`, `month` o `year`. `published_at` viene compilato quando l'articolo o il risultato di ricerca indica una data. Lo stesso filtro di freschezza funziona con `topic: "web"`. È utile per domande come uscite recenti o variazioni di prezzo, dove una pagina vecchia trarrebbe in inganno il modello. *Notizie dell'ultima settimana, primi 3 articoli letti* ```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}' ``` ## Come limito i risultati a determinati siti? Elencali in `include_domains`, fino a 20 voci. Vengono mantenuti solo i risultati il cui host è uno di quei domini, o uno dei loro sottodomini: `example.com` corrisponde anche a `docs.example.com`. Usa `exclude_domains` al contrario, per esempio per escludere il tuo sito dai risultati. In un body POST entrambi i campi sono array JSON. In una richiesta GET, scrivili come un unico valore separato da virgole. Anche la query stessa può contenere un operatore `site:`; viene passato alla ricerca così come scritto. ## Cosa cambiano paese e lingua? `country` imposta dove viene eseguita la ricerca, con un codice di due lettere come `us`, `de` o `br`. Le classifiche differiscono da paese a paese, soprattutto per servizi locali, prezzi e normative. `language` imposta la lingua dei risultati, come `en`, `fr` o `pt-BR`. Entrambi hanno come default Stati Uniti e inglese. Impostali insieme quando l'agente lavora per utenti di un unico mercato: un utente tedesco che chiede di regole fiscali vuole `country: "de"` e `language: "de"`. ## Quanto testo della pagina torna indietro? Fino a `max_chars` caratteri per pagina, 6.000 come default e comunque da 500 a 50.000. Il limite protegge la finestra di contesto del modello: tre pagine da 6.000 caratteri sono circa 4.500 token di inglese. `word_count` conta l'intero testo estratto, prima del taglio, così puoi capire quando una pagina è stata ridotta. Quando una risposta richiede un unico documento lungo, cerca prima con un limite basso, poi recupera quella sola pagina tramite `/extract` con un limite più alto. Una pagina lenta non viene attesa all'infinito: dopo 15 secondi torna come `fetch_timeout`, senza contenuto. ## Endpoint di ricerca: domande frequenti ### Devo usare POST o GET? POST nel codice, perché gli array JSON e le query lunghe sono più semplici in un body. GET si presta a un test rapido in un terminale o a uno strumento che invia solo query string. Entrambi restituiscono la stessa risposta e costano lo stesso. ### Posso chiedere più di 20 risultati? No. 20 è il massimo per chiamata. Gli agenti raramente ne servono di più: una seconda ricerca con una query riformulata di solito porta a fonti migliori di un lungo elenco. ### Le pagine vengono lette una dopo l'altra? No, in parallelo. Una pagina che non risponde entro 15 secondi viene restituita senza contenuto, come `fetch_timeout`, così un sito lento non blocca l'intera risposta. ### Quale motore di ricerca produce i risultati? I risultati provengono da una ricerca web live eseguita al momento della tua chiamata, nell'ordine in cui il motore di ricerca li classifica; nulla viene servito da un vecchio indice. Non pubblichiamo quali provider upstream eseguono la ricerca. --- LLMWebSearch: LLMWebSearch è un'API di ricerca web per agenti AI che restituisce risultati classificati con il contenuto delle pagine principali in Markdown, pagata in criptovalute senza caricare documenti d'identità. I crediti prepagati da 1,20 USD/1K ricerche non scadono mai. Senza KYC — niente documento, niente selfie, niente documenti. Paghi in criptovalute.