Skip to main content
The official SDKs wrap the Stophy API for server-side code. Each language page shows a first request and what is specific to that language. To call Stophy from a terminal, use the CLI.

Set your API key

Both SDKs read STOPHY_API_KEY from the environment when you do not pass a key to the client. Keep it in your secret store or your project’s .env file. Keep the key in server-side code. Never commit it or ship it to a browser. The Quickstart shows where to get one. Without an API key, scrape, search, map and parse work within the free limits. parsers, endpoints, signup and signup.poll need no API key. Every other method fails with the code apiKeyRequired.

Methods

Each method sends one call to the Stophy API and returns its JSON as it is. The SDKs have no methods for agent, browser sessions, monitors, webhooks, feedback, usage history or the team calls. Call those over HTTP with the same API key.

Timeouts and retries

  • Each attempt waits up to 70 seconds. The TypeScript SDK does not retry an attempt that timed out. The Python SDK retries it like a network error.
  • Both SDKs retry twice after a network error and after the statuses 429, 500, 502, 503 and 504. The wait starts at 0.5 seconds and doubles, or follows retryAfterSeconds when the API sends it.
  • If the API asks for a wait longer than 60 seconds, the SDK stops and throws with retryAfterSeconds set.
  • A DELETE call is never retried.
Set maxRetries to 0 to turn retries off. For a call that takes longer than 70 seconds, raise the timeout. See Timeouts.

Handle errors

Both SDKs throw a StophyError with code, retryable, retryAfterSeconds, status and the requestId. The message says what went wrong and what to do next. The codes are the API’s own. See Troubleshooting. A call your balance cannot cover fails with insufficientCredits and status 402, and charges nothing. The message names your balance and the most the call can cost. Add money at stophy.dev/billing and send the call again. See Pricing. 401 with apiKeyRequired means the call needs an API key. 401 with unauthorized means the key is wrong or has been revoked.