Vai al contenuto principale

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.

Attraverso l’endpoint Olostep /v1/monitors puoi creare monitor persistenti che funzionano secondo un programma fisso, rilevano modifiche alle pagine e ti notificano via email, webhook o SMS.
  • Crea un monitor da una query in linguaggio naturale
  • Esegui controlli utilizzando programmi in linguaggio naturale
  • Invia avvisi tramite email, webhook_url o phone_number (SMS)
  • Elenca, ispeziona, aggiorna, metti in pausa, riprendi e elimina monitor
  • Leggi eventi snapshot del monitor da snapshot privati
Per impostazione predefinita, ogni esecuzione del monitor cattura un snapshot completo della pagina monitorata — un’immagine completa del suo stato attuale in quel momento. Se vuoi che il monitor mostri solo ciò che è nuovo o cambiato tra le esecuzioni (delta) invece dello stato completo, devi esprimere tale intento direttamente nella query.

​
Installazione

# pip install requests

import requests

​
Crea un monitor

Crea un monitor con POST /v1/monitors. L’endpoint convalida il tuo input, fornisce il monitor, crea il suo programma interno e restituisce un oggetto monitor attivo.
  • query è obbligatoria. Se la tua query include un URL, il monitor si concentrerà su quell’URL di input. Per impostazione predefinita, ogni esecuzione prende un’istantanea completa di ciò che viene monitorato — un’immagine dello stato attuale della pagina. Se vuoi che il monitor tracci solo ciò che è nuovo o cambiato tra le esecuzioni (ad esempio, solo nuovi post sul blog, o solo cali di prezzo), devi specificarlo esplicitamente nella query; altrimenti viene catturata l’istantanea completa ad ogni esecuzione.
  • frequency accetta istruzioni di programma in linguaggio naturale e predefinisce UTC quando non viene fornito alcun fuso orario.
  • È richiesto esattamente un obiettivo di notifica: email, webhook_url o phone_number (SMS).
  • Usa output_schema quando vuoi risultati di estrazione strutturati. (opzionale)

​
Esempio di richiesta

import requests
import json

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

payload = {
    "query": "Traccia le modifiche su https://example.com/products/widget-pro per informazioni sui prezzi e sulle scorte",
    "frequency": "ogni giorno alle 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))

​
Risposta

La creazione del monitor avvenuta con successo restituisce HTTP 202 con un oggetto monitor: 
{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "created_at": 1777983215,
  "updated_at": 1777983222,
  "fda_id": "fda_n8q2x4m1ak",
  "team_id": "team_n8q2x4m1ak",
  "status": "active",
  "query": "Traccia le modifiche su https://example.com/products/widget-pro per informazioni sui prezzi e sulle scorte",
  "frequency": "ogni giorno alle 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"
  }
}

​
Output strutturato del monitor

Imposta output_schema nella richiesta di creazione quando vuoi che i risultati di estrazione del monitor seguano una struttura JSON specifica. Lo schema deve essere un JSON Schema valido.

​
Canali di notifica

I monitor supportano un canale per monitor:
  • email: imposta un campo email
  • webhook: imposta un campo webhook_url
  • sms: imposta un campo phone_number (formato E.164, ad esempio +14155552671)
Puoi impostare esattamente uno di questi campi per richiesta.

​
Esempio di Webhook

{
  "query": "Osserva le modifiche su https://example.com/terms termini legali",
  "frequency": "ogni giorno alle 10:00 am",
  "webhook_url": "https://hooks.example.com/olostep-monitor"
}

​
Esempio di SMS

{
  "query": "Osserva le modifiche su https://example.com/terms termini legali",
  "frequency": "ogni giorno alle 10:00 am",
  "phone_number": "+14155552671"
}

​
Frequenze

Imposta frequency in linguaggio naturale, ad esempio:
  • ogni giorno alle 9am America/Los_Angeles
  • ogni 5 minuti
  • ogni 6 ore
L’API interpreta questo testo di programmazione e deriva automaticamente l’espressione cron. Se non viene fornito alcun fuso orario, viene utilizzato UTC per impostazione predefinita.

​
Elenca i monitor

Recupera tutti i monitor per il tuo team con GET /v1/monitors. Per impostazione predefinita, i monitor eliminati sono filtrati. Usa ?include_deleted=true per includerli. 
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))

​
Forma della risposta

{
  "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": "Raccogli i nuovi post del blog dal sito web di esempio e inviami aggiornamenti con i nuovi post.",
      "status": "active",
      "team_id": "team_a3yk6z49p8F",
      "updated_at": 1777983222
    }
  ],
  "count": 1
}

​
Ottieni un monitor

Recupera un singolo 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))

​
Forma della risposta

{
  "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": "Raccogli i nuovi post del blog dal sito web di esempio e inviami aggiornamenti con i nuovi post.",
  "status": "active",
  "team_id": "team_a3yk6z49p8",
  "updated_at": 1777983222
}

​
Elenca gli eventi del monitor

Usa GET /v1/monitors/:monitor_id/events per elencare gli eventi snapshot per un monitor. Questo endpoint supporta la paginazione:
  • limit (predefinito 25, max 100)
  • cursor (token di paginazione opaco da una risposta precedente)
Gli eventi vengono restituiti dal più recente. Ogni elemento include un snapshot_url pre-firmato a breve durata per consentirti di recuperare in modo sicuro il contenuto dello snapshot privato.

​
Esempio

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

​
Forma della risposta

{
  "data": [
    {
      "id": "run_v7k2p9m3",
      "run_id": "run_v7k2p9m3",
      "created": 1777960800,
      "changed": true,
      "summary": "Il prezzo è cambiato da $49 a $45 e la disponibilità è passata a bassa.",
      "snapshot_url": "https://olostep-monitor-snapshot.s3.amazonaws.com/private/key?...signature..."
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Se cursor è malformato, l’endpoint restituisce: 
{
  "error": "Invalid cursor."
}

​
Aggiorna un monitor

Aggiorna un monitor con POST /v1/monitors/:monitor_id. Aggiornamenti supportati:
  • metadata (unito ai metadati esistenti; passa valori stringa vuoti per eliminare le chiavi)
  • frequency (testo di programmazione in linguaggio naturale, ad esempio ogni giorno feriale alle 08:30 America/New_York)
Se aggiorni frequency, l’API ricrea internamente il programma del monitor. Se non è incluso alcun fuso orario nel testo, viene utilizzato UTC.

​
Esempio di richiesta

import requests
import json

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

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

​
Metti in pausa un monitor

Metti in pausa un monitor con POST /v1/monitors/:monitor_id/pause. Mettere in pausa disabilita il programma sottostante del monitor in modo che non vengano attivate ulteriori esecuzioni, e imposta lo status del monitor su paused. La riga del monitor, la sua configurazione e i suoi snapshot passati vengono mantenuti — solo le esecuzioni programmate future si fermano. Puoi riprendere il monitor successivamente con POST /v1/monitors/:monitor_id/resume. Solo i monitor con status di active possono essere messi in pausa. Il corpo della richiesta è vuoto. 
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))

​
Risposta

In caso di successo, restituisce 200 con il monitor e status impostato su paused: 
{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "status": "paused",
  "updated_at": 1777986822,
  "query": "Traccia le modifiche su https://example.com/products/widget-pro per informazioni sui prezzi e sulle scorte",
  "frequency": "ogni giorno alle 9am America/Los_Angeles",
  "notification_channel": "email",
  "notification_target": "alerts@example.com"
}
Possibili risposte di errore:
  • 400 — monitor_id malformato, monitor già deleted, monitor non attualmente active, o monitor non ha un programma sottostante.
  • 404 — Monitor non trovato.
  • 409 — Il monitor ha cambiato stato durante il tentativo di pausa (non più active), o il programma sottostante non è stato trovato.

​
Riprendi un monitor

Riprendi un monitor in pausa con POST /v1/monitors/:monitor_id/resume. Riprendere riabilita il programma sottostante del monitor e imposta lo status del monitor di nuovo su active. Le esecuzioni programmate continuano sulla frequency esistente — non è necessaria la ricreazione del programma. Solo i monitor con status di paused possono essere ripresi. Il corpo della richiesta è vuoto. 
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))

​
Risposta

In caso di successo, restituisce 200 con il monitor e status impostato di nuovo su active: 
{
  "id": "monitor_n8q2x4m1ak",
  "object": "monitor",
  "status": "active",
  "updated_at": 1777990422,
  "query": "Traccia le modifiche su https://example.com/products/widget-pro per informazioni sui prezzi e sulle scorte",
  "frequency": "ogni giorno alle 9am America/Los_Angeles",
  "notification_channel": "email",
  "notification_target": "alerts@example.com"
}
Possibili risposte di errore:
  • 400 — monitor_id malformato, monitor già deleted, monitor non attualmente paused, o monitor non ha un programma sottostante.
  • 404 — Monitor non trovato.
  • 409 — Il monitor ha cambiato stato durante il tentativo di ripresa (non più paused), o il programma sottostante non è stato trovato.

​
Elimina un monitor

Elimina un monitor con DELETE /v1/monitors/:monitor_id. L’eliminazione è soft per la riga del monitor (status diventa deleted) e rimuove anche le risorse di programmazione/agent-ombra interne legate a quel 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))

​
Esempi di casi d’uso

Di seguito sono riportati esempi pratici di richieste per l’endpoint /v1/monitors.

​
Traccia problemi di uptime nell’API OpenAI

Esegui un controllo orario che osserva lo stato dell’API OpenAI e ti invia un’email quando vengono rilevati problemi di uptime. 
import requests
import json

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

payload = {
    "query": "Traccia problemi di uptime nell'API OpenAI e inviami un'email a info@olostep.com",
    "frequency": "ogni ora",
    "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))

​
Traccia recensioni di prodotti — snapshot completo per esecuzione

Monitora una pagina di prodotto e invia ogni recensione a un webhook ad ogni esecuzione. Poiché la query non chiede di deduplicare rispetto alle esecuzioni precedenti, ogni esecuzione cattura un snapshot completo delle recensioni attualmente sulla pagina (comportamento predefinito). Usa questo schema quando vuoi lo stato completo ogni volta, ad esempio per sovrascrivere una tabella a valle. 
import requests
import json

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

payload = {
    "query": "Monitora le recensioni di questo prodotto https://www.walmart.com/reviews/product/957245477?sort=submission-desc e notificami tramite webhook. Per ogni recensione estrai la data di pubblicazione, l'autore, il voto, il titolo e il contenuto del testo.",
    "frequency": "ogni giorno alle 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))

​
Traccia solo i nuovi annunci di affitto — delta dall’esecuzione precedente

Monitora una ricerca di affitti paginata ed esegui una pipeline multi-step che mostra solo gli annunci appena apparsi rispetto all’esecuzione precedente, quindi arricchisce e valuta ciascuno prima di notificare il webhook. L’intero workflow — paginazione, rilevamento di nuovi annunci rispetto al checkpoint precedente, arricchimento di ciascun nuovo annuncio con segnali di criminalità per la sua posizione, assegnazione di un punteggio complessivo da 1 a 10 basato su prezzo/posizione/sicurezza, persistenza dello stato e notifica — è espresso direttamente come passaggi ordinati nella query. Poiché i passaggi in linguaggio naturale descrivono sia l’estrazione che la logica delta, non è richiesto alcun output_schema: la query da sola determina cosa viene recuperato, confrontato, arricchito, valutato e consegnato. 
import requests
import json

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

payload = {
    "query": "Monitora le prime 3 pagine di https://streeteasy.com/for-rent/new-jersey/price:1000-1750?sort_by=listed_desc, rileva solo gli annunci appena apparsi rispetto al checkpoint precedente, arricchisci ciascun nuovo annuncio con segnali di criminalità per la sua posizione, assegna un punteggio complessivo da 1 a 10 basato su prezzo/posizione/sicurezza, persisti lo stato e notifica tramite webhook.",
    "frequency": "ogni ora",
    "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))

​
Errori comuni di validazione

Gli endpoint del monitor restituiscono errori di validazione chiari per richieste non valide comuni:
  • query mancante
  • frequency mancante, o istruzione di programma non valida
  • Mancanza di tutti email, webhook_url e phone_number
  • Fornire più di uno tra email, webhook_url e phone_number nella stessa richiesta
  • Formato email non valido
  • URL webhook non valido (deve essere http o https)
  • Formato numero di telefono non valido (deve essere E.164, ad esempio +14155552671)
  • output_schema non valido (deve essere un JSON Schema valido)
  • Formato monitor_id non valido
Esempio di errore: 
{
  "error": "Invalid frequency. Provide a natural-language schedule instruction."
}