Saltar al contenido principal

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.

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, extrae 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 extracción
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 solicitud

CampoTipoRequeridoPredeterminadoDescripción
querystringsí—La consulta de búsqueda en lenguaje natural.
limitintegerno12Número máximo de enlaces a devolver después de la deduplicación. Debe estar entre 1 y 25.
include_domainsstring[]no[]Restringe los resultados a estos dominios. Solo hosts sin prefijos http(s):// y barras finales se eliminan automáticamente.
exclude_domainsstring[]no[]Excluye resultados de estos dominios. Solo hosts sin prefijos http(s):// y barras finales se eliminan automáticamente.
scrape_optionsobjectno—Cuando se proporciona, cada enlace devuelto también se extrae y su contenido se incrusta en la respuesta. Ver scrape_options abajo.

​
Limitando el número de resultados

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

​
Filtrando por dominio

include_domains restringe los resultados a una lista blanca; exclude_domains filtra fuentes no deseadas. Pueden combinarse. 
{
  "query": "OpenAI Sora shutdown analysis",
  "include_domains": ["nytimes.com", "wsj.com", "bbc.com"],
  "exclude_domains": ["pinterest.com"]
}

​
scrape_options

Pasa scrape_options para extraer 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
  }
}
CampoTipoPredeterminadoDescripción
formatsstring[]["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_selectorsstring"default"Se reenvía 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 para eliminar.
timeoutinteger25Presupuesto de tiempo en segundos para toda la fase de extracción. Debe estar entre 1 y 60. Después de que esto transcurra, 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 extraen en paralelo. El timeout limita todo el lote, no cada enlace individual.
  • Los fallos de extracción por enlace (errores de red, tiempos de espera de página individuales) dejan el markdown_content / html_content de ese enlace como null mientras que otros enlaces se devuelven normalmente.
  • Si el timeout global transcurre antes de que todas las extracciones terminen, la búsqueda responde inmediatamente con los enlaces que tiene: las extracciones ya completadas mantienen su contenido; las que están en curso 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 extracción

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

​
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 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..."
      }
    ]
  }
}
Cada enlace en result.links contiene:
CampoTipoDescripción
urlstringLa URL del resultado de búsqueda.
titlestringEl título de la página de resultados.
descriptionstringUn breve fragmento que describe el resultado.
markdown_contentstringContenido en markdown de la página. Solo presente cuando scrape_options.formats incluye "markdown". null si la extracción falló, estaba vacía, o alcanzó el tiempo de espera global.
html_contentstringContenido 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 extraído. Es una lectura idempotente pura: sin re-extracción, sin re-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 extraída 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:
Solicitudcredits_consumed
Solo búsqueda5
Búsqueda + 5 páginas extraídas (1 crédito cada una)10