API di Ricerca - Olostep Docs

L’endpoint Olostep /v1/searches ti permette di cercare sul web con una query in linguaggio naturale e ottenere una lista deduplicata di link rilevanti con titoli e descrizioni.

Invia una query in inglese semplice
Ricevi link strutturati da tutto il web
Facoltativamente, esegui lo scraping di ogni URL restituito in un unico round-trip e incorpora markdown_content / html_content direttamente nella risposta
Filtra per dominio, controlla il numero di risultati e limita il tempo di scraping

Cercando la query semanticamente sul web, restituirà i risultati. Per i dettagli sull’API, consulta la Riferimento API dell’Endpoint di Ricerca.

Installazione

pip install olostep

Uso di base

Invia una query in linguaggio naturale e ricevi una lista di link rilevanti.

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

search = client.searches.create("Best Answer Engine Optimization startups")

print(search.id, len(search.links))

Parametri della richiesta

Campo	Tipo	Richiesto	Default	Descrizione
`query`	string	sì	—	La query di ricerca in linguaggio naturale.
`limit`	integer	no	`12`	Numero massimo di link da restituire dopo la deduplicazione. Deve essere tra `1` e `25`.
`include_domains`	string[]	no	`[]`	Restringi i risultati a questi domini. Solo host nudi — `http(s)://` iniziale e slash finali vengono rimossi automaticamente.
`exclude_domains`	string[]	no	`[]`	Escludi i risultati da questi domini. Solo host nudi — `http(s)://` iniziale e slash finali vengono rimossi automaticamente.
`scrape_options`	object	no	—	Quando fornito, ogni link restituito viene anche sottoposto a scraping e il suo contenuto incorporato nella risposta. Vedi scrape_options sotto.

Limitare il numero di risultati

{
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 5
}

Filtrare per dominio

include_domains restringe i risultati a una whitelist; exclude_domains filtra le fonti indesiderate. Possono essere combinati.

{
  "query": "OpenAI Sora shutdown analysis",
  "include_domains": ["nytimes.com", "wsj.com", "bbc.com"],
  "exclude_domains": ["pinterest.com"]
}

scrape_options

Passa scrape_options per eseguire lo scraping di ogni URL restituito in parallelo e incorpora il contenuto reso direttamente su ciascun link. Questo salva un round-trip per risultato rispetto a chiamare /v1/searches e /v1/scrapes separatamente.

{
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 10,
  "scrape_options": {
    "formats": ["markdown"],
    "remove_css_selectors": "default",
    "timeout": 25
  }
}

Campo	Tipo	Default	Descrizione
`formats`	string[]	`["markdown"]`	Formati di output da allegare a ciascun link. Per `/v1/searches`, sono supportati solo `"html"` e `"markdown"`. Passa `["html", "markdown"]` per ricevere entrambi.
`remove_css_selectors`	string	`"default"`	Inoltrato a `/v1/scrapes`. `"default"` rimuove rumore di nav/footer/script/style/svg/dialog. Usa `"none"` per disabilitare, o passa un array di selettori JSON-stringificato da rimuovere.
`timeout`	integer	`25`	Budget di wallclock in secondi per l’intera fase di scraping. Deve essere tra `1` e `60`. Dopo questo tempo, la ricerca restituisce immediatamente — i campi di contenuto saranno `null` per i link che non sono stati completati.

Comportamento

Tutti i link vengono sottoposti a scraping in parallelo. Il timeout limita l’intero batch, non ogni singolo link.
I fallimenti di scraping per link (errori di rete, timeout della pagina individuale) lasciano il markdown_content / html_content di quel link come null mentre gli altri link vengono restituiti normalmente.
Se il timeout globale scade prima che tutti gli scraping siano completati, la ricerca risponde immediatamente con i link che ha — gli scraping già completati mantengono il loro contenuto; quelli in corso tornano con contenuto null.
Per gli URL reddit.com/.../comments/..., la richiesta viene automaticamente instradata attraverso il parser @olostep/reddit-post e il JSON strutturato viene reso in markdown pulito + HTML di base
Se il contenuto combinato in linea supera i 9MB, i campi di contenuto vengono annullati, result.size_exceeded è impostato su true, e puoi recuperare il payload completo da result.json_hosted_url.

Esempio con scraping

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

search = client.searches.create(
    query="What's going on with OpenAI's Sora shutting down?",
    limit=5,
    scrape_options={"formats": ["markdown"], "timeout": 25},
)

for link in search.links:
    print(link["url"], "—", len(link.get("markdown_content") or ""), "chars")

Risposta

Riceverai un oggetto search in risposta. L’oggetto search contiene un id, la tua query originale, credits_consumed, e un result con una lista di links.

{
  "id": "search_9bi0sbj9xa",
  "object": "search",
  "created": 1760327323,
  "metadata": {},
  "query": "What's going on with OpenAI's Sora shutting down?",
  "credits_consumed": 10,
  "result": {
    "json_content": "...",
    "json_hosted_url": "https://olostep-storage.s3.us-east-1.amazonaws.com/search_9bi0sbj9xa.json",
    "size_exceeded": false,
    "credits_consumed": 10,
    "links": [
      {
        "url": "https://www.bbc.com/news/articles/c3w3e467ewqo",
        "title": "OpenAI to shut down Sora video platform",
        "description": "OpenAI says it will discontinue its Sora app...",
        "markdown_content": "# OpenAI to shut down Sora video platform\n\nOpenAI says it will discontinue..."
      },
      {
        "url": "https://www.reddit.com/r/OutOfTheLoop/comments/1s2u847/whats_going_on_with_openais_sora_shutting_down/",
        "title": "What's going on with OpenAI's Sora shutting down?",
        "description": "Reddit thread discussing the shutdown.",
        "markdown_content": "# What's going on with OpenAI's Sora shutting down?\n\n*r/OutOfTheLoop · u/rm-minus-r · 1mo ago*\n\n..."
      }
    ]
  }
}

Ogni link in result.links contiene:

Campo	Tipo	Descrizione
`url`	string	L’URL del risultato di ricerca.
`title`	string	Il titolo della pagina del risultato.
`description`	string	Un breve snippet che descrive il risultato.
`markdown_content`	string	Contenuto markdown della pagina. Presente solo quando `scrape_options.formats` include `"markdown"`. `null` se lo scraping è fallito, era vuoto, o ha raggiunto il timeout globale.
`html_content`	string	Contenuto HTML della pagina. Presente solo quando `scrape_options.formats` include `"html"`. `null` in caso di fallimento/timeout.

Il risultato completo è anche disponibile come file JSON ospitato su result.json_hosted_url — utile quando result.size_exceeded è true.

Recuperare una ricerca passata

GET /v1/searches/{search_id} restituisce ciò che è stato memorizzato al momento della ricerca, incluso qualsiasi contenuto sottoposto a scraping. È una lettura idempotente pura — nessun nuovo scraping, nessuna nuova fatturazione. Le ricerche più vecchie senza scrape_options semplicemente non hanno campi di contenuto per link.

from olostep import Olostep

client = Olostep(api_key="YOUR_REAL_KEY")

search = client.searches.get(search_id="search_9bi0sbj9xa")
print(search.id, len(search.links))

Consulta Get Search per i dettagli completi.

Prezzi

Ogni ricerca costa 5 crediti per la ricerca stessa. Quando scrape_options è fornito, ogni pagina sottoposta a scraping viene addebitata al tasso standard /v1/scrapes (tipicamente 1 credito per pagina; alcuni parser costano di più). Il totale viene restituito in credits_consumed. Esempi:

Richiesta	`credits_consumed`
Solo ricerca	`5`
Ricerca + 5 pagine sottoposte a scraping (1 credito ciascuna)	`10`

​Installazione

​Uso di base

​Parametri della richiesta

​Limitare il numero di risultati

​Filtrare per dominio

​scrape_options

​Comportamento

​Esempio con scraping

​Risposta

​Recuperare una ricerca passata

​Prezzi