API documentation

Environment profiles

Set device signals, CSS media, color preference, motion preference, locale, and time zone.

Environment object

request.json

"environment": {
  "device": "pixel_7",
  "color_scheme": "dark",
  "reduced_motion": "reduce",
  "media": "screen",
  "locale": "en-US",
  "timezone": "America/Los_Angeles"
}

device accepts desktop, iphone_14, pixel_7, or ipad. Mobile presets apply the installed Playwright device user agent, touch support, and mobile signals. The viewport and device_scale_factor remain explicit. Selecting a device does not change the output dimensions.

Preferences

color_scheme: null/browser default, light, dark, or no-preference. This drives prefers-color-scheme.
reduced_motion: null/browser default, reduce, or no-preference. Screenshots also disable active animations at capture time.
media: null/output default, screen, or print. Null keeps normal screen media for screenshots and print media for PDFs. An explicit value is applied before the target loads, so its CSS and matchMedia logic see the selected medium.
locale: a 2–64 character BCP 47-style language tag such as en-US, fr-FR, or ja.
timezone: a valid IANA zone such as UTC, Europe/Paris, or America/New_York. Abbreviations such as EST are not portable.

Recommended explicit viewports

Common CSS viewports are iPhone 14 390×664, Pixel 7 412×839, and iPad 810×1080. Use density 1 for compact deterministic screenshots or the target hardware density when the plan’s output dimensions and pixel cap allow it. Account limits are evaluated after density: output width is ceil(width × density).

What this does not guarantee

A profile controls browser-visible signals, not a real physical device, GPS, network speed, or OS font inventory. Profiles render in the request’s pinned Chromium, Firefox, or WebKit build. Sites can still vary by their own geolocation, account, cookies, experiment assignment, or server-side detection. Supply authorized same-origin headers when you need controlled application state.