Skip to main content

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 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.
  • 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.
  • 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 limit on a crawl and a search, and maxCost on a browser task.
  • Stay inside your rate limits. Size workers to maxConcurrency from GET /v1/concurrency-check.
  • Retry only when retryable is true, with jitter. See Troubleshooting.
  • 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.
  • Read spend with GET /v1/usage/history and calls with GET /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 its ttl ends.
  • 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 with checkPromptInjection 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:
A 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 answers 404 notFound and links to the OpenAPI document.
  • 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. 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.
Send X-Request-ID with feedback or to support@stophy.dev when an answer is wrong.