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

# Checks and changes

> Read each check of a monitor and what it found, per monitor and across all your monitors, with the diff of every changed page. All reads are free.

Every pass over a monitor's pages is a check. A check holds one result for each page: `same`, `new`, `changed`, `removed` or `error`. A page that changed comes with its diff. You can read all of it whether or not you use a webhook, and every read is free.

## List the checks

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). The samples read the monitor's id from `MONITOR_ID`. `GET /v1/monitor/{id}/checks` lists the checks of one monitor, newest first.

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

```typescript TypeScript theme={null}
const params = new URLSearchParams({ limit: "5" });
const response = await fetch(
  `https://api.stophy.dev/v1/monitor/${process.env.MONITOR_ID}/checks?${params}`,
  { headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` } },
);
const { data } = await response.json();
for (const check of data) console.log(check.startedAt, check.status, check.summary);
```

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

import requests

response = requests.get(
    f"https://api.stophy.dev/v1/monitor/{os.environ['MONITOR_ID']}/checks",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    params={"limit": 5},
)
for check in response.json()["data"]:
    print(check["startedAt"], check["status"], check["summary"])
```

This real answer is the first check of a monitor, cut to the fields that matter. It read one page for the first time, so the page is `new`.

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "bfdcccc0-40ed-4305-84fb-708ec7044e8b",
      "monitorId": "mon_2f3L73izJTdaA1AQ",
      "status": "completed",
      "trigger": "scheduled",
      "scheduledFor": "2026-11-17T18:19:53.976Z",
      "startedAt": "2026-11-17T18:19:53.983Z",
      "finishedAt": "2026-11-17T18:19:54.886Z",
      "estimatedCostUsd": 0.001,
      "actualCostUsd": 0.001,
      "billingStatus": "confirmed",
      "summary": { "totalPages": 1, "same": 0, "changed": 0, "new": 1, "removed": 0, "error": 0 },
      "error": null
    }
  ],
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "06c3b242-ef56-498b-8887-59a7d3f03337"
}
```

| Field | What it holds |
| - | - |
| `status` | `queued`, `running`, `completed`, `partial` (some pages failed), `failed` (every page failed), `skipped_overlap` or `skipped_no_credits`. |
| `trigger` | `scheduled`, or `manual` for a check you ran with [Run now](https://docs.stophy.dev/monitors/schedules.md#run-a-check-now). |
| `scheduledFor`, `startedAt`, `finishedAt` | When the check was due, started and ended. A manual check has no `scheduledFor`. |
| `estimatedCostUsd` | What the pages cost before extras such as the judge. `estimatedCredits` holds the same amount in steps of \$0.002. |
| `actualCostUsd` | What the check was charged once it ended, or `null` before. `actualCredits` holds the same amount in steps of \$0.002. |
| `billingStatus` | `reserved` while the check runs, `confirmed` once charged, and `not_applicable` for a skipped check. |
| `summary` | How many pages ended `same`, `changed`, `new`, `removed` or `error`, out of `totalPages`. |
| `error` | Why the check did not finish, or `null`. |

A check that stays `running` for 30 minutes is shown as `failed`. Send `status` to keep one status, `limit` up to 100 (20 by default) and `offset` to skip checks. A monitor keeps its last 1,000 checks for its `retentionDays`.

## Read one check

`GET /v1/monitor/{id}/checks/{checkId}` returns the check with a result for each page, and the diff of each changed page. Use the `id` of a check from the list, or from [Run now](https://docs.stophy.dev/monitors/schedules.md#run-a-check-now).

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

This real answer is a check that found a changed page, cut to the fields that matter. The monitor had a `goal`, so the page holds a judgment, and the check cost $0.002: $0.001 for the page and \$0.001 for the judge.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "8e19c453-d27e-4680-b10b-e294225d9fd1",
    "monitorId": "mon_2f3L73izJTdaA1AQ",
    "status": "completed",
    "trigger": "manual",
    "scheduledFor": null,
    "startedAt": "2026-11-17T18:20:53.978Z",
    "finishedAt": "2026-11-17T18:20:56.463Z",
    "estimatedCostUsd": 0.001,
    "actualCostUsd": 0.002,
    "billingStatus": "confirmed",
    "summary": { "totalPages": 1, "same": 0, "changed": 1, "new": 0, "removed": 0, "error": 0 },
    "error": null,
    "pages": [
      {
        "id": "1ec7bf8a-0988-4cb2-8e59-d4084a62827d",
        "targetId": "6948afed-e9eb-43be-8f2c-67ad4c3370c5",
        "url": "https://httpbin.org/uuid",
        "status": "changed",
        "statusCode": 200,
        "error": null,
        "judgment": {
          "meaningful": true,
          "confidence": "high",
          "reason": "The uuid value changed, which is exactly what the goal tracks.",
          "meaningfulChanges": [
            {
              "type": "changed",
              "before": "0714c38d-30cf-4c11-9c7a-801260afcaba",
              "after": "ec011f90-1296-47af-8911-bad9f9aa5314",
              "reason": "The uuid field now has a different value."
            }
          ]
        },
        "diff": {
          "text": "@@ -1,3 +1,3 @@\n {\n-  \"uuid\": \"0714c38d-30cf-4c11-9c7a-801260afcaba\"\n+  \"uuid\": \"ec011f90-1296-47af-8911-bad9f9aa5314\"\n }\n\\ No newline at end of file\n"
        },
        "creditsUsed": 1,
        "costUsd": 0.002,
        "createdAt": "2026-11-17T18:20:56.463Z"
      }
    ]
  },
  "next": null,
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "a2508c35-ff67-4c49-a39b-2f40a861a8f1"
}
```

| Page field | What it holds |
| - | - |
| `url`, `targetId` | The page, and the target of the monitor it came from. |
| `status` | `same`, `new`, `changed`, `removed` or `error`. See below. |
| `statusCode`, `error` | The status the page answered with, or why it could not be read. |
| `judgment` | The judge's answer when the monitor has a `goal`, otherwise `null`. See [Goal and judge](https://docs.stophy.dev/monitors/targets.md#goal-and-judge). |
| `diff` | `text` is a unified diff of the compared text, with 2 lines around each change and cut at 20,000 characters. With `json` mode, `json` maps each changed field to its `previous` and `current` value. `null` for a page that did not change. |
| `snapshot` | With `json` mode, `json` holds the fields read on this check. |
| `creditsUsed`, `costUsd` | What the page cost. `creditsUsed` holds the same amount in steps of \$0.002. |

A check holds up to 100 pages in one answer. Send `limit` and `skip`, or call the address in `next` until it is `null`. Send `status` to keep the pages with one status, such as `changed`.

### Page statuses

| `status` | Meaning |
| - | - |
| `new` | The page was read for the first time, or it came back after it was removed. On the first check of a monitor this is the baseline, and no event is sent. For a [crawl or search target](https://docs.stophy.dev/monitors/targets.md), a page or result found after the first check is a change and is sent. |
| `same` | The compared text is the same as the last read. The page is charged. |
| `changed` | The compared text differs from the last read. |
| `removed` | The page used to be read and now answers `404` or `410`. It is charged once. If it still answers that on the next check, the page is `error`. |
| `error` | The page could not be read. It costs nothing, and the monitor keeps trying on the next check. |

### Search results

For a search target, each page is a result. `metadata.searchStatus` says what happened to it. This real result was read and judged, and the judge decided it did not match the goal.

```json theme={null}
{
  "url": "https://github.com/n8n-io/n8n/releases",
  "status": "same",
  "metadata": { "searchStatus": "ignored" },
  "judgment": {
    "meaningful": false,
    "confidence": "high",
    "reason": "This is an n8n release page, not a Bun release or breaking change.",
    "meaningfulChanges": []
  },
  "creditsUsed": 1,
  "costUsd": 0.001
}
```

| `searchStatus` | Meaning |
| - | - |
| `alert` | A result you have not seen before, reported as `new`. |
| `already_seen` | A result you were already told about or that was already judged. It is `same` and costs nothing. |
| `ignored` | The judge found it not meaningful. It is `same`, and it is not looked at again. |
| `skipped` | The judge could not decide. It is `error`, and it is looked at again on the next check. |

## List the changes

`GET /v1/monitor/{id}/changes` lists the page results of a monitor, newest first: one row for each page in each check. Send `status=changed` to keep the changes. Send `url` to keep one page.

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

```json theme={null}
{
  "success": true,
  "data": [
    {
      "at": "2026-11-17T18:20:53.979Z",
      "url": "https://httpbin.org/uuid",
      "changeStatus": "changed",
      "creditsUsed": 1,
      "costUsd": 0.002,
      "diff": "@@ -1,3 +1,3 @@\n {\n-  \"uuid\": \"0714c38d-30cf-4c11-9c7a-801260afcaba\"\n+  \"uuid\": \"ec011f90-1296-47af-8911-bad9f9aa5314\"\n }\n\\ No newline at end of file\n"
    },
    {
      "at": "2026-11-17T18:19:54.237Z",
      "url": "https://httpbin.org/uuid",
      "changeStatus": "new",
      "creditsUsed": 1,
      "costUsd": 0.001,
      "diff": null
    }
  ],
  "next": null,
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "2ea4ec46-efd2-4081-937d-d8fd93284f9d"
}
```

| Field | What it holds |
| - | - |
| `at` | When the page was read. |
| `url`, `changeStatus` | The page, and `new`, `same`, `changed` or `removed`. A page that could not be read has `changeStatus` `null` and an `error`. |
| `diff`, `json` | The text diff, and with `json` mode each field before and after. |
| `creditsUsed`, `costUsd` | What the page cost. |

| Query | Type | Default | Effect |
| - | - | - | - |
| `limit` | `number` | 20 | Rows to return, 1 to 100. |
| `cursor` | `string` | none | The `next` of the last answer, for the next part. `next` is `null` on the last part. |
| `url` | `string` | none | Only rows of this page address. |
| `status` | `string` | none | Only rows with this `changeStatus`. |

A monitor keeps its last 1,000 rows for its `retentionDays`.

## Read all monitors at once

Two calls cover every monitor you have.

`GET /v1/monitor/checks` lists checks across monitors. Filter with `monitorId`, `status`, `trigger` (`scheduled` or `manual`), `limit` up to 100 and `cursor`. The answer holds `data.checks` and `data.cursor`.

`GET /v1/monitor/changes` lists page results across monitors. Filter with `monitorId`, `status`, `url`, `limit` up to 100 and `cursor`. Each row also has its `id` and its `monitorId` and `monitorName`. This real answer listed three rows, two of them `new` first reads. It is cut to the changed row.

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

```json theme={null}
{
  "success": true,
  "data": {
    "changes": [
      {
        "id": "mon_2f3L73izJTdaA1AQ.1794939656196.HJ5ZyIKOK5CtGMcA",
        "monitorId": "mon_2f3L73izJTdaA1AQ",
        "monitorName": "Page that changes",
        "at": "2026-11-17T18:20:53.979Z",
        "url": "https://httpbin.org/uuid",
        "changeStatus": "changed",
        "creditsUsed": 1,
        "costUsd": 0.002
      }
    ]
  },
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "8b28bbea-f081-48d0-9597-b51d276f7703"
}
```

The list leaves out the diff. `GET /v1/monitor/changes/{id}` reads one row with its `diff`, and its `json` when the monitor compares fields.

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

```json theme={null}
{
  "success": true,
  "data": {
    "id": "mon_2f3L73izJTdaA1AQ.1794939656196.HJ5ZyIKOK5CtGMcA",
    "monitorId": "mon_2f3L73izJTdaA1AQ",
    "monitorName": "Page that changes",
    "at": "2026-11-17T18:20:53.979Z",
    "url": "https://httpbin.org/uuid",
    "changeStatus": "changed",
    "creditsUsed": 1,
    "costUsd": 0.002,
    "diff": "@@ -1,3 +1,3 @@\n {\n-  \"uuid\": \"0714c38d-30cf-4c11-9c7a-801260afcaba\"\n+  \"uuid\": \"ec011f90-1296-47af-8911-bad9f9aa5314\"\n }\n\\ No newline at end of file\n"
  },
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "98aab511-d588-41e7-bf96-356179cd0cf3"
}
```

## Limits and errors

* A monitor id that does not exist, or a check or change id that is not yours or has expired, returns `404 notFound`.
* A `cursor` that is not the one from the last answer returns `400 invalidRequest`. Send it unchanged.
* A change id comes from the account-wide list. A monitor keeps its last 1,000 rows for its `retentionDays`, and an older id returns `404 notFound`.

## Price

Free. Reading checks and changes costs nothing. The pages a check reads are charged when the check runs, at the price in [Monitors](https://docs.stophy.dev/monitors/overview#price).

## Related

* [Webhooks](https://docs.stophy.dev/monitors/webhooks.md) sends each change to you as it happens.
* [Schedules](https://docs.stophy.dev/monitors/schedules.md) runs a check now, pauses and resumes.
* [Targets](https://docs.stophy.dev/monitors/targets.md) sets the goal and what each check compares.
* [Website change digest](https://docs.stophy.dev/recipes/website-change-digest.md) turns changes into a daily summary.


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