Risposta rapida
Cosa restituisce l'API LLMWebSearch per una ricerca?
LLMWebSearch restituisce un JSON con query, created_at, credits_used e un array results ordinato per rilevanza. Ogni risultato ha posizione, titolo, URL, host e snippet, e un content_status; quando è ok, il contenuto principale della pagina è in content con un word_count. Una ricerca con un massimo di 3 pagine lette costa 1 credito, a partire da 1,20 USD/1K ricerche a ottobre 2026. Senza KYC; paghi in criptovalute.
Quali campi descrivono la chiamata?
Livello superiore di una risposta /search.
| Campo | Tipo | Significato |
|---|---|---|
query | string | La query così come l'abbiamo eseguita, dopo aver rimosso gli spazi |
created_at | string | Quando è stata eseguita la ricerca, ISO 8601 in UTC |
credits_used | integer | Quanto è costata la chiamata: 1, oppure 2 quando read era da 4 a 10 |
results | array | Risultati ordinati per rilevanza, dal migliore, al massimo max_results elementi |
Quali campi contiene ogni risultato?
Un campo che la pagina o il risultato di ricerca non forniscono viene omesso invece di essere inviato vuoto.
| Campo | Tipo | Quando è presente | Significato |
|---|---|---|---|
position | integer | Sempre | Posizione nella ricerca, a partire da 1 |
title | string | Sempre | Titolo del risultato |
url | string | Sempre | Indirizzo della pagina |
host | string | Sempre | Nome host della pagina, comodo per raggruppare o citare |
snippet | string | Sempre | Breve estratto mostrato dalla ricerca |
published_at | string | Quando la data è nota | Data di pubblicazione dalla pagina o dal risultato di ricerca |
content_status | string | Sempre | Se la pagina è stata letta e, in caso negativo, perché |
content | string | Quando content_status è ok | Contenuto principale in Markdown o testo semplice, tagliato a max_chars |
word_count | integer | Quando content_status è ok | Parole nell'intero testo estratto, contate prima del taglio |
target_status | integer | Con target_refused | Lo stato HTTP con cui il sito ha risposto, come 403 o 429 |
Cosa significa ogni content_status?
Nessuna di queste modifiche cambia il prezzo della ricerca. Descrivono una singola pagina, mai l'intera chiamata.
content_status | Significato | Cosa dovrebbe fare un agente |
|---|---|---|
ok | La pagina è stata letta; content contiene il suo testo principale | Usalo e cita url |
not_requested | Il risultato supera il conteggio read | Aumenta read, oppure leggilo tramite /extract se necessario |
blocked_by_robots | Il robots.txt del sito non consente al nostro reader di accedere a questa pagina | Affidati allo snippet o a un'altra fonte |
blocked_by_site_policy | Il sito dichiara Content-Signal: ai-input=no | Affidati allo snippet o a un'altra fonte |
target_refused | Il sito ha rifiutato la richiesta; vedi target_status | Non ritentare la pagina; usa un'altra fonte |
fetch_failed | Errore DNS, TLS o di connessione, oppure la pagina non esiste più | Prova un altro risultato; un nuovo tentativo più tardi potrebbe funzionare |
fetch_timeout | La pagina non ha risposto entro 15 secondi | Prova un altro risultato; un nuovo tentativo più tardi potrebbe funzionare |
unsupported_content | Il link è un file che non possiamo convertire in testo | Usa lo snippet o un altro risultato |
Come appare una risposta completa?
L'esempio qui sotto ha richiesto 5 risultati con i primi 4 letti, quindi è costato 2 crediti. I risultati 1 e 3 sono stati letti. Il risultato 2 appartiene a un sito il cui robots.txt tiene fuori il nostro reader, il risultato 4 ha rifiutato la richiesta e il risultato 5 è oltre read. Titoli, URL e valori sono illustrativi.
{
"query": "how to rotate api keys without downtime",
"created_at": "2026-10-22T10:15:04Z",
"credits_used": 2,
"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.",
"content_status": "ok",
"content": "# Secrets management basics\n\n**Never** commit keys to a repository.",
"word_count": 1310
},
{
"position": 4,
"title": "Key management service guide",
"url": "https://cloud.example.com/kms-guide",
"host": "cloud.example.com",
"snippet": "Store keys in a managed vault and rotate them on a schedule.",
"content_status": "target_refused",
"target_status": 403
},
{
"position": 5,
"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"
}
]
}Quali risultati ottengono uno stato della pagina diverso da not_requested?
Solo i primi read risultati e ogni voce di una chiamata con /extract. Sono le pagine che il nostro reader ha effettivamente provato. Tutto ciò che va oltre il conteggio di read resta not_requested, qualunque cosa avrebbe risposto il sito.
L'ordine non cambia mai: il reader lavora sulle posizioni 1, 2, 3 e così via, mai su un risultato successivo al posto di uno precedente che ha fallito. Se un agente ha bisogno di un sostituto per una pagina rifiutata, può leggere il risultato successivo tramite /extract.
Come appare una risposta di extract?
/extract restituisce credits_used e un array results nell'ordine degli URL che hai inviato. Ogni voce ha il campo url e un campo content_status; con ok aggiunge title, content e word_count, e con target_refused aggiunge target_status. Non ci sono position, host né snippet, perché nessuna ricerca è stata eseguita.
La documentazione di extract mostra un esempio completo e spiega come vengono contati i suoi crediti.
Come trasformo i risultati in contesto per un modello?
Numera le fonti, tieni l'URL accanto a ciascuna e passa al modello solo ciò che gli serve. Un layout compatto funziona bene: [1] title — url, poi il contenuto di quella pagina, poi la fonte successiva. Chiedi al modello di citare con gli stessi numeri.
Quando un risultato non ha contenuto, passa al modello il suo snippet e specifica che è solo uno snippet. Così eviti risposte basate su una pagina che il modello non ha mai visto. La pagina Python ha un breve ciclo che fa tutto questo entro un budget di token.
Formato della risposta: domande frequenti
Il contenuto è sempre in Markdown?
Markdown per impostazione predefinita. Invia format: "text" per ottenere testo semplice senza markup, ad esempio quando devi solo contare le parole o classificare le pagine. Il nome del campo resta content.
Perché published_at manca su alcuni risultati?
Molte pagine non indicano una data, e alcuni risultati di ricerca non ne mostrano nessuna. In quel caso il campo viene omesso, quindi verifica che sia presente prima di usarlo.
Possono comparire nuovi campi in futuro?
Sì. In versione 1 i campi possono essere aggiunti, ma non vengono mai rinominati o rimossi. Scrivi il tuo parser in modo che ignori i campi che non conosce.
Il contenuto viene conservato da voi?
No. Non addestriamo alcun modello sulle tue query né su ciò che l'API restituisce, e non aggiungiamo regole nostre contro la conservazione dei risultati; restano validi i diritti dei siti di cui leggi le pagine. Il nostro log delle richieste conserva solo una breve traccia di ogni chiamata, descritta nella pagina sulla privacy.