Keep your key on the server
Store the key in a secret manager or an environment variable, never in code you commit or in browser code. Use one key for each app or computer so you can revoke one without breaking the others. Revoke a key you no longer use withDELETE /v1/key. See API keys.
Check every result
- Test
successbefore you readdata. - Responses leave out empty fields, so read optional fields with a default. A field you do not see was empty.
- Read
costUsdon each answer and log it with therequestId. - Handle a cut result.
isTruncatedistruewhen text was cut, andnextOffsetsays where to read on. See Content filtering. - Keep a
warningwith the data it came with, and do not store a partial result as a complete one.
Set freshness
A stored copy of a page can answer a scrape. WithoutmaxAge you get a copy up to 2 days old, or younger for a site whose pages change often. A copy up to twice that age, at most 7 days, comes back at once as stale while a fresh read runs. Send maxAge: 0 when a result must reflect a new read, and a larger maxAge, up to 30 days, for pages that rarely change. metadata.cacheState says which one you got. A stored copy costs the same as a live read. See Freshness and caching.
Bound work, time and retries
- Set a
timeoutand a client timeout that is longer. See Timeouts. - Set a
limiton a crawl and on a search, and amaxCoston a browser task. - Stay inside your rate limits. Size your workers to
maxConcurrencyfromGET /v1/concurrency-check. - Retry only when
retryableistrue. WaitretryAfterSeconds, add jitter, and stop after three tries. See Troubleshooting. - Poll a crawl, a batch or an agent run about every 2 seconds, and stop when
statusiscompleted,failedorcancelled. Read the results within 24 hours.
Watch your balance and spend
- Check
GET /v1/limitsbefore a large job. A call your balance cannot cover fails withinsufficientCreditsand charges nothing. - Turn on auto top-up at stophy.dev/billing for a job that must not stop. See Pricing.
- Read your spend with
GET /v1/usage/historyand your calls withGET /v1/logs. See Usage and Usage and logs.
Close what you open
- Close every browser session with
DELETE /v1/browser/{id}. A session is billed for the time it is open, until it closes or itsttlends. - Cancel a crawl or a batch you no longer need. The pages already read are kept and billed.
- Delete a monitor you do not need. Each check reads every page and costs what a scrape costs, so a monitor bills on its schedule until you delete it.
Reduce transfer size
Ask only for the formats you need, keeponlyMainContent on, and cut long text with maxChars. Add ?maxTextLength=<characters> to the URL to cut every text value in an answer. Longer text ends with ….
Handle 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.
Watch the service
CallGET /v1/status to tell a Stophy-side problem from one with your request. Pin your SDK version and read the changelog before you update. See Status.
Report problems
Save therequestId of every call you care about. If an answer is wrong, send feedback. To reach support, email support@stophy.dev with the requestId.