EarlyWave

Guides

Monitors

View as Markdown
On this page

A monitor watches a subject for you: it checks EarlyWave's sources on a schedule, keeps what matches (events, mentions or a briefing), extracts the fields you asked for and answers your standing questions. You create and tune monitors in the app, on the Monitors page or by asking Ask EarlyWave. The API reads them.

RESTMCP toolReturns
GET /monitorslist_monitorsThe account's monitors.
GET /monitors/{monitor_id}/resultsget_monitor_resultsWhat one monitor found, with sources and current answers.

List your monitors

bash
curl "https://api.earlywave.ai/api/v1/monitors" \
  -H "Authorization: Bearer $EARLYWAVE_API_KEY"
json
{
  "monitors": [
    {
      "id": "0b7c6a52-4c1e-4e0b-9a51-2f8d3c1e7a90",
      "name": "Battery plants in Europe",
      "form": "events",
      "status": "active",
      "icon": "🔋",
      "results_count": 23,
      "articles_count": 88,
      "last_check_at": "2026-10-19T08:00:12.000Z",
      "next_check_at": "2026-10-19T09:00:00.000Z",
      "last_result_at": "2026-10-18T16:20:45.000Z",
      "created_at": "2026-10-02T09:14:03.000Z",
      "updated_at": "2026-10-19T08:00:12.000Z",
      "conversation_ref": "agent-5d1fa0c2-8e44-4b7a-9c3e-71a0b2f4d6e8",
      "cadence": { "check_every_hours": 1 },
      "delivery_mode": "realtime",
      "calm_since": null
    }
  ],
  "total": 1
}

The list returns every monitor at once (no paging). Archived monitors are left out.

FieldMeaning
idThe monitor's ID, a UUID. Pass it to the results operation.
formevents (dated events with fields), mentions (articles that mention the subject) or briefing (a periodic digest).
statusdraft, active, paused or calm. A monitor turns calm after 14 days without a result; calm_since says since when.
results_count / articles_countResults kept so far, and the articles behind them.
last_check_at / next_check_atThe latest check and the next one.
cadenceHow often it checks: { "check_every_hours": 1 } (1, 3, 6, 12 or 24).
delivery_modeHow results are delivered: as they come (realtime) or on a schedule (scheduled).
conversation_refThe conversation that created and tunes the monitor.

Get a monitor's results

bash
curl "https://api.earlywave.ai/api/v1/monitors/0b7c6a52-4c1e-4e0b-9a51-2f8d3c1e7a90/results?days=7" \
  -H "Authorization: Bearer $EARLYWAVE_API_KEY"
ParameterDefaultMeaning
days30The period, 1–90 days back from now.
query—Only results containing this text.
limit20Results to return, 1–100.
json
{
  "monitor": { "id": "0b7c6a52-4c1e-4e0b-9a51-2f8d3c1e7a90", "name": "Battery plants in Europe", "…": "…" },
  "period_days": 7,
  "total": 4,
  "limit": 20,
  "has_more": false,
  "results": [
    {
      "id": "c1d7e0f4-2b9a-4f61-8d0e-5a3b7c9e1f20",
      "kind": "event",
      "type": "NEW_PLANT",
      "title": "Battery maker confirms a second plant in northern France",
      "summary": "The plant would open in 2028 with 30 GWh of yearly capacity.",
      "event_date": "2026-10-17T00:00:00.000Z",
      "fields": { "company": "Example Cells", "country": "FR", "capacity_gwh": 30 },
      "confidence": 0.86,
      "cluster_id": 48517,
      "sources_count": 3,
      "first_seen_at": "2026-10-17T16:20:45.000Z",
      "updated_at": "2026-10-18T07:02:11.000Z",
      "hidden_at": null,
      "feedback": null,
      "sources": [
        {
          "item_id": 9920113,
          "url": "https://news.example.fr/battery-plant",
          "title": "A second battery plant for the north",
          "publisher": "Example News",
          "published_at": "2026-10-17T15:58:00.000Z",
          "excerpt": "The company confirmed on Friday…",
          "provenance": "feeds"
        }
      ]
    }
  ],
  "answers": [
    {
      "question": "Which countries announced a new plant this month?",
      "answer": "France and Hungary, one plant each.",
      "changed_at": "2026-10-17T16:20:45.000Z"
    }
  ]
}
  • results are newest first. Results you hid in the app are left out.
  • kind follows the monitor's form: event, mention or digest.
  • fields holds the values the monitor extracts, under the keys you defined for it. type is the value of its main choice field, when it has one.
  • confidence is between 0 and 1. The app folds results under 0.6 as uncertain; do the same if you show them to people.
  • cluster_id is the trend the result belongs to, when there is one: open it with GET /trends/{trend_id}.
  • sources[].provenance says where the source was found: feeds (your feeds), library (EarlyWave's sources), story (a trend's articles) or web.
  • answers are the monitor's standing questions with their current answers, and when each answer last changed.

This operation has no offset. When has_more is true, narrow the period with days, filter with query, or raise limit up to 100.

An ID that is not one of the account's monitors answers 404 with code monitor_not_found.

A weekly digest in a few lines

python
import os
import requests

API = "https://api.earlywave.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['EARLYWAVE_API_KEY']}"}

monitors = requests.get(f"{API}/monitors", headers=HEADERS, timeout=30).json()["monitors"]
for monitor in monitors:
    page = requests.get(
        f"{API}/monitors/{monitor['id']}/results",
        params={"days": 7, "limit": 100},
        headers=HEADERS,
        timeout=30,
    ).json()
    print(f"\n{monitor['name']}: {page['total']} new")
    for result in page["results"]:
        source = result["sources"][0]["url"] if result["sources"] else ""
        print(f"- {result['title']} {source}")

Over MCP, the same question is one sentence: "Summarise what my monitors found this week, with sources."