Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Save the job or operation ID returned when you submit asynchronous work, then use the API’s documented retrieval endpoint to check its state. Keep waiting while it is pending; when it reaches a terminal state, inspect whether it succeeded, failed, or was cancelled before reading any result. If the API supports completion webhooks, use one to learn when to retrieve the result instead of checking repeatedly.
What an asynchronous API result looks like
An asynchronous API accepts a request but does not finish the work inside the original response. Instead, it returns an identifier for a job, response, or operation that continues to exist as a resource. As Google’s Drive API documentation puts it, “A long-running operation (LRO) is an API method that takes a longer time to complete than is appropriate for an API response.”
The initial response is therefore usually an acknowledgement, not the finished result. The identifier connects your submission to the later status and output. For example, OpenAI’s background Responses workflow uses a response ID, while Google Cloud long-running operation examples use an operation name. Names, endpoints, states, retention, and result formats vary by API, so use the particular endpoint’s reference rather than assuming a shared convention.
The retrieval sequence
- Submit the work and preserve its identifier. Store the returned job ID, response ID, or operation name somewhere durable enough for your application to resume after a restart. For batch work, also keep the provider’s per-item correlation value; OpenAI Batch API uses a unique
custom_idto associate each result with its originating request. - Check state using the documented retrieval method. Call the status or operation endpoint with the saved identifier. Some APIs provide a normal get operation; Google Compute Engine also documents a
waitmethod. - Continue only while the operation is pending. If the API reports a state such as
queued,in_progress, or an operation property likedone=false, wait for the provider’s recommended interval or use its documented wait mechanism, then check again. - Branch on the terminal outcome. A completed operation is not automatically a successful one. Inspect the status and any error information. Consume output only for success; handle failure and cancellation as distinct outcomes.
- Read the result in the provider’s documented shape. It may be included in the retrieved response, exposed as a result field, or made available through a URI. Google Drive’s documented long-running operation flow provides a download URI after completion.
Do not discard the identifier once the first check returns pending. A transient pending response is an expected state, not evidence that the job failed or that the original submission should be repeated.
#1 Best Overall
Polling implementation: loop, bounds, and outcomes
The state names and functions in this language-neutral example are descriptive, not literal API fields. Replace them with the names and response schema in the API you use.
job = submit_request()
job_id = save(job.identifier)
deadline = current_time() + application_timeout
while current_time() < deadline:
job = retrieve_job(job_id)
if job.is_pending_or_running:
wait(provider_recommended_interval)
continue
if job.is_successful:
return read_result(job)
if job.is_failed:
raise JobFailed(job.error_details)
if job.is_cancelled:
raise JobCancelled()
raise UnexpectedJobState(job.state)
raise JobWaitTimedOut(job_id)This outline deliberately does not prescribe an interval, timeout, or retry count: those are API- and application-specific. Prefer a provider’s recommended polling interval or server-side wait method. Use bounded retries and a maximum elapsed time so a lost, expired, or permanently stuck operation does not make your worker wait forever. A timeout while waiting is not the same as the remote job failing; retain enough context to resume or report that the outcome remains unknown.
OpenAI background Responses
OpenAI’s background mode illustrates the pattern: set background to true, retain the response ID, and retrieve the response while its status is queued or in_progress. Check for completed before reading output. The guide describes response data as temporarily stored to disk for roughly 10 minutes to enable asynchronous execution and polling. This is provider-specific behavior, not a general retention promise; the guide also discusses store settings, so confirm the current retention conditions for your request and project.
Rank #2
- Used Book in Good Condition
Google Cloud long-running operations
Google Cloud examples retrieve an operation using the operation name returned by the initiating call and inspect its done property. One Agent Search example uses a 10-second interval, but that is an example for that product, not a recommended interval for every Google API or any other provider. Google Drive documents continuing with operations.get while done=false, then using the returned download URI after completion.
Google Compute Engine wait
For Google Compute Engine, the documented wait call can reduce repeated requests and the delay before noticing completion compared with frequent get calls. It is best-effort and bounded: it may return while the operation is still unfinished. Check the returned state and call again as needed. The documentation advises keeping retry intervals within the minimum operation-retention period, so do not assume an operation identifier remains retrievable indefinitely.
Polling or webhooks?
| Approach | Good fit | Trade-offs and safeguards |
|---|---|---|
| Polling | Simple clients, providers without completion webhooks, and workflows that need to recover by checking current state. | Repeated status calls add load, and the next poll creates some delay before your application notices completion. Respect the provider’s interval guidance, inspect every response, bound retries, and consider a documented wait endpoint. |
| Webhook | Server-side applications that can expose a secure receiver and want an event when supported work completes. | Requires receiver availability, event validation, and safe handling. Verify signatures where the provider requires it; process events idempotently where possible. The event may carry only an identifier, requiring a separate retrieval call for the result. |
Webhooks and polling can complement each other. A webhook can provide prompt notification, while a retrieval call confirms the current state and obtains the output. A recovery path that can query current state is useful if a notification is delayed or missed. Gemini documents webhooks for supported asynchronous/LRO workloads as an alternative to repeated status checks; availability depends on the operation and provider configuration.
Reliability details that prevent lost or misread results
- Persist identifiers before doing unrelated work. Keep the operation ID with the request context, and keep per-item IDs such as
custom_idfor batch outputs. Without correlation, a valid result can be difficult to match to its input. - Make pending a normal state. Treat
done=false,queued, andin_progressas “check later,” not success and not an automatic reason to submit duplicate work. - Separate terminal from successful. Terminal means no more progress is expected; inspect the documented error or cancellation fields before handling output.
- Handle transient retrieval errors deliberately. Network errors and rate limits may justify a bounded retry according to provider guidance. Avoid tight retry loops, and do not continue polling past the operation’s retention window.
- Secure webhook processing. Follow the provider’s signature-verification instructions. Design event processing to tolerate duplicate delivery; a repeated completion event should not cause duplicate downstream side effects.
- Read event payloads as specified. A callback can announce the finished resource without embedding its full result. Use the event’s identifier to call the provider’s retrieve method when the schema requires it.
Common errors and how to recover
- “Not found” or unknown operation: Check that you saved the exact identifier and are using the correct project, account, region, and endpoint for the original request. Also check whether the documented retention period has elapsed.
- Returning too early with no output: The operation may still be pending. Continue checking at the documented interval and read output only after confirming the API’s success state.
- Reporting a failed job as successful: Do not use a single generic “done” test as a success test. Inspect terminal status and error details; represent failure or cancellation separately.
- Repeated rate limits or unnecessary request volume: Poll less often in accordance with provider guidance, use a documented wait call where appropriate, or use a supported webhook. Avoid multiplying polls across workers for the same operation.
- Webhook arrives but result is missing: Inspect the event schema. If it contains a response or operation ID rather than the data itself, retrieve the result using that reference.
- Webhook processing runs twice: Validate the provider’s event identity and make downstream processing idempotent. A notification should not blindly trigger an irreversible action each time it is delivered.
- Job appears stuck: Compare elapsed time with the provider’s documented limits, inspect status and error fields, and stop at your application deadline. A local wait timeout alone does not prove the provider cancelled the work.
Performance and cost considerations
Polling trades implementation simplicity for status-request volume and some notification delay. A server-side wait operation or webhook can reduce repeated checks, but neither removes the need to handle an unfinished state, errors, or result retrieval. Set sensible application bounds, use provider-specified intervals, and avoid polling more frequently than recommended. There is no universal polling interval or cross-provider performance figure: the documented 10-second Google Agent Search example and OpenAI’s roughly 10-minute temporary storage description apply only to their stated contexts.
Also account for result retention and batch correlation when designing storage. Keep identifiers and request-to-result mappings for the period your workflow needs, but do not assume the provider will retain retrievable output forever. Check current API documentation for retention, cancellation, rate limits, and any charges associated with submission, polling, or completed work; those terms are not uniform across APIs.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If the job you need is a website screenshot, ScreenshotNeo can return the capture directly with one GET request instead of requiring you to run a browser. It accepts asynchronous jobs with signed webhooks when that workflow fits, but the exact job-retrieval schema should be taken from its documentation rather than assumed from another provider’s API.
For a direct capture, create an API key and use the documented endpoint; see the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers state the page verdict and billing outcome. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Free tools Windows power users keep installed
One-click scans. No signup required.
Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Can I retrieve a job result using only the original submission response?
Only if that response already contains the completed output. For asynchronous work, it commonly contains an identifier; use that identifier with the API’s documented retrieval method.
Best Value
Does a webhook always contain the finished result?
No. Depending on the event schema, it may provide a notification and resource ID that you use in a separate retrieval request.
Is a pending status an error?
Not by itself. It means the operation has not reached a terminal outcome; follow the provider’s guidance and check again.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
