How to Ask an AI Agent to Screenshot a Webpage at a Specific Viewport Size

To get a screenshot at a specific size, tell the agent the exact URL and the viewport width and height in CSS pixels, and ask it to set those dimensions before navigation. Also specify whether you want the visible viewport, the full scrollable page, or one element; when the page is ready; the image format; and where to save it.

For example:

Using Playwright, open https://example.com with a 1280 × 800 CSS-pixel viewport set before navigation. Wait until the main content is visible. Capture only the current viewport as a PNG, save it as /tmp/page.png, then report the viewport dimensions, capture scope, and file path.

This is a prompt template, not a claim that the example URL was captured. If you use a different browser automation tool, keep the same requirements and ask the agent to state which settings it applied.

1. What to specify in your request

A precise request removes ambiguity the agent would otherwise have to resolve. Include each item that matters to your task:

1. URL: Give the complete page address, including any path or query parameters needed to reach the intended state.
2. Viewport width and height: Give both values and say “CSS pixels” when you mean browser layout dimensions, such as 1280 × 800 CSS pixels.
3. When to set the viewport: Ask for it to be set before navigation if the page responds to viewport size during initial rendering.
4. Readiness condition: State what should be visible or ready before capture, such as a named heading, a chart, or the main content. A relevant page condition is more useful than an arbitrary delay.
5. Capture scope: Choose the visible viewport, full scrollable page, or a particular element.
6. Output format and destination: Name the format, such as PNG, and a path or filename the agent can write in its environment.
7. Emulation and output scale: If needed, specify mobile behavior separately from dimensions, and distinguish CSS-pixel output from device-scaled output.
8. Report back: Ask the agent to report the settings it applied and where it saved the file.

Asking the agent to report configuration makes the result easier to inspect. It does not prove that the page rendered correctly, so check the image when visual correctness matters.

2. Viewport dimensions, image pixels, and device emulation

A viewport is the browser’s layout area. In Playwright, page.setViewportSize({ width, height }) sets its width and height in pixels. Playwright’s Page API recommends setting viewport size before navigation for pages that may react to it, and notes that changing it also resets screen. When you need more control over screen and viewport properties, configure them on the browser context. See the [Playwright Page API](https://playwright.dev/docs/api/class-page).

Viewport dimensions do not necessarily equal the screenshot file’s pixel dimensions. Playwright MCP documents a screenshot scale setting: css uses CSS-pixel sizing, while device uses device-pixel-ratio scaling. If exact image dimensions matter, ask for both the viewport and the screenshot scale. See [Playwright MCP screenshot options](https://playwright.dev/mcp/tools/screenshots).

Changing the viewport alone is not complete phone emulation. Depending on the task, device behavior can also involve screen dimensions, user agent, and touch capability. Ask for the intended device or list the specific properties to emulate. Playwright’s [device emulation guide](https://playwright.dev/docs/emulation) describes these settings.

3. Choose the capture area

Scope	What it captures	When to request it
Viewport	The currently visible browser area	Checking a particular screen layout or fold
Full page	The entire scrollable page	Reviewing a long landing page or document
Element	A chosen element	Capturing one chart, card, or component

A full-page capture is conceptually like a very tall screen showing the whole scrollable page; it is different from a screenshot limited to a fixed viewport. Playwright’s [screenshots guide](https://playwright.dev/docs/next/screenshots) explains this behavior. Its screenshot API exposes a fullPage option, while Playwright MCP supports viewport, full-page, and element captures. The [Chrome DevTools Protocol Page domain](https://chromedevtools.github.io/devtools-protocol/tot/Page/) also documents screenshot formats and clipping options.

4. Copyable prompt templates

Fixed viewport

Using Playwright, navigate to [URL] with a [width] × [height] CSS-pixel viewport set before navigation. Wait until [specific visible condition]. Capture only the visible viewport as [PNG/JPEG/WebP] and save it to [path]. Report the viewport, capture scope, output format, and saved path.

Full-page capture at a chosen viewport

Using Playwright, open [URL] at a [width] × [height] CSS-pixel viewport set before navigation. Wait until [page-ready condition]. Capture the full scrollable page as [format] and save it to [path]. Report the applied viewport and confirm that full-page capture was used.

Mobile-style capture

Using Playwright, open [URL] with [device name or explicit emulation settings], including a [width] × [height] CSS-pixel viewport. Configure screen size, viewport, user agent, and touch behavior as needed before navigation. Wait until [condition], capture [viewport/full page] as [format], save it to [path], and report the emulation settings applied.

Do not call a capture an exact reproduction of a particular phone unless the relevant device properties have actually been configured.

5. Run it yourself with Playwright

If your agent can run JavaScript and install project dependencies, you can give it this self-contained Playwright example. It sets the viewport before navigating, waits for a specific visible heading, and writes a viewport PNG.

import { chromium } from 'playwright';

const browser = await chromium.launch({ headless: true });
const page = await browser.newPage({
  viewport: { width: 1280, height: 800 },
});

try {
  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  await page.getByRole('heading', { name: 'Example Domain' }).waitFor({
    state: 'visible',
  });
  await page.screenshot({ path: '/tmp/page.png', type: 'png' });
} finally {
  await browser.close();
}

Install Playwright in your project and install its supported browser binaries according to the [official Playwright getting-started instructions](https://playwright.dev/docs/intro). The sample assumes the heading is present; replace the URL and readiness locator with ones appropriate to the target page. The output path must be writable in the environment running the script.

Full-page or element variants

For a full-page capture, use the same setup and change the screenshot call to:

await page.screenshot({ path: '/tmp/page-full.png', fullPage: true, type: 'png' });

For one element, target it explicitly and capture that locator:

const chart = page.locator('[data-testid="chart"]');
await chart.waitFor({ state: 'visible' });
await chart.screenshot({ path: '/tmp/chart.png', type: 'png' });

Use a stable selector that identifies the intended element. If the element is below the fold, Playwright’s locator screenshot operation can scroll it into view; ask the agent to report that the capture was an element screenshot so it is not mistaken for a viewport image.

Common Playwright adjustments

• Use a longer navigation timeout: pass timeout in milliseconds to page.goto when the site is slow. Avoid making timeouts unlimited in unattended jobs.
• Wait for a different state: use a locator for the page’s actual ready signal. A fixed waitForTimeout can help with a known animation but is less reliable than waiting for the content you need.
• Set screenshot scale: Playwright’s Page screenshot API offers scale: 'css' or scale: 'device'. Choose based on whether you need CSS-sized output or device-pixel-scaled output; consult the [screenshot API](https://playwright.dev/docs/api/class-page#page-screenshot).
• Set context properties: use a browser context when screen, device scale factor, mobile behavior, or other emulation properties need to be controlled together. See [Playwright emulation](https://playwright.dev/docs/emulation).

6. Make the result verifiable

Ask the agent to return a short capture summary alongside the file:

Report: final URL, viewport width × height in CSS pixels, device emulation settings, readiness condition, capture scope, image format and scale, and output path. If any setting could not be applied or the file could not be saved, say so explicitly.

This summary can reveal common mistakes: a viewport set after navigation, a full-page image when you asked for the visible viewport, or a mobile-sized viewport without phone emulation. For strict checks, inspect the image dimensions and the rendered content separately; the reported configuration alone cannot confirm visual correctness.

7. Performance, reliability, and cost

Browser screenshot work has setup and page-loading costs. Reuse a browser process for multiple captures when appropriate, but isolate pages or contexts when tasks need different viewport or emulation settings. Wait for the particular content required rather than adding a long fixed delay to every run. Full-page captures and high device-scale output can create larger images and take more time or memory than a viewport capture; request them only when the task needs them.

Reliability depends on the page and its environment: network requests, authentication, consent dialogs, animations, lazy-loaded content, and bot checks can affect what appears. Use a relevant readiness condition, handle required authentication explicitly, and have the agent report navigation or capture failures rather than silently saving an incomplete result. A screenshot script also needs an installed browser and permission to write to its destination.

With local Playwright, cost depends on the infrastructure and browser environment you run; this article does not assign a universal per-capture price. If you need an API instead of maintaining browser setup, ScreenshotNeo offers a per-plan allowance described below.

8. Troubleshooting

Symptom	Likely cause	Fix
The layout has the wrong width or height	The viewport was omitted, misstated, or set after navigation	Specify both dimensions in CSS pixels and set them before goto.
The screenshot file has unexpected pixel dimensions	CSS viewport size and screenshot scale were confused	Specify viewport dimensions and CSS/device screenshot scale separately.
The page looks like desktop despite a narrow viewport	Only the viewport changed; device properties were not emulated	Configure the intended screen, user agent, touch, and other required properties.
The screenshot is much taller than expected	Full-page mode was enabled	Request only the visible viewport and omit fullPage: true.
The page is blank or content is missing	Capture ran before the needed content appeared, or navigation failed	Wait for a specific visible element and report navigation errors. Check whether the page requires authentication or blocks automation.
A chart or image is incomplete	It may load after the initial document or after scrolling	Wait for that element or its loaded state; for lazy content, use the page’s appropriate scroll or readiness logic before full-page capture.
Navigation or locator wait times out	The site is slow, the condition is wrong, or the content is unavailable	Check the URL and locator, choose a realistic timeout, and inspect navigation errors.
The image cannot be saved	The destination directory does not exist or is not writable	Choose a writable path and create its parent directory where permitted.
A phone-specific layout is still inaccurate	Viewport dimensions alone do not reproduce all device behavior	Specify and configure device emulation properties; compare the result at the intended device scale.

9. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. It returns a screenshot or PDF from one GET request, and its parameter names also work with the names used by other screenshot APIs, which can make switching easier. You can set viewport dimensions with the API options in the ScreenshotNeo documentation.

For example, this cURL request captures a page. Adapt the target URL and add the documented viewport options for your required width and height:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response indicates the page verdict and billing status in headers. An MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan. See the docs for the API options and sign up for 1,000 free screenshots a month with no card.

10. FAQ

Should I say “screen size” or “viewport size”?

For browser layout, say “viewport” and provide width and height in CSS pixels. Say “screen” separately when you mean the emulated device screen.

Does asking for a viewport guarantee the page will fit?

No. It sets the browser’s layout area. Page content may overflow, be hidden, or require scrolling; specify full-page capture if you need the entire document.

Can the agent prove it took the screenshot at the requested size?

It can report the applied settings, and you can inspect the output dimensions and image. Neither check alone establishes that every page element rendered as intended.