Skip to main content
Get the pages a monitor found since you last looked, without a webhook. Poll the monitor’s results and stop at the last one you’ve seen, read the digest each scheduled run returns, or let your agent read new results over MCP. To get each page pushed to your endpoint instead, see Receive monitor webhooks. You need an API key and a monitor’s id. To make one, see Create a monitor.

Choose how to read

Poll for new results

Polling needs one piece of state: the id of the newest result you’ve already read. Results come newest first, so each poll reads until it reaches that id. This sample keeps the id in last_seen.txt, reads only results with importance 4 or higher, and prints the new ones oldest first:
The SDK tabs need SDK 0.2.0 or later, the first version with Monitors. If your package manager doesn’t offer 0.2.0 yet, use the curl tab, which reads one page of 50. The first poll prints up to 50 results and saves the newest id. Each later poll prints only what arrived since, one line per result:
Example output · results vary
If nothing new arrived, the poll prints nothing and leaves last_seen.txt as it was.

Page through results

Every list in the Monitors API returns data, has_more and next_cursor. To get the next page, pass next_cursor as cursor. The last id on a page is its next_cursor. These parameters apply to List results: Use the same min_importance on every poll. A saved id from an unfiltered poll may not appear in a filtered one, and the poll then reads back through all 500 results.

Read the results of a run

If the monitor has a schedule, each run holds the results found since the previous run. This request returns the latest run:
You get one run in data. Its status is queued, running, completed, failed or cancelled. Its results is a list when the run completed, [] if it found nothing new, and null before it completes. A run returns at most the monitor’s search.max_results, and the results past that limit stay in List results. To get a digest now instead of at the next scheduled time, call Run a monitor now. It returns a run with status queued. Read it a few seconds later with Get a run.

Read results from the CLI

With the CLI installed and keenable login done, this command prints a monitor’s important results in a readable view:
If there are more results, the CLI ends with a hint such as More: add --cursor <id>.

Common mistakes

API reference