メインコンテンツへスキップ

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.

Olostepの/v1/monitorsエンドポイントを通じて、固定スケジュールで動作し、ページの変更を検出し、メール、Webhook、またはSMSで通知する永続的なモニターを作成できます。
  • 自然言語のqueryからモニターを作成
  • 自然言語スケジュールを使用してチェックを実行
  • email、webhook_url、またはphone_number（SMS）でアラートを配信
  • モニターの一覧表示、検査、更新、一時停止、再開、削除
  • プライベートスナップショットからモニタースナップショットイベントを読み取る
デフォルトでは、各モニター実行は監視対象ページの完全なスナップショットをキャプチャします。これは、その時点でのページの現在の状態を完全に示すものです。モニターが実行間で新しいものや変更されたもの（デルタ）のみを表示するようにしたい場合は、その意図をqueryで直接表現する必要があります。

​
インストール

# pip install requests

import requests

​
モニターを作成

POST /v1/monitorsでモニターを作成します。このエンドポイントは入力を検証し、モニターを準備し、その内部スケジュールを作成し、アクティブなモニターオブジェクトを返します。
  • queryは必須です。queryにURLが含まれている場合、モニターはその入力URLに焦点を当てます。デフォルトでは、各実行で監視対象の完全なスナップショットが撮られます。実行間で新しいものや変更されたもの（例えば、新しいブログ投稿のみ、または価格の下落のみ）を追跡したい場合は、それをqueryで明示的に指定する必要があります。そうでない場合、各実行で完全なスナップショットがキャプチャされます。
  • frequencyは自然言語のスケジュール指示を受け入れ、タイムゾーンが提供されない場合はUTCがデフォルトです。
  • 正確に1つの通知ターゲットが必要です：email、webhook_url、またはphone_number（SMS）。
  • 構造化された抽出結果が必要な場合はoutput_schemaを使用します。（オプション）

​
リクエスト例

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

​
レスポンス

モニターの作成が成功すると、HTTP 202とモニターオブジェクトが返されます： 
{
  "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"
  }
}

​
構造化モニター出力

モニター抽出結果を特定のJSON構造に従わせたい場合は、作成リクエストでoutput_schemaを設定します。スキーマは有効なJSON Schemaでなければなりません。

​
通知チャネル

モニターはモニターごとに1つのチャネルをサポートします：
  • email: emailフィールドを設定
  • webhook: webhook_urlフィールドを設定
  • sms: phone_numberフィールドを設定（E.164形式、例：+14155552671）
リクエストごとにこれらのフィールドのうち1つだけを設定できます。

​
Webhookの例

{
  "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の例

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

​
周期

frequencyを自然言語で設定します。例えば：
  • every day at 9am America/Los_Angeles
  • every 5 minutes
  • every 6 hours
APIはこのスケジュールテキストを解釈し、自動的にcron式を導出します。タイムゾーンが提供されない場合、デフォルトでUTCが使用されます。

​
モニターの一覧表示

GET /v1/monitorsでチームのすべてのモニターを取得します。 デフォルトでは、削除されたモニターはフィルタリングされます。?include_deleted=trueを使用してそれらを含めます。 
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))

​
レスポンスの形状

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

​
モニターを取得

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

​
レスポンスの形状

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

​
モニターイベントの一覧表示

GET /v1/monitors/:monitor_id/eventsを使用して、モニターのスナップショットイベントを一覧表示します。 このエンドポイントはページネーションをサポートします：
  • limit（デフォルト25、最大100）
  • cursor（前のレスポンスからの不透明なページネーショントークン）
イベントは新しいものから順に返されます。各アイテムには短期間有効な署名付きsnapshot_urlが含まれており、プライベートスナップショットコンテンツを安全に取得できます。

​
例

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

​
レスポンスの形状

{
  "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
}
cursorが不正な場合、エンドポイントは以下を返します： 
{
  "error": "Invalid cursor."
}

​
モニターを更新

POST /v1/monitors/:monitor_idでモニターを更新します。 サポートされている更新：
  • metadata（既存のメタデータとマージ；空の文字列値を渡してキーを削除）
  • frequency（自然言語のスケジュールテキスト、例：every weekday at 08:30 America/New_York）
frequencyを更新すると、APIは内部的にモニタースケジュールを再作成します。テキストにタイムゾーンが含まれていない場合、UTCが使用されます。

​
リクエスト例

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

​
モニターを一時停止

POST /v1/monitors/:monitor_id/pauseでモニターを一時停止します。 一時停止すると、モニターの基礎となるスケジュールが無効になり、モニターのstatusがpausedに設定されます。モニター行、その設定、および過去のスナップショットは保持されますが、今後のスケジュールされた実行は停止します。後でPOST /v1/monitors/:monitor_id/resumeでモニターを再開できます。 statusがactiveのモニターのみが一時停止できます。リクエストボディは空です。 
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))

​
レスポンス

成功すると、200とモニターが返され、statusがpausedに設定されます： 
{
  "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"
}
可能なエラーレスポンス：
  • 400 — monitor_idが不正、モニターがすでにdeleted、モニターが現在activeでない、またはモニターに基礎となるスケジュールがない。
  • 404 — モニターが見つからない。
  • 409 — 一時停止試行中にモニターの状態が変わった（もはやactiveでない）、または基礎となるスケジュールが見つからなかった。

​
モニターを再開

POST /v1/monitors/:monitor_id/resumeで一時停止されたモニターを再開します。 再開すると、モニターの基礎となるスケジュールが再有効化され、モニターのstatusがactiveに戻ります。スケジュールされた実行は既存のfrequencyで続行されます — スケジュールの再作成は必要ありません。 statusがpausedのモニターのみが再開できます。リクエストボディは空です。 
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))

​
レスポンス

成功すると、200とモニターが返され、statusがactiveに戻ります： 
{
  "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"
}
可能なエラーレスポンス：
  • 400 — monitor_idが不正、モニターがすでにdeleted、モニターが現在pausedでない、またはモニターに基礎となるスケジュールがない。
  • 404 — モニターが見つからない。
  • 409 — 再開試行中にモニターの状態が変わった（もはやpausedでない）、または基礎となるスケジュールが見つからなかった。

​
モニターを削除

DELETE /v1/monitors/:monitor_idでモニターを削除します。 削除はモニター行に対してソフトであり（statusがdeletedになる）、そのモニターに関連付けられた内部スケジューリング/シャドウエージェントリソースも削除されます。 
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))

​
使用例

以下は/v1/monitorsエンドポイントの実用的なリクエスト例です。

​
OpenAI APIの稼働時間の問題を追跡

OpenAI APIのステータスを監視し、稼働時間の問題が検出されたときにメールで通知する毎時チェックを実行します。 
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))

​
商品レビューを追跡 — 各実行ごとの完全なスナップショット

商品ページを監視し、各実行でレビューをWebhookに送信します。queryが前の実行と重複しないように要求していないため、各実行でページ上のレビューの完全なスナップショットがキャプチャされます（デフォルトの動作）。これは、毎回完全な状態が必要な場合に使用するパターンです。例えば、下流のテーブルを上書きするためです。 
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))

​
新しい賃貸リストのみを追跡 — 前回の実行からのデルタ

ページネーションされた賃貸検索を監視し、前回の実行と比較して新たに出現したリストのみを表示し、それぞれを強化し、スコアを付けた後にWebhookに通知するマルチステップパイプラインを実行します。完全なワークフロー — ページネーション、新しいリストを前のチェックポイントと比較して検出、各リストをその場所の犯罪信号で強化、価格/場所/安全性に基づいて1-10のスコアを付け、状態を保持し、通知 — はqueryで直接順序付けられたステップとして表現されます。自然言語のステップが抽出とデルタロジックの両方を記述しているため、output_schemaは必要ありません：クエリだけで何が取得され、比較され、強化され、スコア付けされ、配信されるかが決まります。 
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))

​
一般的なバリデーションエラー

モニターエンドポイントは、一般的な無効なリクエストに対して明確なバリデーションエラーを返します：
  • queryが欠落
  • frequencyが欠落、または無効なスケジュール指示
  • email、webhook_url、およびphone_numberのすべてが欠落
  • 同じリクエストでemail、webhook_url、およびphone_numberのうち複数を提供
  • 無効なメール形式
  • 無効なWebhook URL（httpまたはhttpsでなければならない）
  • 無効な電話番号形式（E.164でなければならない、例：+14155552671）
  • 無効なoutput_schema（有効なJSON Schemaでなければならない）
  • 無効なmonitor_id形式
エラーの例： 
{
  "error": "Invalid frequency. Provide a natural-language schedule instruction."
}