ScreenshotAPI Returns a Blank Screenshot: Causes and Fixes
A blank capture can mean the page was not ready, the wrong content loaded, or the response was handled incorrectly. Use this checklist to find the cause and fix it.
A blank screenshot usually means the capture happened before the expected content appeared, the browser reached a login or error page, or your code interpreted the response incorrectly. First verify the exact API hostname and endpoint, then inspect the response status and headers, and only then adjust the page wait or lazy-load behavior.
This guide uses ScreenshotAPI.net as the meaning of “ScreenshotAPI,” because its official docs describe blank captures and the relevant wait options. The similarly named screenshot-api.org and screenshotapi.to are separate services with different request shapes. Confirm your hostname before copying any example. ScreenshotAPI.net’s current screenshot docs use /v1/screenshot; its older render docs describe a separate v3 endpoint. Do not mix their parameters or authentication examples.
1. Confirm the request targets the right API
Check the hostname, path, authentication method, and URL parameter against the docs for the service and API generation you actually use. ScreenshotAPI.net’s current /v1/screenshot endpoint accepts an HTTP or HTTPS target URL and documents options including viewport dimensions, full_page, delay, cookies, and output format. The older v3 documentation uses a token in the query string. A request assembled from examples for different endpoints can fail or capture something other than the intended page.
Also check that the target URL is present, correctly encoded, and reachable without an unexpected redirect. Don’t assume that an endpoint documented by another similarly named service accepts the same parameter names.
2. Inspect the response before changing timing
ScreenshotAPI.net documents an X-Page-Status response header. Inspect it along with the HTTP status and content type. A final page status of 401 or 403 can mean the browser rendered an authentication or access-denied page. If the target needs a logged-in session, supply the appropriate target-host cookies using the documented option.
Check whether the response is image bytes or JSON. The current /v1/screenshot endpoint returns the image itself with an image content type. The separate /v1/capture endpoint returns JSON that includes image data and page text. Code that tries to parse the screenshot endpoint as JSON can make a valid image look broken; code expecting raw image bytes from the JSON endpoint has the inverse problem.
3. Wait for the page’s real readiness signal
Client-rendered applications may show an empty shell while JavaScript fetches and paints the content. Choose a wait strategy based on how this particular page becomes ready:
| Strategy | Use it when | Watch for |
|---|---|---|
| Wait for a CSS selector | A stable element appears only when the content you need is rendered. | The selector must exist on the final page and should identify meaningful content, not an early-loading shell. |
| Network idle | The page’s needed data arrives through asynchronous requests and network quiet is a useful signal. | Polling, streaming, analytics, or other continuing requests can make network idle a poor completion signal. |
| Fixed delay | The page’s rendering time is predictable and a simple pause is sufficient. | A short pause can still be too short; an unnecessarily long one slows every capture. |
ScreenshotAPI.net documents waiting for a selector, network idle, and a fixed delay. There is no one setting guaranteed to fix every blank page. Prefer an observable selector when the site exposes a reliable ready element. Use a delay when you know the required extra time, and network idle when network completion corresponds to content readiness.
4. Check lazy loading and the captured area
Some pages do not request or display content until it approaches the viewport. If the missing section is below the fold, a viewport-sized capture may simply not include it. Check the viewport dimensions and use full-page capture when the whole scrollable document is required.
For content activated by scrolling or IntersectionObserver, ScreenshotAPI.net documents lazy_load=true, which scrolls to activate lazy-loaded regions, as well as full-page behavior that scrolls through the page. Use the option that matches the desired output and confirm that the missing content is actually in the captured area.
5. Check selectors and binary handling
If you request a selector-based capture, verify that the selector matches an element on the page after it has rendered. A selector that is absent, misspelled, or only present in a different page state can produce a failed or unexpected capture.
For /v1/screenshot, save the response body as binary image data rather than converting it to text or parsing it as JSON. If your integration needs the JSON response with image data and page text, use the documented /v1/capture endpoint and handle its JSON schema instead.
6. A diagnostic sequence
- Record the full API hostname and endpoint path. Confirm that they belong to the same service and API version as your authentication and parameter names.
- Confirm the target URL is valid, encoded, and present in the request.
- Read the HTTP status, content type, and documented
X-Page-Statusheader. Determine whether the browser reached your content, a login page, or an error page. - Verify that your code handles the endpoint’s response format correctly: image bytes for
/v1/screenshot, JSON for/v1/capture. - Choose a readiness condition: a stable content selector, network idle, or a known fixed delay.
- If content appears only after scrolling, enable the documented lazy-load behavior or capture the full page. Check viewport size when the content lies outside the initial view.
- Retry with one change at a time and compare the resulting status, headers, and image. This makes it clear which condition mattered.
7. Troubleshooting common symptoms
| Symptom | Likely cause | What to do |
|---|---|---|
| Entire image is white or nearly empty | Capture starts before client-side content renders, or the target itself returns an empty shell. | Wait for a selector that appears with the real content; otherwise use a suitable delay or network-idle wait. Check the final page status. |
| Screenshot shows a login or access-denied page | The page requires authentication, or the target returned 401/403. | Inspect X-Page-Status; provide the target-host cookies when the page requires a signed-in session. |
| Top of page appears but lower content is missing | Content is below the captured viewport or loads on scroll. | Check viewport and full-page settings; enable documented lazy-load handling for scroll-triggered content. |
| Only a particular element is missing | The selector does not match, or the element is not ready when capture begins. | Validate the selector against the rendered page and wait for that element before capture. |
| Image file is corrupted or application reports a parse error | Binary image bytes were treated as JSON/text, or JSON was treated as raw image data. | Match response handling to the endpoint: image body for /v1/screenshot; JSON for /v1/capture. |
| Authentication or parameter errors after copying a snippet | Hostname, endpoint generation, auth, or parameter names came from different APIs or versions. | Use one service’s current docs end to end; do not combine the current v1 request with older v3 token examples. |
8. Performance, reliability, and cost considerations
Wait only for what the screenshot needs. A meaningful selector can avoid guessing at a delay, while a bounded delay is often simpler for a page with predictable rendering. Network idle is useful only when network quiet correlates with readiness. Full-page scrolling and lazy-load activation can take longer because more of the document must be visited.
For reliability, capture and retain the response status, content type, and page-status header alongside the image. Treat login pages, access denials, selector misses, invalid requests, and render failures as separate diagnoses rather than retrying all of them with a longer delay. The reviewed ScreenshotAPI.net documentation does not establish comparative success rates for its wait strategies, so select based on the target page’s behavior.
Cost depends on the provider’s current plan and billing terms; consult the service’s current pricing directly. Avoid retries that make no diagnostic change, and verify whether your integration is receiving image bytes before paying for repeated captures. No independent live API test or measured benchmark underlies this guide.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF. Its documented flow accepts cookie banners and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response indicates the page verdict and billing status. AI agents can use its MCP tools, including take_screenshot, get_page_info, and capture_pdf.
Install requests with python -m pip install requests, then save this as capture.py and run python capture.py. See the ScreenshotNeo API docs for request options.
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)The same endpoint can be called with cURL or Node.js:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpconst q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);ScreenshotNeo has 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Yearly billing gives two months free, and every feature is on every plan. Sign up free for 1,000 screenshots a month, no card required.
FAQ
Does a blank capture always mean the screenshot API failed?
No. The image may faithfully show a blank app shell, a login page, an error page, or an area without rendered content. Inspect the final page status and response format before classifying it as an API failure.
Should I always use network idle?
No. Use it only when network quiet is a good signal that the content is ready. A stable content selector or a known delay may suit the page better.
Is ScreenshotAPI.net the same as ScreenshotNeo?
No. They are separate products. Confirm the provider hostname before using its endpoint, options, or authentication instructions.
