Naar hoofdinhoud gaan

Documentation Index

Fetch the complete documentation index at: https://docs.olostep.com/llms.txt

Use this file to discover all available pages before exploring further.

De Olostep /v1/searches endpoint stelt je in staat om het web te doorzoeken met een natuurlijke taalquery en een gededupliceerde lijst van relevante links met titels en beschrijvingen terug te krijgen.
  • Stuur een query in gewoon Engels
  • Krijg gestructureerde links van over het hele web terug
  • Optioneel: schraap elke geretourneerde URL in één keer en embed markdown_content / html_content direct in de respons
  • Filter op domein, beheer het aantal resultaten en beperk de scraping wallclock
Het zal semantisch naar de query zoeken op het web en resultaten teruggeven. Voor API-details, zie de Zoek Endpoint API Referentie.

​
Installatie

pip install olostep

​
Basisgebruik

Stuur een natuurlijke taalquery en ontvang een lijst met relevante links. 
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))

​
Verzoekparameters

VeldTypeVereistStandaardBeschrijving
querystringja—De zoekquery in natuurlijke taal.
limitintegernee12Maximum aantal links om te retourneren na deduplicatie. Moet tussen 1 en 25 zijn.
include_domainsstring[]nee[]Beperk resultaten tot deze domeinen. Alleen kale hosts — voorloop http(s):// en achtervoegende slashes worden automatisch verwijderd.
exclude_domainsstring[]nee[]Sluit resultaten van deze domeinen uit. Alleen kale hosts — voorloop http(s):// en achtervoegende slashes worden automatisch verwijderd.
scrape_optionsobjectnee—Wanneer verstrekt, wordt elke geretourneerde link ook geschraapt en wordt de inhoud ingebed in de respons. Zie scrape_options hieronder.

​
Het aantal resultaten beperken

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

​
Filteren op domein

include_domains beperkt resultaten tot een whitelist; exclude_domains filtert ongewenste bronnen uit. Ze kunnen gecombineerd worden. 
{
  "query": "OpenAI Sora shutdown analysis",
  "include_domains": ["nytimes.com", "wsj.com", "bbc.com"],
  "exclude_domains": ["pinterest.com"]
}

​
scrape_options

Geef scrape_options door om elke geretourneerde URL parallel te schrapen en de gerenderde inhoud direct op elke link te embedden. Dit bespaart een round-trip per resultaat in vergelijking met het afzonderlijk aanroepen van /v1/searches en /v1/scrapes. 
{
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 10,
  "scrape_options": {
    "formats": ["markdown"],
    "remove_css_selectors": "default",
    "timeout": 25
  }
}
VeldTypeStandaardBeschrijving
formatsstring[]["markdown"]Uitvoerformaten om aan elke link toe te voegen. Voor /v1/searches worden alleen "html" en "markdown" ondersteund. Geef ["html", "markdown"] door om beide te ontvangen.
remove_css_selectorsstring"default"Doorgestuurd naar /v1/scrapes. "default" verwijdert navigatie/footer/script/style/svg/dialog ruis. Gebruik "none" om uit te schakelen, of geef een JSON-geformatteerde array van selectors om te verwijderen.
timeoutinteger25Wallclock budget in seconden voor de gehele scrape-fase. Moet tussen 1 en 60 zijn. Nadat dit is verstreken, retourneert de zoekopdracht onmiddellijk — inhoudsvelden zullen null zijn voor alle links die niet voltooid waren.

​
Gedrag

  • Alle links worden parallel geschraapt. De timeout beperkt de hele batch, niet elke individuele link.
  • Per-link scrape-fouten (netwerkfouten, individuele paginatime-outs) laten de markdown_content / html_content van die link als null terwijl andere links normaal terugkeren.
  • Als de globale timeout verstrijkt voordat alle scrapes zijn voltooid, reageert de zoekopdracht onmiddellijk met de links die het heeft — al voltooide scrapes behouden hun inhoud; in-flight komen terug met null inhoud.
  • Voor reddit.com/.../comments/... URLs wordt het verzoek automatisch doorgestuurd via de @olostep/reddit-post parser en de gestructureerde JSON wordt gerenderd in schone markdown + basis HTML
  • Als de gecombineerde inline inhoud meer dan 9MB overschrijdt, worden inhoudsvelden genuld, result.size_exceeded wordt ingesteld op true, en je kunt de volledige payload ophalen van result.json_hosted_url.

​
Voorbeeld met schrapen

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")

​
Respons

Je ontvangt een search object als respons. Het search object bevat een id, je oorspronkelijke query, credits_consumed, en een result met een lijst van 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..."
      }
    ]
  }
}
Elke link in result.links bevat:
VeldTypeBeschrijving
urlstringDe URL van het zoekresultaat.
titlestringDe titel van de resultaatpagina.
descriptionstringEen korte snippet die het resultaat beschrijft.
markdown_contentstringMarkdown-inhoud van de pagina. Alleen aanwezig wanneer scrape_options.formats "markdown" bevat. null als de scrape is mislukt, leeg was, of de globale timeout heeft bereikt.
html_contentstringHTML-inhoud van de pagina. Alleen aanwezig wanneer scrape_options.formats "html" bevat. null bij mislukking/timeout.
Het volledige resultaat is ook beschikbaar als een gehost JSON-bestand op result.json_hosted_url — handig wanneer result.size_exceeded true is.

​
Een eerdere zoekopdracht ophalen

GET /v1/searches/{search_id} retourneert wat er op het moment van zoeken is opgeslagen, inclusief eventuele geschraapte inhoud. Het is een pure idempotente read — geen her-scraping, geen her-facturering. Oudere zoekopdrachten zonder scrape_options hebben simpelweg geen per-link inhoudsvelden. 
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))
Zie Get Search voor volledige details.

​
Prijsstelling

Elke zoekopdracht kost 5 credits voor de zoekopdracht zelf. Wanneer scrape_options wordt verstrekt, wordt elke geschraapte pagina gefactureerd tegen het standaard /v1/scrapes tarief (meestal 1 credit per pagina; sommige parsers kosten meer). Het totaal wordt geretourneerd in credits_consumed. Voorbeelden:
Verzoekcredits_consumed
Alleen zoeken5
Zoeken + 5 geschraapte pagina’s (1 credit elk)10