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.
A través del endpoint de Olostep /v1/monitors puedes crear monitores persistentes que se ejecutan en un horario fijo, detectan cambios en la página y te notifican por correo electrónico, webhook o SMS.
- Crea un monitor a partir de una
query en lenguaje natural
- Ejecuta verificaciones usando horarios en lenguaje natural
- Envía alertas vía
email, webhook_url o phone_number (SMS)
- Lista, inspecciona, actualiza, pausa, reanuda y elimina monitores
- Lee eventos de instantáneas de monitores desde instantáneas privadas
Por defecto, cada ejecución del monitor captura una instantánea completa de la página monitoreada — una imagen completa de su estado actual en ese momento. Si deseas que el monitor muestre solo lo que es nuevo o ha cambiado entre ejecuciones (deltas) en lugar del estado completo, debes expresar esa intención directamente en la query.
Instalación
# pip install requests
import requests
Crear un monitor
Crea un monitor con POST /v1/monitors. El endpoint valida tu entrada, provisiona el monitor, crea su horario interno y devuelve un objeto de monitor activo.
query es obligatorio. Si tu query incluye una URL, el monitor se centrará en esa URL de entrada. Por defecto, cada ejecución toma una instantánea completa de lo que se está monitoreando — una imagen del estado actual de la página. Si deseas que el monitor rastree solo lo que es nuevo o ha cambiado entre ejecuciones (por ejemplo, solo nuevas publicaciones de blog, o solo caídas de precios), debes especificarlo explícitamente en la query; de lo contrario, se captura la instantánea completa en cada ejecución.frequency acepta instrucciones de horario en lenguaje natural y por defecto usa UTC cuando no se proporciona una zona horaria.- Se requiere exactamente un objetivo de notificación:
email, webhook_url o phone_number (SMS).
- Usa
output_schema cuando desees resultados de extracción estructurados. (opcional)
Ejemplo de solicitud
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
payload = {
"query": "Rastrear cambios en https://example.com/products/widget-pro información de precios y stock",
"frequency": "todos los días a las 9am America/Los_Angeles",
"email": "alerts@example.com",
"output_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"published_at": {"type": "string"}
},
"required": ["title"]
},
"metadata": {
"product_id": "widget-pro",
"team": "growth"
}
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
response = requests.post(f"{API_URL}/monitors", headers=headers, json=payload)
print(response.status_code)
print(json.dumps(response.json(), indent=2))
Respuesta
La creación exitosa de un monitor devuelve HTTP 202 con un objeto de monitor:
{
"id": "monitor_n8q2x4m1ak",
"object": "monitor",
"created_at": 1777983215,
"updated_at": 1777983222,
"fda_id": "fda_n8q2x4m1ak",
"team_id": "team_n8q2x4m1ak",
"status": "active",
"query": "Rastrear cambios en https://example.com/products/widget-pro información de precios y stock",
"frequency": "todos los días a las 9am America/Los_Angeles",
"cron_expression": "0 0 * * ? *",
"notification_channel": "email",
"notification_target": "alerts@example.com",
"output_schema": {
"type": "object",
"properties": {
"title": { "type": "string" },
"published_at": { "type": "string" }
},
"required": ["title"]
},
"metadata": {
"product_id": "widget-pro",
"team": "growth"
}
}
Salida estructurada del monitor
Establece output_schema en la solicitud de creación cuando desees que los resultados de extracción del monitor sigan una estructura JSON específica. El esquema debe ser un JSON Schema válido.
Canales de notificación
Los monitores admiten un canal por monitor:
email: establece un campo emailwebhook: establece un campo webhook_urlsms: establece un campo phone_number (formato E.164, por ejemplo +14155552671)
Puedes establecer exactamente uno de estos campos por solicitud.
Ejemplo de Webhook
{
"query": "Observar cambios en https://example.com/terms términos legales",
"frequency": "todos los días a las 10:00 am",
"webhook_url": "https://hooks.example.com/olostep-monitor"
}
Ejemplo de SMS
{
"query": "Observar cambios en https://example.com/terms términos legales",
"frequency": "todos los días a las 10:00 am",
"phone_number": "+14155552671"
}
Frecuencias
Establece frequency en lenguaje natural, por ejemplo:
todos los días a las 9am America/Los_Angelescada 5 minutoscada 6 horas
La API interpreta este texto de programación y deriva automáticamente la expresión cron. Si no se proporciona una zona horaria, se usa UTC por defecto.
Listar monitores
Recupera todos los monitores para tu equipo con GET /v1/monitors.
Por defecto, los monitores eliminados se filtran. Usa ?include_deleted=true para incluirlos.
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
response = requests.get(f"{API_URL}/monitors", headers=headers)
result = response.json()
print(f"Total de monitores: {result['count']}")
print(json.dumps(result, indent=2))
{
"monitors": [
{
"id": "monitor_a3yk6z49p8",
"object": "monitor",
"created_at": 1777983215,
"cron_expression": "13 13 * * ? *",
"fda_id": "fda_a3yk6z49p8",
"frequency": "diario",
"metadata": {},
"notification_channel": "email",
"notification_target": "example@olostep.com",
"query": "Recopila las nuevas publicaciones de blog del sitio web de ejemplo y envíame actualizaciones con nuevas publicaciones.",
"status": "active",
"team_id": "team_a3yk6z49p8F",
"updated_at": 1777983222
}
],
"count": 1
}
Obtener un monitor
Recupera un solo monitor con GET /v1/monitors/:monitor_id.
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
response = requests.get(f"{API_URL}/monitors/{MONITOR_ID}", headers=headers)
print(json.dumps(response.json(), indent=2))
{
"id": "monitor_a3yk6z49p8",
"object": "monitor",
"created_at": 1777983215,
"cron_expression": "13 13 * * ? *",
"fda_id": "fda_a3yk6z49p8",
"frequency": "diario",
"metadata": {},
"notification_channel": "email",
"notification_target": "example@olostep.com",
"query": "Recopila las nuevas publicaciones de blog del sitio web de ejemplo y envíame actualizaciones con nuevas publicaciones.",
"status": "active",
"team_id": "team_a3yk6z49p8",
"updated_at": 1777983222
}
Listar eventos de monitores
Usa GET /v1/monitors/:monitor_id/events para listar eventos de instantáneas para un monitor.
Este endpoint admite paginación:
limit (por defecto 25, máximo 100)cursor (token de paginación opaco de una respuesta anterior)
Los eventos se devuelven del más nuevo al más antiguo. Cada elemento incluye un snapshot_url pre-firmado de corta duración para que puedas obtener contenido de instantáneas privadas de manera segura.
Ejemplo
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
response = requests.get(
f"{API_URL}/monitors/{MONITOR_ID}/events?limit=10",
headers=headers
)
print(json.dumps(response.json(), indent=2))
{
"data": [
{
"id": "run_v7k2p9m3",
"run_id": "run_v7k2p9m3",
"created": 1777960800,
"changed": true,
"summary": "El precio cambió de $49 a $45 y el stock pasó a baja disponibilidad.",
"snapshot_url": "https://olostep-monitor-snapshot.s3.amazonaws.com/private/key?...signature..."
}
],
"has_more": false,
"next_cursor": null
}
cursor está mal formado, el endpoint devuelve:
{
"error": "Cursor inválido."
}
Actualizar un monitor
Actualiza un monitor con POST /v1/monitors/:monitor_id.
Actualizaciones admitidas:
metadata (se fusiona con los metadatos existentes; pasa valores de cadena vacíos para eliminar claves)frequency (texto de horario en lenguaje natural, por ejemplo cada día de semana a las 08:30 America/New_York)
Si actualizas frequency, la API recrea el horario del monitor internamente. Si no se incluye una zona horaria en el texto, se usa UTC.
Ejemplo de solicitud
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"
payload = {
"frequency": "cada 2 horas",
"metadata": {
"owner": "ops-team",
"deprecated_field": ""
}
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
response = requests.post(
f"{API_URL}/monitors/{MONITOR_ID}",
headers=headers,
json=payload
)
print(json.dumps(response.json(), indent=2))
Pausar un monitor
Pausa un monitor con POST /v1/monitors/:monitor_id/pause.
Pausar desactiva el horario subyacente del monitor para que no se activen más ejecuciones y establece el status del monitor en paused. La fila del monitor, su configuración y sus instantáneas pasadas se mantienen — solo se detienen las ejecuciones programadas futuras. Puedes reanudar el monitor más tarde con POST /v1/monitors/:monitor_id/resume.
Solo los monitores con status de active pueden ser pausados. El cuerpo de la solicitud está vacío.
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
response = requests.post(f"{API_URL}/monitors/{MONITOR_ID}/pause", headers=headers)
print(response.status_code)
print(json.dumps(response.json(), indent=2))
Respuesta
En caso de éxito, devuelve 200 con el monitor y status establecido en paused:
{
"id": "monitor_n8q2x4m1ak",
"object": "monitor",
"status": "paused",
"updated_at": 1777986822,
"query": "Rastrear cambios en https://example.com/products/widget-pro información de precios y stock",
"frequency": "todos los días a las 9am America/Los_Angeles",
"notification_channel": "email",
"notification_target": "alerts@example.com"
}
400 — monitor_id mal formado, monitor ya deleted, monitor no actualmente active, o el monitor no tiene un horario subyacente.404 — Monitor no encontrado.409 — El monitor cambió de estado durante el intento de pausa (ya no active), o no se pudo encontrar el horario subyacente.
Reanudar un monitor
Reanuda un monitor pausado con POST /v1/monitors/:monitor_id/resume.
Reanudar vuelve a habilitar el horario subyacente del monitor y establece el status del monitor de nuevo en active. Las ejecuciones programadas continúan con la frequency existente — no se necesita recrear el horario.
Solo los monitores con status de paused pueden ser reanudados. El cuerpo de la solicitud está vacío.
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
response = requests.post(f"{API_URL}/monitors/{MONITOR_ID}/resume", headers=headers)
print(response.status_code)
print(json.dumps(response.json(), indent=2))
Respuesta
En caso de éxito, devuelve 200 con el monitor y status establecido de nuevo en active:
{
"id": "monitor_n8q2x4m1ak",
"object": "monitor",
"status": "active",
"updated_at": 1777990422,
"query": "Rastrear cambios en https://example.com/products/widget-pro información de precios y stock",
"frequency": "todos los días a las 9am America/Los_Angeles",
"notification_channel": "email",
"notification_target": "alerts@example.com"
}
400 — monitor_id mal formado, monitor ya deleted, monitor no actualmente paused, o el monitor no tiene un horario subyacente.404 — Monitor no encontrado.409 — El monitor cambió de estado durante el intento de reanudación (ya no paused), o no se pudo encontrar el horario subyacente.
Eliminar un monitor
Elimina un monitor con DELETE /v1/monitors/:monitor_id.
La eliminación es suave para la fila del monitor (status se convierte en deleted) y también elimina los recursos de programación/agente sombra internos vinculados a ese monitor.
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
response = requests.delete(f"{API_URL}/monitors/{MONITOR_ID}", headers=headers)
print(json.dumps(response.json(), indent=2))
Casos de uso de ejemplo
A continuación, se muestran solicitudes de ejemplo prácticas para el endpoint /v1/monitors.
Rastrear problemas de tiempo de actividad en la API de OpenAI
Ejecuta una verificación cada hora que observe el estado de la API de OpenAI y te envíe un correo electrónico cuando se detecten problemas de tiempo de actividad.
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
payload = {
"query": "Rastrear problemas de tiempo de actividad en la API de OpenAI y enviarme un correo electrónico a info@olostep.com",
"frequency": "cada hora",
"email": "alerts@example.com"
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
response = requests.post(f"{API_URL}/monitors", headers=headers, json=payload)
print(response.status_code)
print(json.dumps(response.json(), indent=2))
Rastrear reseñas de productos — instantánea completa por ejecución
Monitorea una página de producto y entrega cada reseña a un webhook en cada ejecución. Debido a que la query no pide deduplicar contra ejecuciones anteriores, cada ejecución captura una instantánea completa de las reseñas actualmente en la página (el comportamiento predeterminado). Usa este patrón cuando desees el estado completo cada vez, por ejemplo, para sobrescribir una tabla downstream.
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
payload = {
"query": "Monitorea las reseñas de este producto https://www.walmart.com/reviews/product/957245477?sort=submission-desc y notifícame por webhook. Para cada reseña extrae la fecha de publicación, autor, calificación, título y contenido del texto.",
"frequency": "todos los días a las 9am",
"webhook_url": "https://webhook.site/3fb2b00b-d66f-4c46-b778-f0c7b93d4d86",
"output_schema": {
"type": "object",
"properties": {
"reviews": {
"type": "array",
"items": {
"type": "object",
"properties": {
"publication_date": {"type": "string"},
"author": {"type": "string"},
"rating": {"type": "number"},
"title": {"type": "string"},
"text_content": {"type": "string"}
}
},
"required": [
"publication_date",
"author",
"rating",
"title",
"text_content"
]
}
}
}
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
response = requests.post(f"{API_URL}/monitors", headers=headers, json=payload)
print(response.status_code)
print(json.dumps(response.json(), indent=2))
Rastrear solo nuevos listados de alquiler — delta de la ejecución anterior
Monitorea una búsqueda de alquileres paginada y ejecuta un pipeline de múltiples pasos que muestra solo los listados recién aparecidos en comparación con la ejecución anterior, luego enriquece y califica cada uno antes de notificar al webhook. Todo el flujo de trabajo — paginar, detectar nuevos listados contra el punto de control anterior, enriquecer cada uno con señales de criminalidad para su ubicación, asignar una puntuación de 1-10 basada en precio/ubicación/seguridad, persistir el estado y notificar — se expresa directamente como pasos ordenados en la query. Debido a que los pasos en lenguaje natural describen tanto la extracción como la lógica delta, no se requiere output_schema: la query por sí sola determina qué se obtiene, compara, enriquece, califica y entrega.
import requests
import json
API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
payload = {
"query": "Monitorea las primeras 3 páginas de https://streeteasy.com/for-rent/new-jersey/price:1000-1750?sort_by=listed_desc, detecta solo los listados recién aparecidos en comparación con el punto de control anterior, enriquece cada nuevo listado con señales de criminalidad para su ubicación, asigna una puntuación general de 1-10 basada en precio/ubicación/seguridad, persiste el estado y notifica vía webhook.",
"frequency": "cada hora",
"webhook_url": "https://webhook.site/3fb2b00b-d66f-4c46-b778-f0c7b93d4d86"
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
response = requests.post(f"{API_URL}/monitors", headers=headers, json=payload)
print(response.status_code)
print(json.dumps(response.json(), indent=2))
Errores comunes de validación
Los endpoints de monitores devuelven errores de validación claros para solicitudes no válidas comunes:
- Falta
query
- Falta
frequency, o instrucción de horario no válida
- Falta de todos
email, webhook_url y phone_number
- Proporcionar más de uno de
email, webhook_url y phone_number en la misma solicitud
- Formato de correo electrónico no válido
- URL de webhook no válida (debe ser
http o https)
- Formato de número de teléfono no válido (debe ser E.164, por ejemplo
+14155552671)
output_schema no válido (debe ser un JSON Schema válido)- Formato de
monitor_id no válido
Ejemplo de error:
{
"error": "Frecuencia no válida. Proporciona una instrucción de horario en lenguaje natural."
}
