How Async Screenshot Processing Works (Queues, Status, and Retries)

PeekShot processes screenshots asynchronously to handle high volume and ensure reliability. Understanding how async processing works helps you build robust integrations.

How Async Processing Works

The processing flow:

1. Request: You submit a screenshot request via API

2. Queued: Request is added to a processing queue

3. Processing: PeekShot captures the screenshot

4. Complete: Screenshot is ready, fileUrl available

This async approach allows PeekShot to handle many requests efficiently and scale automatically.

Status Values

Screenshots progress through these statuses:

PENDING

Request is queued and waiting to be processed:

• Request received and validated

• Waiting in queue for available resources

• Usually brief, but may be longer during high load

PROCESSING

Screenshot is being captured:

• Page is being loaded and rendered

• Screenshot is being taken

• Image is being processed and stored

• Typically takes 5-30 seconds depending on page complexity

COMPLETE

Screenshot is ready:

• Processing finished successfully

• fileUrl is available

• Image can be downloaded or accessed

• Credits have been deducted

FAILED

Capture failed:

• Error occurred during processing

• Check error message for details

• Credits may have been deducted (see Credits documentation)

• May be retryable depending on error type

Polling vs Webhooks

Polling

Periodically check status by calling the API:

• Simple to implement

• No webhook endpoint needed

• Less efficient (makes many API calls)

• Good for development or low volume

Example polling:

async function pollStatus(requestId) {
  while (true) {
    const response = await fetch(
      `https://api.peekshot.com/v1/screenshots/${requestId}`,
      { headers: { 'x-api-key': API_KEY } }
    );
    const data = await response.json();
    
    if (data.status === 'COMPLETE') {
      return data.fileUrl;
    }
    if (data.status === 'FAILED') {
      throw new Error(data.error);
    }
    
    // Wait before next poll
    await sleep(2000); // 2 seconds
  }
}

Webhooks (Recommended)

Receive notifications when status changes:

• More efficient (no polling needed)

• Real-time updates

• Better for production

• Requires webhook endpoint

See: How to Receive Screenshot Results Using Webhooks for setup.

Retry Logic

Automatic Retries

PeekShot may automatically retry:

• Transient errors (network issues, temporary failures)

• System errors on PeekShot's side

• Some timeout scenarios

Automatic retries happen transparently - you don't need to do anything.

Manual Retries

You can manually retry failed requests:

• For transient errors that automatic retries didn't resolve

• After fixing issues (e.g., URL accessibility)

• When you believe the failure was temporary

See: How to Retry Failed Screenshots Safely for retry strategies.

Best Practices

Polling Intervals

If using polling:

• Start with 2-3 second intervals

• Don't poll too frequently (wastes API calls)

• Don't poll too infrequently (delays results)

• Consider exponential backoff for long waits

Webhook Reliability

For webhooks:

• Make handlers idempotent (handle duplicates)

• Respond quickly (within seconds)

• Handle errors gracefully

• Log webhook events for debugging

See: Designing Idempotent Webhook Handlers (Engineering) for details.

Error Handling

• Check status regularly if using polling

• Handle FAILED status appropriately

• Implement retry logic for transient errors

• Log errors for debugging

Timeout Handling

• Set reasonable timeouts for polling

• Don't wait indefinitely

• Handle cases where processing takes longer than expected