An interactive lookup and a scheduled research run need different waiting behavior. A person opening an answer may accept a short wait. A recurring report needs a durable record of work that can finish after the original HTTP request ends.
ProtoScrape supports both through the same job API. You can return a job response promptly or wait up to 25 seconds for a terminal status. Understanding that distinction makes it easier to handle slow responses without accidentally submitting duplicate observations.
A short wait still creates a job
Submit to POST /v1/jobs?wait_seconds=25 when your application can wait briefly. If the job reaches a terminal state during that window, the server returns HTTP 200 with the job object. Check its status: a terminal job is not necessarily successful.
If the window ends first, the API returns HTTP 202 and the same job ID. The work continues. A 202 is an accepted job, not a failed collection and not an instruction to submit another job. After success, fetch the answer from GET /v1/jobs/{id}/result; the submission response itself is a job object.
Use a client timeout longer than the requested wait window, allowing room for network overhead. If your user interface has a tighter deadline, choose a shorter wait or switch to asynchronous submission.
Background collection starts with a saved ID
Omit wait_seconds, or set it to zero, to return without waiting for collection to finish. Persist the returned ID before moving to the next observation. Poll GET /v1/jobs/{id} with increasing delays and some random jitter so clients do not all request updates at the same moment.
Handle every terminal state: succeeded, failed, cancelled and expired. Retrieve the result only after success. Set a deadline in your own application so a disconnected client cannot poll forever, and resume from the saved job ID if the application restarts.
Reading status or retrieving an existing result does not start another collection or consume additional collection credits. Reads still count toward request rate limits, so aggressive polling is unnecessary.
Retry a submission safely
Include an Idempotency-Key with each submission. If a network timeout leaves it unclear whether the API accepted the request, retry with the same key and identical inputs. A new key represents a new observation and can create additional work.
Choose a key that identifies the intended observation, such as a study ID, question ID and scheduled run time. Keep it stable across transport retries. Use a different key for tomorrow’s deliberately repeated measurement. Keys are retained for 30 days, while result retention is shorter; idempotency is not long-term result storage.
Design for limits and unavailable engines
Keep active jobs within the account’s concurrency allowance. A 429 can indicate a concurrency or request-rate limit; wait for capacity and use backoff. A 503 can mean that the requested engine is unavailable. Check GET /v1/engines before continuing instead of repeatedly sending unsupported work.
The current API supports individual job submissions and polling. It does not provide batch submission or customer callback webhooks. Your application can schedule individual jobs over time, respecting its available credits and concurrency.
Choose based on the user experience
Use a short wait for a single lookup with a visible loading state and a way to resume. Use asynchronous jobs for scheduled studies or workflows that must survive a browser tab closing. Both paths share the same result retrieval and credit rules. Start with the working request example, then use the credit planning guide to size your workload.