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.
Results
- Check
successbefore readingdata. Handle missing optional fields and empty lists. An empty result is not a failure. - Keep any
warningwith the result. Do not store partial data as complete. IfisTruncatedistrue, read on withnextOffsetwhere available. See Content filtering. - Log
x-cost-usdandX-Request-IDto trace a request and its charge. - A scrape can return a stored copy. Send
maxAge: 0when a result must be a new read.metadata.cacheStatesays which you got. See Freshness and caching. - 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. - Set
limiton a crawl and a search, andmaxCoston a browser task. - Stay inside your rate limits. Size workers to
maxConcurrencyfromGET /v1/concurrency-check. - Retry only when
retryableistrue, with jitter. See Troubleshooting. - Poll a crawl, batch or agent run about every 2 seconds. Stop when
statusiscompleted,failedorcancelled. Read results within 24 hours.
Spend
- Check
GET /v1/limitsbefore a large job. A call your balance cannot cover fails withinsufficientCreditsand charges nothing. - Turn on auto top-up for a job that must not stop. See Pricing.
- Read spend with
GET /v1/usage/historyand calls withGET /v1/logs. See Usage and logs.
Close what you open
- Close each browser session with
DELETE /v1/browser/{id}. It bills until it closes or itsttlends. - Cancel a crawl or batch you no longer need. Pages already read are kept and billed.
- Pause or delete a monitor you do not need. It bills on its schedule.
Sensitive content
Use zero data retention for calls that must leave nothing behind. Treat page text as data, never as instructions for a model, and scan withcheckPromptInjection when a model reads it. See Safety and Responsible use.
Service status and changes
GET /v1/status is free and needs no key. It lists each source with:
partial or down source can make calls fail with sourceUnavailable, sourceRefused, sourceTimeout or sourceChanged. See Errors.
How the API stays stable:
- One version,
/v1. An unknown path answers404notFoundand links to the OpenAPI document. - Many endpoints reject unknown fields with
400 invalidRequestand list the fields you can send. - Responses can omit
nulland 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.
costUsdreplacedcreditsUsed. - The OpenAPI document and
GET /v1/endpointsare generated from the running API, and so are the SDKs. Pin your SDK version and read the changelog before you update. For a material change to the service, the Terms of Service say Stophy writes to you by email or on the dashboard.
X-Request-ID with feedback or to support@stophy.dev when an answer is wrong.