Screenshots

The Screenshots API allows you to capture high-quality screenshots of any webpage. Perfect for visual testing, content verification, social media previews, and automated monitoring. All screenshots are processed asynchronously as jobs.

Important: Creating a screenshot returns only a job ID and metadata. The actual screenshot URL is generated after processing completes because it is a short‑lived, signed URL. Retrieve it by polling /v1/crawl/{id} until the status is completed or by calling GET /v1/screenshots?job_id=... to issue a fresh 15‑minute signed URL.

Quick example

Capture a high-quality screenshot of any webpage:

curl https://api.supacrawler.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "desktop",
    "full_page": true,
    "format": "png"
  }'

Job created

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "screenshot",
  "status": "processing",
  "status_url": "/v1/crawl/550e8400-e29b-41d4-a716-446655440001",
  "url": "https://example.com",
  "metadata": {
    "device": "desktop"
  }
}

curl https://api.supacrawler.com/api/v1/crawl/550e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer YOUR_API_KEY"

Screenshot ready

{
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "screenshot",
  "status": "completed",
  "data": {
    "url": "https://example.com",
    "screenshot": "https://storage.supacrawler.com/screenshots/550e8400-e29b-41d4-a716-446655440001.png",
    "metadata": {
      "device": "desktop",
      "format": "png",
      "width": 1920,
      "height": 1080,
      "file_size": 245760,
      "load_time": 1250
    }
  }
}

Example screenshot output:

Example screenshot of a webpage captured using the Screenshots API

Desktop screenshot (1920x1080) • PNG format • Full page capture

The screenshot job response model

Screenshot jobs return information about the job status and results when completed.

Properties

Name
success
Type
boolean
Description
Indicates whether the screenshot job operation was successful (creation response only).
Name
job_id
Type
string
Description
Unique identifier for the screenshot job.
Name
type
Type
string
Description
The type of job. Always screenshot for screenshot jobs.
Name
status
Type
string
Description
Current status of the job: processing, completed, failed.
Name
status_url
Type
string
Description
URL to check the job status and retrieve results (creation response only).
Name
url
Type
string
Description
The URL that was screenshotted (creation response only).
Name
screenshot
Type
string
Description
URL to the generated screenshot image. Only present on completion. This is a 15-minute signed URL from a private bucket.
Name
metadata
Type
object
Description
Screenshot metadata and device information.
- Name
  width
  Type
  integer
  Description
  Screenshot width in pixels.
- Name
  height
  Type
  integer
  Description
  Screenshot height in pixels.
- Name
  device
  Type
  string
  Description
  The device type used for the screenshot.
- Name
  format
  Type
  string
  Description
  Image format (png, jpeg, webp).
- Name
  quality
  Type
  integer
  Description
  Image quality (1-100, for JPEG/WebP).
- Name
  file_size
  Type
  integer
  Description
  File size in bytes (completion response only).
- Name
  load_time
  Type
  integer
  Description
  Page load time in milliseconds (completion response only).
- Name
  device_scale
  Type
  number
  Description
  Device pixel ratio used.

POST/v1/screenshots

Create a screenshot job

This endpoint creates a new screenshot job that will capture a screenshot of the specified webpage. The job runs asynchronously, and you can check its status and retrieve the screenshot using the returned job ID.

Required attributes

Name
url
Type
string
Description
The URL of the webpage to capture. Must be a valid HTTP or HTTPS URL.

Optional attributes

Name
device
Type
string
Description
Device type: desktop (default), tablet, mobile, or custom.
Name
full_page
Type
boolean
Description
Whether to capture the full page or just the viewport (default: false).
Name
format
Type
string
Description
Image format: png (default), jpeg, or webp.
Name
quality
Type
integer
Description
Image quality from 1-100 (default: 80, applies to JPEG/WebP).
Name
width
Type
integer
Description
Custom viewport width (when device=custom).
Name
height
Type
integer
Description
Custom viewport height (when device=custom).
Name
device_scale
Type
number
Description
Device pixel ratio (1.0, 2.0, 3.0). Used for high-DPI displays.
Name
is_mobile
Type
boolean
Description
Mobile emulation flag for custom device configurations.
Name
has_touch
Type
boolean
Description
Touch events support for mobile emulation.
Name
is_landscape
Type
boolean
Description
Landscape orientation for device emulation.
Name
delay
Type
integer
Description
Delay before screenshot in seconds.
Name
timeout
Type
integer
Description
Page load timeout in seconds (default: 60).
Name
wait_for_selector
Type
string
Description
CSS selector to wait for before taking screenshot.
Name
wait_until
Type
string
Description
Page load state to wait for: load, domcontentloaded, or networkidle.
Name
scroll_delay
Type
integer
Description
Delay between scrolls for full page screenshots (milliseconds).
Name
click_selector
Type
string
Description
CSS selector to click before taking screenshot.
Name
hide_selectors
Type
array
Description
Array of CSS selectors to hide before screenshot.
Name
block_ads
Type
boolean
Description
Block advertisements (default: false).
Name
block_cookies
Type
boolean
Description
Block cookie banners (default: false).
Name
block_chats
Type
boolean
Description
Block chat widgets (default: false).
Name
block_trackers
Type
boolean
Description
Block tracking scripts (default: false).
Name
block_resources
Type
array
Description
Array of resource types to block: image, stylesheet, script, font.
Name
user_agent
Type
string
Description
Custom user agent string.
Name
headers
Type
object
Description
Custom HTTP headers to send with the request.
Name
cookies
Type
array
Description
Array of custom cookies to set.
Name
dark_mode
Type
boolean
Description
Request dark mode (default: false).
Name
reduced_motion
Type
boolean
Description
Reduce animations and motion (default: false).
Name
high_contrast
Type
boolean
Description
High contrast mode (default: false).
Name
disable_js
Type
boolean
Description
Disable JavaScript execution (default: false).
Name
print_mode
Type
boolean
Description
Emulate print media (default: false).
Name
ignore_https
Type
boolean
Description
Ignore HTTPS certificate errors (default: false).

Request

POST

/v1/screenshots

curl https://api.supacrawler.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "desktop",
    "full_page": true,
    "format": "png",
    "quality": 90,
    "block_ads": true,
    "dark_mode": false
  }'

Response

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "screenshot",
  "status": "processing",
  "status_url": "/v1/crawl/550e8400-e29b-41d4-a716-446655440001",
  "url": "https://example.com",
  "metadata": {
    "width": 1920,
    "height": 1080,
    "device": "desktop",
    "format": "png",
    "quality": 90,
    "device_scale": 1.0
  }
}

GET/v1/crawl/{id}

Get screenshot results

After creating a screenshot job, use the job status endpoint to check progress and retrieve the screenshot when completed. Screenshot jobs typically complete within 5-15 seconds.

Path parameters

Name
id
Type
string
Description
The unique job ID returned when creating the screenshot job.

Request

GET

/v1/crawl/{id}

curl https://api.supacrawler.com/api/v1/crawl/550e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (Processing)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "screenshot",
  "status": "processing"
}

Response (Completed — signed URL, valid 15 min)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "screenshot",
  "status": "completed",
  "data": {
    "url": "https://example.com",
    "screenshot": "https://storage.supacrawler.com/screenshots/550e8400-e29b-41d4-a716-446655440001.png",
    "metadata": {
      "device": "desktop",
      "format": "png",
      "width": 1920,
      "height": 1080,
      "file_size": 245760,
      "quality": 90,
      "load_time": 1250,
      "device_scale": 1.0
    }
  }
}

Screenshots are stored in a private bucket. The API returns a signed URL valid for 15 minutes upon completion.

GET/v1/screenshots

Refresh screenshot URL

Use this endpoint to obtain a fresh 15-minute signed URL for an already-completed screenshot job. The underlying file remains in a private bucket; this endpoint issues a new signed URL on demand.

Query parameters

Name
job_id
Type
string
Description
The screenshot job ID to re-sign.
Name
ttl
Type
integer
Description
Optional signed URL TTL in seconds (default: 900).

JavaScript

const renewed = await client.getScreenshot(job.job_id)
console.log('Renewed screenshot URL:', renewed.screenshot)

Python

renewed = client.get_screenshot(job.job_id)
print('Renewed screenshot URL:', renewed.screenshot)

Response (Completed — renewed signed URL)

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "url": "https://example.com",
  "screenshot": "https://storage.supacrawler.com/screenshots/550e8400-e29b-41d4-a716-446655440001.png",
  "metadata": {
    "device": "desktop",
    "format": "png",
    "width": 1920,
    "height": 1080
  }
}

Device presets

Choose the appropriate device type based on your use case:

Desktop (default)

Viewport: 1920x1080 pixels
Device Scale: 1.0
Use case: Website previews, desktop testing
User Agent: Desktop Chrome browser

Tablet

Viewport: 1024x768 pixels (768x1024 in portrait)
Device Scale: 2.0
Use case: Tablet responsiveness testing
User Agent: iPad Safari browser

Mobile

Viewport: 375x667 pixels
Device Scale: 2.0
Use case: Mobile responsiveness testing, app store screenshots
User Agent: iPhone Safari browser

curl https://api.supacrawler.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "mobile",
    "full_page": true,
    "format": "png",
    "is_landscape": false
  }'

Custom

Viewport: Specify your own width and height
Device Scale: Configurable
Use case: Specific viewport requirements

curl https://api.supacrawler.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "custom",
    "width": 1440,
    "height": 900,
    "device_scale": 1.5
  }'

Advanced features

Content blocking

Block unwanted content for cleaner screenshots:

curl https://api.supacrawler.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "block_ads": true,
    "block_cookies": true,
    "block_chats": true,
    "hide_selectors": [".popup", ".banner", "#newsletter-signup"]
  }'

Dark mode and accessibility

Capture screenshots with accessibility features:

curl https://api.supacrawler.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "dark_mode": true,
    "reduced_motion": true,
    "high_contrast": true
  }'

Wait for content

For dynamic content, wait for specific elements or timeouts:

curl https://api.supacrawler.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://spa-example.com",
    "wait_for_selector": ".content-loaded",
    "delay": 3,
    "timeout": 30
  }'

Best practices

Timing considerations

Use delay parameter for content that loads after page load
Use wait_for_selector for specific elements to appear
For SPAs (Single Page Applications), consider waiting 2-3 seconds
For static sites, the default 1 second delay is usually sufficient

Full page vs viewport

Viewport: Captures only what's visible without scrolling (faster, smaller files)
Full page: Captures the entire page content (slower, larger files)

Polling for results

Check job status every 2-3 seconds for screenshot jobs:

Polling example

# Check status periodically
while true; do
  response=$(curl -s https://api.supacrawler.com/api/v1/crawl/YOUR_JOB_ID \
    -H "Authorization: Bearer YOUR_API_KEY")

  status=$(echo $response | jq -r '.status')

  if [ "$status" = "completed" ]; then
    screenshot_url=$(echo $response | jq -r '.data.screenshot')
    echo "Screenshot ready: $screenshot_url"
    break
  elif [ "$status" = "failed" ]; then
    echo "Screenshot failed"
    break
  fi

  echo "Screenshot processing..."
  sleep 3
done

Screenshot retention

Active jobs: Jobs in processing status are kept in memory
Completed screenshots: Images are stored for 30 days after creation
Failed jobs: Error information is kept for 1 hour

After the retention period, you'll need to create a new screenshot job.

Error handling

Name
400 Bad Request
Description
Invalid URL or screenshot parameters.
Name
401 Unauthorized
Description
Invalid or missing API key.
Name
404 Not Found
Description
Screenshot job ID not found or expired.
Name
429 Too Many Requests
Description
Rate limit exceeded or too many concurrent screenshot jobs.

Error response example

{
  "success": false,
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "screenshot",
  "status": "failed",
  "error": "URL is not accessible or returned an error"
}

Use cases

Visual Testing

Capture screenshots of your web applications across different devices to ensure consistent appearance.

Content Verification

Take screenshots of web pages to verify content changes or monitor for unauthorized modifications.

Social Media Previews

Generate preview images for social media sharing or link previews in applications.

Automated Monitoring

Set up automated screenshot capture to monitor website changes or detect visual regressions.