Skip to main content

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.

Through the Olostep /v1/monitors endpoint you can create persistent monitors that run on a fixed schedule, detect page changes, and notify you by email or webhook.
  • Create a monitor from a query, a url, or both
  • Run checks hourly, daily, or weekly
  • Deliver alerts to either email or webhook_url
  • List, inspect, update, and delete monitors
  • Read monitor snapshot events from private snapshots

​
Installation

# pip install requests

import requests

​
Create a monitor

Create a monitor with POST /v1/monitors. The endpoint validates your input, provisions the monitor, creates its internal schedule, and returns an active monitor object. At least one of query or url is required. Exactly one notification target is required: either email or webhook_url.

​
Example request

import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"

payload = {
    "query": "Track changes in product pricing and stock information",
    "url": "https://example.com/products/widget-pro",
    "frequency": "daily",
    "email": "alerts@example.com",
    "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))

​
Response

Successful monitor creation returns HTTP 202 with a monitor object: 
{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "status": "active",
  "schedule_id": "schedule_r4h9n2j7",
  "query": "Track changes in product pricing and stock information",
  "url": "https://example.com/products/widget-pro",
  "frequency": "daily",
  "cron_expression": "0 0 * * ? *",
  "notification_channel": "email",
  "notification_target": "alerts@example.com",
  "metadata": {
    "product_id": "widget-pro",
    "team": "growth"
  },
  "created": 1745673871,
  "updated": 1745673871
}

​
Notification channels

Monitors support one channel per monitor:
  • email: set an email field
  • webhook: set a webhook_url field
You cannot set both in one request.

​
Webhook example

{
  "query": "Watch for changes in legal terms",
  "url": "https://example.com/terms",
  "frequency": "weekly",
  "webhook_url": "https://hooks.example.com/olostep-monitor"
}

​
Frequencies

Supported monitor frequencies are:
  • hourly
  • daily
  • weekly
The API derives the schedule cron expression automatically from the selected frequency.

​
List monitors

Retrieve all monitors for your team with GET /v1/monitors. By default, deleted monitors are filtered out. Use ?include_deleted=true to include them. 
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 monitors: {result['count']}")
print(json.dumps(result, indent=2))

​
Get a monitor

Retrieve a single monitor with 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))

​
List monitor events

Use GET /v1/monitors/:monitor_id/events to list snapshot events for a monitor. This endpoint supports pagination:
  • limit (default 25, max 100)
  • cursor (opaque pagination token from a previous response)
Events are returned newest-first. Each item includes a short-lived pre-signed snapshot_url so you can fetch private snapshot content securely.

​
Example

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

​
Response shape

{
  "data": [
    {
      "id": "run_v7k2p9m3",
      "run_id": "run_v7k2p9m3",
      "created": 1777960800,
      "changed": true,
      "summary": "Price changed from $49 to $45 and stock moved to low availability.",
      "snapshot_url": "https://olostep-monitor-snapshot.s3.amazonaws.com/private/key?...signature..."
    }
  ],
  "has_more": false,
  "next_cursor": null
}
If cursor is malformed, the endpoint returns: 
{
  "error": "Invalid cursor."
}

​
Update a monitor

Update a monitor with POST /v1/monitors/:monitor_id. Supported updates:
  • metadata (merged with existing metadata; pass empty string values to delete keys)
  • frequency (hourly, daily, weekly)
If you update frequency, the API recreates the monitor schedule internally.

​
Example request

import requests
import json

API_KEY = "<YOUR_API_KEY>"
API_URL = "https://api.olostep.com/v1"
MONITOR_ID = "monitor_n8q2x4m1ak"

payload = {
    "frequency": "hourly",
    "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))

​
Delete a monitor

Delete a monitor with DELETE /v1/monitors/:monitor_id. Deletion is soft for the monitor row (status becomes deleted) and also removes internal scheduling/shadow-agent resources tied to that 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))

​
Common validation errors

The monitor endpoints return clear validation errors for common invalid requests:
  • Missing both query and url
  • Missing frequency, or unsupported frequency value
  • Missing both email and webhook_url
  • Providing both email and webhook_url
  • Invalid email format
  • Invalid webhook URL (must be http or https)
  • Invalid monitor_id format
Example error: 
{
  "error": "'frequency' must be one of: hourly, daily, weekly."
}