Moniteurs

Grâce à l’endpoint Olostep /v1/monitors, tu peux créer des moniteurs persistants qui s’exécutent selon un calendrier fixe, détectent les changements de page et te notifient par email, webhook ou SMS.

Crée un moniteur à partir d’une query en langage naturel
Exécute des vérifications en utilisant des calendriers en langage naturel
Envoie des alertes via email, webhook_url ou phone_number (SMS)
Liste, inspecte, mets à jour, mets en pause, reprends et supprime des moniteurs
Lis les événements de snapshot de moniteur à partir de snapshots privés

Par défaut, chaque exécution de moniteur capture un snapshot complet de la page surveillée — une image complète de son état actuel à ce moment-là. Si tu veux que le moniteur ne fasse ressortir que ce qui est nouveau ou a changé entre les exécutions (deltas) au lieu de l’état complet, tu dois exprimer cette intention directement dans la query.

Installation

# pip install requests

import requests

Créer un moniteur

Crée un moniteur avec POST /v1/monitors. L’endpoint valide ton entrée, provisionne le moniteur, crée son calendrier interne et renvoie un objet moniteur actif.

query est requis. Si ta query inclut une URL, le moniteur se concentrera sur cette URL d’entrée. Par défaut, chaque exécution prend un snapshot complet de ce qui est surveillé — une image de l’état actuel de la page. Si tu veux que le moniteur ne suive que ce qui est nouveau ou a changé entre les exécutions (par exemple, seulement les nouveaux articles de blog, ou seulement les baisses de prix), tu dois le spécifier explicitement dans la query; sinon, le snapshot complet est capturé à chaque exécution.
frequency accepte des instructions de calendrier en langage naturel et par défaut utilise UTC lorsqu’aucun fuseau horaire n’est fourni.
Un seul objectif de notification est requis : email, webhook_url ou phone_number (SMS).
Utilise output_schema lorsque tu veux des résultats d’extraction structurés. (optionnel)

Exemple de requête

import requests
import json

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

payload = {
    "query": "Suivre les changements de prix et d'informations de stock sur https://example.com/products/widget-pro",
    "frequency": "tous les jours à 9h 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))

Réponse

La création réussie d’un moniteur renvoie HTTP 202 avec un objet moniteur :

{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "created_at": 1777983215,
  "updated_at": 1777983222,
  "fda_id": "fda_n8q2x4m1ak",
  "team_id": "team_n8q2x4m1ak",
  "status": "active",
  "query": "Suivre les changements de prix et d'informations de stock sur https://example.com/products/widget-pro",
  "frequency": "tous les jours à 9h 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"
  }
}

Sortie structurée du moniteur

Définis output_schema dans la requête de création lorsque tu veux que les résultats d’extraction du moniteur suivent une structure JSON spécifique. Le schéma doit être un JSON Schema valide.

Canaux de notification

Les moniteurs prennent en charge un canal par moniteur :

email : définis un champ email
webhook : définis un champ webhook_url
sms : définis un champ phone_number (format E.164, par exemple +14155552671)

Tu peux définir exactement un de ces champs par requête.

Exemple de webhook

{
  "query": "Surveiller les changements dans les termes légaux de https://example.com/terms",
  "frequency": "tous les jours à 10:00",
  "webhook_url": "https://hooks.example.com/olostep-monitor"
}

Exemple de SMS

{
  "query": "Surveiller les changements dans les termes légaux de https://example.com/terms",
  "frequency": "tous les jours à 10:00",
  "phone_number": "+14155552671"
}

Fréquences

Définis frequency en langage naturel, par exemple :

tous les jours à 9h America/Los_Angeles
toutes les 5 minutes
toutes les 6 heures

L’API interprète ce texte de calendrier et dérive automatiquement l’expression cron. Si aucun fuseau horaire n’est fourni, UTC est utilisé par défaut.

Lister les moniteurs

Récupère tous les moniteurs pour ton équipe avec GET /v1/monitors. Par défaut, les moniteurs supprimés sont filtrés. Utilise ?include_deleted=true pour les inclure.

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

Forme de la réponse

{
  "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": "Récupérer les nouveaux articles de blog du site exemple et m'envoyer des mises à jour avec les nouveaux articles.",
      "status": "active",
      "team_id": "team_a3yk6z49p8F",
      "updated_at": 1777983222
    }
  ],
  "count": 1
}

Obtenir un moniteur

Récupère un moniteur unique avec 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))

Forme de la réponse

{
  "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": "Récupérer les nouveaux articles de blog du site exemple et m'envoyer des mises à jour avec les nouveaux articles.",
  "status": "active",
  "team_id": "team_a3yk6z49p8",
  "updated_at": 1777983222
}

Lister les événements de moniteur

Utilise GET /v1/monitors/:monitor_id/events pour lister les événements de snapshot pour un moniteur. Cet endpoint prend en charge la pagination :

limit (par défaut 25, max 100)
cursor (jeton de pagination opaque d’une réponse précédente)

Les événements sont renvoyés du plus récent au plus ancien. Chaque élément inclut une snapshot_url pré-signée à durée de vie limitée pour que tu puisses récupérer le contenu du snapshot privé en toute sécurité.

Exemple

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

Forme de la réponse

{
  "data": [
    {
      "id": "run_v7k2p9m3",
      "run_id": "run_v7k2p9m3",
      "created": 1777960800,
      "changed": true,
      "summary": "Le prix est passé de 49 $ à 45 $ et le stock est passé à faible disponibilité.",
      "snapshot_url": "https://olostep-monitor-snapshot.s3.amazonaws.com/private/key?...signature..."
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Si cursor est mal formé, l’endpoint renvoie :

{
  "error": "Invalid cursor."
}

Mettre à jour un moniteur

Mets à jour un moniteur avec POST /v1/monitors/:monitor_id. Mises à jour prises en charge :

metadata (fusionné avec les métadonnées existantes ; passe des valeurs de chaîne vide pour supprimer des clés)
frequency (texte de calendrier en langage naturel, par exemple chaque jour de la semaine à 08:30 America/New_York)

Si tu mets à jour frequency, l’API recrée le calendrier du moniteur en interne. Si aucun fuseau horaire n’est inclus dans le texte, UTC est utilisé.

Exemple de requête

import requests
import json

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

payload = {
    "frequency": "toutes les 2 heures",
    "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))

Mettre en pause un moniteur

Mets en pause un moniteur avec POST /v1/monitors/:monitor_id/pause. La mise en pause désactive le calendrier sous-jacent du moniteur afin qu’aucune exécution future ne soit déclenchée, et met le status du moniteur à paused. La ligne du moniteur, sa configuration et ses snapshots passés sont conservés — seules les exécutions planifiées futures s’arrêtent. Tu peux reprendre le moniteur plus tard avec POST /v1/monitors/:monitor_id/resume. Seuls les moniteurs avec un status de active peuvent être mis en pause. Le corps de la requête est vide.

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

Réponse

En cas de succès, renvoie 200 avec le moniteur et status mis à paused :

{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "status": "paused",
  "updated_at": 1777986822,
  "query": "Suivre les changements de prix et d'informations de stock sur https://example.com/products/widget-pro",
  "frequency": "tous les jours à 9h America/Los_Angeles",
  "notification_channel": "email",
  "notification_target": "alerts@example.com"
}

Réponses d’erreur possibles :

400 — monitor_id mal formé, moniteur déjà deleted, moniteur pas actuellement active, ou moniteur n’a pas de calendrier sous-jacent.
404 — Moniteur non trouvé.
409 — Le moniteur a changé d’état pendant la tentative de pause (n’est plus active), ou le calendrier sous-jacent n’a pas pu être trouvé.

Reprendre un moniteur

Reprends un moniteur en pause avec POST /v1/monitors/:monitor_id/resume. La reprise réactive le calendrier sous-jacent du moniteur et remet le status du moniteur à active. Les exécutions planifiées continuent sur la frequency existante — aucune recréation du calendrier n’est nécessaire. Seuls les moniteurs avec un status de paused peuvent être repris. Le corps de la requête est vide.

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

Réponse

En cas de succès, renvoie 200 avec le moniteur et status remis à active :

{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "status": "active",
  "updated_at": 1777990422,
  "query": "Suivre les changements de prix et d'informations de stock sur https://example.com/products/widget-pro",
  "frequency": "tous les jours à 9h America/Los_Angeles",
  "notification_channel": "email",
  "notification_target": "alerts@example.com"
}

Réponses d’erreur possibles :

400 — monitor_id mal formé, moniteur déjà deleted, moniteur pas actuellement paused, ou moniteur n’a pas de calendrier sous-jacent.
404 — Moniteur non trouvé.
409 — Le moniteur a changé d’état pendant la tentative de reprise (n’est plus paused), ou le calendrier sous-jacent n’a pas pu être trouvé.

Supprimer un moniteur

Supprime un moniteur avec DELETE /v1/monitors/:monitor_id. La suppression est douce pour la ligne du moniteur (status devient deleted) et supprime également les ressources de planification/agent fantôme internes liées à ce moniteur.

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

Exemples d’utilisation

Ci-dessous des exemples pratiques de requêtes pour l’endpoint /v1/monitors.

Suivre les problèmes de disponibilité dans l’API OpenAI

Exécute une vérification horaire qui surveille le statut de l’API OpenAI et t’envoie un email lorsque des problèmes de disponibilité sont détectés.

import requests
import json

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

payload = {
    "query": "Suivre les problèmes de disponibilité dans l'API OpenAI et m'envoyer un email à info@olostep.com",
    "frequency": "toutes les heures",
    "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))

Suivre les avis sur les produits — snapshot complet par exécution

Surveille une page produit et envoie chaque avis à un webhook à chaque exécution. Comme la query ne demande pas de dédupliquer par rapport aux exécutions précédentes, chaque exécution capture un snapshot complet des avis actuellement sur la page (le comportement par défaut). Utilise ce modèle lorsque tu veux l’état complet à chaque fois, par exemple pour écraser une table en aval.

import requests
import json

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

payload = {
    "query": "Surveiller les avis de ce produit https://www.walmart.com/reviews/product/957245477?sort=submission-desc et me notifier par webhook. Pour chaque avis, extraire la date de publication, l'auteur, la note, le titre et le contenu du texte.",
    "frequency": "tous les jours à 9h",
    "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))

Suivre uniquement les nouvelles annonces de location — delta par rapport à l’exécution précédente

Surveille une recherche de locations paginée et exécute un pipeline multi-étapes qui fait ressortir uniquement les annonces nouvellement apparues par rapport à l’exécution précédente, puis enrichit et évalue chacune avant de notifier le webhook. Le workflow complet — paginer, détecter les nouvelles annonces par rapport au point de contrôle précédent, enrichir chaque nouvelle annonce avec des signaux de criminalité pour son emplacement, attribuer un score de 1 à 10 basé sur le prix/l’emplacement/la sécurité, persister l’état, et notifier — est exprimé directement comme étapes ordonnées dans la query. Comme les étapes en langage naturel décrivent à la fois l’extraction et la logique de delta, aucun output_schema n’est requis : la query seule détermine ce qui est récupéré, comparé, enrichi, évalué et livré.

import requests
import json

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

payload = {
    "query": "Surveille les 3 premières pages de https://streeteasy.com/for-rent/new-jersey/price:1000-1750?sort_by=listed_desc, détecte uniquement les annonces nouvellement apparues par rapport au point de contrôle précédent, enrichit chaque nouvelle annonce avec des signaux de criminalité pour son emplacement, attribue un score global de 1 à 10 basé sur le prix/l'emplacement/la sécurité, persiste l'état, et notifie via webhook.",
    "frequency": "toutes les heures",
    "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))

Erreurs de validation courantes

Les endpoints de moniteur renvoient des erreurs de validation claires pour les requêtes invalides courantes :

query manquante
frequency manquante, ou instruction de calendrier invalide
Absence de tous email, webhook_url et phone_number
Fournir plus d’un email, webhook_url et phone_number dans la même requête
Format d’email invalide
URL de webhook invalide (doit être http ou https)
Format de numéro de téléphone invalide (doit être E.164, par exemple +14155552671)
output_schema invalide (doit être un JSON Schema valide)
Format de monitor_id invalide

Exemple d’erreur :

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

Commencer

Fonctionnalités

Intégrations

Installation

Créer un moniteur

Exemple de requête

Réponse

Sortie structurée du moniteur

Canaux de notification

Exemple de webhook

Exemple de SMS

Fréquences

Lister les moniteurs

Forme de la réponse

Obtenir un moniteur

Forme de la réponse

Lister les événements de moniteur

Exemple

Forme de la réponse

Mettre à jour un moniteur

Exemple de requête

Mettre en pause un moniteur

Réponse

Reprendre un moniteur

Réponse

Supprimer un moniteur

Exemples d’utilisation

Suivre les problèmes de disponibilité dans l’API OpenAI

Suivre les avis sur les produits — snapshot complet par exécution

Suivre uniquement les nouvelles annonces de location — delta par rapport à l’exécution précédente

Erreurs de validation courantes

Commencer

Fonctionnalités

Intégrations

Documentation Index

​Installation

​Créer un moniteur

​Exemple de requête

​Réponse

​Sortie structurée du moniteur

​Canaux de notification

​Exemple de webhook

​Exemple de SMS

​Fréquences

​Lister les moniteurs

​Forme de la réponse

​Obtenir un moniteur

​Forme de la réponse

​Lister les événements de moniteur

​Exemple

​Forme de la réponse

​Mettre à jour un moniteur

​Exemple de requête

​Mettre en pause un moniteur

​Réponse

​Reprendre un moniteur

​Réponse

​Supprimer un moniteur

​Exemples d’utilisation

​Suivre les problèmes de disponibilité dans l’API OpenAI

​Suivre les avis sur les produits — snapshot complet par exécution

​Suivre uniquement les nouvelles annonces de location — delta par rapport à l’exécution précédente

​Erreurs de validation courantes

Installation

Créer un moniteur

Exemple de requête

Réponse

Sortie structurée du moniteur

Canaux de notification

Exemple de webhook

Exemple de SMS

Fréquences

Lister les moniteurs

Forme de la réponse

Obtenir un moniteur

Forme de la réponse

Lister les événements de moniteur

Exemple

Forme de la réponse

Mettre à jour un moniteur

Exemple de requête

Mettre en pause un moniteur

Réponse

Reprendre un moniteur

Réponse

Supprimer un moniteur

Exemples d’utilisation

Suivre les problèmes de disponibilité dans l’API OpenAI

Suivre les avis sur les produits — snapshot complet par exécution

Suivre uniquement les nouvelles annonces de location — delta par rapport à l’exécution précédente

Erreurs de validation courantes