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

# Limits and errors

> Read how many monitors and pages you may watch, what each monitor cost in dollars, and every error the monitor calls return, including 409 while a check runs.

`GET /v1/monitor/limits` shows how much of your monitor allowance you use, and `GET /v1/monitor/usage` shows what each monitor cost. Both are free.

## Read your limits

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart).

```bash cURL theme={null}
curl https://api.stophy.dev/v1/monitor/limits \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/monitor/limits", {
  headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` },
});
const { data } = await response.json();
console.log(`${data.monitors.used} of ${data.monitors.limit} monitors`);
console.log(`${data.pages.used} of ${data.pages.limit} pages`);
```

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

import requests

response = requests.get(
    "https://api.stophy.dev/v1/monitor/limits",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
)
data = response.json()["data"]
print(data["monitors"]["used"], "of", data["monitors"]["limit"], "monitors")
print(data["pages"]["used"], "of", data["pages"]["limit"], "pages")
```

This real answer came from an account with two monitors.

```json theme={null}
{
  "success": true,
  "data": {
    "monitors": { "used": 2, "limit": 25, "active": 2 },
    "pages": { "used": 2, "limit": 1000 },
    "perMonitor": { "pages": 100, "targets": 50 },
    "intervalSeconds": { "min": 300, "max": 2592000 },
    "estimatedCreditsPerMonth": 2
  },
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "db0d69f0-6a06-4ffe-9508-1fcfe6f17705"
}
```

| Field | What it holds |
| - | - |
| `monitors` | `used` is how many monitors you have, paused ones included. `limit` is the most you can have. `active` is how many are not paused. |
| `pages` | `used` is the pages all your monitors watch, paused ones included, and `limit` is the most. A crawl target counts its `limit`, and a search target its `maxResults`. |
| `perMonitor` | The most `pages` and `targets` one monitor takes. |
| `intervalSeconds` | The shortest and longest `interval` in seconds, 5 minutes and 30 days. A `cron` schedule may be less frequent than the longest, never more frequent than the shortest. |
| `estimatedCreditsPerMonth` | What your active monitors cost over 30 days, in steps of $0.002. 2 is $0.004. |

Each monitor shows its own estimate as `estimatedCostUsdPerMonth`. See [Monitors](https://docs.stophy.dev/monitors/overview).

## Read what monitors cost

`GET /v1/monitor/usage` adds up what your account was charged for checks, per monitor, in dollars. Send `from` and `to` as an ISO date or time, such as `2026-11-01` or `2026-11-01T08:00:00Z`. `to` is not included. With neither, it reads the last 30 days. The window may span 366 days at most.

```bash theme={null}
curl https://api.stophy.dev/v1/monitor/usage \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

This real answer is cut to three of the monitors it listed, and the total is of all of them. The window was the default 30 days.

```json theme={null}
{
  "success": true,
  "data": {
    "from": "2026-10-18T18:21:12.966Z",
    "to": "2026-11-17T18:21:12.966Z",
    "totalCredits": 25,
    "totalCostUsd": 0.05,
    "monitors": [
      { "id": "mon_0t7c4BOHDH9HfJUK", "credits": 6, "costUsd": 0.012, "charges": 4, "deleted": true },
      { "id": "mon_2f3L73izJTdaA1AQ", "name": "Page that changes", "credits": 3, "costUsd": 0.006, "charges": 2, "deleted": false },
      { "id": "mon_hpJ-ZKa4FJLr4h1m", "name": "Example home page", "credits": 1, "costUsd": 0.002, "charges": 1, "deleted": false }
    ]
  },
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "43a6d858-0183-4940-b3c2-595f1a947ff1"
}
```

`totalCostUsd` and each `costUsd` are in dollars. `credits` and `totalCredits` hold the same amounts in steps of \$0.002. `charges` is how many times the monitor was charged. Every monitor you have is listed, with 0 when it cost nothing in the window. A monitor you deleted is listed with `deleted: true` and no `name`. The list is sorted by cost, highest first.

## Limits

| Limit | Value |
| - | - |
| Monitors | 25 per account |
| Pages watched | 1,000 across all monitors |
| Pages in one scrape target | 100 |
| Targets in one monitor | 50 |
| Time between checks | At least 5 minutes |
| Monitor name | 1 to 256 characters |
| Retention | 1 to 365 days, 30 by default |
| Checks and changes kept | The last 1,000 of each, for the retention days |
| Calls on a monitor | 60 a minute for creating, listing, reading, changing, deleting and running monitors and reading the checks and changes of one monitor |

Paused monitors count toward the first two limits. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md) for the limits on the other calls.

## Errors

Every error has the flat shape on [Errors](https://docs.stophy.dev/api-reference/errors.md). A failed call costs nothing.

| Status | Code | When | What to do |
| - | - | - | - |
| 400 | `invalidRequest` | The body is not valid. The `error` names the field. | Read the message and fix the field. |
| 400 | `invalidRequest` | `You can run 25 monitors. Delete one to add another.` | Delete a monitor. Pausing does not free a slot. |
| 400 | `invalidRequest` | `Your monitors can watch 1,000 pages in total, and N are in use.` | Watch fewer pages, or delete a monitor. |
| 401 | `apiKeyRequired` | The call has no API key. Monitors need an API key. | Send your API key. See [API keys](https://docs.stophy.dev/account/api-keys.md). |
| 404 | `notFound` | `There is no monitor with that id on your account.` A check or change id that is not yours or has expired gives the same code. | Check the id. List with `GET /v1/monitor`. |
| 409 | `checkRunning` | `A check of this monitor is already running. Wait for it to finish, then run it again.` | Wait for the check to end, then run it again. |
| 429 | `rateLimited` | You went over the limit on monitor calls. | Wait `retryAfterSeconds`. |

These are real `400` messages for a body that is not valid.

| Mistake | `error` |
| - | - |
| A schedule that runs too often | `schedule: the minimum interval is 5 minutes` |
| A target address that is not public | `targets.0.urls.0: Expected a public website URL` |
| A search target with no goal | `goal: a search target needs a goal to judge results against, or judgeEnabled set to false` |
| An event that does not exist | `webhook.events.0: Send one of: monitor.page, monitor.check.completed, monitor.changed, monitor.failed.` |
| `zeroDataRetention` on a target | `targets.0.scrapeOptions.zeroDataRetention: zeroDataRetention is not available for monitors, which keep a snapshot to compare` |
| `PATCH` with no field | `Send at least one field to change` |
| A `status` that does not exist | `status: Send one of: active, paused.` |
| An interval outside the limits | `interval: interval must be between 5 minutes and 30 days` |

A monitor that cannot read a page does not fail the call. The check shows the page as `error`, and a monitor whose balance runs out pauses with `pausedReason` `insufficientCredits`. See [Schedules](https://docs.stophy.dev/monitors/schedules.md#when-a-monitor-pauses-itself).

## Related

* [Monitors](https://docs.stophy.dev/monitors/overview) creates and manages monitors.
* [Schedules](https://docs.stophy.dev/monitors/schedules.md) runs a check now, pauses and resumes.
* [Pricing](https://docs.stophy.dev/account/pricing.md) lists the price of every call.
* [Usage](https://docs.stophy.dev/account/usage.md) shows your balance and everything you spent.


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