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

# Schedules

> Set when a monitor checks, in plain words or a cron expression, from every 5 minutes. Check now, pause and resume, and learn when a monitor pauses itself.

A monitor checks on its `schedule`, from every 5 minutes up. You can also check now, and pause and resume a monitor without losing its history.

## Change the schedule

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). The samples read the monitor's id from `MONITOR_ID`. Send `schedule` when you create a monitor, or change it later with `PATCH /v1/monitor/{id}`. This request moves a monitor to 9:00 every day in Ljubljana.

```bash cURL theme={null}
curl -X PATCH https://api.stophy.dev/v1/monitor/$MONITOR_ID \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": { "text": "daily at 9:00", "timezone": "Europe/Ljubljana" }
  }'
```

```typescript TypeScript theme={null}
const response = await fetch(`https://api.stophy.dev/v1/monitor/${process.env.MONITOR_ID}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    schedule: { text: "daily at 9:00", timezone: "Europe/Ljubljana" },
  }),
});
const { data } = await response.json();
console.log(data.schedule);
```

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

import requests

response = requests.patch(
    f"https://api.stophy.dev/v1/monitor/{os.environ['MONITOR_ID']}",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={"schedule": {"text": "daily at 9:00", "timezone": "Europe/Ljubljana"}},
)
print(response.json()["data"]["schedule"])
```

## Read the response

The call answers with the monitor. `schedule` holds the plain words as a cron expression. This real answer is cut to `schedule`. The next check of that monitor was due at `2026-11-18T08:00:00.000Z`, which is 09:00 in Ljubljana.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "mon_hpJ-ZKa4FJLr4h1m",
    "schedule": { "cron": "0 9 * * *", "timezone": "Europe/Ljubljana", "everySeconds": null }
  }
}
```

A check starts at its time, or within about a minute of it. Checks of one monitor never overlap. When the last check is still running as the next one falls due, the due check is recorded as `skipped_overlap` and costs nothing.

## Options

Send `cron` or `text`, not both.

| Field | Type | Default | Effect |
| - | - | - | - |
| `cron` | `string` | none | A five-field cron expression, minute to weekday. Runs may be no closer than 5 minutes. A monthly expression such as `0 0 1 * *` is fine. |
| `text` | `string` | none | The schedule in plain words. See the table below. |
| `timezone` | `string` | `UTC` | An IANA timezone such as `Europe/Ljubljana`. It sets what `daily at 9:00` and a cron expression mean. |

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

The older `interval` field takes seconds, or text such as `30m`, `6h` or `1d`, from 5 minutes to 30 days. Use it only with the older `url` and `urls` fields.

## Run a check now

`POST /v1/monitor/{id}/run` queues a check outside the schedule. It answers at once with the queued check, and its `id` is the check's id. The schedule does not move. A check you run costs the same as a scheduled one.

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

This real answer is cut. The check started 52 seconds later and was `completed`.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "8e19c453-d27e-4680-b10b-e294225d9fd1",
    "monitorId": "mon_2f3L73izJTdaA1AQ",
    "status": "queued",
    "trigger": "manual",
    "estimatedCostUsd": 0.001,
    "billingStatus": "reserved",
    "summary": { "totalPages": 1, "same": 0, "changed": 0, "new": 0, "removed": 0, "error": 0 }
  },
  "id": "8e19c453-d27e-4680-b10b-e294225d9fd1",
  "costUsd": 0,
  "creditsUsed": 0
}
```

Read the result with `GET /v1/monitor/{id}/checks/{checkId}`. See [Checks and changes](https://docs.stophy.dev/monitors/checks-and-changes.md).

A monitor runs one check at a time. While a check is queued or running, a second run returns `409 checkRunning`.

```json theme={null}
{
  "success": false,
  "error": "A check of this monitor is already running. Wait for it to finish, then run it again.",
  "code": "checkRunning",
  "retryable": false,
  "requestId": "cab2af1f-a17a-40f0-b637-161f8bb368e3"
}
```

Run a check on an active monitor. Resume a paused monitor first.

## Pause and resume

Send `status` to `PATCH /v1/monitor/{id}`.

```json theme={null}
{ "status": "paused" }
```

A paused monitor reads nothing and costs nothing, and its `nextRunAt` is `null`. This real answer is cut.

```json theme={null}
{ "data": { "id": "mon_hpJ-ZKa4FJLr4h1m", "status": "paused", "nextRunAt": null } }
```

Send `{ "status": "active" }` to resume it. A resumed monitor checks again at once: `nextRunAt` was the moment of the call, and the check ran within a minute and cost \$0.001.

```json theme={null}
{ "data": { "id": "mon_hpJ-ZKa4FJLr4h1m", "status": "active", "nextRunAt": "2026-11-17T18:23:01.881Z" } }
```

Changing the schedule of a paused monitor keeps it paused. A paused monitor still counts toward your limit of 25 monitors and 1,000 pages. See [Limits and errors](https://docs.stophy.dev/monitors/limits-and-errors.md).

## When a monitor pauses itself

* **Your balance ran out.** The monitor pauses, `pausedReason` is `insufficientCredits`, and a `monitor.failed` event is sent if you subscribed to it. Add funds, then send `{ "status": "active" }`.
* **A page cannot be read.** The monitor keeps running. The check shows the page as `error` and costs nothing for it. After 5 checks in a row that fail to read the same page, a `monitor.failed` event is sent once.

A check where every page failed for lack of balance is recorded as `skipped_no_credits`.

## Limits and errors

Every `400` below has the code `invalidRequest`.

| Error | When |
| - | - |
| `400` `schedule: the minimum interval is 5 minutes` | A cron expression or a text runs more often than every 5 minutes. |
| `400` `schedule.text: could not read "every banana". Try every 30 minutes, hourly, every 2 hours, daily at 9:00 or weekly` | The plain words are not one of the forms above. |
| `400` `schedule.cron: send five fields, minute to weekday` | The cron expression has the wrong number of fields. |
| `400` `schedule.timezone: Mars/Base is not an IANA timezone such as Europe/Ljubljana` | The timezone is not known. |
| `400` `schedule: Send cron or text in schedule, not both` | You sent both. |
| `400` `schedule: send cron or text` | You created a monitor with no schedule. |
| `409` `checkRunning` | A check of this monitor is queued or running. |

## Related

* [Targets](https://docs.stophy.dev/monitors/targets.md) sets what each check reads.
* [Checks and changes](https://docs.stophy.dev/monitors/checks-and-changes.md) reads what a check found.
* [Webhooks](https://docs.stophy.dev/monitors/webhooks.md) sends an event after each check.


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