Viewport & Full Page

When the API takes a screenshot, it opens the page in a real browser window. The viewport is that window — its width and height determine how the page renders. A wider viewport shows a desktop layout; a narrower one triggers mobile or tablet breakpoints. Getting the viewport right is the first step to getting the screenshot you need.

Viewport size

By default, the browser window is 1280 pixels wide and 800 pixels tall — a standard desktop size. You can change it with the width and height parameters.

Parameter	Type	Default	Description
`width`	integer	1280	Viewport width in pixels. Range: 320–3840.
`height`	integer	800	Viewport height in pixels. Range: 200–2160.

The page renders exactly as it would in a real browser at that size. If a site has responsive breakpoints at 768px and 1024px, setting width=600 will trigger the mobile layout, and width=900 will show the tablet version.

Example: Full HD viewport

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&width=1920&height=1080" \
  -o screenshot.png

Example: Narrow mobile-width viewport

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&width=375&height=812" \
  -o mobile.png

Device presets

Instead of setting width and height manually, you can use the device parameter to pick a preset. Each preset sets the viewport size and a matching User-Agent string, so the site thinks it's being viewed on that type of device.

Parameter	Type	Default	Description
`device`	string	`desktop`	Device preset: `desktop` (1280×800), `mobile` (375×812, iPhone UA), or `tablet` (768×1024, iPad UA).

The mobile preset uses an iPhone viewport and User-Agent, so sites that serve different HTML or redirect mobile users will show their mobile version. Same idea for tablet with iPad dimensions.

When to use device vs custom width/height

Use device when you want the site to believe it's on a phone or tablet — the User-Agent matters for sites that do server-side device detection. Use custom width and height when you just need a specific viewport size but don't care about the User-Agent (for example, testing responsive CSS breakpoints).

Example: Mobile screenshot

const response = await fetch('https://api.screenshotrun.com/v1/screenshots', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    device: 'mobile',
    format: 'png',
  }),
});

const { data } = await response.json();
console.log(data.links.image);

import requests

response = requests.post(
    "https://api.screenshotrun.com/v1/screenshots",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "url": "https://example.com",
        "device": "mobile",
        "format": "png",
    },
)

data = response.json()["data"]
print(data["links"]["image"])

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://api.screenshotrun.com/v1/screenshots', [
        'url' => 'https://example.com',
        'device' => 'mobile',
        'format' => 'png',
    ]);

$data = $response->json('data');

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

require "net/http"
require "json"

uri = URI("https://api.screenshotrun.com/v1/screenshots")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  url: "https://example.com",
  device: "mobile",
  format: "png",
}.to_json

response = http.request(request)
data = JSON.parse(response.body)["data"]

body, _ := json.Marshal(map[string]any{
        "url": "https://example.com",
        "device": "mobile",
        "format": "png",
    })

req, _ := http.NewRequest("POST",
    "https://api.screenshotrun.com/v1/screenshots",
    bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]any
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

var client = HttpClient.newHttpClient();

var body = """
    {
        "url": "https://example.com",
        "device": "mobile",
        "format": "png"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.screenshotrun.com/v1/screenshots"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Example: Tablet screenshot

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

For a full list of device presets with their exact viewport sizes and User-Agent strings, see the Devices page.

Retina (HiDPI)

Modern screens pack twice as many pixels into the same space — Apple calls it Retina, others call it HiDPI. If your screenshots look slightly blurry on a high-resolution display, or you need extra-sharp images for design work, enable the retina parameter.

Parameter	Type	Default	Description
`retina`	boolean	`false`	Capture at 2× resolution. Output image will be twice the viewport dimensions.

With a 1280×800 viewport and retina=true, the output image is 2560×1600 pixels. The page layout stays the same — everything just renders at double the pixel density.

When to use retina

Design portfolios and presentations where image quality matters
Thumbnails that need to look sharp on Retina displays
Print materials where higher resolution prevents pixelation

Example: Retina screenshot

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&width=1280&height=800&retina=true" \
  -o retina.png

Note

Retina screenshots are 4× the pixel count (2× width × 2× height), so file sizes will be significantly larger. Consider using format=webp with a lower quality to keep file sizes manageable. See File Type & Quality for details.

Full page screenshots

By default, the API captures only what fits in the viewport — the visible area without scrolling, just like pressing PrtSc on your keyboard. To capture the entire page from top to bottom, including everything you would see by scrolling, set full_page=true.

Parameter	Type	Default	Description
`full_page`	boolean	`false`	Capture the entire scrollable page instead of just the viewport.

How it works

The browser renders the full page, then stitches together viewport-height slices into one tall image. The width stays the same as your viewport width — only the height extends to cover all the content.

Common use cases

Archiving entire web pages for records or compliance
Capturing long landing pages or articles
Creating before/after comparisons during website redesigns
Generating full-page previews for link sharing tools

Example: Full page in WebP

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

const { data } = await response.json();
console.log(data.links.image);

import requests

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

data = response.json()["data"]
print(data["links"]["image"])

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://api.screenshotrun.com/v1/screenshots', [
        'url' => 'https://example.com',
        'full_page' => true,
        'format' => 'webp',
    ]);

$data = $response->json('data');

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

require "net/http"
require "json"

uri = URI("https://api.screenshotrun.com/v1/screenshots")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  url: "https://example.com",
  full_page: true,
  format: "webp",
}.to_json

response = http.request(request)
data = JSON.parse(response.body)["data"]

body, _ := json.Marshal(map[string]any{
        "url": "https://example.com",
        "full_page": true,
        "format": "webp",
    })

req, _ := http.NewRequest("POST",
    "https://api.screenshotrun.com/v1/screenshots",
    bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]any
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result["data"])

var client = HttpClient.newHttpClient();

var body = """
    {
        "url": "https://example.com",
        "full_page": true,
        "format": "webp"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.screenshotrun.com/v1/screenshots"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Tip

The width parameter still controls how wide the full-page capture is. A wider viewport often means a shorter page (less content wrapping), while a narrower viewport produces taller images. Choose the width that matches your target layout.

Combining parameters

All viewport and full-page parameters work together. Here are some practical combinations.

Mobile full-page retina screenshot

Capture a complete mobile page at high resolution — useful for app store screenshots, design reviews, or mobile UX audits.

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

Wide viewport for data dashboards

Dashboards with tables and charts often need more horizontal space. Use a wide viewport to prevent columns from wrapping or charts from shrinking.

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

Tip

If your full-page screenshot shows blank areas where images should be, the page likely uses lazy loading. See Timing & Delay for a JavaScript scroll snippet that triggers lazy-loaded images before capture.