# Formato di risposta della Read API, campo per campo

> Formato di risposta della Read API: ogni campo restituito per pagina, da markdown a final_url, più i risultati dei job. Senza KYC, paghi in criptovalute.

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

Ogni chiamata `/read` restituisce un oggetto JSON: il contenuto della pagina nel formato che hai richiesto, i suoi metadati e tre campi che ti dicono cosa è successo e quanto è costato. I risultati dei job riutilizzano lo stesso oggetto.

**Risposta rapida — Cosa contiene la risposta della WebReaderAPI read?**

Una risposta **WebReaderAPI** `/read` contiene il contenuto della pagina in `markdown` (o `text` o `html`), i suoi metadati (`title`, `description`, `author`, `published_at`, `language`, `site_name`, `word_count`) e i fatti del recupero: `final_url`, `status_code`, `rendered` e `credits_used`. Una pagina normale usa 1 credito, a partire da 0,07 USD/1K pagine da ottobre 2026. Senza KYC; paghi in criptovalute.

## Quali campi descrivono il recupero?

Questi campi sono sempre presenti in una risposta riuscita.

| Campo | Tipo | Significato |
| --- | --- | --- |
| `url` | string | L'indirizzo che hai inviato |
| `final_url` | string | L'indirizzo effettivamente letto, dopo i redirect (al massimo 5) |
| `status_code` | integer | Lo stato HTTP restituito dal sito per l'indirizzo finale, normalmente 200 |
| `fetched_at` | string | Ora del recupero, ISO 8601 in UTC |
| `rendered` | boolean | `true` quando una pagina è stata costruita da un browser headless |
| `credits_used` | integer | Crediti fatturati per questa pagina: 1, 2 con un browser, più 10 con `country`; i PDF 1 ogni 10 pagine iniziate |

## Quali campi descrivono la pagina?

I metadati provengono dalla pagina stessa: il suo tag title, i meta tag, i dati strutturati e la firma visibile. Un campo che la pagina non fornisce è assente, quindi verificalo prima di usarlo.

| Campo | Tipo | Significato |
| --- | --- | --- |
| `title` | string | Il titolo della pagina o dell'articolo |
| `description` | string | Il riassunto che la pagina dà di sé |
| `language` | string | Codice lingua del contenuto, come `en` o `de` |
| `author` | string | L'autore indicato sulla pagina |
| `published_at` | string | Data di pubblicazione dichiarata dalla pagina |
| `site_name` | string | Il nome del sito stesso |
| `word_count` | integer | Parole nel contenuto restituito, dopo l'estrazione e prima di `max_chars` |

## Dov'è il contenuto stesso?

Viene restituito un campo di contenuto, denominato in base al `format` che hai scelto.

| Campo | Quando | Contenuto |
| --- | --- | --- |
| `markdown` | `format=markdown` (predefinito) | Titoli, paragrafi, elenchi, tabelle e link in Markdown; anche le immagini con `include_images=true` |
| `text` | `format=text` | Testo semplice, paragrafi separati da righe vuote |
| `html` | `format=html` | HTML pulito del contenuto principale, senza script, stili o annunci |
| `links` | `include_links=true` | Elenco di `{url, text}` per i link trovati nella pagina, URL assoluti |

*Una risposta completa (i valori sono a scopo illustrativo)*

```json
{
  "url": "https://example.com/guides/compost",
  "final_url": "https://example.com/guides/compost-at-home",
  "status_code": 200,
  "fetched_at": "2026-10-22T10:02:44Z",
  "rendered": false,
  "credits_used": 1,
  "title": "Compost at home: a beginner's guide",
  "description": "What to put in a compost bin, and what to leave out.",
  "language": "en",
  "author": "Sam Rivera",
  "published_at": "2026-09-14",
  "site_name": "Example Garden",
  "markdown": "# Compost at home: a beginner's guide\n\nA compost bin turns kitchen scraps into soil...\n\n## What goes in\n\n- Fruit and vegetable peels\n- Coffee grounds\n\nSee also [Choosing a bin](https://example.com/guides/bins).",
  "word_count": 1184,
  "links": [
    { "url": "https://example.com/guides/bins", "text": "Choosing a bin" }
  ]
}
```

## Come distinguo una pagina renderizzata da una semplice?

Guarda `rendered`. Con `render=auto`, l'API legge prima l'HTML grezzo; avvia un browser solo quando quell'HTML contiene troppo poco testo, e in quel caso imposta `rendered` su `true` e `credits_used` su 2. Se un sito che leggi spesso torna sempre renderizzato, invia `render=true` fin dall'inizio: il costo è lo stesso e salti un primo passo inutile.

Se una pagina torna non renderizzata ma scarna, confronta `word_count` con ciò che vedi in un browser. Un conteggio basso di solito significa che il contenuto richiede JavaScript; riprova una volta con `render=true`.

## Perché final_url può differire da url?

Perché i siti reindirizzano. Un link breve, un vecchio indirizzo, una barra finale mancante o un cambio di lingua ti mandano altrove. L'API segue fino a 5 redirect e riporta l'indirizzo che ha effettivamente letto in `final_url`.

Salva `final_url` come fonte canonica di un documento in un indice RAG. Due valori diversi di `url` che finiscono sullo stesso `final_url` sono la stessa pagina, quindi puoi scartare il duplicato prima di incorporarlo.

## Come appare il risultato di un job?

`GET https://webreaderapi.com/api/v1/jobs/{job_id}` restituisce `job_id`, `status` (`queued`, `running` o `done`), `results`, `next_cursor` e il `credits_used` in corso del job. Ogni elemento di `results` ha una di due forme:

- una risposta completa di `/read`, esattamente come descritto sopra, per una pagina che è stata letta;
- `{url, error}` per una pagina che non lo è stata, dove `error` ha gli stessi `code` e `message` di un [errore API](https://webreaderapi.com/it/docs/errors/).

`next_cursor` è presente finché ci sono altri risultati pronti; invialo indietro come `cursor` per ottenerli. La [pagina batch e crawl](https://webreaderapi.com/it/docs/crawl/) ha un ciclo di polling completo.

*Una pagina di risultato di un job (i valori sono a scopo illustrativo)*

```json
{
  "job_id": "job_5c1e8a90d2",
  "status": "done",
  "results": [
    { "url": "https://example.com/blog/post-1", "final_url": "https://example.com/blog/post-1", "status_code": 200, "rendered": false, "credits_used": 1, "title": "Post one", "markdown": "# Post one\n\n...", "word_count": 802 },
    { "url": "https://example.org/members/area", "error": { "code": "target_refused", "message": "The site refused the request.", "target_status": 403 } }
  ],
  "credits_used": 1
}
```

## Come appare una risposta di errore?

Un errore torna con uno status HTTP pari o superiore a 400 e un body JSON `{"error": {"code", "message"}}`. Quando è il sito stesso a rifiutare la richiesta, `target_status` indica lo status inviato dal sito. Nessun errore viene addebitato. La [pagina degli errori](https://webreaderapi.com/it/docs/errors/) elenca ogni codice con la sua causa e se un nuovo tentativo può aiutare.

## Formato della risposta: domande frequenti

### Il Markdown viene tagliato quando imposto max_chars?

Sì. Il campo content si ferma a quel numero di caratteri. `word_count` descrive comunque l'intero contenuto estratto, così puoi vedere quanto è stato omesso.

### Perché mancano author o published_at?

Perché la pagina non lo dichiara in un modo che possa essere letto. Molte pagine non indicano autore né data. I campi assenti vengono omessi anziché restituiti vuoti.

### I link nel Markdown sono assoluti?

I link nell'elenco `links` sono assoluti. Scrivi il tuo codice per accettare entrambe le forme nel corpo Markdown e risolvi quelli relativi rispetto a `final_url`.

### Posso ottenere l'HTML grezzo dell'intera pagina?

La cosa più vicina è `format=html` con `main_content=false`, che restituisce l'intera pagina ripulita da script e stili. L'HTML originale byte per byte non fa parte della v1.

---

WebReaderAPI: WebReaderAPI è un'API web reader per agenti AI che converte qualsiasi pagina web pubblica in Markdown pulito, con pagamento in criptovalute e senza caricare documenti d'identità. I crediti prepagati da 0,07 USD/1K pagine non scadono mai e robots.txt viene rispettato. Senza KYC — niente documento, niente selfie, niente documenti. Paga in criptovalute.