API de Búsqueda - Olostep Docs

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

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

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. Consulta scrape_options a continuación.

Limitando el número de resultados

{
  "query": "¿Qué está pasando con el cierre de Sora de OpenAI?",
  "limit": 5
}

Filtrando por dominio

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

{
  "query": "Análisis del cierre de OpenAI Sora",
  "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": "¿Qué está pasando con el cierre de Sora de OpenAI?",
  "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 JSON de selectores a 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) 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 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 supera 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="¿Qué está pasando con el cierre de Sora de OpenAI?",
    limit=5,
    scrape_options={"formats": ["markdown"], "timeout": 25},
)

for link in search.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": "¿Qué está pasando con el cierre de Sora de OpenAI?",
  "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 cerrará la plataforma de video Sora",
        "description": "OpenAI dice que descontinuará su aplicación Sora...",
        "markdown_content": "# OpenAI cerrará la plataforma de video Sora\n\nOpenAI dice que descontinuará..."
      },
      {
        "url": "https://www.reddit.com/r/OutOfTheLoop/comments/1s2u847/whats_going_on_with_openais_sora_shutting_down/",
        "title": "¿Qué está pasando con el cierre de Sora de OpenAI?",
        "description": "Hilo de Reddit discutiendo el cierre.",
        "markdown_content": "# ¿Qué está pasando con el cierre de Sora de OpenAI?\n\n*r/OutOfTheLoop · u/rm-minus-r · hace 1 mes*\n\n..."
      }
    ]
  }
}

Cada enlace en result.links contiene:

Campo	Tipo	Descripción
`url`	string	La URL del resultado de la 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 tiempo de espera global.
`html_content`	string	Contenido en HTML de la página. Solo presente cuando `scrape_options.formats` incluye `"html"`. `null` en caso de fallo/tiempo de espera.

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 pura e idempotente — 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))

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`

​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