Skip to content
Cloudflare Docs

/screenshot - Capture screenshot

The /screenshot endpoint renders the webpage by processing its HTML and JavaScript, then captures a screenshot of the fully rendered page.

Basic usage

Capture a screenshot from HTML

Sets the HTML content of the page to Hello World! and then takes a screenshot. The option omitBackground hides the default white background and allows capturing screenshots with transparency.

Terminal window
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "Hello World!",
    "screenshotOptions": {
      "omitBackground": true
    }
  }' \
  --output "screenshot.png"

Capture a screenshot from a URL

Terminal window
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "Hello World!",
    "screenshotOptions": {
      "omitBackground": true
    }
  }' \
  --output "screenshot.png"

For more options to control the final screenshot, like clip, captureBeyondViewport, fullPage and others, check the endpoint reference.

Advanced usage

Capture a screenshot of an authenticated page

Some webpages require authentication before you can view their content. To capture a screenshot of these pages, you must provide valid session cookies. The following example navigates to a page that requires login. By providing a valid cookie in the cookies array, Browser Rendering will be able to access the secure content in order to capture the screenshot.

Terminal window
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/protected-page",
    "cookies": [
      {
        "name": "session_id",
        "value": "your-session-cookie-value",
        "domain": "example.com",
        "path": "/"
      }
    ]
  }' \
  --output "authenticated-screenshot.png"

Navigate and capture a full-page screenshot

Navigate to https://cloudflare.com/, changing the page size (viewport) and waiting until there are no active network connections (waitUntil) or up to a maximum of 4500ms (timeout). Then take a fullPage screenshot.

Terminal window
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://cloudflare.com/",
    "screenshotOptions": {
       "fullPage": true
    },
    "viewport": {
      "width": 1280,
      "height": 720
    },
    "gotoOptions": {
      "waitUntil": "networkidle0",
      "timeout": 45000
    }
  }' \
  --output "advanced-screenshot.png"

Customize CSS and embed custom JavaScript

Instruct the browser to go to https://example.com, embed custom JavaScript (addScriptTag) and add extra styles (addStyleTag), both inline (addStyleTag.content) and by loading an external stylesheet (addStyleTag.url).

Terminal window
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "addScriptTag": [
      { "content": "document.querySelector(`h1`).innerText = `Hello World!!!`" }
    ],
    "addStyleTag": [
      {
        "content": "div { background: linear-gradient(45deg, #2980b9  , #82e0aa  ); }"
      },
      {
        "url": "https://cdn.jsdelivr.net/npm/bootstrap@3.3.7/dist/css/bootstrap.min.css"
      }
    ]
  }' \
  --output "screenshot.png"

Capture a specific element using the selector option

To capture a screenshot of a specific element on a webpage, use the selector option with a valid CSS selector. You can also configure the viewport to control the page dimensions during rendering.

Terminal window
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "selector": "#example_element_name",
    "viewport": {
      "width": 1200,
      "height": 1600
    }
  }' \
  --output "screenshot.png"

Many more options exist, like setting HTTP credentials using authenticate, setting cookies, and using gotoOptions to control page load behaviour - check the endpoint reference for all available parameters.

Set a custom user agent

You can change the user agent at the page level by passing userAgent as a top-level parameter in the JSON body. This is useful if the target website serves different content based on the user agent.