Skip to main content
Start with a call that works, a page that cannot be read and an empty result. Check that your product handles all three before you raise traffic.

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 with DELETE /v1/key. See API keys.

Check every result

  • Test success before you read data.
  • Responses leave out empty fields, so read optional fields with a default. A field you do not see was empty.
  • Read costUsd on each answer and log it with the requestId.
  • Handle a cut result. isTruncated is true when text was cut, and nextOffset says where to read on. See Content filtering.
  • Keep a warning with 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. Without maxAge 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 timeout and a client timeout that is longer. See Timeouts.
  • Set a limit on a crawl and on a search, and a maxCost on a browser task.
  • Stay inside your rate limits. Size your workers to maxConcurrency from GET /v1/concurrency-check.
  • Retry only when retryable is true. Wait retryAfterSeconds, 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 status is completed, failed or cancelled. Read the results within 24 hours.

Watch your balance and 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 at stophy.dev/billing for a job that must not stop. See Pricing.
  • Read your spend with GET /v1/usage/history and your calls with GET /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 its ttl ends.
  • 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, keep onlyMainContent 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 with checkPromptInjection when a model reads it. See Safety and Responsible use.

Watch the service

Call GET /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 the requestId of every call you care about. If an answer is wrong, send feedback. To reach support, email support@stophy.dev with the requestId.