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

# Monitors

> Watch pages, a site section or a search on a schedule. Each change comes with its diff, by signed webhook or by reading checks.

A monitor checks your targets on a schedule and records what changed.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/monitor \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example home page",
    "targets": [{ "type": "scrape", "urls": ["https://example.com"] }],
    "schedule": { "text": "weekly" }
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/monitor", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Example home page",
    targets: [{ type: "scrape", urls: ["https://example.com"] }],
    schedule: { text: "weekly" },
  }),
});
const { data } = (await response.json()) as { data: { id: string; nextRunAt: string } };
console.log(data.id, data.nextRunAt);
```

```python Python theme={null}
import os

import httpx

response = httpx.post(
    "https://api.stophy.dev/v1/monitor",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "name": "Example home page",
        "targets": [{"type": "scrape", "urls": ["https://example.com"]}],
        "schedule": {"text": "weekly"},
    },
)
data = response.json()["data"]
print(data["id"], data["nextRunAt"])
```

`name`, `targets` and `schedule` are required. Creating is free, but every check bills for each page it reads until you pause or delete the monitor. See [Pricing](https://docs.stophy.dev/account/pricing.md).

```json theme={null}
{
  "success": true,
  "data": {
    "id": "mon_p7WUO7dQ3A-h0h4m",
    "status": "active",
    "schedule": { "cron": "0 0 * * 1", "timezone": "UTC", "everySeconds": null },
    "nextRunAt": "2026-11-20T20:53:26.983Z",
    "retentionDays": 30,
    "checks": 0
  }
}
```

The monitor is in `data`. The first check starts at once: page targets record a baseline and report no change, and a search target can report results. To be told about changes, add a [`webhook`](https://docs.stophy.dev/monitors/checks-and-changes#webhooks).

| Field | Holds |
| - | - |
| `status`, `pausedReason` | `active` or `paused`. A paused monitor reads nothing and costs nothing. `pausedReason` says why Stophy paused it, such as `insufficientCredits`. |
| `nextRunAt`, `lastRunAt`, `currentCheckId` | The next due check (`null` while paused), the last one, and the one queued or running now. |
| `targets`, `goal`, `judgeEnabled` | See [Targets](https://docs.stophy.dev/monitors/targets.md). |
| `retentionDays` | Days checks, diffs and snapshots are kept, 1 to 365. |
| `estimatedCostUsdPerMonth` | Pages watched times checks in 30 days. |
| `checks`, `costUsd` | Checks run and what they cost so far. |

`urls`, `interval`, `formats`, `changeTracking`, `nextCheckAt` and `lastCheckAt` repeat other fields for older clients.

## Manage a monitor

All of these are free. A monitor that does not exist, or belongs to another account, returns `404 notFound`.

| Call | Does |
| - | - |
| `GET /v1/monitor` | Lists newest first. `limit` up to 100 (default 20), and `next` as `cursor` for the next page. |
| `GET /v1/monitor/{id}` | Reads one. |
| `PATCH /v1/monitor/{id}` | Changes `name`, `schedule`, `targets`, `goal`, `webhook`, `notification`, `retentionDays` or `status`. It replaces `targets` and `webhook` whole. |
| `DELETE /v1/monitor/{id}` | Deletes it and stops billing. |
| `POST /v1/monitor/{id}/run` | Queues a check now. |
| `GET /v1/monitor/limits`, `GET /v1/monitor/usage` | Your allowance, and cost per monitor. |

## Set the schedule

Send `text` or `cron` in `schedule`, not both, with an optional IANA `timezone` (default `UTC`) that sets what a time means. A daily time comes back as a `cron` expression.

```json theme={null}
{ "schedule": { "text": "daily at 9:00", "timezone": "Europe/Ljubljana" } }
```

| `text` | Runs |
| - | - |
| `every 30 minutes` | At least `every 5 minutes`. A number that divides 60 keeps to the clock. Another, such as 7, counts from the last check. |
| `every 15 minutes starting at :07` | At minutes 7, 22, 37 and 52. |
| `hourly`, `every hour` | At the start of every hour. |
| `every 2 hours` | A number that divides 24 keeps to the clock. Another counts from the last check. |
| `daily`, `daily at 9:00`, `daily at 5:30 PM` | Every day, at midnight when no time is given. |
| `weekly` | Monday at midnight. |

A `cron` expression has five fields, minute to weekday, and runs no closer than 5 minutes apart. The older `interval` field takes seconds, or `30m`, `6h`, `1d`, and works only with `url` and `urls`.

Checks of one monitor never overlap: a check that falls due while the last one runs is recorded as `skipped_overlap` and is free.

## Run, pause and resume

`POST /v1/monitor/{id}/run` queues a check outside the schedule, which does not move. It returns the check with `status: "queued"`, `trigger: "manual"` and `estimatedCostUsd`. Read it with `GET /v1/monitor/{id}/checks/{checkId}`. A manual check costs the same as a scheduled one.

`PATCH` with `"status": "paused"` stops checks and keeps history. `"status": "active"` resumes with a check at once. Changing the schedule of a paused monitor keeps it paused.

* When your balance runs out, the monitor pauses with `pausedReason: "insufficientCredits"` and sends `monitor.failed` if you subscribed. Add funds, then resume.
* A page that cannot be read is `error` and free, and the monitor keeps running. After 5 failed checks in a row on the same page, `monitor.failed` is sent once.
* A check where every page failed for lack of balance is `skipped_no_credits`.

## Limits

`GET /v1/monitor/limits` returns these as `monitors`, `pages`, `perMonitor` and `intervalSeconds`. Call rates are on [Rate limits](https://docs.stophy.dev/production/rate-limits.md).

| Limit | Value |
| - | - |
| Monitors per account | 25. Paused ones count. |
| Pages watched across all monitors | 1,000. Paused ones count. A crawl target counts its `limit`, a search target its `maxResults`. |
| Pages in one scrape target | 100 |
| Targets in one monitor | 50 |
| Time between checks | 5 minutes to 30 days |
| Name | 1 to 256 characters |
| Checks and changes kept | The last 1,000 of each, within `retentionDays` |

`GET /v1/monitor/usage` totals what checks cost per monitor, highest first, including deleted ones (`deleted: true`). Send `from` and `to` as an ISO date or time, with `to` excluded and at most 366 days between them. The default is the last 30 days.

## Errors

Each `error` below is `400 invalidRequest` unless its code says otherwise. A failed call is free.

| `error` or code | Fix |
| - | - |
| `You can run 25 monitors. Delete one to add another.` | Delete one. Pausing does not free a slot. |
| `Your monitors can watch 1,000 pages in total, and N are in use.` | Watch fewer pages. |
| `schedule: the minimum interval is 5 minutes`, `the maximum interval is 30 days` | Change the schedule. |
| `schedule.text: could not read "every banana". …`, `schedule.cron: send five fields, minute to weekday`, `schedule.timezone: Mars/Base is not an IANA timezone …` | Use a form above, five cron fields, or an IANA name. |
| `schedule: send cron or text`, `Send cron or text in schedule, not both` | Send exactly one. |
| `409 checkRunning` | A check is queued or running. Wait, then run again. |
| `409 invalidRequest`, `This monitor is paused. …` | Send `{ "status": "active" }`, then run again. |

Other codes are on [Errors](https://docs.stophy.dev/api-reference/errors.md). Target and webhook errors are on [Targets](https://docs.stophy.dev/monitors/targets.md#limits-and-errors) and [Checks, changes and webhooks](https://docs.stophy.dev/monitors/checks-and-changes.md#limits-and-errors).

## Next

* [Targets](https://docs.stophy.dev/monitors/targets.md): watch a site section or a search.
* [Checks, changes and webhooks](https://docs.stophy.dev/monitors/checks-and-changes.md): read diffs.
* [Website change digest](https://docs.stophy.dev/recipes/website-change-digest.md): a recipe.


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