Zoek-API

Het Olostep /v1/searches eindpunt stelt je in staat om het web te doorzoeken met een natuurlijke taalvraag en een gededupliceerde lijst van relevante links met titels en beschrijvingen terug te krijgen.

Stuur een vraag in gewoon Engels
Krijg gestructureerde links van over het hele web terug
Optioneel kun je elke geretourneerde URL in één keer scrapen en markdown_content / html_content direct in de respons opnemen
Filter op domein, bepaal het aantal resultaten en stel de scraping tijdslimiet in

Het zal semantisch naar de query zoeken over het web en resultaten retourneren. Voor API-details, zie de Zoek Eindpunt API Referentie.

Installatie

pip install olostep

npm install olostep

# curl is standaard beschikbaar op macOS, Linux en Windows

npm install node-fetch

pip install requests

Basisgebruik

Stuur een natuurlijke taalvraag 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))

import Olostep from 'olostep'

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

const search = await client.searches.create('Best Answer Engine Optimization startups')

console.log(search.id, search.links.length)

curl -s -X POST "https://api.olostep.com/v1/searches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Best Answer Engine Optimization startups"
  }'

const res = await fetch('https://api.olostep.com/v1/searches', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'Best Answer Engine Optimization startups'
  })
})
console.log(await res.json())

import requests, json

endpoint = "https://api.olostep.com/v1/searches"
payload = {
  "query": "Best Answer Engine Optimization startups"
}
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))

Verzoekparameters

Veld	Type	Vereist	Standaard	Beschrijving
`query`	string	ja	—	De zoekvraag in natuurlijke taal.
`limit`	integer	nee	`12`	Maximum aantal links om te retourneren na deduplicatie. Moet tussen `1` en `25` zijn.
`include_domains`	string[]	nee	`[]`	Beperk resultaten tot deze domeinen. Alleen hoofddomeinen — leidende `http(s)://` en afsluitende slashes worden automatisch verwijderd.
`exclude_domains`	string[]	nee	`[]`	Sluit resultaten van deze domeinen uit. Alleen hoofddomeinen — leidende `http(s)://` en afsluitende slashes worden automatisch verwijderd.
`scrape_options`	object	nee	—	Wanneer verstrekt, wordt elke geretourneerde link ook gescraped en de inhoud in de respons opgenomen. Zie scrape_options hieronder.
`fast_mode`	boolean	nee	`false`	Vraag een directe, lage-latentie zoekopdracht aan met je query letterlijk. De standaardmodus voert een bredere zoekpass uit voor bredere dekking van resultaten.

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 eruit. 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 scrapen en de gerenderde inhoud direct op elke link in te bedden. 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
  }
}

Veld	Type	Standaard	Beschrijving
`formats`	string[]	`["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_selectors`	string	`"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.
`timeout`	integer	`25`	Tijdslimiet in seconden voor de hele scrape-fase. Moet tussen `1` en `60` zijn. Nadat deze verstreken is, retourneert de zoekopdracht onmiddellijk — inhoudsvelden zullen `null` zijn voor links die nog niet voltooid waren.

Gedrag

Alle links worden parallel gescraped. De timeout begrenst de hele batch, niet elke individuele link.
Per-link scrape-fouten (netwerkfouten, individuele pagina time-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 voltooid zijn, reageert de zoekopdracht onmiddellijk met de links die het heeft — reeds voltooide scrapes behouden hun inhoud; in-flight komen terug met null inhoud.
Voor reddit.com/.../comments/... URL’s wordt het verzoek automatisch gerouteerd 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 genulled, result.size_exceeded wordt ingesteld op true, en je kunt de volledige payload ophalen van result.json_hosted_url.

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

import Olostep, { Format } from 'olostep'

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

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

for (const link of search.links) {
  console.log(link.url, '—', (link.markdown_content || '').length, 'chars')
}

curl -s -X POST "https://api.olostep.com/v1/searches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What'"'"'s going on with OpenAI'"'"'s Sora shutting down?",
    "limit": 5,
    "scrape_options": {
      "formats": ["markdown"],
      "timeout": 25
    }
  }'

const res = await fetch('https://api.olostep.com/v1/searches', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer <YOUR_API_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: "What's going on with OpenAI's Sora shutting down?",
    limit: 5,
    scrape_options: {
      formats: ['markdown'],
      timeout: 25
    }
  })
})
const data = await res.json()
for (const link of data.result.links) {
  console.log(link.url, '—', (link.markdown_content || '').length, 'chars')
}

import requests, json

endpoint = "https://api.olostep.com/v1/searches"
payload = {
  "query": "What's going on with OpenAI's Sora shutting down?",
  "limit": 5,
  "scrape_options": {
    "formats": ["markdown"],
    "timeout": 25
  }
}
headers = {"Authorization": "Bearer <YOUR_API_KEY>", "Content-Type": "application/json"}

response = requests.post(endpoint, json=payload, headers=headers)
data = response.json()
for link in data["result"]["links"]:
  print(link["url"], "—", len(link.get("markdown_content") or ""), "chars")

Respons

Je ontvangt een search object als antwoord. Het search object bevat een id, je originele 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 zegt dat het zijn Sora-app zal stopzetten...",
        "markdown_content": "# OpenAI to shut down Sora video platform\n\nOpenAI zegt dat het zal stoppen..."
      },
      {
        "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 die de sluiting bespreekt.",
        "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:

Veld	Type	Beschrijving
`url`	string	De URL van het zoekresultaat.
`title`	string	De titel van de resultaatpagina.
`description`	string	Een korte samenvatting van het resultaat.
`markdown_content`	string	Markdown-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_content`	string	HTML-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 gescrapete inhoud. Het is een puur idempotente leesactie — geen opnieuw scrapen, geen opnieuw factureren. Oudere zoekopdrachten zonder scrape_options hebben simpelweg geen inhoudsvelden 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))

import Olostep from 'olostep'

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

const search = await client.searches.get('search_9bi0sbj9xa')
console.log(search.id, search.links.length)

curl -s "https://api.olostep.com/v1/searches/search_9bi0sbj9xa" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY"

Zie Get Search voor volledige details.

Opslag

Opgeslagen bestanden voor een zoekopdracht worden standaard 7 dagen bewaard. Geef een storage object door bij POST /v1/searches om ze langer of voor onbepaalde tijd te bewaren. De instelling dekt het gehoste JSON-bestand op result.json_hosted_url en, wanneer scrape_options is ingesteld, de inhoud die voor elke link is gescrapet.

Parameter	Type	Standaard	Beschrijving
`storage.expires_in`	`string`	`7d`	Hoe lang de opgeslagen bestanden bewaard moeten blijven. Een van `7d`, `10d`, `30d`, `60d`, `90d`, `180d`, `365d`, of `never` (onbepaald).

Het weglaten van storage, of het verzenden van storage zonder expires_in, gebruikt 7d. Zowel de creatierespons als GET /v1/searches/{search_id} bevatten de waarde die van kracht is:

"storage": { "expires_in": "30d" }

cURL

curl -s -X POST "https://api.olostep.com/v1/searches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best open source vector databases",
    "storage": { "expires_in": "30d" }
  }'

Een ongeldige waarde retourneert 400:

{
  "type": "invalid_request_error",
  "message": "Invalid storage.expires_in. Allowed values: \"7d\", \"10d\", \"30d\", \"60d\", \"90d\", \"180d\", \"365d\", \"never\".",
  "code": "invalid_storage_expires_in"
}

Prijzen

Elke zoekopdracht kost 5 credits voor de zoekopdracht zelf. Wanneer scrape_options wordt verstrekt, wordt elke gescrapete pagina gefactureerd tegen het standaardtarief van /v1/scrapes (meestal 1 credit per pagina; sommige parsers kosten meer). Het totaal wordt geretourneerd in credits_consumed. Voorbeelden:

Verzoek	`credits_consumed`
Alleen zoeken	`5`
Zoeken + 5 gescrapete pagina’s (1 credit elk)	`10`

Aan de slag

Functies

Saldo & Facturering

Installatie

Basisgebruik

Verzoekparameters

Het aantal resultaten beperken

Filteren op domein

scrape_options

Gedrag

Voorbeeld met scraping

Respons

Een eerdere zoekopdracht ophalen

Opslag

Prijzen

​Installatie

​Basisgebruik

​Verzoekparameters

​Het aantal resultaten beperken

​Filteren op domein

​scrape_options

​Gedrag

​Voorbeeld met scraping

​Respons

​Een eerdere zoekopdracht ophalen

​Opslag

​Prijzen

Installatie

Basisgebruik

Verzoekparameters

Het aantal resultaten beperken

Filteren op domein

scrape_options

Gedrag

Voorbeeld met scraping

Respons

Een eerdere zoekopdracht ophalen

Opslag

Prijzen