October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsClean PCRecommendedOne scan can reveal what keeps slowing WindowsLook for cleanup and repair opportunities.Run ScanOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
World desk4 min

How to Include a Custom User-Agent in a Screenshot API Request

Screenshot APIs use different User-Agent fields and transports. See working request patterns, verification tips, common fixes, and a ScreenshotNeo alternative.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use the User-Agent field or option documented by the screenshot tool you chose; there is no universal parameter name or request format. For example, Screenshot APIs accepts user_agent in a JSON body, ScreenshotCenter documents a user_agent query parameter, and the command-line tool shot-scraper uses --user-agent. Check the captured page afterward: a successful image response does not necessarily mean the target content loaded.

Put the User-Agent where your provider expects it

A User-Agent is a string sent with a request to identify the client. Screenshot services expose it through different interfaces, so do not assume a field accepted by one service works with another. The documented examples below illustrate three distinct patterns.

Screenshot APIs: send user_agent in the JSON body

Screenshot APIs documents POST /v1/screenshot with a user_agent string in the JSON request body. Supply either url or html. Its API reference shows API-key authentication with an X-Api-Key header; bearer-token authentication is also documented. See the Screenshot APIs reference for the provider’s current request details.

curl -X POST https://screenshotapis.org/v1/screenshot 
  -H "X-Api-Key: YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"url":"https://example.com","user_agent":"Mozilla/5.0 (compatible; ExampleBot/1.0)"}' 
  --output screenshot.png

Replace the example key, URL, and User-Agent with values appropriate to your integration. Keep real API keys out of source control and published examples.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

ScreenshotCenter: use the documented query parameter

ScreenshotCenter’s endpoint reference lists user_agent as an optional query parameter. Use your HTTP client’s query-parameter encoding rather than concatenating an unescaped string: User-Agent values contain characters that need URL encoding. Its help article also shows user_agent in a JSON request object, so confirm which request format applies to the particular endpoint or client you are using. See the ScreenshotCenter documentation.

curl -G "YOUR_SCREENSHOTCENTER_ENDPOINT" 
  --data-urlencode "url=https://example.com" 
  --data-urlencode "user_agent=Mozilla/5.0 (compatible; ExampleBot/1.0)"

Use the actual endpoint and authentication required by your ScreenshotCenter account; this pattern illustrates query encoding, not a substitute endpoint or credential format.

Rank #2
Sale
HTML and CSS: Design and Build Websites
  • HTML CSS Design and Build Web Sites
  • Comes with secure packaging
  • It can be a gift option

shot-scraper: pass --user-agent

For the open-source command-line tool shot-scraper, the documentation identifies --user-agent as the User-Agent header option:

shot-scraper https://example.com --user-agent "Mozilla/5.0 (compatible; ExampleBot/1.0)"

Refer to the shot-scraper documentation for installation, output options, and other CLI flags.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Choose a value and verify the captured page

Use a truthful, purpose-specific string

Set a custom User-Agent for legitimate testing or compatibility work, such as checking how your own site responds to a client identifier. Do not use it to bypass a site’s access controls or terms. A User-Agent alone does not provide login credentials, cookies, or authorization.

Inspect the result, not just the API response

Some screenshot APIs can return an image of a login or error page rather than the page you intended to capture. Screenshot API documentation says a final page status of 401 or 403 indicates the result may be a login or error page. Check the final page status and image content, then address any authentication or cookie requirements. The User-Agent setting is documented configuration; it is not a guarantee that every provider applies it identically across redirects or subresource requests.

Rank #4
Sale
Web Design with HTML, CSS, JavaScript and jQuery Set
  • Brand: Wiley
  • Set of 2 Volumes
  • A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers

Compare request details before adapting an example

When integrating a different provider, check its own documentation for these details rather than copying a field name from another API:

  • Transport and parameter: GET query, POST JSON, or CLI flag, including exact spelling.
  • Authentication: API key, bearer token, or another documented method.
  • Related request controls: whether custom headers and cookies are supported, and how they interact with the User-Agent.
  • Capture behavior: response format, viewport, and wait options relevant to the page you are testing.

These interfaces differ across the documented services; no single format should be treated as a universal screenshot API standard.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Troubleshooting

The target still shows the wrong content

Confirm the User-Agent parameter is spelled and placed exactly as the selected provider documents. Then inspect the captured image and final page status. If the page is a login or error screen, check whether the target requires authentication or cookies; changing the User-Agent by itself will not satisfy those requirements.

The API rejects the request or ignores the value

Check the endpoint’s required method and content type. A JSON property belongs in the request body when the provider documents a JSON body; a query parameter must be URL-encoded when sent in a URL. Do not assume a query parameter, body field, or command-line flag is interchangeable.

The custom value appears not to persist after navigation

Provider documentation describes how to configure the request, but does not establish identical propagation through redirects or every resource request. Test the relevant destination and ask the provider for details if the behavior matters to your integration.

Or skip the browser setup

ScreenshotNeo accepts a custom User-Agent and provides a one-request screenshot API. For example, this cURL call passes the User-Agent as a request parameter and saves the response:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com --data-urlencode user_agent="Mozilla/5.0 (compatible; ExampleBot/1.0)" -o shot.webp

See the ScreenshotNeo API documentation for authentication and request options. Before capture, it accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 shots a month without a card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo’s free plan.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Crashes, No Sound, or Screen Glitches?Free driver scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.