Monitor

Create Monitor

Changed on Oct 16, 2026

Create a monitor.

Monitors run on a fixed frequency to detect material changes in web content. Set type=event_stream to monitor a search query, or type=snapshot to monitor a specific task run's output. The monitor runs once immediately at creation, then continues on the configured schedule.

Request body

type'event_stream' | 'snapshot' required

Type of monitor to create. event_stream monitors a search query for material changes; snapshot monitors a specific task run's output. Determines the expected shape of settings.

frequencystring required

Frequency of the monitor. Format: '<number><unit>' where unit is 'h' (hours), 'd' (days), or 'w' (weeks). Must be between 1h and 30d (inclusive).

processor'lite' | 'base' | 'core'

Processor to use for the monitor. lite is the cheapest; base performs more thorough analysis for higher-quality results at higher cost; core performs the most thorough analysis for the highest-quality results at the highest cost. Defaults to lite.

metadataobject nullable

User-provided metadata stored with the monitor and echoed back in webhook notifications and GET responses, so you can map events to objects in your application. Keys: max 16 chars; values: max 512 chars.

memory_scope_keystring nullable

User-provided key identifying the memory scope to use. Omit to use personal memory, if available.

Example request

{
  "type": "event_stream",
  "frequency": "1h",
  "webhook": {
    "url": "https://example.com/webhook"
  },
  "metadata": {
    "slack_thread_id": "1234567890.123456",
    "user_id": "U123ABC"
  },
  "settings": {
    "query": "Extract recent news about AI",
    "output_schema": {
      "json_schema": {
        "additionalProperties": false,
        "properties": {
          "gdp": {
            "description": "GDP in USD for the year, formatted like '$3.1 trillion (2023)'",
            "type": "string"
          }
        },
        "required": [
          "gdp"
        ],
        "type": "object"
      }
    },
    "advanced_settings": {
      "source_policy": {
        "include_domains": [
          "wikipedia.org",
          "docs.python.org/3",
          ".edu"
        ],
        "exclude_domains": [
          "reddit.com",
          "youtube.com/shorts",
          ".ai"
        ],
        "after_date": "2024-01-01"
      },
      "location": "us"
    }
  }
}

Response

Monitor created successfully.

type'event_stream' | 'snapshot' required

The type of monitor.

monitor_idstring required

ID of the monitor.

status'active' | 'cancelled' required

Status of the monitor.

frequencystring required

Frequency of the monitor. Format: '<number><unit>' where unit is 'h' (hours), 'd' (days), or 'w' (weeks). Must be between 1h and 30d (inclusive).

processor'lite' | 'base' | 'core' required

Processor to use for the monitor. lite is the cheapest; base performs more thorough analysis for higher-quality results at higher cost; core performs the most thorough analysis for the highest-quality results at the highest cost. Defaults to lite.

metadataobject nullable

User-provided metadata stored with the monitor and echoed back in webhook notifications and GET responses, so you can map events to objects in your application. Keys: max 16 chars; values: max 512 chars.

created_atstring date-time required

Timestamp of the creation of the monitor, as an RFC 3339 string.

last_run_atstring nullable

Timestamp of the last run for the monitor, as an RFC 3339 string.

Example response

{
  "type": "event_stream",
  "status": "active",
  "frequency": "1h",
  "processor": "lite",
  "webhook": {
    "url": "https://example.com/webhook"
  },
  "metadata": {
    "slack_thread_id": "1234567890.123456",
    "user_id": "U123ABC"
  },
  "created_at": "2025-01-15T10:30:00Z",
  "last_run_at": "2025-01-15T10:30:00Z",
  "settings": {
    "query": "Extract recent news about AI",
    "output_schema": {
      "json_schema": {
        "additionalProperties": false,
        "properties": {
          "gdp": {
            "description": "GDP in USD for the year, formatted like '$3.1 trillion (2023)'",
            "type": "string"
          }
        },
        "required": [
          "gdp"
        ],
        "type": "object"
      }
    },
    "advanced_settings": {
      "source_policy": {
        "include_domains": [
          "wikipedia.org",
          "docs.python.org/3",
          ".edu"
        ],
        "exclude_domains": [
          "reddit.com",
          "youtube.com/shorts",
          ".ai"
        ],
        "after_date": "2024-01-01"
      },
      "location": "us"
    }
  },
  "output": {
    "latest_snapshot": {
      "basis": [
        {
          "confidence": "low"
        }
      ]
    }
  }
}

Create Monitor

Request

Request body

Example request

Response 201Created

Example response

Changes

Response