API de Búsqueda

El endpoint de Olostep /v1/searches te permite buscar en la web con una consulta en lenguaje natural y obtener una lista deduplicada de enlaces relevantes con títulos y descripciones.

Envía una consulta en inglés sencillo
Recibe enlaces estructurados de toda la web
Opcionalmente, raspa cada URL devuelta en un solo viaje de ida y vuelta e incrusta markdown_content / html_content directamente en la respuesta
Filtra por dominio, controla el número de resultados y limita el tiempo de raspado

Buscará la consulta semánticamente en toda la web y devolverá resultados. Para detalles de la API, consulta la Referencia de la API del Endpoint de Búsqueda.

Instalación

pip install olostep

npm install olostep

# curl está disponible por defecto en macOS, Linux y Windows

npm install node-fetch

pip install requests

Uso básico

Envía una consulta en lenguaje natural y recibe una lista de enlaces relevantes.

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

Parámetros de la solicitud

Campo	Tipo	Requerido	Predeterminado	Descripción
`query`	string	sí	—	La consulta de búsqueda en lenguaje natural.
`limit`	integer	no	`12`	Número máximo de enlaces a devolver después de la deduplicación. Debe estar entre `1` y `25`.
`include_domains`	string[]	no	`[]`	Restringe los resultados a estos dominios. Solo hosts básicos — los prefijos `http(s)://` y las barras finales se eliminan automáticamente.
`exclude_domains`	string[]	no	`[]`	Excluye resultados de estos dominios. Solo hosts básicos — los prefijos `http(s)://` y las barras finales se eliminan automáticamente.
`scrape_options`	object	no	—	Cuando se proporciona, cada enlace devuelto también se raspa y su contenido se incrusta en la respuesta. Ver scrape_options abajo.
`fast_mode`	boolean	no	`false`	Solicita una búsqueda directa y de baja latencia usando tu consulta literalmente. El modo predeterminado realiza una búsqueda más amplia para una mayor cobertura de resultados.

Limitando el número de resultados

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

Filtrando por dominio

include_domains limita los resultados a una lista blanca; exclude_domains filtra las fuentes no deseadas. Se pueden combinar.

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

scrape_options

Pasa scrape_options para raspar cada URL devuelta en paralelo e incrustar el contenido renderizado directamente en cada enlace. Esto ahorra un viaje de ida y vuelta por resultado en comparación con llamar a /v1/searches y /v1/scrapes por separado.

{
  "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	Predeterminado	Descripción
`formats`	string[]	`["markdown"]`	Formatos de salida para adjuntar a cada enlace. Para `/v1/searches`, solo se admiten `"html"` y `"markdown"`. Pasa `["html", "markdown"]` para recibir ambos.
`remove_css_selectors`	string	`"default"`	Reenviado a `/v1/scrapes`. `"default"` elimina ruido de navegación/pie de página/script/estilo/svg/dialog. Usa `"none"` para desactivar, o pasa un array de selectores en formato JSON para eliminar.
`timeout`	integer	`25`	Presupuesto de tiempo en segundos para toda la fase de raspado. Debe estar entre `1` y `60`. Después de que esto expire, la búsqueda se devuelve inmediatamente — los campos de contenido serán `null` para cualquier enlace que no haya terminado.

Comportamiento

Todos los enlaces se raspan en paralelo. El timeout limita todo el lote, no cada enlace individual.
Los fallos de raspado por enlace (errores de red, tiempos de espera individuales de página) dejan el markdown_content / html_content de ese enlace como null mientras que otros enlaces se devuelven normalmente.
Si el timeout global expira antes de que todos los raspados terminen, la búsqueda responde inmediatamente con los enlaces que tiene — los raspados ya completados mantienen su contenido; los que están en proceso regresan con contenido null.
Para URLs de reddit.com/.../comments/..., la solicitud se enruta automáticamente a través del analizador @olostep/reddit-post y el JSON estructurado se renderiza en markdown limpio + HTML básico.
Si el contenido combinado en línea excede los 9MB, los campos de contenido se anulan, result.size_exceeded se establece en true, y puedes obtener la carga completa desde result.json_hosted_url.

Ejemplo con raspado

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

Respuesta

Recibirás un objeto search en respuesta. El objeto search contiene un id, tu query original, credits_consumed, y un result con una lista de 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 dice que descontinuará su aplicación Sora...",
        "markdown_content": "# OpenAI to shut down Sora video platform\n\nOpenAI dice que descontinuará..."
      },
      {
        "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": "Hilo de Reddit discutiendo el cierre.",
        "markdown_content": "# What's going on with OpenAI's Sora shutting down?\n\n*r/OutOfTheLoop · u/rm-minus-r · 1mo ago*\n\n..."
      }
    ]
  }
}

Cada enlace en result.links contiene:

Campo	Tipo	Descripción
`url`	string	La URL del resultado de búsqueda.
`title`	string	El título de la página de resultados.
`description`	string	Un breve fragmento que describe el resultado.
`markdown_content`	string	Contenido en markdown de la página. Solo presente cuando `scrape_options.formats` incluye `"markdown"`. `null` si el raspado falló, estaba vacío o alcanzó el timeout global.
`html_content`	string	Contenido en HTML de la página. Solo presente cuando `scrape_options.formats` incluye `"html"`. `null` en caso de fallo/timeout.

El resultado completo también está disponible como un archivo JSON alojado en result.json_hosted_url — útil cuando result.size_exceeded es true.

Recuperando una búsqueda pasada

GET /v1/searches/{search_id} devuelve lo que se guardó en el momento de la búsqueda, incluyendo cualquier contenido raspado. Es una lectura idempotente pura — sin nuevo raspado, sin nueva facturación. Las búsquedas antiguas sin scrape_options simplemente no tienen campos de contenido por enlace.

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"

Consulta Obtener Búsqueda para más detalles.

Precios

Cada búsqueda cuesta 5 créditos por la búsqueda en sí. Cuando se proporciona scrape_options, cada página raspada se factura a la tarifa estándar de /v1/scrapes (típicamente 1 crédito por página; algunos analizadores cuestan más). El total se devuelve en credits_consumed. Ejemplos:

Solicitud	`credits_consumed`
Solo búsqueda	`5`
Búsqueda + 5 páginas raspadas (1 crédito cada una)	`10`

Comenzar

Características

Saldo y Facturación

Instalación

Uso básico

Parámetros de la solicitud

Limitando el número de resultados

Filtrando por dominio

scrape_options

Comportamiento

Ejemplo con raspado

Respuesta

Recuperando una búsqueda pasada

Precios

​Instalación

​Uso básico

​Parámetros de la solicitud

​Limitando el número de resultados

​Filtrando por dominio

​scrape_options

​Comportamiento

​Ejemplo con raspado

​Respuesta

​Recuperando una búsqueda pasada

​Precios

Instalación

Uso básico

Parámetros de la solicitud

Limitando el número de resultados

Filtrando por dominio

scrape_options

Comportamiento

Ejemplo con raspado

Respuesta

Recuperando una búsqueda pasada

Precios