Olostep Docs - Endpoint Scrape

Attraverso l’endpoint /v1/scrapes di Olostep puoi estrarre Markdown, HTML, testo, screenshot o JSON strutturato da qualsiasi URL in tempo reale.

Produce markdown pulito, dati strutturati, screenshot o html
Estrai JSON tramite Parsers o estrazione LLM
Gestisce contenuti dinamici: siti renderizzati in js, flussi di login tramite azioni, PDF
Controlla per quanto tempo i risultati vengono conservati con il parametro storage

Per i dettagli dell’API consulta la Riferimento API Endpoint Scrape.

Scraping di un URL

Usa l’endpoint /v1/scrapes per eseguire lo scraping di un singolo URL e scegliere i formati di output.

Installazione

pip install olostep

npm install olostep

# curl è disponibile di default su macOS, Linux e Windows

npm install node-fetch

pip install requests

Utilizzo

Puoi usare l’endpoint per eseguire lo scraping di un singolo URL e scegliere i formati di output. I parametri obbligatori sono url_to_scrape e formats. Altri parametri comuni sono wait_before_scraping (in millisecondi), remove_css_selectors (default, none, o un array di selettori), e country.

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

result = client.scrapes.create(
    url_to_scrape="https://en.wikipedia.org/wiki/Alexander_the_Great",
    formats=["markdown", "html"],
)

print(result.markdown_content)
print(result.html_content)

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

const result = await client.scrapes.create({
  url: 'https://en.wikipedia.org/wiki/Alexander_the_Great',
  formats: ['markdown', 'html'],
})

console.log(result.markdown_content)
console.log(result.html_content)

curl -s -X POST "https://api.olostep.com/v1/scrapes" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url_to_scrape": "https://en.wikipedia.org/wiki/Alexander_the_Great",
    "formats": ["markdown", "html"]
  }'

olostep scrape "https://en.wikipedia.org/wiki/Alexander_the_Great" \
  --formats markdown,html

const endpoint = 'https://api.olostep.com/v1/scrapes'
const payload = {
  url_to_scrape: 'https://en.wikipedia.org/wiki/Alexander_the_Great',
  formats: ['markdown', 'html']
}
const res = await fetch(endpoint, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
})
const data = await res.json()
console.log(data)

import requests
import json

endpoint = "https://api.olostep.com/v1/scrapes"
payload = {
    "url_to_scrape": "https://en.wikipedia.org/wiki/Alexander_the_Great",
    "formats": ["markdown", "html"]
}
headers = {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json"
}

response = requests.post(endpoint, json=payload, headers=headers)
print(json.dumps(response.json(), indent=2))

Risposta

L’API restituisce un oggetto scrape in risposta. Il scrape ha alcune proprietà come id e result. L’oggetto result ha i seguenti campi (secondo il parametro formats alcuni potrebbero essere nulli):

html_content: il contenuto HTML della pagina. Passa formats: ["html"] per ottenere questo.
markdown_content: il contenuto MD della pagina. Passa formats: ["markdown"] per ottenere questo.
text_content: il contenuto di testo della pagina. Passa formats: ["text"] per ottenere questo.
json_content: il contenuto JSON della pagina. Passa formats: ["json"] per ottenere questo e fornisci anche un parametro parser o llm_extract.
screenshot_hosted_url: l’URL ospitato dello screenshot.
html_hosted_url: l’URL ospitato del contenuto HTML
markdown_hosted_url: l’URL ospitato del contenuto Markdown
json_hosted_url: l’URL ospitato del contenuto JSON
text_hosted_url: l’URL ospitato del contenuto di testo
links_on_page: i link sulla pagina
page_metadata: i metadati della pagina

{
  "id": "scrape_6h89o8u1kt",
  "object": "scrape",
  "created": 1745673871,
  "metadata": {},
  "retrieve_id": "6h89o8u1kt",
  "url_to_scrape": "https://en.wikipedia.org/wiki/Alexander_the_Great",
  "result": {
    "html_content": "<html...",
    "markdown_content": "## Alexander the Great...",
    "text_content": null,
    "json_content": null,
    "screenshot_hosted_url": null,
    "html_hosted_url": "https://olostep-storage.s3.us-east-1.amazonaws.com/text_6h89o8u1kt.txt",
    "markdown_hosted_url": "https://olostep-storage.s3.us-east-1.amazonaws.com/markDown_6h89o8u1kt.txt",
    "json_hosted_url": null,
    "text_hosted_url": null,
    "links_on_page": [],
    "page_metadata": { "status_code": 200, "title": "" }
  }
}

Caching

Per ottimizzare la velocità, Olostep fornisce uno strato di caching condiviso opzionale per risultati HTML, Markdown, testo e JSON analizzati.

Come funziona

Quando viene richiesto uno scrape, Olostep verifica se esiste già uno scrape corrispondente con gli stessi parametri. Se viene trovato un match abbastanza recente, il contenuto viene servito istantaneamente dallo storage di Olostep senza avviare un nuovo browser scrape.

Cache Condivisa: La cache è condivisa a livello globale. Se un’altra richiesta ha eseguito lo scraping dello stesso URL con la stessa configurazione entro la tua finestra di freschezza, benefici della velocità.
Elaborazione post-live: Operazioni come llm_extract e filtri links_on_page vengono eseguite al volo sul documento memorizzato nella cache. Memorizzi solo il recupero della pagina principale, mantenendo le tue estrazioni strutturate dinamiche.

Freschezza e `max_age`

Per impostazione predefinita, l’API di produzione esegue sempre uno scrape live per garantire l’accuratezza in tempo reale. Puoi optare per il caching utilizzando il parametro max_age.

Parametro	Tipo	Default	Descrizione
`max_age`	`integer`	`0`	Età accettabile del contenuto in secondi. Se esiste una copia memorizzata nella cache e più recente di `max_age` secondi, viene servita dalla cache.

Comportamento API Predefinito (max_age: 0): Ogni richiesta API attiva uno scrape fresco.
Comportamento Playground Predefinito: Nel dashboard playground, max_age predefinito è di 24 ore (86400 secondi).
Età Massima: La cache ha un limite massimo di 7 giorni (604800 secondi). Qualsiasi max_age richiesto sopra questo limite ricadrà su un massimo di 7 giorni.

Esempi di utilizzo

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

# Opt-in per il caching: Accetta risultati fino a 1 giorno (86400 secondi) vecchi
result = client.scrapes.create(
    url_to_scrape="https://example.com",
    formats=["markdown"],
    max_age=86400
)

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

// Opt-in per il caching: Accetta risultati fino a 1 giorno (86400 secondi) vecchi
const result = await client.scrapes.create({
  url: 'https://example.com',
  formats: ['markdown'],
  maxAge: 86400,
})

# Opt-in per il caching: Accetta risultati fino a 1 ora (3600 secondi) vecchi
curl -X POST "https://api.olostep.com/v1/scrapes" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url_to_scrape": "https://example.com",
    "formats": ["markdown"],
    "max_age": 3600
  }'

const endpoint = 'https://api.olostep.com/v1/scrapes'
const payload = {
  url_to_scrape: 'https://example.com',
  formats: ['markdown'],
  max_age: 86400 // Accetta risultati fino a 1 giorno (86400 secondi) vecchi
}
const res = await fetch(endpoint, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
})
const data = await res.json()
console.log(data)

import requests
import json

endpoint = "https://api.olostep.com/v1/scrapes"
payload = {
    "url_to_scrape": "https://example.com",
    "formats": ["markdown"],
    "max_age": 86400 # Accetta risultati fino a 1 giorno (86400 secondi) vecchi
}
headers = {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json"
}

response = requests.post(endpoint, json=payload, headers=headers)
print(json.dumps(response.json(), indent=2))

Quando viene saltata la cache?

La cache viene automaticamente bypassata (forzando uno scrape live) quando la tua richiesta necessita di:

Sessioni interattive: Richieste che utilizzano session_id o caricano un context del browser personalizzato.
Screenshot: Qualsiasi richiesta che include screenshot nei formati o imposta l’opzione screenshot bypassa la cache.
Tipi di file speciali: Download di file binari o rendering PDF grezzi.
Debugging & Network: Cattura di network_calls o utilizzo di lavori di parser asincroni.

Storage

I risultati dello scrape vengono conservati per circa 7 giorni di default. Passa un oggetto storage per mantenere un risultato più a lungo — o indefinitamente — in modo da poterlo recuperare di nuovo in seguito. Il risultato, i suoi URL ospitati e GET /v1/scrapes/{scrape_id} rimangono disponibili per quella finestra. max_age controlla se una nuova richiesta può riutilizzare una pagina memorizzata nella cache. storage.expires_in controlla per quanto tempo il risultato di questo scrape rimane disponibile. Vedi Caching per max_age. storage è disponibile su tutti i piani per POST /v1/scrapes.

Parametro	Tipo	Default	Descrizione
`storage.expires_in`	`string`	circa 7 giorni (quando `storage` è omesso)	Quanto tempo mantenere il risultato. Uno di `10d`, `30d`, `60d`, `90d`, `180d`, `365d`, o `never` (indefinito).

Utilizzo

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

# Mantieni questo scrape per 90 giorni
result = client.scrapes.create(
    url_to_scrape="https://example.com/product/reviews",
    formats=["markdown"],
    storage={"expires_in": "90d"},
)

print(result.id)

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

// Mantieni questo scrape per 90 giorni
const result = await client.scrapes.create({
  url: 'https://example.com/product/reviews',
  formats: ['markdown'],
  storage: { expires_in: '90d' },
})

console.log(result.id)

curl -X POST "https://api.olostep.com/v1/scrapes" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url_to_scrape": "https://example.com/product/reviews",
    "formats": ["markdown"],
    "storage": { "expires_in": "90d" }
  }'

const endpoint = 'https://api.olostep.com/v1/scrapes'
const payload = {
  url_to_scrape: 'https://example.com/product/reviews',
  formats: ['markdown'],
  storage: { expires_in: '90d' }
}
const res = await fetch(endpoint, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
})
const data = await res.json()
console.log(data)

import requests
import json

endpoint = "https://api.olostep.com/v1/scrapes"
payload = {
    "url_to_scrape": "https://example.com/product/reviews",
    "formats": ["markdown"],
    "storage": {"expires_in": "90d"}
}
headers = {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json"
}

response = requests.post(endpoint, json=payload, headers=headers)
print(json.dumps(response.json(), indent=2))

Estrazione dei link

Passa un oggetto links_on_page nella richiesta per raccogliere i link trovati sulla pagina. Tutti i link vengono restituiti come URL assoluti.

"links_on_page": {
  "include_links": ["/blog/*"],
  "exclude_links": ["*.pdf"],
  "query_to_order_links_by": "pricing"
}

include_links / exclude_links: pattern glob abbinati contro il percorso URL di ciascun link.
query_to_order_links_by: riordina i link restituiti in base alla rilevanza rispetto a questo testo.

I pattern glob abbinano i segmenti di percorso. Un singolo * non attraversa /, quindi "/blog/*" corrisponde a "/blog/post-1" ma non all’indice "/blog" stesso — e non corrisponde mai a "/blog?tag=x" perché le stringhe di query non fanno parte del percorso. Per includere anche l’indice, usa "/blog*" o "{/blog,/blog/**}".

Formati di Scrape

Scegli uno o più formati di output tramite formats:

markdown: markdown adatto a LLM
html: HTML pulito
text: testo semplice
json: output strutturato (tramite parser o llm_extract)
raw_pdf: byte PDF grezzi estratti a URL ospitato
screenshot: impostato tramite azioni per catturare uno screenshot e restituire un URL ospitato

Le chiavi di output vengono restituite all’interno di result come campi *_content e anche come *_hosted_url.

Estrazione di dati strutturati

Puoi estrarre JSON strutturato in due modi: utilizzando Parsers o estrazione LLM.

Utilizzando un Parser (consigliato per la scalabilità)

Definisci formats: ["json"] e fornisci un id del parser.

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

result = client.scrapes.create(
    url_to_scrape="https://www.google.com/search?q=alexander+the+great&gl=us&hl=en",
    formats=["json"],
    parser="@olostep/google-search",
)

print(result.json_content)

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

const result = await client.scrapes.create({
  url: 'https://www.google.com/search?q=alexander+the+great&gl=us&hl=en',
  formats: ['json'],
  parser: '@olostep/google-search',
})

console.log(result.json_content)

curl -s -X POST "https://api.olostep.com/v1/scrapes" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url_to_scrape": "https://www.google.com/search?q=alexander+the+great&gl=us&hl=en",
    "formats": ["json"],
    "parser": {"id": "@olostep/google-search"}
  }'

olostep scrape "https://www.google.com/search?q=alexander+the+great&gl=us&hl=en" \
  --formats json \
  --payload-json '{"parser":{"id":"@olostep/google-search"}}'

const res = await fetch('https://api.olostep.com/v1/scrapes', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url_to_scrape: 'https://www.google.com/search?q=alexander+the+great&gl=us&hl=en',
    formats: ['json'],
    parser: { id: '@olostep/google-search' }
  })
})
console.log(await res.json())

import requests, json

endpoint = "https://api.olostep.com/v1/scrapes"
payload = {
  "url_to_scrape": "https://www.google.com/search?q=alexander+the+great&gl=us&hl=en",
  "formats": ["json"],
  "parser": { 
    "id": "@olostep/google-search" 
  }
}
headers = {
    "Authorization": "Bearer <YOUR_API_KEY>", 
    "Content-Type": "application/json"
}

res = requests.post(endpoint, json=payload, headers=headers)
print(json.dumps(res.json(), indent=2))

Olostep ha alcuni parser pre-costruiti per siti web popolari ma puoi anche creare i tuoi parser tramite il dashboard o chiedere al nostro team di farlo per te. I parser sono auto-riparanti e si aggiorneranno all’ultima versione del sito web.

Utilizzando l’estrazione LLM (schema e/o prompt)

Fornisci llm_extract con uno Schema JSON (schema) e/o un’istruzione in linguaggio naturale (prompt). Puoi passare entrambi i parametri, ma se entrambi sono forniti, schema ha la precedenza. In alternativa, se passi solo un prompt, l’LLM estrarrà i dati in base al prompt e deciderà autonomamente la struttura dei dati.

from olostep import LLMExtract, Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

result = client.scrapes.create(
    url_to_scrape="https://www.berklee.edu/events/stefano-marchese-friends",
    formats=["markdown", "json"],
    llm_extract=LLMExtract(
        schema={
            "type": "object",
            "properties": {
                "event": {
                    "type": "object",
                    "properties": {
                        "title": {"type": "string"},
                        "date": {"type": "string"},
                        "description": {"type": "string"},
                        "venue": {"type": "string"},
                        "address": {"type": "string"},
                        "start_time": {"type": "string"},
                    },
                }
            },
        }
    ),
)

print(result.json_content)

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

const result = await client.scrapes.create({
  url: 'https://www.berklee.edu/events/stefano-marchese-friends',
  formats: ['markdown', 'json'],
  llmExtract: {
    schema: {
      type: 'object',
      properties: {
        event: {
          type: 'object',
          properties: {
            title: { type: 'string' },
            date: { type: 'string' },
            description: { type: 'string' },
            venue: { type: 'string' },
            address: { type: 'string' },
            start_time: { type: 'string' },
          },
        },
      },
    },
  },
})

console.log(result.json_content)

curl -s -X POST "https://api.olostep.com/v1/scrapes" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url_to_scrape": "https://www.berklee.edu/events/stefano-marchese-friends",
    "formats": ["json"],
    "llm_extract": {
      "prompt": "Extract the event title, date, description, venue, address, and start time from the page."
    }
  }'

olostep scrape "https://www.berklee.edu/events/stefano-marchese-friends" \
  --formats json \
  --payload-json '{"llm_extract":{"prompt":"Extract the event title, date, description, venue, address, and start time from the page."}}'

const res = await fetch('https://api.olostep.com/v1/scrapes', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url_to_scrape: 'https://www.berklee.edu/events/stefano-marchese-friends',
    formats: ['json'],
    llm_extract: {
      prompt: 'Extract the event title, date, description, venue, address, and start time from the page.'
    }
  })
})
console.log(await res.json())

import requests, json

endpoint = "https://api.olostep.com/v1/scrapes"
payload = {
  "url_to_scrape": "https://www.berklee.edu/events/stefano-marchese-friends",
  "formats": ["markdown", "json"],
  "llm_extract": {
    "schema": {
      "type": "object",
      "properties": {
        "event": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "date": {"type": "string"},
            "description": {"type": "string"},
            "venue": {"type": "string"},
            "address": {"type": "string"},
            "start_time": {"type": "string"}
          }
        }
      }
    }
  }
}
headers = {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json"
}
res = requests.post(endpoint, json=payload, headers=headers)
print(json.dumps(res.json(), indent=2))

Nota: nel SDK Python, result.json_content è già un dizionario. Nel SDK Node e nell’API grezza è una stringa JSON, quindi analizzala (JSON.parse / json.loads) se hai bisogno di un oggetto. Prezzi: llm_extract costa 10 crediti per scrape. Per ridurre il costo, puoi portare le tue chiavi API o abilitare la tariffazione basata sull’uso. Contatta info@olostep.com per ottenere l’accesso.

Estrazione dei link sulla pagina

Con l’opzione links_on_page, puoi estrarre tutti i link presenti sulla pagina che esegui lo scraping. Accetta i seguenti parametri per aiutare a filtrare e ordinare i link estratti:

absolute_links (booleano, default: true): Quando è vero, restituisce URL completi (es. https://example.com/page) invece di percorsi relativi (es. /page).
query_to_order_links_by (stringa): Ordina i link restituiti in base alla loro somiglianza con il testo della query fornita, dando priorità ai match più rilevanti.
include_links (array di stringhe): Filtra i link estratti utilizzando pattern glob. Usa pattern come *.pdf per abbinare estensioni di file, /blog/* per percorsi specifici, o URL completi come https://example.com/*. Supporta caratteri jolly (*), classi di caratteri ([a-z]), e alternanza ({pattern1,pattern2}).
exclude_links (array di stringhe): Escludi link specifici utilizzando pattern glob, seguendo la stessa sintassi di include_links.

Interazione con la pagina tramite Azioni

Esegui azioni prima dello scraping per interagire con siti dinamici. Azioni supportate:

wait con milliseconds
click con selector
fill_input con selector e value
scroll con direction e amount

È spesso utile usare wait prima/dopo altre azioni per permettere il caricamento della pagina.

Esempio

from olostep import FillInputAction, Olostep, WaitAction

client = Olostep(api_key="YOUR_REAL_KEY")

result = client.scrapes.create(
    url_to_scrape="https://example.com/login",
    formats=["markdown"],
    actions=[
        FillInputAction(selector="input[type=email]", value="john@example.com"),
        WaitAction(milliseconds=500),
        FillInputAction(selector="input[type=password]", value="secret"),
        {"type": "click", "selector": "button[type=\"submit\"]"},
        WaitAction(milliseconds=1500),
    ],
)

print(result.markdown_content)

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_REAL_KEY' })

const result = await client.scrapes.create({
  url: 'https://example.com/login',
  formats: ['markdown'],
  actions: [
    { type: 'fill_input', selector: 'input[type=email]', value: 'john@example.com' },
    { type: 'wait', milliseconds: 500 },
    { type: 'fill_input', selector: 'input[type=password]', value: 'secret' },
    { type: 'click', selector: 'button[type="submit"]' },
    { type: 'wait', milliseconds: 1500 },
  ],
})

console.log(result.markdown_content)

curl -s -X POST "https://api.olostep.com/v1/scrapes" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url_to_scrape": "https://example.com/login",
    "formats": ["markdown"],
    "actions": [
      { "type": "fill_input", "selector": "input[type=email]", "value": "john@example.com" },
      { "type": "wait", "milliseconds": 500 },
      { "type": "fill_input", "selector": "input[type=password]", "value": "secret" },
      { "type": "click", "selector": "button[type=\"submit\"]" },
      { "type": "wait", "milliseconds": 1500 }
    ]
  }'

# Per opzioni complesse come le azioni, usa --payload-file con un file JSON
olostep scrape "https://example.com/login" \
  --formats markdown \
  --payload-file actions.json

# Dove actions.json contiene:
# {
#   "actions": [
#     {"type": "fill_input", "selector": "input[type=email]", "value": "john@example.com"},
#     {"type": "wait", "milliseconds": 500},
#     {"type": "fill_input", "selector": "input[type=password]", "value": "secret"},
#     {"type": "click", "selector": "button[type=\"submit\"]"},
#     {"type": "wait", "milliseconds": 1500}
#   ]
# }

const res = await fetch('https://api.olostep.com/v1/scrapes', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url_to_scrape: 'https://example.com/login',
    formats: ['markdown'],
    actions: [
      { type: 'fill_input', selector: 'input[type=email]', value: 'john@example.com' },
      { type: 'wait', milliseconds: 500 },
      { type: 'fill_input', selector: 'input[type=password]', value: 'secret' },
      { type: 'click', selector: 'button[type="submit"]' },
      { type: 'wait', milliseconds: 1500 }
    ]
  })
})
console.log(await res.json())

import requests, json

endpoint = "https://api.olostep.com/v1/scrapes"
payload = {
  "url_to_scrape": "https://example.com/login",
  "formats": ["markdown"],
  "actions": [
    {"type": "fill_input", "selector": "input[type=email]", "value": "john@example.com"},
    {"type": "wait", "milliseconds": 500},
    {"type": "fill_input", "selector": "input[type=password]", "value": "secret"},
    {"type": "click", "selector": "button[type=\"submit\"]"},
    {"type": "wait", "milliseconds": 1500}
  ]
}
headers = {
    "Authorization": "Bearer <YOUR_API_KEY>", 
    "Content-Type": "application/json"
}
res = requests.post(endpoint, json=payload, headers=headers)
print(json.dumps(res.json(), indent=2))

La risposta includerà qualsiasi formato richiesto (es. markdown_content).

Casi d’Uso

Di seguito sono riportate alcune applicazioni pratiche dei clienti che utilizzano l’endpoint /scrapes.

Analisi dei Contenuti & Ricerca

Analisi Competitiva: Estrai dettagli sui prodotti, prezzi e caratteristiche dai siti web dei concorrenti
Ricerca di Mercato: Analizza landing page, descrizioni dei prodotti e testimonianze dei clienti
Ricerca Accademica: Raccogli dati specifici da pubblicazioni scientifiche o portali di ricerca
Documentazione Legale: Estrai studi di casi, regolamenti o precedenti legali da siti ufficiali

E-commerce & Retail

Strategie di Prezzi Dinamici: Ottieni prezzi dei prodotti in tempo reale dai negozi concorrenti
Gestione delle Informazioni sui Prodotti: Estrai specifiche dettagliate e descrizioni
Monitoraggio Stock/Inventario: Controlla la disponibilità dei prodotti presso altri rivenditori
Analisi delle Recensioni: Raccogli feedback dei consumatori e sentiment per prodotti specifici

Marketing & Creazione di Contenuti

Curazione dei Contenuti: Estrai articoli e post di blog rilevanti per newsletter
Analisi SEO: Esamina l’uso delle parole chiave dei concorrenti, meta descrizioni e struttura delle pagine
Generazione di Lead: Estrai informazioni di contatto da directory aziendali o pagine aziendali
Ricerca di Influencer: Raccogli metriche di coinvolgimento e stili di contenuto dai profili degli influencer
Generazione Personalizzata di Social Media: Crea marketing sui social media alimentato da AI analizzando i siti web dei clienti

Applicazioni di Dati

Raccolta Dati per l’Addestramento AI: Raccogli esempi specifici per modelli di machine learning
Costruzione di Basi di Conoscenza Personalizzate: Estrai documentazione o istruzioni da siti software
Archivi di Dati Storici: Conserva il contenuto del sito web in momenti specifici nel tempo
Estrazione di Dati Strutturati: Trasforma il contenuto web in dataset formattati per l’analisi

Monitoraggio & Avvisi

Monitoraggio della Conformità Regolamentare: Traccia le modifiche ai siti web legali o regolatori
Gestione delle Crisi: Monitora i siti di notizie per menzioni di eventi o organizzazioni specifiche
Tracciamento degli Eventi: Estrai dettagli su eventi imminenti da siti di luoghi o organizzatori
Monitoraggio dello Stato del Servizio: Controlla le pagine di stato del servizio per piattaforme o strumenti specifici

Pubblicazione & Media

Aggregazione di Notizie: Estrai notizie dell’ultima ora da fonti ufficiali
Monitoraggio dei Media: Traccia argomenti specifici sui siti di notizie
Verifica dei Contenuti: Estrai informazioni per verificare affermazioni o dichiarazioni
Estrazione Multimediale: Raccogli video, immagini o audio incorporati per librerie multimediali

Applicazioni Finanziarie

Ricerca sugli Investimenti: Estrai bilanci o rapporti annuali dai siti web aziendali
Indicatori Economici: Raccogli dati economici da siti web governativi o di istituzioni finanziarie
Dati sulle Criptovalute: Estrai informazioni sui prezzi in tempo reale e sulla capitalizzazione di mercato
Analisi delle Notizie Finanziarie: Monitora i siti di notizie finanziarie per segnali di mercato specifici

Applicazioni Tecniche

Estrazione della Documentazione API: Raccogli documentazione tecnica per riferimento
Test di Integrazione: Estrai elementi del sito web per verificare integrazioni di terze parti
Test di Accessibilità: Analizza la struttura del sito web per la conformità agli standard di accessibilità
Creazione di Archivi Web: Cattura il contenuto completo del sito web per la conservazione storica

Scenari di Integrazione

Sistemi CRM: Migliora i profili dei clienti con dati dai siti web aziendali o Linkedin
Sistemi di Gestione dei Contenuti: Importa contenuti esterni rilevanti
Strumenti di Business Intelligence: Integra dati interni con informazioni di mercato esterne
Software di Gestione dei Progetti: Estrai specifiche o requisiti dai siti web dei clienti
Dashboard Personalizzati: Visualizza i dati estratti insieme a metriche interne

Gestione degli Errori

Tutti gli errori seguono una forma di busta condivisa. Controlla error.type e error.code per ramificare programmaticamente:

{
  "id": "error_abc123",
  "object": "error",
  "created": 1745673871,
  "url": "https://example.com",
  "metadata": {},
  "error": {
    "type": "...",
    "code": "...",
    "message": "..."
  }
}

HTTP	`error.type`	`error.code`	Significato
400	`invalid_request_error`	`dns_resolution_failed`	Il dominio non esiste o l’URL contiene un errore di battitura.
400	`invalid_request_error`	`invalid_url`	L’URL è malformato.
502	`invalid_request_error`	`tls_error`	Il sito web ha un certificato TLS/SSL non valido o incompatibile. `error.detail` contiene il codice SSL di basso livello.
504	`request_timeout`	`scrape_poll_timeout`	Lo scrape non è stato completato entro il budget di attesa di ~55 secondi.

Errore DNS (400)

Il dominio non risolve. Controlla l’URL per errori di battitura.

{
  "error": {
    "type": "invalid_request_error",
    "code": "dns_resolution_failed",
    "message": "L'URL contiene un errore di battitura, o il dominio non esiste."
  }
}

Errore TLS/SSL (502)

Il sito web di destinazione ha una configurazione HTTPS rotta o incompatibile. error.detail fornisce il codice di errore SSL specifico per la diagnostica; error.code è sempre tls_error.

{
  "error": {
    "type": "invalid_request_error",
    "code": "tls_error",
    "detail": "err_ssl_tlsv1_alert_internal_error",
    "message": "Il sito web ha chiuso o rifiutato la stretta di mano TLS. Il server potrebbe essere configurato male o utilizzare una versione SSL/TLS non supportata."
  }
}

Timeout della richiesta (504)

Lo scrape non è stato completato entro il budget di attesa. La pagina potrebbe essere lenta, protetta da bot, o temporaneamente non disponibile. Questa risposta è sicura da riprovare.

{
  "error": {
    "type": "request_timeout",
    "code": "scrape_poll_timeout",
    "message": "Richiesta scaduta mentre si attendeva il risultato dello scrape. La pagina potrebbe essere lenta, bloccata per i nostri fetcher, o temporaneamente non disponibile."
  }
}

Prezzi

Lo scrape costa 1 credito di default. Se passi anche parsers, i costi variano per parser (1-5 crediti). Se usi LLM extract, costa 10 crediti.

Inizia

Funzionalità

Saldo e Fatturazione

Scrape

Scraping di un URL

Installazione

Utilizzo

Risposta

Caching

Come funziona

Freschezza e `max_age`

Esempi di utilizzo

Quando viene saltata la cache?

Storage

Utilizzo

Estrazione dei link

Formati di Scrape

Estrazione di dati strutturati

Utilizzando un Parser (consigliato per la scalabilità)

Utilizzando l’estrazione LLM (schema e/o prompt)

Estrazione dei link sulla pagina

Interazione con la pagina tramite Azioni

Esempio

Casi d’Uso

Analisi dei Contenuti & Ricerca

E-commerce & Retail

Marketing & Creazione di Contenuti

Applicazioni di Dati

Monitoraggio & Avvisi

Pubblicazione & Media

Applicazioni Finanziarie

Applicazioni Tecniche

Scenari di Integrazione

Gestione degli Errori

Errore DNS (400)

Errore TLS/SSL (502)

Timeout della richiesta (504)

Prezzi

​Scraping di un URL

​Installazione

​Utilizzo

​Risposta

​Caching

​Come funziona

​Freschezza e max_age

​Esempi di utilizzo

​Quando viene saltata la cache?

​Storage

​Utilizzo

​Estrazione dei link

​Formati di Scrape

​Estrazione di dati strutturati

​Utilizzando un Parser (consigliato per la scalabilità)

​Utilizzando l’estrazione LLM (schema e/o prompt)

​Estrazione dei link sulla pagina

​Interazione con la pagina tramite Azioni

​Esempio

​Casi d’Uso

​Analisi dei Contenuti & Ricerca

​E-commerce & Retail

​Marketing & Creazione di Contenuti

​Applicazioni di Dati

​Monitoraggio & Avvisi

​Pubblicazione & Media

​Applicazioni Finanziarie

​Applicazioni Tecniche

​Scenari di Integrazione

​Gestione degli Errori

​Errore DNS (400)

​Errore TLS/SSL (502)

​Timeout della richiesta (504)

​Prezzi

Scraping di un URL

Installazione

Utilizzo

Risposta

Caching

Come funziona

Freschezza e `max_age`

Esempi di utilizzo

Quando viene saltata la cache?

Storage

Utilizzo

Estrazione dei link

Formati di Scrape

Estrazione di dati strutturati

Utilizzando un Parser (consigliato per la scalabilità)

Utilizzando l’estrazione LLM (schema e/o prompt)

Estrazione dei link sulla pagina

Interazione con la pagina tramite Azioni

Esempio

Casi d’Uso

Analisi dei Contenuti & Ricerca

E-commerce & Retail

Marketing & Creazione di Contenuti

Applicazioni di Dati

Monitoraggio & Avvisi

Pubblicazione & Media

Applicazioni Finanziarie

Applicazioni Tecniche

Scenari di Integrazione

Gestione degli Errori

Errore DNS (400)

Errore TLS/SSL (502)

Timeout della richiesta (504)

Prezzi