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

# Competitor watch: a weekday digest of a rival's own sites

> Watch a competitor's own domains with a Keenable monitor and get a weekday 9:00 digest of new pages, summarized in your own JSON Schema.

Get one digest each weekday morning of what a competitor published on its own sites: pricing changes, new plans and launches. A Keenable monitor keeps only new pages from the competitor's domains. A cron schedule runs it at 9:00, and each run returns the new pages plus a summary in the shape of a JSON Schema you choose.

## Recipe prompt

Paste this into your coding agent to have it build the recipe in your project:

```text Recipe prompt theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
Read https://docs.keenable.ai/recipes/competitor-watch.md and create a competitor monitor with the official Keenable SDK, version 0.2.0 or later, in this project's language. Ask me for the competitor's name, its domains, my time zone and the webhook URL first. Read KEENABLE_API_KEY from the environment, list existing monitors by name and reuse one on the same topic instead of creating a second, and store webhook.secret where the webhook handler can read it. Show me the monitor id and its upcoming_runs.
```

## What you build

| Setting | Value in the sample | What it does |
| - | - | - |
| `search.query` | `Example Corp pricing change, new plan or product launch` | The topic, in plain words |
| `search.include_domains` | `["example.com", "blog.example.com"]` | Keeps only pages on the competitor's own hosts |
| `search.max_results` | `20` | The most pages one run returns, from 1 to 100 |
| `schedule` | `{"type": "cron", "value": "0 9 * * 1-5", "timezone": "Europe/Paris"}` | Runs at 9:00 Paris time, Monday to Friday |
| `output_schema` | An object with `headline` and `pricing_changed` | Each run that finds pages also returns `output.structured` in this shape |
| `webhook.url` | `https://hooks.example.com/keenable` | Gets `monitor.run.completed` with the run's results and output |
| `webhook.events` | `["monitor.run.completed", "monitor.run.failed", "monitor.disabled"]` | Sends one event per run instead of each result as it's found. Without a list, the webhook also gets `monitor.result.found` for every new result |
| `metadata` | `{"competitor": "example-corp"}` | Your own tags, sent back in every webhook event |

To watch the coverage of a competitor on other sites, such as news or review sites, leave `include_domains` out and use `exclude_domains` to drop the competitor's own hosts.

## When it runs

At each cron time. A run returns the pages found since the previous run that no earlier run returned, most important first. A run with no new pages still sends `monitor.run.completed`, with `results: []`. A monitor matches only pages crawled after you create it, so the first digest covers the time since creation, not the past week.

## Code

This sample creates the monitor and prints its ID, its status, the webhook signing secret and the next three run times:

```typescript TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
// Needs keenable 0.2.0 or later on npm.
import { Keenable } from "keenable";

async function main() {
  const client = new Keenable(); // reads KEENABLE_API_KEY from the environment
  const monitor = await client.monitors.create({
    name: "Example Corp product and pricing changes",
    search: {
      query: "Example Corp pricing change, new plan or product launch",
      includeDomains: ["example.com", "blog.example.com"],
      maxResults: 20,
    },
    schedule: { type: "cron", value: "0 9 * * 1-5", timezone: "Europe/Paris" },
    outputSchema: {
      type: "object",
      properties: {
        headline: { type: "string" },
        pricing_changed: { type: "boolean" },
      },
    },
    webhook: {
      url: "https://hooks.example.com/keenable",
      events: ["monitor.run.completed", "monitor.run.failed", "monitor.disabled"],
    },
    metadata: { competitor: "example-corp" },
    idempotencyKey: "example-corp-watch", // a rerun within 24 hours returns this monitor
  });
  console.log(monitor.id, monitor.status);
  console.log(monitor.webhook?.secret); // shown once: store it
  for (const runAt of monitor.upcomingRuns) console.log(runAt);
}

main();
```

```python Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
# Needs keenable 0.2.0 or later on PyPI.
from keenable import Keenable

client = Keenable()  # reads KEENABLE_API_KEY from the environment
monitor = client.monitors.create(
    name="Example Corp product and pricing changes",
    search={
        "query": "Example Corp pricing change, new plan or product launch",
        "include_domains": ["example.com", "blog.example.com"],
        "max_results": 20,
    },
    schedule={"type": "cron", "value": "0 9 * * 1-5", "timezone": "Europe/Paris"},
    output_schema={
        "type": "object",
        "properties": {
            "headline": {"type": "string"},
            "pricing_changed": {"type": "boolean"},
        },
    },
    webhook={
        "url": "https://hooks.example.com/keenable",
        "events": ["monitor.run.completed", "monitor.run.failed", "monitor.disabled"],
    },
    metadata={"competitor": "example-corp"},
    idempotency_key="example-corp-watch",  # a rerun within 24 hours returns this monitor
)
print(monitor.id, monitor.status)
print(monitor.webhook.secret)  # shown once: store it
for run_at in monitor.upcoming_runs:
    print(run_at)
```

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

import (
	"context"
	"fmt"
	"log"

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

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

	monitor, err := client.Monitors.Create(context.Background(), &keenable.MonitorCreateParams{
		Name: "Example Corp product and pricing changes",
		Search: keenable.MonitorSearchParams{
			Query:          "Example Corp pricing change, new plan or product launch",
			IncludeDomains: []string{"example.com", "blog.example.com"},
			MaxResults:     20,
		},
		Schedule: &keenable.MonitorScheduleParams{Type: "cron", Value: "0 9 * * 1-5", Timezone: "Europe/Paris"},
		OutputSchema: map[string]any{
			"type": "object",
			"properties": map[string]any{
				"headline":        map[string]any{"type": "string"},
				"pricing_changed": map[string]any{"type": "boolean"},
			},
		},
		Webhook: &keenable.MonitorWebhookParams{
			URL:    "https://hooks.example.com/keenable",
			Events: []string{"monitor.run.completed", "monitor.run.failed", "monitor.disabled"},
		},
		Metadata:       map[string]string{"competitor": "example-corp"},
		IdempotencyKey: "example-corp-watch", // a rerun within 24 hours returns this monitor
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(monitor.ID, monitor.Status)
	if monitor.Webhook != nil && monitor.Webhook.Secret != nil {
		fmt.Println(*monitor.Webhook.Secret) // shown once: store it
	}
	for _, runAt := range monitor.UpcomingRuns {
		fmt.Println(runAt)
	}
}
```

```rust Rust theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
// Needs keenable 0.2.0 or later, plus serde_json in Cargo.toml.
use std::collections::HashMap;

use keenable::{
    Client, MonitorCreateParams, MonitorScheduleParams, MonitorSearchParams, MonitorWebhookParams,
};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), keenable::Error> {
    let client = Client::new()?; // reads KEENABLE_API_KEY from the environment
    let monitor = client
        .monitors()
        .create(&MonitorCreateParams {
            name: Some("Example Corp product and pricing changes".into()),
            search: MonitorSearchParams {
                include_domains: Some(vec!["example.com".into(), "blog.example.com".into()]),
                max_results: Some(20),
                ..MonitorSearchParams::new(
                    "Example Corp pricing change, new plan or product launch",
                )
            },
            schedule: Some(MonitorScheduleParams {
                schedule_type: "cron".into(),
                value: Some("0 9 * * 1-5".into()),
                timezone: Some("Europe/Paris".into()),
            }),
            output_schema: Some(json!({
                "type": "object",
                "properties": {
                    "headline": {"type": "string"},
                    "pricing_changed": {"type": "boolean"}
                }
            })),
            webhook: Some(MonitorWebhookParams {
                url: Some("https://hooks.example.com/keenable".into()),
                events: Some(vec![
                    "monitor.run.completed".into(),
                    "monitor.run.failed".into(),
                    "monitor.disabled".into(),
                ]),
            }),
            metadata: Some(HashMap::from([(
                "competitor".into(),
                "example-corp".into(),
            )])),
            // A rerun within 24 hours returns this monitor
            idempotency_key: Some("example-corp-watch".into()),
            ..Default::default()
        })
        .await?;
    println!("{} {}", monitor.id, monitor.status);
    if let Some(webhook) = &monitor.webhook {
        println!("{}", webhook.secret.clone().unwrap_or_default()); // shown once: store it
    }
    for run_at in &monitor.upcoming_runs {
        println!("{}", run_at);
    }
    Ok(())
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -X POST https://api.keenable.ai/v1/monitors \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example-corp-watch" \
  -d '{
    "name": "Example Corp product and pricing changes",
    "search": {
      "query": "Example Corp pricing change, new plan or product launch",
      "include_domains": ["example.com", "blog.example.com"],
      "max_results": 20
    },
    "schedule": {"type": "cron", "value": "0 9 * * 1-5", "timezone": "Europe/Paris"},
    "output_schema": {
      "type": "object",
      "properties": {
        "headline": {"type": "string"},
        "pricing_changed": {"type": "boolean"}
      }
    },
    "webhook": {
      "url": "https://hooks.example.com/keenable",
      "events": ["monitor.run.completed", "monitor.run.failed", "monitor.disabled"]
    },
    "metadata": {"competitor": "example-corp"}
  }'
```

You see the monitor's ID and `active`, the `whsec_` secret and three timestamps in UTC. Store the secret before anything else: only the create response carries it. To receive the digests, verify each delivery as in [Verify a webhook](https://docs.keenable.ai/products/monitors#verify-a-webhook), then read `data.run.results` and `data.run.output` from `monitor.run.completed` events.

## Example output

```text Example output · created on Thursday 19 November 2026 after 9:00 Paris time, IDs vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
mon_3kq9z2c8f1a04b7d9e6f5a21 active
whsec_example
2026-11-20T08:00:00.000Z
2026-11-23T08:00:00.000Z
2026-11-24T08:00:00.000Z
```

9:00 in Paris is 08:00 UTC in winter, and Saturday and Sunday are skipped. `upcoming_runs` always lists the next three run times in UTC.

## Production notes

| Situation | What happens | What to do |
| - | - | - |
| A schedule that breaks a rule | The API returns `400` with `invalid_request`, and `message` names the rule, such as `a cron schedule may run at most once an hour`. | Run at most once an hour. `timezone` works with cron schedules only. |
| A field the API doesn't offer | The API returns `400` with `monitor_option_not_supported` and the field's name. It never ignores a field. | Remove the field. See [Not supported yet](https://docs.keenable.ai/products/monitors#not-supported-yet). |
| A rerun of the create | Every tab sends the `Idempotency-Key` `example-corp-watch`. The same key and body within 24 hours return the first monitor. A later run creates a second one. | Use your own key. Before a later run, list your monitors and reuse the one on this topic. |
| A run fails | It returns nothing, and its results come with the next run that succeeds. After 10 failed runs in a row, Keenable disables the monitor. | Watch for `monitor.run.failed` and `monitor.disabled`. |
| More results than `max_results` | A run returns at most `max_results` results. Later runs don't return the rest. | Raise `max_results`, or read every result with [List results](https://docs.keenable.ai/api-reference/monitors/results.md). |
| `429` from the Monitors API | Over 120 requests per minute per organization, or more than 10 of them creating monitors. | Wait, then retry. Limits on active monitors are on the [Monitors](https://docs.keenable.ai/products/monitors#limits) page. |

Monitors needs an API key and is free for now. `output.structured` is a summary written by an LLM from the run's pages, and `output.grounding` names the pages behind each field. Check a field against its pages before you act on it.

## Next steps

* [News monitor to Slack](https://docs.keenable.ai/recipes/news-monitor-to-slack.md): one message per page instead of a daily digest.
* [Schedules](https://docs.keenable.ai/products/monitors#schedules): interval and one-off schedules.
* [Monitors API reference](https://docs.keenable.ai/api-reference/monitors/create.md): every field of a monitor.
* [Recipes](https://docs.keenable.ai/recipes.md): every recipe on one page.


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