Skip to content
ScreenshotDude

Core concepts

Async jobs

Queue long-running requests, track progress and fetch results.

Add is_async=true to any billable endpoint to process the request in the background. Async jobs are ideal for slow pages, bulk processing and platforms with short function timeouts.

Flow

  1. Send the request with is_async=true. You immediately receive 202 Accepted:
{ "success": true, "job_id": "job_4f8k2m9q1x7c3v5b6n0z8l2p", "status": "Queued" }
  1. Poll GET /v1/jobs/{id} (free) until the status is terminal — or pass webhook_url and wait for the webhook.
  2. Read result from the job object.

You're billed once, when the job completes successfully. The request log shows it with status 201.

Statuses

Status Terminal Meaning
Queued No Accepted and waiting for a worker.
Running No Being processed; progress goes from 0 to 100.
CompletedJob Yes Finished successfully; result holds the output.
Error Yes Processing failed; not billed.
NotFound Yes No job with this id exists in your workspace (or it expired).
BadRequest Yes The original parameters were invalid; not billed.

The job object

{
  "id": "job_4f8k2m9q1x7c3v5b6n0z8l2p",
  "success": true,
  "status": "CompletedJob",
  "endpoint": "/v1/content",
  "created_at": "2026-11-09T10:15:02.120Z",
  "started_at": "2026-11-09T10:15:02.410Z",
  "completed_at": "2026-11-09T10:15:04.032Z",
  "duration_ms": 1622,
  "args": { "url": "https://acme.example", "include_markdown": true },
  "result": { "metadata": { "title": "Acme" }, "links": { "internal": [], "external": [], "social": [] } },
  "progress": 100
}
Field Type Description
id string Job id (job_…).
success boolean true once completed successfully.
status string One of the statuses above.
endpoint string Endpoint path the job was created from.
created_at ISO date When the job was queued.
started_at ISO date | null When a worker picked it up.
completed_at ISO date | null When it reached a terminal status.
duration_ms number | null Processing time.
args object Parameters the job was created with (secrets such as s3_secret_key are redacted).
result any The endpoint's output. For captures: a JSON object with a temporary download url for the file, or the S3 location with s3_url=true. For errors: the error message.
progress number 0–100.

Polling

curl "http://localhost:4000/v1/jobs/job_4f8k2m9q1x7c3v5b6n0z8l2p" \
  -H "x-api-key: $SNAPLENS_API_KEY"

Start at a 1–2 second interval and back off (×1.5) to avoid needless requests. Polling is free but subject to your plan's rate limits.

Retention

Job results are kept for a limited time after completion, then deleted. Download files or store the result promptly — or upload directly to your own bucket with the S3 parameters.