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

# Freshness and caching

> Choose how old a stored copy of a page may be with maxAge and minAge, skip storing with storeInCache and read a finished scrape again by its id.

Choose between a live read and a stored copy. `metadata.cacheState` tells you which you got. This request always reads the page live:

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "maxAge": 0 }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "metadata": {
      "cacheState": "miss",
      "scrapeId": "c6e9511e-0150-424c-80e0-a8af6cf4f4b8"
    }
  }
}
```

| `cacheState` | What you got |
| - | - |
| `miss` | The page was read live. |
| `hit` | A stored copy that was recent enough. `cachedAt` says when it was made. |
| `stale` | A stored copy older than the default `maxAge`, returned at once while a fresh read runs. Only when the call does not send `maxAge`. |

| Field | Default | Effect |
| - | - | - |
| `maxAge` | 2 days | Accept a stored copy up to this many milliseconds old, at most 30 days (`2592000000`). The default is shorter for a site whose pages change often. Left out, a copy up to twice that age, at most 7 days, comes back at once as `stale` while a fresh read runs. `0` always reads live. |
| `minAge` | none | Answer only from a stored copy at least this many milliseconds old, and never read live. `0` accepts any stored copy. |
| `lockdown` | `false` | Answer only from a stored copy of any age, the same as `minAge: 0`. See [Safety](https://docs.stophy.dev/scrape/safety.md). |
| `storeInCache` | `true` | `false` neither reads nor keeps a stored copy of this page. |

For a page that changes slowly, send `"maxAge": 604800000` to accept a week old copy.

## Reads that are always live

These are never answered from a stored copy and never saved as one: `headers`, `location.languages`, `profile`, `skipTlsVerification`, `actions`, PDF options in `parsers`, `zeroDataRetention`, `storeInCache: false`, and the formats `screenshot`, `rawBase64`, `audio`, `video`, `network`, `branding` and `changeTracking`.

## Read a scrape again

`GET /v1/scrape/{id}` returns an earlier answer, not the current page, using `metadata.scrapeId`. It needs the API key of the account that sent the scrape, returns the original fields including `costUsd`, and adds nothing to your bill.

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

* Answers are kept 24 hours. After that the call returns `404 notFound`: `No scrape with that id. Results are kept for 24 hours.`
* Not kept: a scrape sent with `zeroDataRetention`, one sent without an API key, and an answer with more than 4,194,304 UTF-16 code units of JSON text.
* Without an API key the call returns `401 apiKeyRequired`.

## Limits and errors

* `maxAge` below 0 or not a whole number returns `400 invalidRequest`. A value above 30 days is read as 30 days.
* `minAge` or `lockdown` on a page with no stored copy returns `404 notFound`: `Stophy has no stored copy of that page. Remove minAge or lockdown to read the page live.`
* A stored copy costs the same as a live read. A 404 or 410 page, or one that cannot be read, costs nothing. See [Pricing](https://docs.stophy.dev/account/pricing.md).

To compare a page with your last read, see [Change tracking](https://docs.stophy.dev/scrape/change-tracking.md). To read on a schedule, see [Monitors](https://docs.stophy.dev/monitors/overview).


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