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

# Change tracking

> Find out what changed on a page since your API key last read it: new, same or changed, with a diff. Kept 30 days. $1 per 1,000 pages.

`changeTracking` compares a page with the last time your API key read it. It tells you if the page is `new`, `same` or `changed`, and for a change it returns a diff.

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). Change tracking needs one, because Stophy compares the page with what that API key read before. Send `changeTracking` as an object. This request reads a page that changes on every read, to show a change.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://httpbin.org/uuid",
    "formats": [
      "markdown",
      { "type": "changeTracking" }
    ]
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/scrape", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://httpbin.org/uuid",
    formats: [
      "markdown",
      { type: "changeTracking" },
    ],
  }),
});
const { data } = await response.json();
console.log(data.changeTracking.changeStatus);
console.log(data.changeTracking.diff);
```

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

import requests

response = requests.post(
    "https://api.stophy.dev/v1/scrape",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "url": "https://httpbin.org/uuid",
        "formats": [
            "markdown",
            {"type": "changeTracking"},
        ],
    },
)
data = response.json()["data"]
print(data["changeTracking"]["changeStatus"])
print(data["changeTracking"].get("diff"))
```

## Read the response

The first read of a page has nothing to compare with. It returns `new`, with `previousScrapeAt` set to `null` and no diff.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "{\n  \"uuid\": \"33789d8f-642c-49f9-a333-827012a0146f\"\n}",
    "changeTracking": {
      "previousScrapeAt": null,
      "changeStatus": "new",
      "visibility": "visible"
    },
    "metadata": {
      "sourceURL": "https://httpbin.org/uuid",
      "statusCode": 200,
      "contentType": "application/json",
      "cacheState": "miss",
      "scrapeId": "e1b859f9-0c07-4f41-ad30-a1d0d4119b68",
      "costUsd": 0.001
    }
  },
  "id": "e1b859f9-0c07-4f41-ad30-a1d0d4119b68",
  "costUsd": 0.001,
  "requestId": "e1b859f9-0c07-4f41-ad30-a1d0d4119b68"
}
```

Send the same request again. The page has changed, so you get `changed`, the time of the previous read, and a unified diff of the Markdown.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "{\n  \"uuid\": \"86a45d4a-252b-4686-a8a0-3d98b1396796\"\n}",
    "changeTracking": {
      "previousScrapeAt": "2026-11-17T17:45:51.219Z",
      "changeStatus": "changed",
      "visibility": "visible",
      "diff": "@@ -1,3 +1,3 @@\n {\n-  \"uuid\": \"33789d8f-642c-49f9-a333-827012a0146f\"\n+  \"uuid\": \"86a45d4a-252b-4686-a8a0-3d98b1396796\"\n }\n\\ No newline at end of file\n"
    },
    "metadata": {
      "sourceURL": "https://httpbin.org/uuid",
      "statusCode": 200,
      "contentType": "application/json",
      "cacheState": "miss",
      "scrapeId": "b46817b0-e5a1-4113-a98f-a5aff35f6f6c",
      "costUsd": 0.001
    }
  },
  "id": "b46817b0-e5a1-4113-a98f-a5aff35f6f6c",
  "costUsd": 0.001,
  "requestId": "b46817b0-e5a1-4113-a98f-a5aff35f6f6c"
}
```

When nothing changed, `changeStatus` is `same` and there is no `diff`. Every read replaces the stored one, so the next call compares with this call.

## Options

| Field | Type | Default | Effect |
| - | - | - | - |
| `type` | `string` | none | `"changeTracking"`. Required. |
| `modes` | `array of string` | `["git-diff"]` | `git-diff` returns a unified diff of the Markdown. `json` compares fields between this read and the last. Send both to get both. |
| `schema` | `object` | none | With `json` mode: the fields to compare, as a JSON Schema. Up to 100 top-level fields and 32 KB. |
| `prompt` | `string` | none | With `json` mode: what to compare, in plain words, such as `the price and the stock`. 1 to 10,000 characters. |

With `json` mode, `changeTracking.json` holds each field with its `previous` and `current` value, and a field with no earlier value has `null` as `previous`. With no `schema` or `prompt`, the model compares the main facts of the page, such as its title, price and status.

## What is compared

A read is compared with the last read of the same URL with the same `location.country`, `onlyMainContent`, `includeTags`, `excludeTags` and `actions`. Change any of them and you start a new history. The comparison is kept for 30 days after the last read.

## Limits and errors

* Without an API key, the call returns `400 invalidRequest` with the message `formats: changes needs an API key, so the page can be compared with what that key read before. Send the call with your API key, or leave changes out.`
* A diff is cut at 20,000 characters.
* The page is always read live, never from a stored copy, whatever `maxAge` says.

## Price

$1 per 1,000 pages with `git-diff`. With `json` mode, add $3 per 1,000 pages when it returns something.

## Related

* [Monitors](https://docs.stophy.dev/monitors/overview) run a read on a schedule and call you when a page changes.
* [Website change digest](https://docs.stophy.dev/recipes/website-change-digest.md) builds a daily summary of changes.
* [Freshness and caching](https://docs.stophy.dev/scrape/freshness-and-caching.md) explains `maxAge` and stored copies.
* [Product](https://docs.stophy.dev/scrape/product.md) reads a price in a fixed shape.


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