How to Capture a Mobile-Sized Webpage Screenshot with Cloudinary

To capture a mobile-sized webpage with Cloudinary, use its URL2PNG website screenshot add-on. Set viewport to the desired width and height, supply a mobile browser user_agent if the site changes its layout based on that value, and set fullpage=false to capture only the viewport. Cloudinary’s documented URL2PNG format places these options after the website URL. The resulting screenshot can then be cropped or resized with Cloudinary transformations. Cloudinary URL2PNG documentation.

For example, an illustrative URL2PNG public ID looks like this:

https://example.com/page/url2png/viewport=390x844|user_agent=YOUR_MOBILE_USER_AGENT|fullpage=false

That is the add-on’s public ID pattern, not a complete Cloudinary delivery URL. Build and sign or eagerly generate the delivery URL through your Cloudinary account and SDK, following the account’s current URL2PNG setup instructions. URL2PNG is an add-on for generating website screenshots; it is separate from Cloudinary’s responsive image delivery features.

1. Choose the viewport and mobile user agent

viewport sets the requested capture dimensions in pixels. Choose dimensions that match the CSS viewport you want to inspect. A screenshot’s pixel dimensions do not by themselves specify a real phone’s CSS viewport or device-pixel ratio, so document those separately when you need repeatable visual comparisons.

A mobile user agent can prompt a site to serve a mobile-specific layout. It does not reproduce every part of a physical phone: the source material does not establish a canonical current device-size matrix or user-agent catalog. Use the user agent your test target expects, and treat old examples as historical. Cloudinary’s older blog uses an iPhone 5-era example with a 640×1136 viewport; that is not a universal modern phone preset. Cloudinary’s mobile screenshot example.

Use fullpage=false when you want the visible viewport only. If you need the whole page, use the full-page option instead; expect the output to be taller and larger. Check the current add-on documentation for the supported option spelling and behavior before relying on a full-page capture in production.

2. Configure Cloudinary and protect screenshot generation

1. Enable and configure the URL2PNG add-on for your Cloudinary account, including any eligibility or third-party terms shown in the console.
2. Construct the URL2PNG public ID from the public target URL and the desired options. Encode URL characters appropriately when constructing the delivery URL, especially reserved characters in the target URL and user-agent value.
3. Use an authenticated eager-generation request or a signed delivery URL. Cloudinary requires add-on transformations to be eagerly generated or signed by default; account settings can change that requirement. Do not put API secrets in browser code.
4. Apply Cloudinary image transformations after capture if you need a fixed card size or crop. Set the output dimensions and crop behavior to suit the destination rather than assuming the viewport itself is the final asset size.
5. Check the Cloudinary console for current add-on availability, account eligibility, quota, and price before launching a workload.

The exact SDK signing calls depend on your Cloudinary SDK and account configuration. Follow Cloudinary’s linked integration guide for the authenticated/eager and signed URL examples rather than hand-assembling a supposedly signed URL.

3. Validate the result

• Confirm the screenshot has the requested pixel dimensions and shows the intended viewport rather than the entire page.
• Check that the target site actually served its mobile layout. Some sites use more than the user-agent string to decide layout.
• Inspect pages with sticky headers, consent layers, delayed content, or lazy-loaded images. A capture can reflect what rendered by capture time, not necessarily every asset a person would see after scrolling.
• Test the generated URL from the environment where it will be delivered. A public webpage must be reachable by the screenshot service; a local development URL or private intranet page is not a public target.
• For a fixed design card, crop or resize the completed screenshot with Cloudinary image transformations and verify that important page content remains visible.

4. Use Cloudinary transformations for the output

URL2PNG creates the screenshot image; Cloudinary transformations can then reshape it for delivery. For instance, a 500×300 crop can fit a preview card, but the correct dimensions and crop mode depend on your design. Keep the captured mobile viewport and the final display dimensions conceptually separate: capture the layout you want to inspect first, then create the presentation-sized derivative.

5. Troubleshooting

Symptom	Likely cause	What to check
URL is rejected or the transformation does not run	The add-on is not enabled, the account is not eligible, or the URL does not follow the URL2PNG delivery format.	Confirm add-on setup and compare the generated public ID and delivery URL with the current Cloudinary documentation.
Unauthorized or forbidden response	The URL is unsigned when signing is required, or the signature was generated for a different URL.	Generate the URL through the Cloudinary SDK or use authenticated eager generation. Keep credentials on the server.
Desktop layout appears in the screenshot	The target site did not receive or honor the mobile user agent, or its responsive breakpoint is based on another condition.	Check the exact user-agent option and requested viewport. Verify the site’s own mobile behavior independently.
Screenshot is unexpectedly tall	Full-page capture is enabled or the option was omitted.	Set fullpage=false for a viewport-only result and inspect the resulting dimensions.
Screenshot is blank, incomplete, or missing images	The page may need more time to render, depend on inaccessible resources, or behave differently for automated requests.	Check that the page is public and inspect its loading behavior. URL2PNG documents a delay option; use it when a fixed wait is appropriate, then verify the result.
Reserved characters break the URL	The target URL or user-agent includes characters that were not encoded correctly in the delivery URL.	Use the Cloudinary SDK’s URL construction and signing support, and encode nested URL values according to the documented format.
Unexpected screenshot generation or cost	Unplanned dynamic URLs may trigger screenshot work when accessed.	Keep the default signed/eager safeguard in place and review current add-on billing and quotas in the console.

6. Performance, reliability, and cost

Each URL2PNG capture requires the service to load and render the target page, so page complexity, network requests, and any deliberate delay affect how long the result takes. Reuse or eagerly generate assets that should be stable instead of letting arbitrary public requests trigger dynamic screenshot generation. For repeatable output, keep the target URL, viewport, user agent, and capture options consistent.

Cloudinary’s add-on console showed these plan listings during the research for this article: Free 50 screenshots/month, Bronze 1,000/$6, Silver 5,000/$30, Gold 15,000/$75, and Titanium 50,000/$200 per month. These observed values may change; verify current quotas, prices, eligibility, and third-party terms in your Cloudinary console before budgeting or publishing them. Signing or eager generation is also an access and cost-control measure because it limits unplanned dynamic screenshot URLs by default.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Its capture options include viewport sizing, device presets, full-page capture, waiting, custom CSS and JavaScript, and more. See the ScreenshotNeo API documentation.

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

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)

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 removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Does a mobile viewport guarantee a mobile layout?

No. The viewport sets capture dimensions; the site may also use the user agent or other signals to select its layout.

Is 640×1136 a recommended current phone size?

No. It appears in Cloudinary’s historical iPhone 5 example. Pick dimensions for your intended CSS viewport and test target.

Can I use URL2PNG for a page behind my login?

The cited URL2PNG guidance describes capturing public websites. It does not establish support for authenticated private pages; check the current add-on documentation for supported authentication options.

Can I remove the signing requirement?

Cloudinary says account settings can allow unsigned add-on transformations. The default is signed or eager generation; review the security and cost implications before changing that setting.