Screenshots

The Screenshots API allows you to capture, retrieve, list, and delete website screenshots. All endpoints require authentication.

Create a Screenshot

POST /api/v1/screenshots

Queues a new screenshot for capture. Returns a 202 Accepted response with the screenshot object in pending status.

Feature Availability

Some parameters are only available on certain plans. If you use a feature not included in your plan, the API returns a 422 error with a message indicating which feature requires an upgrade.

Note: The table below reflects the current plan configuration. Plan features and limits are managed dynamically and may change over time. Always check your current plan details via GET /api/v1/account for the most up-to-date information.

Feature / Parameter	Free	Starter	Pro	Business
`url`, `width`, `height`	Yes	Yes	Yes	Yes
`full_page`	Yes	Yes	Yes	Yes
`delay`	Yes	Yes	Yes	Yes
`block_cookies`	Yes	Yes	Yes	Yes
`selector`	Yes	Yes	Yes	Yes
`device` (mobile/tablet)	—	Yes	Yes	Yes
`retina`	—	Yes	Yes	Yes
`block_ads`	—	Yes	Yes	Yes
`format: pdf`	—	Yes	Yes	Yes
`webhook_url`	—	Yes	Yes	Yes
`dark_mode`	—	—	Yes	Yes
`css`	—	—	Yes	Yes
`js`	—	—	Yes	Yes
S3 export, geolocation	—	—	—	Yes

Image Retention

Screenshot images are stored temporarily and automatically deleted after the retention period expires. The retention period depends on your current plan and may change if you upgrade or downgrade:

Plan	Retention
Free	24 hours
Starter	48 hours
Pro	7 days
Business	30 days

Once expired, the screenshot metadata remains accessible via the API, but the image file returns 410 Gone. Download images promptly or use webhooks to automate downloads upon completion.

Parameters

Parameter	Type	Required	Default	Description
`url`	string	Yes	—	The URL to capture. Must be a valid HTTP or HTTPS URL.
`width`	integer	No	1280	Viewport width in pixels. Range: 320–3840.
`height`	integer	No	800	Viewport height in pixels. Range: 200–2160.
`format`	string	No	`png`	Image format: `png`, `jpeg`, `webp`, or `pdf`.
`quality`	integer	No	80	Image quality for JPEG and WebP formats. Range: 1–100.
`full_page`	boolean	No	`false`	Capture the full scrollable page instead of just the viewport.
`device`	string	No	`desktop`	Device preset: `desktop`, `tablet`, or `mobile`. Sets appropriate viewport and user-agent.
`block_ads`	boolean	No	`false`	Block ads and trackers before capturing.
`block_cookies`	boolean	No	`true`	Block cookie consent banners before capturing.
`dark_mode`	boolean	No	`false`	Emulate `prefers-color-scheme: dark` media feature.
`delay`	integer	No	0	Wait time in seconds before capture (0–10). Useful for pages with animations or lazy-loaded content.
`timeout`	integer	No	30	Page load timeout in seconds. Range: 5–60.
`css`	string	No	—	Custom CSS to inject into the page before capturing. Max 10,000 characters.
`js`	string	No	—	Custom JavaScript to execute on the page before capturing. Max 10,000 characters.
`selector`	string	No	—	CSS selector of a specific element to capture instead of the full page. Max 500 characters.
`retina`	boolean	No	`false`	Capture at 2x resolution (Retina display).
`webhook_url`	string	No	—	URL to receive a POST notification when the screenshot is ready. See Webhooks.

Example Request

cURL

curl -X POST https://screenshotrun.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "width": 1440,
    "height": 900,
    "format": "webp",
    "full_page": true,
    "device": "desktop",
    "dark_mode": true
  }'

PHP

$response = Http::withToken(env('SCREENSHOT_API_KEY'))
    ->post('https://screenshotrun.com/api/v1/screenshots', [
        'url' => 'https://example.com',
        'width' => 1440,
        'height' => 900,
        'format' => 'webp',
        'full_page' => true,
        'dark_mode' => true,
    ]);

$screenshot = $response->json('data');
echo "Screenshot ID: " . $screenshot['id'];

Python

import requests

response = requests.post(
    "https://screenshotrun.com/api/v1/screenshots",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "url": "https://example.com",
        "width": 1440,
        "height": 900,
        "format": "webp",
        "full_page": True,
        "dark_mode": True,
    }
)

screenshot = response.json()["data"]
print(f"Screenshot ID: {screenshot['id']}")

JavaScript (Node.js)

const response = await fetch("https://screenshotrun.com/api/v1/screenshots", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    width: 1440,
    height: 900,
    format: "webp",
    full_page: true,
    dark_mode: true,
  }),
});

const { data } = await response.json();
console.log(`Screenshot ID: ${data.id}`);

Response (202 Accepted)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "url": "https://example.com",
    "options": {
      "width": 1440,
      "height": 900,
      "format": "webp",
      "quality": 80,
      "full_page": true,
      "device": "desktop",
      "block_ads": false,
      "block_cookies": true,
      "dark_mode": true,
      "delay": 0,
      "timeout": 30,
      "retina": false
    },
    "estimated_time": 5,
    "created_at": "2026-03-09T10:30:00.000000Z",
    "links": {
      "self": "https://screenshotrun.com/api/v1/screenshots/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Get a Screenshot

GET /api/v1/screenshots/{id}

Returns the screenshot object with its current status and details.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://screenshotrun.com/api/v1/screenshots/550e8400-e29b-41d4-a716-446655440000

Response — Completed

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "url": "https://example.com",
    "options": {
      "width": 1440,
      "height": 900,
      "format": "webp",
      "quality": 80,
      "full_page": true,
      "device": "desktop",
      "block_ads": false,
      "block_cookies": true,
      "dark_mode": true,
      "delay": 0,
      "timeout": 30,
      "retina": false
    },
    "file_size": 245760,
    "mime_type": "image/webp",
    "width": 1440,
    "height": 3200,
    "processing_time_ms": 3450,
    "completed_at": "2026-03-09T10:30:05.000000Z",
    "expires_at": "2026-04-09T10:30:05.000000Z",
    "created_at": "2026-03-09T10:30:00.000000Z",
    "links": {
      "self": "https://screenshotrun.com/api/v1/screenshots/550e8400-e29b-41d4-a716-446655440000",
      "image": "https://screenshotrun.com/api/v1/screenshots/550e8400-e29b-41d4-a716-446655440000/image"
    }
  }
}

Response — Failed

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "url": "https://example.com",
    "options": { ... },
    "error": {
      "message": "Page load timed out after 30 seconds.",
      "code": "TIMEOUT"
    },
    "created_at": "2026-03-09T10:30:00.000000Z",
    "links": {
      "self": "https://screenshotrun.com/api/v1/screenshots/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Get Screenshot Image

GET /api/v1/screenshots/{id}/image

Returns the binary image file. Only available for screenshots with completed status.

Example Request

# Download to file
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://screenshotrun.com/api/v1/screenshots/550e8400-.../image \
  -o screenshot.webp

Responses

Status	Description
`200 OK`	Image file with appropriate `Content-Type` header (`image/png`, `image/jpeg`, or `image/webp`)
`404 Not Found`	Screenshot not ready yet (status is `pending` or `processing`)
`410 Gone`	Screenshot image has expired and is no longer available

List Screenshots

GET /api/v1/screenshots

Returns a paginated list of your screenshots, sorted by creation date (newest first).

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Results per page (max 100)
`status`	string	—	Filter by status: `pending`, `processing`, `completed`, `failed`
`sort_by`	string	`created_at`	Sort field
`sort_dir`	string	`desc`	Sort direction: `asc` or `desc`
`date_from`	string	—	Filter screenshots created after this date (ISO 8601)
`date_to`	string	—	Filter screenshots created before this date (ISO 8601)

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://screenshotrun.com/api/v1/screenshots?status=completed&per_page=10&sort_dir=desc"

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "url": "https://example.com",
      "options": { ... },
      "file_size": 245760,
      "mime_type": "image/webp",
      "width": 1440,
      "height": 3200,
      "processing_time_ms": 3450,
      "completed_at": "2026-03-09T10:30:05.000000Z",
      "expires_at": "2026-04-09T10:30:05.000000Z",
      "created_at": "2026-03-09T10:30:00.000000Z",
      "links": {
        "self": "...",
        "image": "..."
      }
    }
  ],
  "links": {
    "first": "https://screenshotrun.com/api/v1/screenshots?page=1",
    "last": "https://screenshotrun.com/api/v1/screenshots?page=5",
    "prev": null,
    "next": "https://screenshotrun.com/api/v1/screenshots?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "links": [
      {"url": null, "label": "« Previous", "page": null, "active": false},
      {"url": "...?page=1", "label": "1", "page": 1, "active": true},
      {"url": "...?page=2", "label": "2", "page": 2, "active": false},
      {"url": "...?page=2", "label": "Next »", "page": 2, "active": false}
    ],
    "path": "https://screenshotrun.com/api/v1/screenshots",
    "per_page": 10,
    "to": 10,
    "total": 48
  }
}

Delete a Screenshot

DELETE /api/v1/screenshots/{id}

Permanently deletes a screenshot and its associated image file. This action cannot be undone.

Example Request

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  https://screenshotrun.com/api/v1/screenshots/550e8400-e29b-41d4-a716-446655440000

Response

Returns 204 No Content on success with an empty body.

Common Use Cases

Capture a mobile screenshot

curl -X POST https://screenshotrun.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "mobile",
    "format": "png"
  }'

Full-page screenshot in dark mode

curl -X POST https://screenshotrun.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "full_page": true,
    "dark_mode": true,
    "format": "webp"
  }'

Screenshot with delay (wait for animations)

curl -X POST https://screenshotrun.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "delay": 3
  }'

Screenshot with webhook notification

curl -X POST https://screenshotrun.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "webhook_url": "https://yourapp.com/webhooks/screenshot"
  }'

Poll until completed (Python)

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://screenshotrun.com/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Create screenshot
response = requests.post(
    f"{BASE_URL}/screenshots",
    headers=headers,
    json={"url": "https://example.com"}
)
screenshot_id = response.json()["data"]["id"]

# Poll until ready
while True:
    status_response = requests.get(
        f"{BASE_URL}/screenshots/{screenshot_id}",
        headers=headers,
    )
    data = status_response.json()["data"]

    if data["status"] == "completed":
        # Download the image
        image_response = requests.get(
            f"{BASE_URL}/screenshots/{screenshot_id}/image",
            headers=headers,
        )
        with open("screenshot.png", "wb") as f:
            f.write(image_response.content)
        print("Screenshot saved!")
        break
    elif data["status"] == "failed":
        print(f"Failed: {data['error']['message']}")
        break

    time.sleep(2)  # Wait 2 seconds before next poll