Monitors

Via het Olostep /v1/monitors eindpunt kun je permanente monitors maken die op een vast schema draaien, paginawijzigingen detecteren en je op de hoogte stellen via e-mail, webhook of SMS.

Maak een monitor vanuit een natuurlijke taal query
Voer controles uit met natuurlijke-taal schema’s
Lever meldingen via email, webhook_url, of phone_number (SMS)
Lijst, inspecteer, update, pauzeer, hervat en verwijder monitors
Lees monitor snapshot evenementen van privé snapshots

Standaard legt elke monitor run een volledige snapshot vast van de gemonitorde pagina — een compleet beeld van de huidige staat op dat moment. Als je wilt dat de monitor alleen toont wat nieuw is of veranderd is tussen runs (delta’s) in plaats van de volledige staat, moet je dat expliciet aangeven in de query.

Installatie

# pip install requests

import requests

Maak een monitor

Maak een monitor met POST /v1/monitors. Het eindpunt valideert je invoer, voorziet de monitor, maakt het interne schema aan en retourneert een actief monitorobject.

query is vereist. Als je query een URL bevat, zal de monitor zich richten op die invoer-URL. Standaard neemt elke run een volledige snapshot van wat wordt gemonitord — een afbeelding van de huidige staat van de pagina. Als je wilt dat de monitor alleen bijhoudt wat nieuw is of veranderd is tussen runs (bijvoorbeeld alleen nieuwe blogposts, of alleen prijsdalingen), moet je dat expliciet aangeven in de query; anders wordt de volledige snapshot elke run vastgelegd.
frequency accepteert natuurlijke-taal schema-instructies en standaard naar UTC wanneer er geen tijdzone is opgegeven.
Precies één meldingsdoel is vereist: email, webhook_url, of phone_number (SMS).
Gebruik output_schema wanneer je gestructureerde extractieresultaten wilt. (optioneel)

Voorbeeldverzoek

import requests
import json

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

payload = {
    "query": "Volg wijzigingen in https://example.com/products/widget-pro prijs- en voorraadinformatie",
    "frequency": "elke dag om 9 uur 's ochtends 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))

Reactie

Succesvolle monitorcreatie retourneert HTTP 202 met een monitorobject:

{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "created_at": 1777983215,
  "updated_at": 1777983222,
  "fda_id": "fda_n8q2x4m1ak",
  "team_id": "team_n8q2x4m1ak",
  "status": "active",
  "query": "Volg wijzigingen in https://example.com/products/widget-pro prijs- en voorraadinformatie",
  "frequency": "elke dag om 9 uur 's ochtends 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"
  }
}

Gestructureerde monitor output

Stel output_schema in bij het aanmaken van de aanvraag wanneer je wilt dat monitor extractieresultaten een specifieke JSON-structuur volgen. Het schema moet een geldige JSON Schema zijn.

Meldingskanalen

Monitors ondersteunen één kanaal per monitor:

email: stel een email veld in
webhook: stel een webhook_url veld in
sms: stel een phone_number veld in (E.164 formaat, bijvoorbeeld +14155552671)

Je kunt precies één van deze velden per aanvraag instellen.

Webhook voorbeeld

{
  "query": "Houd wijzigingen in https://example.com/terms juridische voorwaarden in de gaten",
  "frequency": "elke dag om 10:00 uur",
  "webhook_url": "https://hooks.example.com/olostep-monitor"
}

SMS voorbeeld

{
  "query": "Houd wijzigingen in https://example.com/terms juridische voorwaarden in de gaten",
  "frequency": "elke dag om 10:00 uur",
  "phone_number": "+14155552671"
}

Frequenties

Stel frequency in natuurlijke taal in, bijvoorbeeld:

elke dag om 9 uur 's ochtends America/Los_Angeles
elke 5 minuten
elke 6 uur

De API interpreteert deze schema-tekst en leidt automatisch de cron-expressie af. Als er geen tijdzone is opgegeven, wordt standaard UTC gebruikt.

Lijst monitors

Haal alle monitors voor je team op met GET /v1/monitors. Standaard worden verwijderde monitors eruit gefilterd. Gebruik ?include_deleted=true om ze op te nemen.

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"Totaal aantal monitors: {result['count']}")
print(json.dumps(result, indent=2))

Reactievorm

{
  "monitors": [
    {
      "id": "monitor_a3yk6z49p8",
      "object": "monitor",
      "created_at": 1777983215,
      "cron_expression": "13 13 * * ? *",
      "fda_id": "fda_a3yk6z49p8",
      "frequency": "dagelijks",
      "metadata": {},
      "notification_channel": "email",
      "notification_target": "example@olostep.com",
      "query": "Verzamel de nieuwe blogposts van de voorbeeldwebsite en stuur me updates met nieuwe posts.",
      "status": "active",
      "team_id": "team_a3yk6z49p8F",
      "updated_at": 1777983222
    }
  ],
  "count": 1
}

Haal een monitor op

Haal een enkele monitor op met 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))

Reactievorm

{
  "id": "monitor_a3yk6z49p8",
  "object": "monitor",
  "created_at": 1777983215,
  "cron_expression": "13 13 * * ? *",
  "fda_id": "fda_a3yk6z49p8",
  "frequency": "dagelijks",
  "metadata": {},
  "notification_channel": "email",
  "notification_target": "example@olostep.com",
  "query": "Verzamel de nieuwe blogposts van de voorbeeldwebsite en stuur me updates met nieuwe posts.",
  "status": "active",
  "team_id": "team_a3yk6z49p8",
  "updated_at": 1777983222
}

Lijst monitor evenementen

Gebruik GET /v1/monitors/:monitor_id/events om snapshot evenementen voor een monitor op te sommen. Dit eindpunt ondersteunt paginering:

limit (standaard 25, max 100)
cursor (ondoorzichtige pagineringstoken van een eerdere reactie)

Evenementen worden van nieuw naar oud geretourneerd. Elk item bevat een kortdurende voorgetekende snapshot_url zodat je privé snapshot inhoud veilig kunt ophalen.

Voorbeeld

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

Reactievorm

{
  "data": [
    {
      "id": "run_v7k2p9m3",
      "run_id": "run_v7k2p9m3",
      "created": 1777960800,
      "changed": true,
      "summary": "Prijs veranderd van $49 naar $45 en voorraad verplaatst naar lage beschikbaarheid.",
      "snapshot_url": "https://olostep-monitor-snapshot.s3.amazonaws.com/private/key?...signature..."
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Als cursor onjuist is, retourneert het eindpunt:

{
  "error": "Ongeldige cursor."
}

Update een monitor

Update een monitor met POST /v1/monitors/:monitor_id. Ondersteunde updates:

metadata (samengevoegd met bestaande metadata; geef lege stringwaarden door om sleutels te verwijderen)
frequency (natuurlijke-taal schema tekst, bijvoorbeeld elke werkdag om 08:30 America/New_York)

Als je frequency bijwerkt, maakt de API het monitorschema intern opnieuw aan. Als er geen tijdzone in de tekst is opgenomen, wordt UTC gebruikt.

Voorbeeldverzoek

import requests
import json

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

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

Pauzeer een monitor

Pauzeer een monitor met POST /v1/monitors/:monitor_id/pause. Pauzeren schakelt het onderliggende schema van de monitor uit zodat er geen verdere runs worden gestart, en stelt de status van de monitor in op paused. De monitorrij, de configuratie en de eerdere snapshots worden behouden — alleen toekomstige geplande uitvoeringen stoppen. Je kunt de monitor later hervatten met POST /v1/monitors/:monitor_id/resume. Alleen monitors met de status van active kunnen worden gepauzeerd. Het aanvraaglichaam is leeg.

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

Reactie

Bij succes retourneert 200 met de monitor en status ingesteld op paused:

{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "status": "paused",
  "updated_at": 1777986822,
  "query": "Volg wijzigingen in https://example.com/products/widget-pro prijs- en voorraadinformatie",
  "frequency": "elke dag om 9 uur 's ochtends America/Los_Angeles",
  "notification_channel": "email",
  "notification_target": "alerts@example.com"
}

Mogelijke foutreacties:

400 — monitor_id onjuist, monitor al deleted, monitor niet momenteel active, of monitor heeft geen onderliggend schema.
404 — Monitor niet gevonden.
409 — De monitor veranderde van status tijdens de pauze poging (niet langer active), of het onderliggende schema kon niet worden gevonden.

Hervat een monitor

Hervat een gepauzeerde monitor met POST /v1/monitors/:monitor_id/resume. Hervatten schakelt het onderliggende schema van de monitor weer in en stelt de status van de monitor terug op active. Geplande runs gaan door op de bestaande frequency — er is geen hercreatie van het schema nodig. Alleen monitors met de status van paused kunnen worden hervat. Het aanvraaglichaam is leeg.

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

Reactie

Bij succes retourneert 200 met de monitor en status teruggezet naar active:

{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "status": "active",
  "updated_at": 1777990422,
  "query": "Volg wijzigingen in https://example.com/products/widget-pro prijs- en voorraadinformatie",
  "frequency": "elke dag om 9 uur 's ochtends America/Los_Angeles",
  "notification_channel": "email",
  "notification_target": "alerts@example.com"
}

Mogelijke foutreacties:

400 — monitor_id onjuist, monitor al deleted, monitor niet momenteel paused, of monitor heeft geen onderliggend schema.
404 — Monitor niet gevonden.
409 — De monitor veranderde van status tijdens de hervat poging (niet langer paused), of het onderliggende schema kon niet worden gevonden.

Verwijder een monitor

Verwijder een monitor met DELETE /v1/monitors/:monitor_id. Verwijdering is zacht voor de monitorrij (status wordt deleted) en verwijdert ook interne planning/schaduw-agent resources die aan die monitor zijn gekoppeld.

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

Voorbeeld gebruiksscenario’s

Hieronder staan praktische voorbeeldverzoeken voor het /v1/monitors eindpunt.

Volg uptime problemen in de OpenAI API

Voer elk uur een controle uit die de status van de OpenAI API bewaakt en je een e-mail stuurt wanneer uptime problemen worden gedetecteerd.

import requests
import json

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

payload = {
    "query": "Volg uptime problemen in OpenAI API en stuur me een e-mail op info@olostep.com",
    "frequency": "elk uur",
    "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))

Volg productrecensies — volledige snapshot per run

Monitor een productpagina en lever elke recensie aan een webhook bij elke run. Omdat de query niet vraagt om deduplicatie ten opzichte van eerdere runs, legt elke run een volledige snapshot vast van de recensies die momenteel op de pagina staan (het standaardgedrag). Gebruik dit patroon wanneer je elke keer de volledige staat wilt, bijvoorbeeld om een downstream tabel te overschrijven.

import requests
import json

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

payload = {
    "query": "Monitor de recensies van dit product https://www.walmart.com/reviews/product/957245477?sort=submission-desc en informeer me via webhook. Voor elke recensie extraheer de publicatiedatum, auteur, beoordeling, titel en tekstinhoud.",
    "frequency": "elke dag om 9 uur 's ochtends",
    "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))

Volg alleen nieuwe huuradvertenties — delta van vorige run

Monitor een gepagineerde huurzoekopdracht en voer een meerstappige pijplijn uit die alleen nieuw verschenen advertenties ten opzichte van de vorige run naar voren brengt, verrijkt en scoort elke advertentie voordat de webhook wordt geïnformeerd. De volledige workflow — pagineren, detecteer nieuwe advertenties ten opzichte van de vorige controlepunt, verrijk elke nieuwe advertentie met misdaadsignalen voor zijn locatie, ken een 1-10 score toe op basis van prijs/locatie/veiligheid, bewaar staat en informeer — wordt direct als geordende stappen in de query uitgedrukt. Omdat de natuurlijke-taal stappen zowel de extractie als de delta logica beschrijven, is er geen output_schema vereist: de query alleen bepaalt wat wordt opgehaald, vergeleken, verrijkt, gescoord en geleverd.

import requests
import json

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

payload = {
    "query": "Monitor de eerste 3 pagina's van https://streeteasy.com/for-rent/new-jersey/price:1000-1750?sort_by=listed_desc, detecteer alleen nieuw verschenen advertenties ten opzichte van het vorige controlepunt, verrijk elke nieuwe advertentie met misdaadsignalen voor zijn locatie, ken een 1-10 algehele score toe op basis van prijs/locatie/veiligheid, bewaar staat en informeer via webhook.",
    "frequency": "elk uur",
    "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))

Veelvoorkomende validatiefouten

De monitor eindpunten geven duidelijke validatiefouten terug voor veelvoorkomende ongeldige aanvragen:

Ontbrekende query
Ontbrekende frequency, of ongeldige schema-instructie
Ontbreken van alle email, webhook_url, en phone_number
Meer dan één van email, webhook_url, en phone_number in dezelfde aanvraag verstrekken
Ongeldig e-mailformaat
Ongeldige webhook URL (moet http of https zijn)
Ongeldig telefoonnummerformaat (moet E.164 zijn, bijvoorbeeld +14155552671)
Ongeldige output_schema (moet geldige JSON Schema zijn)
Ongeldige monitor_id formaat

Voorbeeldfout:

{
  "error": "Ongeldige frequentie. Geef een natuurlijke-taal schema-instructie."
}

Aan de slag

Functies

Integraties

Installatie

Maak een monitor

Voorbeeldverzoek

Reactie

Gestructureerde monitor output

Meldingskanalen

Webhook voorbeeld

SMS voorbeeld

Frequenties

Lijst monitors

Reactievorm

Haal een monitor op

Reactievorm

Lijst monitor evenementen

Voorbeeld

Reactievorm

Update een monitor

Voorbeeldverzoek

Pauzeer een monitor

Reactie

Hervat een monitor

Reactie

Verwijder een monitor

Voorbeeld gebruiksscenario’s

Volg uptime problemen in de OpenAI API

Volg productrecensies — volledige snapshot per run

Volg alleen nieuwe huuradvertenties — delta van vorige run

Veelvoorkomende validatiefouten

Aan de slag

Functies

Integraties

Documentation Index

​Installatie

​Maak een monitor

​Voorbeeldverzoek

​Reactie

​Gestructureerde monitor output

​Meldingskanalen

​Webhook voorbeeld

​SMS voorbeeld

​Frequenties

​Lijst monitors

​Reactievorm

​Haal een monitor op

​Reactievorm

​Lijst monitor evenementen

​Voorbeeld

​Reactievorm

​Update een monitor

​Voorbeeldverzoek

​Pauzeer een monitor

​Reactie

​Hervat een monitor

​Reactie

​Verwijder een monitor

​Voorbeeld gebruiksscenario’s

​Volg uptime problemen in de OpenAI API

​Volg productrecensies — volledige snapshot per run

​Volg alleen nieuwe huuradvertenties — delta van vorige run

​Veelvoorkomende validatiefouten

Installatie

Maak een monitor

Voorbeeldverzoek

Reactie

Gestructureerde monitor output

Meldingskanalen

Webhook voorbeeld

SMS voorbeeld

Frequenties

Lijst monitors

Reactievorm

Haal een monitor op

Reactievorm

Lijst monitor evenementen

Voorbeeld

Reactievorm

Update een monitor

Voorbeeldverzoek

Pauzeer een monitor

Reactie

Hervat een monitor

Reactie

Verwijder een monitor

Voorbeeld gebruiksscenario’s

Volg uptime problemen in de OpenAI API

Volg productrecensies — volledige snapshot per run

Volg alleen nieuwe huuradvertenties — delta van vorige run

Veelvoorkomende validatiefouten