Monitore

Über den Olostep-Endpunkt /v1/monitors kannst du persistente Monitore erstellen, die nach einem festen Zeitplan laufen, Seitenänderungen erkennen und dich per E-Mail, Webhook oder SMS benachrichtigen.

Erstelle einen Monitor aus einer natürlichen Sprach-query
Führe Überprüfungen mit Zeitplänen in natürlicher Sprache durch
Sende Benachrichtigungen über email, webhook_url oder phone_number (SMS)
Listen, inspizieren, aktualisieren, pausieren, fortsetzen und löschen von Monitoren
Lese Monitor-Schnappschussereignisse aus privaten Schnappschüssen

Standardmäßig erfasst jeder Monitorlauf einen vollständigen Schnappschuss der überwachten Seite — ein vollständiges Bild ihres aktuellen Zustands zu diesem Zeitpunkt. Wenn du möchtest, dass der Monitor nur das Neue oder Geänderte zwischen den Läufen (Deltas) anzeigt, anstatt den vollständigen Zustand, musst du diese Absicht direkt in der query ausdrücken.

Installation

# pip install requests

import requests

Erstelle einen Monitor

Erstelle einen Monitor mit POST /v1/monitors. Der Endpunkt validiert deine Eingabe, stellt den Monitor bereit, erstellt seinen internen Zeitplan und gibt ein aktives Monitorobjekt zurück.

query ist erforderlich. Wenn deine query eine URL enthält, wird sich der Monitor auf diese Eingabe-URL konzentrieren. Standardmäßig nimmt jeder Lauf einen vollständigen Schnappschuss von dem auf, was überwacht wird — ein Bild des aktuellen Zustands der Seite. Wenn du möchtest, dass der Monitor nur das Neue oder Geänderte zwischen den Läufen verfolgt (zum Beispiel nur neue Blogbeiträge oder nur Preisrückgänge), musst du dies ausdrücklich in der query angeben; andernfalls wird bei jedem Lauf der vollständige Schnappschuss erfasst.
frequency akzeptiert Zeitplananweisungen in natürlicher Sprache und verwendet standardmäßig UTC, wenn keine Zeitzone angegeben ist.
Genau ein Benachrichtigungsziel ist erforderlich: email, webhook_url oder phone_number (SMS).
Verwende output_schema, wenn du strukturierte Extraktionsergebnisse möchtest. (optional)

Beispielanfrage

import requests
import json

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

payload = {
    "query": "Track changes in https://example.com/products/widget-pro pricing and stock information",
    "frequency": "every day at 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))

Antwort

Die erfolgreiche Erstellung eines Monitors gibt HTTP 202 mit einem Monitorobjekt zurück:

{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "created_at": 1777983215,
  "updated_at": 1777983222,
  "fda_id": "fda_n8q2x4m1ak",
  "team_id": "team_n8q2x4m1ak",
  "status": "active",
  "query": "Track changes in https://example.com/products/widget-pro pricing and stock information",
  "frequency": "every day at 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"
  }
}

Strukturierte Monitor-Ausgabe

Setze output_schema in der Erstellungsanfrage, wenn du möchtest, dass die Monitor-Extraktionsergebnisse einer bestimmten JSON-Struktur folgen. Das Schema muss ein gültiges JSON-Schema sein.

Benachrichtigungskanäle

Monitore unterstützen einen Kanal pro Monitor:

email: setze ein email-Feld
webhook: setze ein webhook_url-Feld
sms: setze ein phone_number-Feld (E.164-Format, zum Beispiel +14155552671)

Du kannst genau eines dieser Felder pro Anfrage setzen.

Webhook-Beispiel

{
  "query": "Watch for changes in https://example.com/terms legal terms",
  "frequency": "everyday at 10:00 am",
  "webhook_url": "https://hooks.example.com/olostep-monitor"
}

SMS-Beispiel

{
  "query": "Watch for changes in https://example.com/terms legal terms",
  "frequency": "everyday at 10:00 am",
  "phone_number": "+14155552671"
}

Frequenzen

Setze frequency in natürlicher Sprache, zum Beispiel:

every day at 9am America/Los_Angeles
every 5 minutes
every 6 hours

Die API interpretiert diesen Zeitplantext und leitet den Cron-Ausdruck automatisch ab. Wenn keine Zeitzone angegeben ist, wird standardmäßig UTC verwendet.

Monitore auflisten

Rufe alle Monitore für dein Team mit GET /v1/monitors ab. Standardmäßig werden gelöschte Monitore herausgefiltert. Verwende ?include_deleted=true, um sie einzuschließen.

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

Antwortform

{
  "monitors": [
    {
      "id": "monitor_a3yk6z49p8",
      "object": "monitor",
      "created_at": 1777983215,
      "cron_expression": "13 13 * * ? *",
      "fda_id": "fda_a3yk6z49p8",
      "frequency": "daily",
      "metadata": {},
      "notification_channel": "email",
      "notification_target": "example@olostep.com",
      "query": "Gather the new blogposts from example website and send me updates with new posts.",
      "status": "active",
      "team_id": "team_a3yk6z49p8F",
      "updated_at": 1777983222
    }
  ],
  "count": 1
}

Einen Monitor abrufen

Rufe einen einzelnen Monitor mit GET /v1/monitors/:monitor_id ab.

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

Antwortform

{
  "id": "monitor_a3yk6z49p8",
  "object": "monitor",
  "created_at": 1777983215,
  "cron_expression": "13 13 * * ? *",
  "fda_id": "fda_a3yk6z49p8",
  "frequency": "daily",
  "metadata": {},
  "notification_channel": "email",
  "notification_target": "example@olostep.com",
  "query": "Gather the new blogposts from example website and send me updates with new posts.",
  "status": "active",
  "team_id": "team_a3yk6z49p8",
  "updated_at": 1777983222
}

Monitor-Ereignisse auflisten

Verwende GET /v1/monitors/:monitor_id/events, um Schnappschussereignisse für einen Monitor aufzulisten. Dieser Endpunkt unterstützt die Paginierung:

limit (Standard 25, max 100)
cursor (undurchsichtiger Paginierungs-Token aus einer vorherigen Antwort)

Ereignisse werden neueste zuerst zurückgegeben. Jedes Element enthält eine kurzlebige, vorab signierte snapshot_url, damit du private Schnappschussinhalte sicher abrufen kannst.

Beispiel

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

Antwortform

{
  "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
}

Wenn cursor fehlerhaft ist, gibt der Endpunkt zurück:

{
  "error": "Invalid cursor."
}

Einen Monitor aktualisieren

Aktualisiere einen Monitor mit POST /v1/monitors/:monitor_id. Unterstützte Aktualisierungen:

metadata (wird mit vorhandenen Metadaten zusammengeführt; leere Zeichenfolgenwerte übergeben, um Schlüssel zu löschen)
frequency (Zeitplantext in natürlicher Sprache, zum Beispiel every weekday at 08:30 America/New_York)

Wenn du frequency aktualisierst, erstellt die API den Monitor-Zeitplan intern neu. Wenn keine Zeitzone im Text enthalten ist, wird UTC verwendet.

Beispielanfrage

import requests
import json

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

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

Einen Monitor pausieren

Pausiere einen Monitor mit POST /v1/monitors/:monitor_id/pause. Das Pausieren deaktiviert den zugrunde liegenden Zeitplan des Monitors, sodass keine weiteren Läufe ausgelöst werden, und setzt den status des Monitors auf paused. Die Monitorzeile, ihre Konfiguration und ihre vergangenen Schnappschüsse bleiben erhalten — nur zukünftige geplante Ausführungen werden gestoppt. Du kannst den Monitor später mit POST /v1/monitors/:monitor_id/resume fortsetzen. Nur Monitore mit dem status active können pausiert werden. Der Anfragekörper ist leer.

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

Antwort

Bei Erfolg wird 200 mit dem Monitor und status auf paused zurückgegeben:

{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "status": "paused",
  "updated_at": 1777986822,
  "query": "Track changes in https://example.com/products/widget-pro pricing and stock information",
  "frequency": "every day at 9am America/Los_Angeles",
  "notification_channel": "email",
  "notification_target": "alerts@example.com"
}

Mögliche Fehlermeldungen:

400 — monitor_id fehlerhaft, Monitor bereits deleted, Monitor derzeit nicht active, oder Monitor hat keinen zugrunde liegenden Zeitplan.
404 — Monitor nicht gefunden.
409 — Der Monitor hat während des Pausierungsversuchs den Status geändert (nicht mehr active), oder der zugrunde liegende Zeitplan konnte nicht gefunden werden.

Einen Monitor fortsetzen

Setze einen pausierten Monitor mit POST /v1/monitors/:monitor_id/resume fort. Das Fortsetzen aktiviert den zugrunde liegenden Zeitplan des Monitors wieder und setzt den status des Monitors zurück auf active. Geplante Läufe werden mit der bestehenden frequency fortgesetzt — eine Neuerstellung des Zeitplans ist nicht erforderlich. Nur Monitore mit dem status paused können fortgesetzt werden. Der Anfragekörper ist leer.

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

Antwort

Bei Erfolg wird 200 mit dem Monitor und status zurück auf active zurückgegeben:

{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "status": "active",
  "updated_at": 1777990422,
  "query": "Track changes in https://example.com/products/widget-pro pricing and stock information",
  "frequency": "every day at 9am America/Los_Angeles",
  "notification_channel": "email",
  "notification_target": "alerts@example.com"
}

Mögliche Fehlermeldungen:

400 — monitor_id fehlerhaft, Monitor bereits deleted, Monitor derzeit nicht paused, oder Monitor hat keinen zugrunde liegenden Zeitplan.
404 — Monitor nicht gefunden.
409 — Der Monitor hat während des Fortsetzungsversuchs den Status geändert (nicht mehr paused), oder der zugrunde liegende Zeitplan konnte nicht gefunden werden.

Einen Monitor löschen

Lösche einen Monitor mit DELETE /v1/monitors/:monitor_id. Die Löschung ist soft für die Monitorzeile (status wird deleted) und entfernt auch interne Planungs-/Schatten-Agent-Ressourcen, die mit diesem Monitor verbunden sind.

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

Beispielanwendungen

Nachfolgend sind praktische Beispielanfragen für den /v1/monitors-Endpunkt aufgeführt.

Verfolge Betriebszeitprobleme in der OpenAI API

Führe eine stündliche Überprüfung durch, die den Status der OpenAI API überwacht und dich per E-Mail benachrichtigt, wenn Betriebszeitprobleme erkannt werden.

import requests
import json

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

payload = {
    "query": "Track uptime issues in OpenAI API and email me at info@olostep.com",
    "frequency": "every hour",
    "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))

Produktbewertungen verfolgen — vollständiger Schnappschuss pro Lauf

Überwache eine Produktseite und sende bei jedem Lauf jede Bewertung an einen Webhook. Da die query nicht verlangt, dass gegen vorherige Läufe dedupliziert wird, erfasst jeder Lauf einen vollständigen Schnappschuss der aktuell auf der Seite befindlichen Bewertungen (das Standardverhalten). Verwende dieses Muster, wenn du jedes Mal den vollständigen Zustand möchtest, zum Beispiel um eine nachgelagerte Tabelle zu überschreiben.

import requests
import json

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

payload = {
    "query": "Monitor the reviews of this product https://www.walmart.com/reviews/product/957245477?sort=submission-desc and notify me by webhook. For each review extract the publication date, author, rating, title, and text content.",
    "frequency": "everyday at 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))

Nur neue Mietangebote verfolgen — Delta vom vorherigen Lauf

Überwache eine paginierte Mietsuche und führe eine mehrstufige Pipeline aus, die nur neu erschienene Angebote im Vergleich zum vorherigen Lauf anzeigt, dann jedes einzelne anreichert und bewertet, bevor der Webhook benachrichtigt wird. Der vollständige Workflow — paginieren, neue Angebote im Vergleich zum vorherigen Kontrollpunkt erkennen, jedes neue Angebot mit Kriminalitätssignalen für seinen Standort anreichern, eine 1-10-Bewertung basierend auf Preis/Standort/Sicherheit zuweisen, Zustand speichern und benachrichtigen — wird direkt als geordnete Schritte in der query ausgedrückt. Da die Schritte in natürlicher Sprache sowohl die Extraktion als auch die Delta-Logik beschreiben, ist kein output_schema erforderlich: die query allein bestimmt, was abgerufen, verglichen, angereichert, bewertet und geliefert wird.

import requests
import json

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

payload = {
    "query": "Monitor the first 3 pages of https://streeteasy.com/for-rent/new-jersey/price:1000-1750?sort_by=listed_desc, detect only newly appeared listings versus the previous checkpoint, enrich each new listing with crime signals for its location, assign a 1-10 overall score based on price/location/safety, persist state, and notify via webhook.",
    "frequency": "every hour",
    "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))

Häufige Validierungsfehler

Die Monitor-Endpunkte geben klare Validierungsfehler für häufige ungültige Anfragen zurück:

Fehlende query
Fehlende frequency oder ungültige Zeitplananweisung
Fehlen aller email, webhook_url und phone_number
Mehr als eine von email, webhook_url und phone_number in derselben Anfrage angeben
Ungültiges E-Mail-Format
Ungültige Webhook-URL (muss http oder https sein)
Ungültiges Telefonnummernformat (muss E.164 sein, zum Beispiel +14155552671)
Ungültiges output_schema (muss ein gültiges JSON-Schema sein)
Ungültiges monitor_id-Format

Beispiel für einen Fehler:

{
  "error": "Invalid frequency. Provide a natural-language schedule instruction."
}

Loslegen

Funktionen

Integrationen

Installation

Erstelle einen Monitor

Beispielanfrage

Antwort

Strukturierte Monitor-Ausgabe

Benachrichtigungskanäle

Webhook-Beispiel

SMS-Beispiel

Frequenzen

Monitore auflisten

Antwortform

Einen Monitor abrufen

Antwortform

Monitor-Ereignisse auflisten

Beispiel

Antwortform

Einen Monitor aktualisieren

Beispielanfrage

Einen Monitor pausieren

Antwort

Einen Monitor fortsetzen

Antwort

Einen Monitor löschen

Beispielanwendungen

Verfolge Betriebszeitprobleme in der OpenAI API

Produktbewertungen verfolgen — vollständiger Schnappschuss pro Lauf

Nur neue Mietangebote verfolgen — Delta vom vorherigen Lauf

Häufige Validierungsfehler

Loslegen

Funktionen

Integrationen

Documentation Index

​Installation

​Erstelle einen Monitor

​Beispielanfrage

​Antwort

​Strukturierte Monitor-Ausgabe

​Benachrichtigungskanäle

​Webhook-Beispiel

​SMS-Beispiel

​Frequenzen

​Monitore auflisten

​Antwortform

​Einen Monitor abrufen

​Antwortform

​Monitor-Ereignisse auflisten

​Beispiel

​Antwortform

​Einen Monitor aktualisieren

​Beispielanfrage

​Einen Monitor pausieren

​Antwort

​Einen Monitor fortsetzen

​Antwort

​Einen Monitor löschen

​Beispielanwendungen

​Verfolge Betriebszeitprobleme in der OpenAI API

​Produktbewertungen verfolgen — vollständiger Schnappschuss pro Lauf

​Nur neue Mietangebote verfolgen — Delta vom vorherigen Lauf

​Häufige Validierungsfehler

Installation

Erstelle einen Monitor

Beispielanfrage

Antwort

Strukturierte Monitor-Ausgabe

Benachrichtigungskanäle

Webhook-Beispiel

SMS-Beispiel

Frequenzen

Monitore auflisten

Antwortform

Einen Monitor abrufen

Antwortform

Monitor-Ereignisse auflisten

Beispiel

Antwortform

Einen Monitor aktualisieren

Beispielanfrage

Einen Monitor pausieren

Antwort

Einen Monitor fortsetzen

Antwort

Einen Monitor löschen

Beispielanwendungen

Verfolge Betriebszeitprobleme in der OpenAI API

Produktbewertungen verfolgen — vollständiger Schnappschuss pro Lauf

Nur neue Mietangebote verfolgen — Delta vom vorherigen Lauf

Häufige Validierungsfehler