How to Capture a Website Using a Proxy with ScreenshotOne
Pass an external HTTP proxy URL in ScreenshotOne’s `proxy` option. This guide covers setup, runnable requests, location behavior, retries, errors, and alternatives.
To capture a website through a proxy with ScreenshotOne, get an HTTP proxy URL from a proxy provider and pass it as the proxy option in a request to ScreenshotOne’s /take endpoint. Include the target page’s url and your ScreenshotOne access key. The proxy is external: ScreenshotOne’s guide says rotating residential proxies are not included with the product. ScreenshotOne’s proxy guide and options reference document the behavior.
Example request shape (replace all placeholders):
https://api.screenshotone.com/take?proxy=http%3A%2F%2Fuser%3Apassword%40proxy-host%3Aport&access_key=YOUR_ACCESS_KEY&url=https%3A%2F%2Fexample.comThe API call uses HTTPS. The value supplied for proxy must be an HTTP proxy URL; ScreenshotOne documents support for HTTP proxies only. Use a proxy when its network route or IP location is relevant to the capture. It adds routing latency and is not a general fix for screenshot errors.
1. Get an HTTP proxy URL
Obtain the endpoint and any required credentials from a proxy provider. ScreenshotOne names Decodo, Bright Data, and Geonode as examples in its guide; those names are examples, not endorsements or a ranking. Its guide uses residential proxies as an example but recommends starting with a data-center proxy because it costs less, then considering residential or mobile routing only if needed.
Proxy URLs commonly use this structure:
http://USERNAME:PASSWORD@PROXY_HOST:PORTUse the exact scheme, host, port, and authentication format supplied by your provider. Do not assume an HTTPS proxy endpoint will work: ScreenshotOne says the custom proxy option supports HTTP proxies only.
2. Send a ScreenshotOne request with the proxy
These examples make a GET request to /take. The HTTP client encodes query parameters, including proxy credentials. Run them on a server you control; an access key and authenticated proxy URL in a query string can appear in application, proxy, or infrastructure logs. ScreenshotOne’s getting-started documentation describes access-key placement options, including a request header, if you need to avoid putting the key in the query string.
cURL
curl -G 'https://api.screenshotone.com/take' \
--data-urlencode 'access_key=YOUR_ACCESS_KEY' \
--data-urlencode 'url=https://example.com' \
--data-urlencode 'proxy=http://USERNAME:PASSWORD@PROXY_HOST:PORT' \
--output screenshot.pngChange the output filename or request options as appropriate for the returned format and your integration. Keep the proxy value as the provider supplied it; --data-urlencode handles encoding it as a query parameter.
Python
import requests
params = {
"access_key": "YOUR_ACCESS_KEY",
"url": "https://example.com",
"proxy": "http://USERNAME:PASSWORD@PROXY_HOST:PORT",
}
response = requests.get(
"https://api.screenshotone.com/take",
params=params,
timeout=90,
)
response.raise_for_status()
with open("screenshot.png", "wb") as image_file:
image_file.write(response.content)Node.js
const params = new URLSearchParams({
access_key: 'YOUR_ACCESS_KEY',
url: 'https://example.com',
proxy: 'http://USERNAME:PASSWORD@PROXY_HOST:PORT',
});
const response = await fetch(`https://api.screenshotone.com/take?${params}`);
if (!response.ok) {
throw new Error(`ScreenshotOne returned HTTP ${response.status}`);
}
const image = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('screenshot.png', image));For production code, handle HTTP errors and avoid logging the full request URL. Store API keys and proxy credentials in server-side secret storage, and redact them from exception and request logs.
3. Choose proxy location and routing deliberately
A custom proxy takes precedence over ScreenshotOne’s ip_country_code option. Do not set both expecting the country option to override the custom proxy’s location. Pick a provider endpoint in the region whose view you need. ScreenshotOne says random locations are unlikely to be stable for most providers.
If a page’s regional content depends on more than the apparent IP country, ScreenshotOne advises considering language and time-zone preferences too. The relevant options depend on the page and the desired result; consult the request options reference for their accepted values.
Send static assets directly when appropriate
Use proxy_bypass_hosts when matching hostnames serve static assets that do not need the proxy’s IP or location. ScreenshotOne documents this option as routing matching hosts directly through its network while other requests continue through the proxy. Each entry is a hostname pattern, not a full URL. For example, the value should identify a host pattern rather than include https:// or a page path. Confirm the precise pattern syntax in the options reference before relying on it.
4. Decide when to retry through a proxy
Use a proxy retry only when the failure could plausibly be caused by the route or source IP. ScreenshotOne’s guide identifies network errors, selected host-returned errors, and known block-page markers as cases where a proxy may help. A proxy does not guarantee access or defeat every bot check or CAPTCHA.
- Record the original request’s HTTP result and error details without exposing credentials.
- Check whether the failure looks route-related or location-related, rather than a malformed request or account issue.
- Retry once through a deliberate proxy endpoint, keeping the target URL and other settings unchanged so the result is comparable.
- If it succeeds, use the proxy only for the affected targets or cases. If it fails similarly, investigate the page, request settings, or account instead of retrying blindly.
A proxy is unlikely to fix invalid API parameters, missing permissions, bad selectors, storage errors, or quota limits. It adds another service and route whose health can affect the capture.
5. Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Proxy option is rejected or the request fails before capture | The proxy URL is malformed, uses an unsupported scheme, or was encoded incorrectly. | Use an HTTP proxy URL in the provider’s documented format. Pass it as a parameter through a client that encodes query values. ScreenshotOne documents support for HTTP proxies only. |
| Proxy authentication fails | Credentials, escaping, host, or port do not match the provider’s endpoint. | Copy the provider’s current endpoint and credentials. Let your HTTP client encode the complete value; avoid manually encoding it twice. |
| The capture still shows a block page or CAPTCHA | The target may block that proxy, require another route, or present a challenge the proxy does not resolve. | Do not assume any proxy bypasses bot protection. Try a suitable deliberate provider route only if permitted and appropriate, or handle the page’s access requirements separately. |
| Requests are slow or time out | Proxy routing adds latency; the endpoint may be slow, or too many captures may share one proxy. | Compare without a proxy where location is unnecessary. Reduce parallel requests through one proxy, or use different ports or proxies if your provider supports them. |
| Regional content is still wrong | The custom proxy location takes precedence over ip_country_code, or the page also varies by language or time zone. |
Choose the proxy region intentionally and configure language or time-zone preferences where the page requires them. |
| Some assets fail while the page loads | The proxy route may be unsuitable for assets that do not need that IP or location. | Consider proxy_bypass_hosts for matching asset hostnames, using hostname patterns rather than full URLs. |
| The request reports a parameter, permission, selector, storage, or quota error | The failure is unrelated to proxy routing. | Correct the option or selector, check account permissions and quota, or investigate storage as indicated by the error. A proxy retry will not repair these conditions. |
| Proxy network errors persist | The provider endpoint, account balance, or proxy user may have a problem. | Check the provider balance and endpoint status, then contact the provider. ScreenshotOne’s guide notes that recreating a proxy user or account has helped with some providers; it is an observation, not a guaranteed fix. |
6. Performance, reliability, and cost
- Latency: A proxy adds a network hop, so avoid it when the request does not need a different route or location.
- Concurrency: Many parallel requests through one proxy can slow requests and increase timeouts or other errors. Spread load across endpoints or ports only where your provider supports that setup.
- Provider cost: ScreenshotOne recommends trying data-center routing first on cost grounds. It does not publish a quantified price comparison or success rate in the cited guide; compare provider pricing directly.
- Failure isolation: Keep proxy retries targeted. Retrying every failed capture through a proxy increases latency and may add provider charges without fixing configuration or account errors.
- Credential handling: Keep the API key and proxy credentials server-side, redact query strings from logs, and rotate credentials according to your provider’s practices.
7. Alternatives: use ScreenshotNeo when its workflow fits
If your main concern is clean screenshots without setting up browser infrastructure, ScreenshotNeo is a website screenshot API and MCP server. Its documented features include accepting cookie banners and removing more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. It does not list a custom proxy option in the product details for this article, so use ScreenshotOne’s proxy parameter when routing through your own HTTP proxy is the requirement.
Or skip the browser setup
One GET request returns a screenshot. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo 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 per month with no card; paid plans start at $5 for 3,000.
Sign up free and get 1,000 screenshots a month with no card.
FAQ
Does ScreenshotOne provide the proxy?
No. Its guide describes connecting an external proxy provider and says rotating residential proxies are not included as part of ScreenshotOne.
Can I use an HTTPS proxy URL?
ScreenshotOne’s options reference says only HTTP proxies are supported for the custom proxy option. The request to ScreenshotOne’s API itself should use HTTPS.
Can I combine a proxy with a country code?
A custom proxy overrides ip_country_code. Select the proxy endpoint’s location deliberately.
Will a proxy solve every CAPTCHA or access restriction?
No. The cited guide describes selected cases where a proxy may help, but does not promise that it bypasses all bot checks or CAPTCHA challenges.
What should I try first if I only need a different region?
Choose a proxy endpoint in the intended region and account for any language or time-zone variation the target site uses. Start with a data-center proxy on cost grounds; consider residential or mobile routing only if needed.
