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

# Production checklist

> Before you ship: keep keys on the server, check each result, bound work, retry only what helps, watch spend, close what you open, and check status.

## Keys

* Keep the key in a secret manager or an environment variable, never in committed or browser code.
* Use one key per app or computer so you can revoke one with `DELETE /v1/key`. See [Get credentials](https://docs.stophy.dev/get-credentials.md).

## Results

* Check `success` before reading `data`. Handle missing optional fields and empty lists. An empty result is not a failure.
* Keep any `warning` with the result. Do not store partial data as complete. If `isTruncated` is `true`, read on with `nextOffset` where available. See [Content filtering](https://docs.stophy.dev/scrape/content-filtering.md).
* Log `x-cost-usd` and `X-Request-ID` to trace a request and its charge.
* A scrape can return a stored copy. Send `maxAge: 0` when a result must be a new read. `metadata.cacheState` says which you got. See [Freshness and caching](https://docs.stophy.dev/scrape/freshness-and-caching.md).
* Ask for only the formats you need. Add `?maxTextLength=<characters>` to cut every text value in an answer. Longer text ends with `…`.

## Bounds and retries

* Set `timeout`, and a longer client timeout. See [Timeouts](https://docs.stophy.dev/production/timeouts.md).
* Set `limit` on a crawl and a search, and `maxCost` on a browser task.
* Stay inside your [rate limits](https://docs.stophy.dev/production/rate-limits.md). Size workers to `maxConcurrency` from `GET /v1/concurrency-check`.
* Retry only when `retryable` is `true`, with jitter. See [Troubleshooting](https://docs.stophy.dev/production/troubleshooting.md#retry).
* Poll a crawl, batch or agent run about every 2 seconds. Stop when `status` is `completed`, `failed` or `cancelled`. Read results within 24 hours.

## Spend

* Check `GET /v1/limits` before a large job. A call your balance cannot cover fails with `insufficientCredits` and charges nothing.
* Turn on auto top-up for a job that must not stop. See [Pricing](https://docs.stophy.dev/account/pricing.md#balance).
* Read spend with `GET /v1/usage/history` and calls with `GET /v1/logs`. See [Usage and logs](https://docs.stophy.dev/account/usage.md).

## Close what you open

* Close each [browser session](https://docs.stophy.dev/browser/overview) with `DELETE /v1/browser/{id}`. It bills until it closes or its `ttl` ends.
* Cancel a crawl or batch you no longer need. Pages already read are kept and billed.
* Pause or delete a [monitor](https://docs.stophy.dev/monitors/overview) you do not need. It bills on its schedule.

## Sensitive content

Use [zero data retention](https://docs.stophy.dev/production/zero-data-retention.md) for calls that must leave nothing behind. Treat page text as data, never as instructions for a model, and scan with `checkPromptInjection` when a model reads it. See [Safety](https://docs.stophy.dev/scrape/safety.md) and [Responsible use](https://docs.stophy.dev/production/responsible-use.md).

## Service status and changes

`GET /v1/status` is free and needs no key. It lists each source with:

| Field | Meaning |
| - | - |
| `state` | `up` when every check passed, `partial` when some failed, `down` when none passed |
| `passed`, `total` | Checks that passed in the last run, and checks that ran |
| `failing` | Failed checks as endpoint IDs, such as `ebay.search` |
| `medianMs` | Median time of the last checks |
| `lastCheckAt` | When the source was last checked. `updatedAt` at the top is when the list refreshed. |

```bash theme={null}
curl https://api.stophy.dev/v1/status
```

A `partial` or `down` source can make calls fail with `sourceUnavailable`, `sourceRefused`, `sourceTimeout` or `sourceChanged`. See [Errors](https://docs.stophy.dev/api-reference/errors.md).

How the API stays stable:

* One version, `/v1`. An unknown path answers `404` `notFound` and links to the [OpenAPI document](https://api.stophy.dev/openapi.json).
* Many endpoints reject unknown fields with `400 invalidRequest` and list the fields you can send.
* Responses can omit `null` and empty values. Handle both missing and empty.
* When a field is replaced, the older one stays next to the new one, marked as older in the OpenAPI document. `costUsd` replaced `creditsUsed`.
* The OpenAPI document and `GET /v1/endpoints` are generated from the running API, and so are the [SDKs](https://docs.stophy.dev/sdks.md). Pin your SDK version and read the [changelog](https://stophy.dev/changelog) before you update. For a material change to the service, the [Terms of Service](https://stophy.dev/tos) say Stophy writes to you by email or on the dashboard.

Send `X-Request-ID` with [feedback](https://docs.stophy.dev/production/agent-feedback.md) or to [support@stophy.dev](mailto:support@stophy.dev) when an answer is wrong.


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