Capture Web Page Screenshots via API

The Screenshot service renders any URL in a headless browser and returns a PNG image. Because rendering takes a few seconds, the API is asynchronous: you submit a request, poll for completion, then download the result.

What You'll Learn

  • How to submit a screenshot capture request
  • How the async flow works: PENDING → PROCESSING → COMPLETED
  • How to download the finished screenshot image

Prerequisites

Before you start: You need an API key. Follow the Platform Quick Start to get one.

  • curl (or any HTTP client)
  • A valid API key in the X-API-KEY header

Step 1: Submit a Capture Request

POST the target URL and desired viewport dimensions. The service returns a captureId immediately.

bash
curl -X POST /api/screenshot/capture \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "url": "https://example.com",
    "viewportWidth": 1280,
    "viewportHeight": 800,
    "fullPage": false
  }'
python
import requests, time

# Step 1: Submit
resp = requests.post(
    "/api/screenshot/capture",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "url": "https://example.com",
        "viewportWidth": 1280,
        "viewportHeight": 800,
        "fullPage": False
    }
)
capture_id = resp.json()["data"]["captureId"]
print(f"Capture ID: {capture_id}")
Response — 202 Accepted
{
  "status": "OK",
  "data": {
    "captureId": "cap_7f3a1b2c4d5e",
    "state": "PENDING",
    "createdAt": "2026-03-26T15:00:00Z"
  }
}

The 202 Accepted status confirms the job is queued. Save the captureId for the next step.

Step 2: Poll for Status

Check the capture status using the captureId. The state transitions through PENDING → PROCESSING → COMPLETED (or FAILED).

bash
curl -X GET "/api/screenshot/capture/cap_7f3a1b2c4d5e" \
  -H "X-API-KEY: your-api-key"
python
# Step 2: Poll until complete
while True:
    status = requests.get(
        f"/api/screenshot/capture/{capture_id}",
        headers={"X-API-KEY": "your-api-key"}
    ).json()
    state = status["data"]["state"]
    print(f"State: {state}")
    if state in ("COMPLETED", "FAILED"):
        break
    time.sleep(2)
Response — 200 OK (COMPLETED)
{
  "status": "OK",
  "data": {
    "captureId": "cap_7f3a1b2c4d5e",
    "state": "COMPLETED",
    "url": "https://example.com",
    "imageUrl": "/api/screenshot/capture/cap_7f3a1b2c4d5e/image",
    "fileSize": 284672,
    "completedAt": "2026-03-26T15:00:04Z"
  }
}

Typical timing: Most captures complete within 3–8 seconds. Poll every 2 seconds to balance responsiveness and API calls.

Step 3: Download the Image

Fetch the PNG from the imageUrl returned in the status response.

bash
curl -o screenshot.png \
  -H "X-API-KEY: your-api-key" \
  "/api/screenshot/capture/cap_7f3a1b2c4d5e/image"
python
# Step 3: Download
image_url = status["data"]["imageUrl"]
img = requests.get(image_url, headers={"X-API-KEY": "your-api-key"})
with open("screenshot.png", "wb") as f:
    f.write(img.content)
print(f"Saved {len(img.content)} bytes to screenshot.png")

The image is served as image/png with a Content-Disposition: attachment header. Screenshots are retained for 24 hours before automatic deletion.

Integration Tips

  • Use fullPage: true to capture the entire scrollable page, not just the viewport.
  • Webhook callback: Set "callbackUrl" in the request to receive a POST notification when the capture completes, instead of polling.
  • Link previews: Capture thumbnails for URL-sharing features (use a small viewport like 600x400).
  • Visual regression: Capture screenshots before and after deployments and diff them programmatically.

Next Steps