Such-API

Der Olostep-Endpunkt /v1/searches ermöglicht es dir, das Web mit einer natürlichen Sprachabfrage zu durchsuchen und eine deduplizierte Liste relevanter Links mit Titeln und Beschreibungen zurückzubekommen.

Sende eine Abfrage in einfachem Englisch
Erhalte strukturierte Links aus dem gesamten Web
Optional kannst du jede zurückgegebene URL in einem Durchgang scrapen und markdown_content / html_content direkt in die Antwort einbetten
Filtere nach Domain, steuere die Ergebnisanzahl und begrenze die Scraping-Zeit

Die Abfrage wird semantisch im gesamten Web gesucht und Ergebnisse werden zurückgegeben. Für API-Details siehe die Such-Endpunkt-API-Referenz.

Installation

pip install olostep

npm install olostep

# curl ist standardmäßig auf macOS, Linux und Windows verfügbar

npm install node-fetch

pip install requests

Grundlegende Nutzung

Sende eine Abfrage in natürlicher Sprache und erhalte eine Liste relevanter 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))

Anfrageparameter

Feld	Typ	Erforderlich	Standard	Beschreibung
`query`	string	ja	—	Die Suchabfrage in natürlicher Sprache.
`limit`	integer	nein	`12`	Maximale Anzahl von Links, die nach der Deduplizierung zurückgegeben werden. Muss zwischen `1` und `25` liegen.
`include_domains`	string[]	nein	`[]`	Beschränke Ergebnisse auf diese Domains. Nur Basis-Hosts — führende `http(s)://` und nachfolgende Schrägstriche werden automatisch entfernt.
`exclude_domains`	string[]	nein	`[]`	Schließe Ergebnisse von diesen Domains aus. Nur Basis-Hosts — führende `http(s)://` und nachfolgende Schrägstriche werden automatisch entfernt.
`scrape_options`	object	nein	—	Wenn angegeben, wird jeder zurückgegebene Link auch gescraped und sein Inhalt in die Antwort eingebettet. Siehe scrape_options unten.
`fast_mode`	boolean	nein	`false`	Fordere eine direkte, latenzarme Suche mit deiner Abfrage im Wortlaut an. Der Standardmodus führt eine breitere Suchpassage für eine größere Ergebnisabdeckung durch.

Begrenzung der Anzahl der Ergebnisse

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

Filtern nach Domain

include_domains beschränkt Ergebnisse auf eine Whitelist; exclude_domains filtert unerwünschte Quellen aus. Sie können kombiniert werden.

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

scrape_options

Übergebe scrape_options, um jede zurückgegebene URL parallel zu scrapen und den gerenderten Inhalt direkt auf jedem Link einzubetten. Dies spart eine Runde pro Ergebnis im Vergleich zum separaten Aufruf von /v1/searches und /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
  }
}

Feld	Typ	Standard	Beschreibung
`formats`	string[]	`["markdown"]`	Ausgabeformate, die jedem Link angehängt werden. Für `/v1/searches` werden nur `"html"` und `"markdown"` unterstützt. Übergebe `["html", "markdown"]`, um beide zu erhalten.
`remove_css_selectors`	string	`"default"`	Weitergeleitet an `/v1/scrapes`. `"default"` entfernt Navigations-/Fußzeilen-/Skript-/Stil-/SVG-/Dialoggeräusche. Verwende `"none"`, um es zu deaktivieren, oder übergebe ein JSON-stringifiziertes Array von Selektoren, die entfernt werden sollen.
`timeout`	integer	`25`	Zeitbudget in Sekunden für die gesamte Scraping-Phase. Muss zwischen `1` und `60` liegen. Nach Ablauf dieser Zeit wird die Suche sofort zurückgegeben — Inhaltsfelder sind `null` für alle Links, die nicht fertiggestellt wurden.

Verhalten

Alle Links werden parallel gescraped. Der timeout begrenzt das gesamte Batch, nicht jeden einzelnen Link.
Bei Scraping-Fehlern pro Link (Netzwerkfehler, individuelle Seitenauszeiten) bleibt der markdown_content / html_content dieses Links null, während andere Links normal zurückgegeben werden.
Wenn der globale timeout abläuft, bevor alle Scrapes abgeschlossen sind, antwortet die Suche sofort mit den Links, die sie hat — bereits abgeschlossene Scrapes behalten ihren Inhalt; in Bearbeitung befindliche kommen mit null-Inhalt zurück.
Für reddit.com/.../comments/... URLs wird die Anfrage automatisch über den @olostep/reddit-post Parser geleitet und das strukturierte JSON wird in sauberes Markdown + einfaches HTML gerendert.
Wenn der kombinierte Inline-Inhalt 9MB überschreitet, werden Inhaltsfelder genullt, result.size_exceeded wird auf true gesetzt, und du kannst die vollständige Nutzlast von result.json_hosted_url abrufen.

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

Antwort

Du erhältst ein search-Objekt als Antwort. Das search-Objekt enthält eine id, deine ursprüngliche query, credits_consumed und ein result mit einer Liste von 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 sagt, dass es seine Sora-App einstellen wird...",
        "markdown_content": "# OpenAI stellt die Sora-Videoplattform ein\n\nOpenAI sagt, dass es seine Sora-App einstellen wird..."
      },
      {
        "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 über die Schließung.",
        "markdown_content": "# What's going on with OpenAI's Sora shutting down?\n\n*r/OutOfTheLoop · u/rm-minus-r · vor 1 Monat*\n\n..."
      }
    ]
  }
}

Jeder Link in result.links enthält:

Feld	Typ	Beschreibung
`url`	string	Die URL des Suchergebnisses.
`title`	string	Der Titel der Ergebnisseite.
`description`	string	Ein kurzer Ausschnitt, der das Ergebnis beschreibt.
`markdown_content`	string	Markdown-Inhalt der Seite. Nur vorhanden, wenn `scrape_options.formats` `"markdown"` enthält. `null`, wenn das Scraping fehlschlug, leer war oder das globale Timeout erreicht wurde.
`html_content`	string	HTML-Inhalt der Seite. Nur vorhanden, wenn `scrape_options.formats` `"html"` enthält. `null` bei Fehler/Timeout.

Das vollständige Ergebnis ist auch als gehostete JSON-Datei unter result.json_hosted_url verfügbar — nützlich, wenn result.size_exceeded true ist.

Abrufen einer vergangenen Suche

GET /v1/searches/{search_id} gibt alles zurück, was zum Zeitpunkt der Suche gespeichert wurde, einschließlich aller gescrapten Inhalte. Es ist ein reines idempotentes Lesen — kein erneutes Scraping, keine erneute Abrechnung. Ältere Suchen ohne scrape_options haben einfach keine Inhaltsfelder pro 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"

Siehe Suche abrufen für vollständige Details.

Speicherung

Gespeicherte Dateien für eine Suche werden standardmäßig 7 Tage lang aufbewahrt. Übergebe ein storage-Objekt bei POST /v1/searches, um sie länger oder unbegrenzt zu behalten. Die Einstellung umfasst die gehostete JSON-Datei unter result.json_hosted_url und, wenn scrape_options gesetzt ist, den für jeden Link gescrapten Inhalt.

Parameter	Typ	Standard	Beschreibung
`storage.expires_in`	`string`	`7d`	Wie lange die gespeicherten Dateien aufbewahrt werden sollen. Eine der Optionen `7d`, `10d`, `30d`, `60d`, `90d`, `180d`, `365d` oder `never` (unbegrenzt).

Das Weglassen von storage oder das Senden von storage ohne expires_in verwendet 7d. Sowohl die Erstellungsantwort als auch GET /v1/searches/{search_id} enthalten den wirksamen Wert:

"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" }
  }'

Ein ungültiger Wert gibt 400 zurück:

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

Preisgestaltung

Jede Suche kostet 5 Credits für die Suche selbst. Wenn scrape_options angegeben ist, wird jede gescrapte Seite zum Standardtarif von /v1/scrapes berechnet (typischerweise 1 Credit pro Seite; einige Parser kosten mehr). Die Gesamtsumme wird in credits_consumed zurückgegeben. Beispiele:

Anfrage	`credits_consumed`
Nur Suche	`5`
Suche + 5 gescrapte Seiten (je 1 Credit)	`10`

Loslegen

Funktionen

Kontostand & Abrechnung

Installation

Grundlegende Nutzung

Anfrageparameter

Begrenzung der Anzahl der Ergebnisse

Filtern nach Domain

scrape_options

Verhalten

Beispiel mit Scraping

Antwort

Abrufen einer vergangenen Suche

Speicherung

Preisgestaltung

​Installation

​Grundlegende Nutzung

​Anfrageparameter

​Begrenzung der Anzahl der Ergebnisse

​Filtern nach Domain

​scrape_options

​Verhalten

​Beispiel mit Scraping

​Antwort

​Abrufen einer vergangenen Suche

​Speicherung

​Preisgestaltung

Installation

Grundlegende Nutzung

Anfrageparameter

Begrenzung der Anzahl der Ergebnisse

Filtern nach Domain

scrape_options

Verhalten

Beispiel mit Scraping

Antwort

Abrufen einer vergangenen Suche

Speicherung

Preisgestaltung