> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Read monitor results by polling, runs or MCP

> How to read the pages a Keenable monitor found: poll new results since your last read, read each run's digest, or let your agent read them over MCP.

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](https://docs.keenable.ai/guides/monitor-webhooks.md).

You need an [API key](https://docs.keenable.ai/api-keys.md) and a monitor's `id`. To make one, see [Create a monitor](https://docs.keenable.ai/guides/create-a-monitor.md).

## Choose how to read

| Way | Endpoint or tool | What it returns | Use it if |
| - | - | - | - |
| Poll results | [List results](https://docs.keenable.ai/api-reference/monitors/results.md), `GET /v1/monitors/{id}/results` | Every result the monitor accepted, newest first, from its last 500 | Your code runs on its own timer, such as a cron job |
| Read runs | [List runs](https://docs.keenable.ai/api-reference/monitors/runs.md), `GET /v1/monitors/{id}/runs` | Each run with the results found since the previous run, most important first | The monitor has a `schedule` and you want a digest |
| Ask your agent | [`get_monitor_results`](https://docs.keenable.ai/mcp-server#monitors-tools) on the MCP server | Results this reader hasn't been given yet, across all monitors, each once | An agent reads the news for you |

## 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:

```typescript TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import { existsSync, readFileSync, writeFileSync } from "node:fs";
import { Keenable, type MonitorResult } from "keenable";

const MONITOR_ID = "mon_3kq9z2c8f1a04b7d9e6f5a21";
const STATE = "last_seen.txt";

async function main() {
  // reads KEENABLE_API_KEY from the environment
  const client = new Keenable();
  const lastSeen = existsSync(STATE) ? readFileSync(STATE, "utf8").trim() : null;

  const fresh: MonitorResult[] = [];
  let cursor: string | undefined;
  while (true) {
    const page = await client.monitors.results(MONITOR_ID, { minImportance: 4, limit: 50, cursor });
    const at = page.data.findIndex((result) => result.id === lastSeen);
    fresh.push(...(at === -1 ? page.data : page.data.slice(0, at)));
    // the first poll reads one page; later polls page back to the last seen result
    if (at !== -1 || lastSeen === null || !page.nextCursor) break;
    cursor = page.nextCursor;
  }

  for (const result of [...fresh].reverse()) {
    console.log(result.importance, result.title, result.url);
  }
  if (fresh.length > 0) writeFileSync(STATE, fresh[0].id ?? "");
}

main();
```

```python Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
from pathlib import Path

from keenable import Keenable

MONITOR_ID = "mon_3kq9z2c8f1a04b7d9e6f5a21"
STATE = Path("last_seen.txt")

# reads KEENABLE_API_KEY from the environment
client = Keenable()
last_seen = STATE.read_text().strip() if STATE.exists() else None

new, cursor = [], None
while True:
    page = client.monitors.results(MONITOR_ID, min_importance=4, limit=50, cursor=cursor)
    seen = False
    for result in page.data:
        if result.id == last_seen:
            seen = True
            break
        new.append(result)
    # the first poll reads one page; later polls page back to the last seen result
    if seen or last_seen is None or not page.next_cursor:
        break
    cursor = page.next_cursor

for result in reversed(new):
    print(result.importance, result.title, result.url)
if new:
    STATE.write_text(new[0].id or "")
```

```go Go theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
package main

import (
	"context"
	"errors"
	"fmt"
	"io/fs"
	"log"
	"os"
	"strings"

	"github.com/keenableai/keenable-sdk/go"
)

const (
	monitorID = "mon_3kq9z2c8f1a04b7d9e6f5a21"
	state     = "last_seen.txt"
)

func main() {
	// reads KEENABLE_API_KEY from the environment
	client, err := keenable.New(nil)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	lastSeen := ""
	if saved, err := os.ReadFile(state); err == nil {
		lastSeen = strings.TrimSpace(string(saved))
	} else if !errors.Is(err, fs.ErrNotExist) {
		log.Fatal(err)
	}

	var fresh []keenable.MonitorResult
	cursor := ""
	for {
		page, err := client.Monitors.Results(context.Background(), monitorID,
			&keenable.MonitorResultsParams{MinImportance: 4, Limit: 50, Cursor: cursor})
		if err != nil {
			log.Fatal(err)
		}
		seen := false
		for _, result := range page.Data {
			if result.ID != nil && *result.ID == lastSeen {
				seen = true
				break
			}
			fresh = append(fresh, result)
		}
		// the first poll reads one page; later polls page back to the last seen result
		if seen || lastSeen == "" || page.NextCursor == "" {
			break
		}
		cursor = page.NextCursor
	}

	for i := len(fresh) - 1; i >= 0; i-- {
		result := fresh[i]
		importance, title := 0, ""
		if result.Importance != nil {
			importance = *result.Importance
		}
		if result.Title != nil {
			title = *result.Title
		}
		fmt.Println(importance, title, result.URL)
	}
	if len(fresh) > 0 && fresh[0].ID != nil {
		if err := os.WriteFile(state, []byte(*fresh[0].ID), 0o644); err != nil {
			log.Fatal(err)
		}
	}
}
```

```rust Rust theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use keenable::{Client, MonitorResultsParams};

const MONITOR_ID: &str = "mon_3kq9z2c8f1a04b7d9e6f5a21";
const STATE: &str = "last_seen.txt";

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // reads KEENABLE_API_KEY from the environment
    let client = Client::new()?;
    let last_seen = std::fs::read_to_string(STATE).ok().map(|s| s.trim().to_string());

    let mut fresh = Vec::new();
    let mut cursor = None;
    loop {
        let params = MonitorResultsParams { min_importance: Some(4), limit: Some(50), cursor };
        let page = client.monitors().results(MONITOR_ID, &params).await?;
        let mut seen = false;
        for result in page.data {
            if result.id.is_some() && result.id == last_seen {
                seen = true;
                break;
            }
            fresh.push(result);
        }
        // the first poll reads one page; later polls page back to the last seen result
        if seen || last_seen.is_none() || page.next_cursor.is_none() {
            break;
        }
        cursor = page.next_cursor;
    }

    for result in fresh.iter().rev() {
        let importance = result.importance.unwrap_or_default();
        let title = result.title.as_deref().unwrap_or_default();
        println!("{importance} {title} {}", result.url);
    }
    if let Some(id) = fresh.first().and_then(|result| result.id.as_deref()) {
        std::fs::write(STATE, id)?;
    }
    Ok(())
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -G https://api.keenable.ai/v1/monitors/mon_3kq9z2c8f1a04b7d9e6f5a21/results \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  --data-urlencode "min_importance=4" \
  --data-urlencode "limit=50"
```

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:

```text Example output · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
4 Commission opens first AI Act investigation into a model provider https://example.com/news/ai-act-investigation
5 Regulator fines company under the AI Act https://example.org/2026/11/ai-act-fine
```

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](https://docs.keenable.ai/api-reference/monitors/results.md):

| Parameter | Effect | Values |
| - | - | - |
| `limit` | Results per page | 1 to 100, default 50 |
| `cursor` | Start after this result | The previous page's `next_cursor` |
| `min_importance` | Keep results rated at least this important | 1 to 5. A monitor accepts no page under 3, so `4` and `5` are the useful values |

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:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -G https://api.keenable.ai/v1/monitors/mon_3kq9z2c8f1a04b7d9e6f5a21/runs \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  --data-urlencode "limit=1"
```

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](https://docs.keenable.ai/api-reference/monitors/results.md).

To get a digest now instead of at the next scheduled time, call [Run a monitor now](https://docs.keenable.ai/api-reference/monitors/trigger.md). It returns a run with `status` `queued`. Read it a few seconds later with [Get a run](https://docs.keenable.ai/api-reference/monitors/run.md).

## Read results from the CLI

With the [CLI](https://docs.keenable.ai/cli.md) installed and `keenable login` done, this command prints a monitor's important results in a readable view:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
keenable monitors results mon_3kq9z2c8f1a04b7d9e6f5a21 --min-importance 4 -p
```

If there are more results, the CLI ends with a hint such as `More: add --cursor <id>`.

## Common mistakes

| Wrong | Right | Why |
| - | - | - |
| Sorting or deduplicating on `published_at` | Use `matched_at`, or the result's `id` | `published_at` is when the page was published, and it can be `null`. `matched_at` is when the monitor accepted the page. |
| Reading every page of results on each poll | Stop at the `id` you saved last time | Results come newest first, so everything after that `id` is already read. |
| Expecting results from before the monitor existed | Use [Search](https://docs.keenable.ai/products/search.md) with `published_after` | A monitor matches only pages crawled after it was created, and it doesn't backfill. |
| Polling runs on a monitor with no schedule | Poll [List results](https://docs.keenable.ai/api-reference/monitors/results.md), or add a `schedule` | Without a schedule, a monitor runs only when you trigger it. |
| Expecting more than the last 500 results | Poll often enough to stay inside the window | [List results](https://docs.keenable.ai/api-reference/monitors/results.md) covers a monitor's last 500 results. |

## API reference

* [List results](https://docs.keenable.ai/api-reference/monitors/results.md): every parameter and result field.
* [List runs](https://docs.keenable.ai/api-reference/monitors/runs.md) and [Get a run](https://docs.keenable.ai/api-reference/monitors/run.md): a run's `results`, `output` and `error`.
* [Result fields](https://docs.keenable.ai/products/monitors#read-the-results): `summary`, `importance`, `same_story` and the rest.
* [Webhook payload](https://docs.keenable.ai/api-reference/monitors-webhook-payload.md): the same result fields, pushed to your endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.