# Quick start dell'API di ricerca web: la tua prima ricerca in due minuti

> API di ricerca web: ottieni una chiave, esegui la prima ricerca con curl, Python o Node.js e leggi le pagine in Markdown. Senza KYC, paghi in criptovalute.

- URL: https://llmwebsearch.com/it/docs/
- Ultimo aggiornamento: 2026-10-22
- Editore: LLMWebSearch (https://llmwebsearch.com)

Un solo endpoint fa il lavoro: invia una domanda a `/search` e ricevi risultati classificati, con le prime pagine già lette e ripulite in Markdown. Questa pagina va da un saldo vuoto a una chiamata funzionante, poi rimanda a ogni altra pagina della documentazione.

**Risposta rapida — Come eseguo la mia prima ricerca con un'API di ricerca web per agenti AI?**

Invia la tua domanda a `POST https://llmwebsearch.com/api/v1/search` con la tua chiave API come Bearer token. **LLMWebSearch** esegue una ricerca web live e restituisce fino a 20 risultati classificati, con le prime 3 pagine lette e restituite in Markdown. Un credito paga l'intera chiamata, a partire da 1,20 USD/1K ricerche da ottobre 2026. Senza KYC; paghi in criptovalute.

## L'API in una sola scheda

| Attributo | Valore |
| --- | --- |
| Base URL | `https://llmwebsearch.com/api/v1` |
| Cerca | `POST` o `GET https://llmwebsearch.com/api/v1/search` |
| Leggi URL che hai già | `POST https://llmwebsearch.com/api/v1/extract` |
| Crediti rimanenti | `GET https://llmwebsearch.com/api/v1/credits`, gratis |
| Autenticazione | Passa la tua chiave API come Bearer token nell'header Authorization, oppure come query parameter api_key |
| 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 |
| Il nostro lettore di pagine | `LLMWebSearch/1.0 (+https://llmwebsearch.com/bot/)`, token robots.txt `LLMWebSearch` |
| Pack più piccolo | 5.000 ricerche per 9,25 USD; i crediti non scadono mai |

## Come ottengo una chiave API?

Non c'è un modulo di registrazione. Aspettare che la blockchain confermi la tua ricarica è la parte più lunga.

1. **Ricarica il saldo in criptovalute** — Invia almeno 25 USD in BTC, USDT, USDC, ETH, SOL, LTC. Accedi con un numero di account; un indirizzo email è facoltativo.
2. **Acquista un pack di ricerche** — 5.000 ricerche per 9,25 USD basta abbondantemente per collegare la ricerca a un agent e provare tutte le opzioni.
3. **Copia la chiave** — Una volta confermato il tuo top-up in criptovalute e acquistato un pack, la tua chiave API ti aspetta nella dashboard. Conservala in una variabile d'ambiente chiamata LLMWEBSEARCH_API_KEY.

## Come appare la prima ricerca?

È una singola POST HTTPS con un piccolo body JSON. È obbligatoria solo `q`: la domanda o le parole chiave, come le digiterebbe una persona. I valori predefiniti vanno già bene per la maggior parte degli agent. Ottieni 5 risultati classificati, e le pagine dietro i primi 3 vengono lette e restituite come Markdown fino a 6.000 caratteri ciascuna.

Gli tre snippet qui sotto inviano la stessa ricerca. Scegli quello che corrisponde al tuo stack, imposta `LLMWEBSEARCH_API_KEY` nella tua shell ed eseguilo.

*curl: una ricerca, lette le prime 3 pagine*

```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: elenca le fonti e la loro dimensione*

```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()
data = resp.json()
print("credits used:", data["credits_used"])
for r in data["results"]:
    size = r.get("word_count", 0)
    print(r["position"], r["title"], r["url"], r["content_status"], size, "words")

```

*Node.js 18+: stampa la prima pagina che è stata letta*

```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 data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
const first = data.results.find((r) => r.content_status === 'ok');
console.log(first ? `${first.title}\n${first.url}\n\n${first.content.slice(0, 600)}` : 'No page could be read.');

```

## Cosa torna indietro?

Un oggetto JSON con la tua `query`, l'ora della chiamata in `created_at`, il prezzo in `credits_used` e un array `results` in ordine classificato. Ogni risultato ha `position`, `title`, `url`, `host` e `snippet`, più `published_at` quando la data è nota.

Il campo da tenere d'occhio è `content_status`. Quando dice `ok`, la pagina è stata letta e il suo contenuto principale si trova in `content`, con un `word_count`. I risultati oltre `read` dicono `not_requested`. Una pagina che non è stato possibile leggere indica il motivo, per esempio `blocked_by_robots`. La [pagina del formato di risposta](https://llmwebsearch.com/it/docs/response/) spiega ogni campo.

## Quali parametri cambierò più spesso?

Sei parametri coprono quasi ogni agent. Sono tutti opzionali.

| Parametro | Cosa cambia |
|---|---|
| `max_results` | Quanti risultati classificati tornano indietro, da 1 a 20 |
| `read` | Quanti dei primi risultati vengono letti, da 0 a 10 |
| `max_chars` | Il limite di lunghezza del contenuto di ogni pagina, da 500 a 50.000 caratteri |
| `topic` e `time_range` | Notizie invece di pagine web, e una finestra di freschezza |
| `include_domains` | Risultati solo dai siti che elenchi |
| `country` e `language` | Dove e in quale lingua viene eseguita la ricerca |

Il [riferimento della ricerca](https://llmwebsearch.com/it/docs/search/) documenta ognuno con un esempio, più `format` e `exclude_domains`.

## Quanti crediti usa una chiamata?

La maggior parte delle chiamate ne usa uno. L'insieme completo delle regole:

- **Ricerca che legge da 0 a 3 pagine: 1 credito.** Include fino a 20 risultati classificati.
- **Ricerca che legge da 4 a 10 pagine: 2 crediti.**
- **Extract:** Leggere pagine di cui hai già gli URL costa 1 credito per ogni gruppo iniziato di 3 pagine restituite con contenuto, fino a 20 URL per chiamata; gli URL rifiutati o falliti non vengono contati.
- **Errori: 0 crediti.** Un parametro sbagliato, una chiave errata, un saldo vuoto o una ricerca fallita non costano nulla.
- **Una pagina che non è stato possibile leggere** all'interno di una ricerca riuscita non ne cambia il prezzo.
- **Controllare il saldo** con `GET https://llmwebsearch.com/api/v1/credits` è gratis.

I crediti di ricerca non hanno data di scadenza: quello che non usi questo mese è ancora lì l'anno prossimo.

## Cosa succede quando un sito non vuole essere letto?

Il risultato appare comunque, con titolo, URL e snippet, ma senza il contenuto della pagina. Il nostro reader rispetta robots.txt: si presenta come LLMWebSearch, segue le regole che un sito scrive per lui o per tutti i robot, e lascia fuori il contenuto di qualsiasi pagina che non gli è permesso leggere. Un sito che imposta Content-Signal: ai-input=no nel suo robots.txt tiene le sue pagine fuori dal contenuto dei tuoi risultati.

Quando un sito risponde al nostro lettore con un rifiuto, il risultato riporta `content_status: "target_refused"` e lo status HTTP del sito stesso in `target_status`. Quando un sito respinge il nostro reader, il risultato torna senza contenuto e con lo status del sito: non risolviamo mai CAPTCHA, non accediamo agli account e non aggiriamo un blocco o un paywall. La [pagina degli errori](https://llmwebsearch.com/it/docs/errors/) elenca ogni status e quelli per cui vale la pena riprovare.

## Dove vado dopo?

- [Endpoint di ricerca](https://llmwebsearch.com/it/docs/search/) — Ogni parametro di /search, con esempi
- [Endpoint di estrazione](https://llmwebsearch.com/it/docs/extract/) — Leggi da 1 a 20 URL che hai già
- [Formato della risposta](https://llmwebsearch.com/it/docs/response/) — Ogni campo e ogni content_status
- [Errori](https://llmwebsearch.com/it/docs/errors/) — Errori HTTP, status delle pagine, regole di retry
- [Python](https://llmwebsearch.com/it/docs/python/) — requests, httpx async, una risposta con citazioni
- [Node.js](https://llmwebsearch.com/it/docs/node/) — fetch, un piccolo pool, lo stesso ciclo di citazioni
- [curl e jq](https://llmwebsearch.com/it/docs/curl/) — Ricette da terminale
- [Server MCP](https://llmwebsearch.com/it/docs/mcp/) — search_web per Claude Code e Claude Desktop
- [LangChain e LlamaIndex](https://llmwebsearch.com/it/docs/langchain/) — Uno strumento e un retriever
- [OpenAI function calling](https://llmwebsearch.com/it/docs/openai/) — Schema dello strumento, loop e Agents SDK
- [n8n](https://llmwebsearch.com/it/docs/n8n/) — Strumento HTTP Request per un AI Agent
- [OpenClaw](https://llmwebsearch.com/it/docs/openclaw/) — La nostra ricerca tramite MCP

## Avvio rapido: domande frequenti

### Serve un SDK?

No. LLMWebSearch è una semplice API HTTPS, quindi funziona qualsiasi client HTTP. Questa documentazione fornisce codice da copiare e incollare per Python, Node.js e curl, e definizioni degli strumenti per MCP, LangChain, LlamaIndex, OpenAI function calling, n8n e OpenClaw. Non pubblichiamo alcun package.

### L'API scrive la risposta al posto mio?

No. L'API restituisce fonti, non una risposta scritta: il tuo modello legge le pagine, scrive la risposta e cita gli URL. Così resti libero di scegliere il modello, il prompt e lo stile delle citazioni.

### Posso mettere la chiave nell'URL?

Sì, come parametro di query `api_key` di `GET /search`. L'header `Authorization` è la scelta più sicura, perché gli URL finiscono nei log e nella cronologia della shell. Crea una chiave API per agente, app o teammate e revoca qualsiasi di esse dalla dashboard senza toccare le altre.

### C'è un piano gratuito per provarla?

No. Non c'è un piano gratuito: il pack da 5.000 ricerche è il modo per provarlo, acquistato dal top-up minimo; quello che hai aggiunto solo per raggiungere quel minimo torna su richiesta entro 30 giorni, in USDT o USDC, purché non sia stato speso.

---

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.