Docs · response

Formato di risposta della Read API, campo per campo

Q: 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.

Q: 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.

Q: 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.

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.

Ultimo aggiornamento: 22 ottobre 2026 · 5 min di lettura

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)

{
  "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.

next_cursor è presente finché ci sono altri risultati pronti; invialo indietro come cursor per ottenerli. La pagina batch e crawl ha un ciclo di polling completo.

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

{
  "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 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.