Skip to main content
Captures a full-page screenshot of a URL using a headless browser (Puppeteer) and returns a public URL to the image. Cost: 1 credit

​
Endpoint

POST /api/v1/crawl/screenshot

​
Request

​
Headers

HeaderRequiredDescription
AuthorizationYesApiKey ck_... or Bearer <token>
Content-TypeYesapplication/json

​
Body

{
  "url": "https://example.com",
  "options": {
    "width": 1920,
    "height": 1080,
    "timeout": 30000,
    "waitForSelector": null
  }
}

​
Parameters

ParameterTypeRequiredDefaultDescription
urlstringYes-The URL to screenshot
options.widthnumberNo1920Viewport width (320-3840)
options.heightnumberNo1080Viewport height (240-2160)
options.timeoutnumberNo30000Page load timeout in ms (max: 60000)
options.waitForSelectorstringNonullCSS selector to wait for before capture

​
Common Viewport Sizes

DeviceWidthHeight
Desktop HD19201080
Desktop1366768
Tablet7681024
Mobile375667
4K38402160

​
Response

​
Success (200)

{
  "success": true,
  "data": {
    "url": "https://files.example.com/screenshots/abc123.png",
    "width": 1920,
    "height": 1080,
    "timing": {
      "total": 4521
    },
    "creditsUsed": 1,
    "creditsRemaining": 997
  }
}

​
Response Fields

FieldTypeDescription
urlstringPublic URL to the screenshot image
widthnumberViewport width used
heightnumberViewport height used
timing.totalnumberTotal capture time in milliseconds
creditsUsednumberCredits charged (always 1)
creditsRemainingnumberYour remaining credit balance
The screenshot URL is publicly accessible and hosted temporarily. Download and store the image if you need it long-term.

​
Examples

​
Basic Screenshot

curl -X POST https://api.crawlkit.com/api/v1/crawl/screenshot \
  -H "Authorization: ApiKey ck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

​
Mobile Viewport

Capture how a site looks on mobile: 
curl -X POST https://api.crawlkit.com/api/v1/crawl/screenshot \
  -H "Authorization: ApiKey ck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "width": 375,
      "height": 667
    }
  }'

​
Wait for Content to Load

Wait for a specific element before capturing: 
curl -X POST https://api.crawlkit.com/api/v1/crawl/screenshot \
  -H "Authorization: ApiKey ck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "waitForSelector": ".content-loaded"
    }
  }'

​
Slow-Loading Page

Increase timeout for pages that load slowly: 
curl -X POST https://api.crawlkit.com/api/v1/crawl/screenshot \
  -H "Authorization: ApiKey ck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-website.com",
    "options": {
      "timeout": 60000
    }
  }'

​
Download the Screenshot

# Get the screenshot URL
RESPONSE=$(curl -s -X POST https://api.crawlkit.com/api/v1/crawl/screenshot \
  -H "Authorization: ApiKey ck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}')

# Extract and download the image
IMAGE_URL=$(echo $RESPONSE | jq -r '.data.url')
curl -o screenshot.png "$IMAGE_URL"

​
Error Responses

​
Invalid URL (400)

{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "URL must include protocol (http:// or https://)"
  }
}

​
Unauthorized (401)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

​
Insufficient Credits (402)

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "You have 0 credits remaining"
  }
}

​
Timeout (408)

{
  "success": false,
  "error": {
    "code": "TIMEOUT",
    "message": "Page load timed out after 30000ms"
  }
}

​
Screenshot Failed (502)

{
  "success": false,
  "error": {
    "code": "CRAWL_FAILED",
    "message": "Failed to capture screenshot"
  }
}

​
Use Cases

Website Monitoring

Track visual changes on websites

Social Media Previews

Generate preview images for links

PDF Generation

Convert web pages to images for reports

Archiving

Save snapshots of web content

​
Tips

If the page loads content dynamically (like with JavaScript), use waitForSelector to ensure the content is visible before the screenshot is taken.
Use desktop size (1920x1080) for full layouts, mobile size (375x667) for responsive testing.
Pages with lots of images or JavaScript may need more time. Increase timeout to 60000ms for these.
Screenshot URLs are temporary. Download and store the images if you need them long-term.