# Formato della risposta: ogni campo di una ricerca, spiegato

> Formato della risposta della Search API: ogni campo di /search e /extract, gli otto valori di content_status, con un esempio. Senza KYC, in criptovalute.

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

La risposta di una ricerca è un oggetto JSON: alcuni campi sulla chiamata, poi un array `results` ordinato per rilevanza. Ogni risultato indica se la sua pagina è stata letta e, in tal caso, contiene il contenuto. Ecco ogni campo, con gli stati che un agente dovrebbe gestire.

**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.

*Risposta di POST /search (illustrativa)*

```json
{
  "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](https://llmwebsearch.com/it/docs/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](https://llmwebsearch.com/it/docs/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](https://llmwebsearch.com/it/privacy/).

---

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.