API documentation
A short integration reference: pass the API key correctly, choose a response structure, make the first request, handle errors, and validate mock payloads.
This page collects the rules that do not depend on a specific API method: authentication, response version, error handling, retries, mock API usage, and launch checks.
Use the API reference for API method parameters, schemas, and method-specific examples. Use platform pages to compare coverage and method groups.
Send your API key in the `X-API-Key` header on every Platform API request.
The key does not inherit from a dashboard session. Backend services, workers, and background jobs must attach this header explicitly.
V1 and V2 expose the same API method catalog, but they return different data structures. Pick the version before you build the client and keep it fixed in integration config.
Do not mix V1 and V2 in the same processing flow. It makes mapping, caching, tests, and maintenance harder.
Keeps the source platform response shape with minimal Scrape Storm reshaping.
Migrations, backward compatibility, and clients that already depend on platform-native fields.
Provides a steadier data contract for product code, analytics, and internal services.
New integrations, new services, and any code that does not need the source platform payload shape.
After you choose a version, verify the integration on one live API method: base URL, headers, query parameters, timeout, and error handling.
| HTTP method | GET |
|---|---|
| Endpoint | /api/v2/youtube.com/profile/about-by-user-identifier |
| Example query parameter | user_identifier=mkbhd |
| Header | X-API-Key |
This example uses the YouTube `profile/about-by-user-identifier` API method. Replace `user_identifier` with a test identifier from your own scenario.
Public platform API methods in both V1 and V2 use the same outer envelope: `success`, `status`, and `data`. Collection methods can also include top-level `pagination`.
The version choice changes the schema inside `data`, not the transport wrapper. Use the API reference for the exact payload fields of the API method you selected.
| Response case | Top-level fields | What to read first |
|---|---|---|
| Successful response |
success,
status,
data
|
`data` holds the method payload. |
| Paginated success |
success,
status,
pagination,
data
|
`pagination` stays top-level; method payload still lives in `data`. |
| Error response |
success,
status,
error,
meta
|
Branch on HTTP status and `error.code`. |
Errors use one shared envelope. Branch on HTTP status and `error.code`. The `message` field is fine for display or logs, but not as application control flow.
| HTTP status | Error code | Client action |
|---|---|---|
| 401 |
Unauthorized
UNAUTHORIZED
|
Check the API key and environment. Do not loop the same request with the same key. |
| 422 |
Validation failed
VALIDATION_FAILED
|
Fix the request parameters. The same input will return the same error. |
| 402 |
Insufficient credits
INSUFFICIENT_CREDITS
|
Stop the flow until the balance or account limits are updated. |
| 429 |
Concurrent connections exceeded
CONCURRENT_CONNECTIONS_EXCEEDED
|
Reduce parallel work per API key or queue requests. |
| 429 |
Rate limit exceeded
RATE_LIMIT_EXCEEDED
|
Wait for the published retry interval and coordinate retries across workers. |
| 503 |
Endpoint unavailable
ENDPOINT_UNAVAILABLE
|
Apply API method-level backoff instead of pausing the entire integration if other methods are healthy. |
| 500 |
Internal server error
INTERNAL_SERVER_ERROR
|
Retry with bounded backoff. After the attempt limit, log and escalate through monitoring. |
Mock API methods return static JSON examples without calling the source platforms. Use them for client development, UI work, and parser tests.
| Mock API | https://www.scrapestorm.net/api-mock |
|---|---|
| Example | https://www.scrapestorm.net/api-mock/v2/youtube.com/profile/about-by-user-identifier |
| API reference |
Review these checks before live traffic and before increasing worker concurrency.
New clients use V2. V1 is only allowed for compatibility or migration of an existing integration.
The key lives in secret storage and stays out of frontend code, public repositories, client bundles, and logs.
Client branches depend on HTTP status and `error.code`. `message` is not used in business logic.
`RATE_LIMIT_EXCEEDED` waits for `Retry-After` or `error.retry_after_seconds`. `402` and `422` do not retry unchanged input. `500` and `503` have backoff and an attempt cap.
A queue or rate limiter caps simultaneous requests from workers, cron jobs, and background processes.
Mock validates payload shape. Live API validates real parameters, limits, availability, and credit usage.
Check the cost of the API methods you plan to use before traffic ramps up.
Open the API reference version you need for API method parameters, schemas, and concrete examples. Use Platforms to choose the source and method group.