Skip to main content

​
Monitors API Reference

Standalone recurring-search surface via https://api.exa.ai/monitors.
  • Base docs URL: https://exa.ai/docs
  • Monitors guide: /reference/monitors-api-guide
  • Monitors coding-agent reference: /reference/monitors-api-guide-for-coding-agents

​
Contents

  • Overview
  • Endpoint summary
  • Create shape
  • Search payload and trigger shape
  • Runs, statuses, and updates
  • Webhook handling
  • Critical pitfalls

​
Overview

The Monitors API runs Exa searches on a schedule and delivers results to a webhook. Use it for recurring monitoring workflows such as:
  • competitor announcements
  • funding events
  • policy or regulatory changes
  • new publications on a topic
This file covers the standalone Monitors API only. Websets has its own monitor subresources inside the Websets API family and is documented separately in websets.md.

​
Endpoint Summary

MethodPathPurpose
POST/monitorsCreate a monitor
GET/monitorsList monitors
GET/monitors/{id}Get one monitor
PATCH/monitors/{id}Update a monitor
DELETE/monitors/{id}Delete a monitor
POST/monitors/{id}/triggerTrigger an on-demand run
GET/monitors/{id}/runsList runs
GET/monitors/{id}/runs/{runId}Get one run

​
Create Shape

POST https://api.exa.ai/monitors
{
  "name": "AI Funding Tracker",
  "search": {
    "query": "AI startups that raised Series A funding",
    "numResults": 10
  },
  "trigger": {
    "type": "interval",
    "period": "1d"
  },
  "webhook": {
    "url": "https://example.com/webhook"
  }
}

​
Create Fields

FieldTypeNotes
namestringOptional display name
searchobjectRequired search payload
triggerobjectOptional interval schedule; omit for manual-only monitors
outputSchemaobjectOptional structured output
metadataobjectOptional caller metadata
webhookobjectRequired webhook configuration

​
Search Payload and Trigger Shape

  • query
  • optional numResults
  • optional nested contents
For recurring behavior, the key extra concept is trigger: 
{
  "trigger": {
    "type": "interval",
    "period": "7d"
  }
}
trigger can be removed on update by setting it to null.

​
Runs, Statuses, and Updates

Monitor statuses in current Exa docs:
  • active: runs on schedule and accepts manual triggers
  • paused: does not run on schedule but still accepts manual triggers
  • disabled: system-disabled, not manually chosen in normal create flows
Update semantics:
  • all update fields are optional
  • search supports partial updates
  • manual testing is done through POST /monitors/{id}/trigger

​
Webhook Handling

Creating a monitor returns a one-time webhookSecret. Store it immediately. It is required for verifying webhook signatures and cannot be fetched later. This is one of the most important operational details in the Monitors API.

​
Python Example

from exa_py import Exa

exa = Exa(api_key="YOUR_EXA_API_KEY")
monitor = exa.monitors.create(params={
    "name": "AI Funding Tracker",
    "search": {
        "query": "AI startups that raised Series A funding",
        "numResults": 10
    },
    "trigger": {
        "type": "interval",
        "period": "1d"
    },
    "webhook": {
        "url": "https://example.com/webhook"
    }
})

print(monitor.id)
print(monitor.webhook_secret)
Current Exa Python monitor examples use an API-shaped params dict, so the nested search payload commonly stays in camelCase even though the core Python search helpers are snake_case.

​
Critical Pitfalls

  1. Use search, not searchParams.
  2. Use trigger, not a top-level schedule string.
  3. Store webhookSecret immediately on create.
  4. Keep this Monitors API separate from Websets-owned monitor subresources.
  5. Manual triggers still work for paused monitors, but not for system-disabled ones.
Last modified on June 26, 2026