How to include a custom User-Agent in a screenshot API request
Set a custom User-Agent using your screenshot provider’s documented field or option. See runnable API and CLI examples, troubleshooting tips, and a ScreenshotNeo alternative.
To include a custom User-Agent in a screenshot request, use the field or option documented by your chosen provider. There is no universal parameter name or transport: one API may accept user_agent in a JSON body, another may accept it as a query parameter, and a command-line tool may use a flag. Verify the provider’s endpoint documentation before copying an example.
What the User-Agent changes
A User-Agent is a string sent with an HTTP request to identify the client. A screenshot service may let you choose the value used for page capture, which can help test how a site responds to a particular client identity. The exact requests affected, including redirects and subresources, depend on the provider; do not assume the value is propagated identically everywhere.
Use a truthful value for legitimate compatibility testing, and follow the target site’s terms and access rules. A custom User-Agent does not authenticate you, grant access to restricted content, or guarantee that a site will render the same way it does for another browser.
Find the provider’s request format
- Confirm the exact endpoint and HTTP method.
- Find the documented User-Agent parameter name and location: JSON body, query string, header, or CLI option.
- Check the provider’s authentication and required fields.
- Encode the value with your HTTP client instead of concatenating it into a URL manually.
- Inspect the response and captured page to confirm the intended content loaded.
The examples below demonstrate distinct documented interfaces. Do not mix their field names or authentication details across providers.
POST JSON example: Screenshot APIs
Screenshot APIs documents POST /v1/screenshot with a user_agent string in the JSON body. Its documented request uses an API key and requires either url or html. The provider also documents bearer-token authentication as an alternative to the X-Api-Key header.
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.pngReplace the placeholder key and URL with your own values. Keep real API keys out of source control and published examples. Consult the [Screenshot APIs API reference](https://screenshotapis.org/) for the current endpoint, response format, and authentication requirements.
GET query parameter example: ScreenshotCenter
ScreenshotCenter documents user_agent as an optional query parameter. Encode it as a query parameter using your HTTP client’s URL-encoding support. The precise authentication and other required parameters depend on the endpoint documentation.
curl -G "https://api.screenshotcenter.com/v1/screenshot" \
--data-urlencode "url=https://example.com" \
--data-urlencode "user_agent=Mozilla/5.0 (compatible; ExampleBot/1.0)" \
--output screenshot.pngConfirm the current endpoint and any required credentials in the [ScreenshotCenter endpoint reference](https://screenshotcenter.com/). Do not assume that the example endpoint or parameter set is interchangeable with another provider.
CLI example: shot-scraper
The shot-scraper documentation identifies --user-agent as the option for setting the User-Agent header.
shot-scraper https://example.com \
--user-agent "Mozilla/5.0 (compatible; ExampleBot/1.0)"Install and configure shot-scraper according to its [documentation](https://shot-scraper.datasette.io/). The command above shows the relevant flag; available output and browser options are tool-specific.
Choosing where to put the value
| Interface | Example documented by | Where the value goes |
|---|---|---|
| POST JSON | Screenshot APIs | user_agent in the JSON request body |
| GET query | ScreenshotCenter | user_agent query parameter |
| Command line | shot-scraper | --user-agent option |
These are examples of provider-specific interfaces, not a universal standard. Check whether the same provider separately supports custom headers, cookies, a viewport, wait conditions, or a particular output format. A User-Agent setting alone does not configure those behaviors.
Check the captured result
- Check the HTTP response from the screenshot service for errors.
- Open the image or PDF and verify that it contains the expected page rather than a login, access-denied, or error screen.
- If the provider exposes final page status, inspect it. Screenshot API documentation identifies a final status of
401or403as a sign that the capture may show a login or error page. - Confirm that the target URL, authentication, cookies, and any required wait behavior are correct.
- Compare with a capture using the default User-Agent to see whether the custom value changed the result.
Provider documentation describes its configuration interface; it does not establish a guarantee that every redirect or subresource request receives the same value.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| The API rejects the request or ignores the value | Wrong parameter spelling or location, or an unsupported option | Verify the exact endpoint and whether the field belongs in JSON, the query string, a header, or a CLI flag. |
| The request fails before a capture is returned | Missing required URL or HTML, invalid JSON, or incorrect authentication | Check required fields, content type, key placement, and the provider’s response error. |
| The image shows a login or error page | The target requires authentication, denies access, or returned an error | Inspect the final page status; a 401 or 403 can indicate a login or error page. Check allowed authentication and cookie options. |
| The image is blank or incomplete | The page did not finish loading, content depends on client-side scripts, or the selected User-Agent changes site behavior | Check the target URL and the provider’s documented wait and rendering controls. Try the default value to isolate the cause. |
| Some assets look different from the main page | The provider may apply request settings differently to redirects or subresources | Check the provider’s documentation for the scope of the setting; do not infer universal propagation. |
| Special characters break the request | The value was inserted into a URL without encoding or JSON escaping | Use URL-encoding helpers for query parameters and a JSON serializer for request bodies. |
Reliability, performance, and cost considerations
A custom User-Agent is a request configuration choice, not a performance guarantee. It can change the page a site serves, so validate captures when changing it and keep the value stable when comparing results. The research sources do not establish comparative speed, reliability, or pricing across the example tools; check each provider’s current documentation and plan terms for those details.
For repeatable capture jobs, record the provider, endpoint, User-Agent value, target URL, and relevant capture settings alongside the resulting file. Avoid placing secrets in URLs or logs. Treat login pages, access-denied pages, timeouts, and incomplete captures as outcomes to detect and handle rather than as successful screenshots.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. Its API accepts a URL in one GET request; custom User-Agent is one of its capture options. Use the documented user_agent parameter and check the [ScreenshotNeo API docs](https://screenshotneo.com/docs/) for the full request options.
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.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan and get 1,000 screenshots a month with no card.
FAQ
Is there one standard User-Agent parameter for screenshot APIs?
No. The documented examples use a JSON field, a query parameter, and a CLI flag. Use the interface documented by your selected provider.
Does changing the User-Agent bypass a site’s access controls?
No. It identifies the client string in a request; it does not provide authorization or guarantee access.
Will the custom value apply to every redirect and page asset?
That depends on the provider’s implementation. Confirm its documented behavior rather than assuming it applies uniformly.
What should I do if the screenshot is a 401 or 403 page?
Check the target’s authentication and access requirements and the provider’s supported way to supply any required credentials or cookies. A different User-Agent alone may not resolve it.
