DEVELOPER DOCUMENTATION

One request.
A consistent workflow.

Use https://api.protoscrape.com for requests. Create an account, verify your email, and generate an API key in your workspace. Check GET /v1/engines for current engine availability before submitting jobs.

1. Submit a job

curl https://api.protoscrape.com/v1/jobs \
  -H "Authorization: Bearer $PROTOSCRAPE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-query-001' \
  -d '{"engine":"google_ai_mode","query":"workflow automation tools","country":"US"}'

2. Follow the job ID

A 202 response means the job was accepted. Poll GET /v1/jobs/{job_id} with increasing delays. When it succeeds, retrieve GET /v1/jobs/{job_id}/result. Reading a result does not create a new charge.

3. Choose how long to wait

Use ?wait_seconds=25 for interactive requests. If collection takes longer, the response points to the same job. Reuse the idempotency key when retrying a timed-out submission.

Engine IDs and availability

Google AI Mode is available in early access. Google Search, ChatGPT and Perplexity are in validation and cannot currently accept collection jobs. Check GET /v1/engines for current status.

Plan for real-world responses

AI answers can differ between observations and may not include citations. The initial market is US, English, desktop. GET /v1/engines lists enabled engines and supported options. Incomplete extraction is an error, not a successful billed result.

Errors and safe retries

400: correct the input. 401/403: check your key or verified account. 402: insufficient credits. 409: check idempotency or job state. 410: the original idempotent result has expired. 429: wait for an active job to finish, or wait at least one minute for a request rate limit. 503: check engine availability, then retry with backoff and the same idempotency key.

Download the OpenAPI specification. Use exponential backoff with jitter for transient failures. Idempotency keys are retained for 30 days and must not be reused for different inputs.

Keep keys private

Call the API from your server. Never include secret keys in browser code or URLs. Revoke unused keys in your workspace. No automatic overage charges are enabled. Results and job records are retained for approximately seven days. Requests are limited to 120 per minute per account, with up to 30 job submissions per minute. POST /v1/jobs/{job_id}/cancel releases the reservation for a pending job. Batch submission and customer callback webhooks are not available in this release.