Why Does a Screenshot API Return an Old Version of My Web Page?
A screenshot can be stale because of API caching, page-render timing, or your site’s own delivery path. Trace each layer and fix the right one.
A screenshot API can return an old-looking page for three different reasons: the API reused a stored screenshot, the browser captured the page before its JavaScript update appeared, or the website itself served old content. First confirm whether you received a new render or a cached image; then check when the page becomes ready; finally compare the renderer’s result with a direct fetch of the site. The right fix depends on which layer is stale.
1. Identify which version of the page you received
Before changing settings, save the exact request and response. Record the target URL, all screenshot parameters, response status and headers, and whether the response is image bytes or a URL pointing to a stored image. Compare those details with a request that produced the expected version.
- Image or cache URL: A service may return an existing stored image. Fetching that image URL may only download the stored result; it may not start a new browser render. ScreenshotOne documents this distinction for its cache URLs.
- New screenshot request: The service should start or retrieve a render according to its own cache rules. Check its documentation for the exact bypass parameter, cache key, and TTL behavior.
- Old content inside a fresh render: Investigate page readiness or the website’s delivery path. A new screenshot does not guarantee that the page’s JavaScript has finished updating or that the site returned current content.
Do not assume that a query parameter such as ?t=timestamp forces a fresh render. It only helps if the screenshot service documents that the parameter affects cache behavior or its cache key. Controls differ across providers.
2. Request a fresh screenshot using your provider’s documented control
Look up the screenshot API’s current documentation and identify its cache behavior. Depending on the provider, relevant settings may include:
- A cache bypass or “fresh” flag.
- A screenshot cache enable/disable option.
- A cache TTL or stale-result TTL.
- Cache-key rules that determine whether different options create separate stored results.
For example, ScreenshotAPI.net documents fresh=true for bypassing its stored screenshot. Screenshot API documents cache-related settings including cache, cacheTTL, and staleTTL. ScreenshotOne documents TTL and request-option cache-key behavior. Those parameters are provider-specific: do not copy one service’s setting into another service’s request.
Also check whether you are requesting a new capture or repeatedly downloading a cache URL. If the provider returns a stored image URL, follow its documented process for requesting a new render after expiration or bypassing the stored result.
3. Wait for the page’s updated state
A browser can finish navigation before a JavaScript application has rendered the content you care about. This is common with single-page applications, client-side data fetching, delayed widgets, and content that appears only after interaction. Cloudflare’s Browser Run documentation warns that JavaScript-heavy pages and SPAs may be incomplete when the browser considers loading complete too early.
Prefer waiting for a selector that represents the new content. For example, wait for .updated-price or [data-state="ready"], using the syntax supported by your provider. A suitable network-idle condition can help if the page loads its data over requests, but some applications keep connections open or poll continuously. A fixed delay is a fallback for a known delay, not proof that the desired state appeared.
Screenshot APIs commonly expose some combination of the following controls; names and supported values vary by provider:
| Control | When it helps | Trade-off or caveat |
|---|---|---|
| Wait for a selector | The updated page has a stable element that appears when ready. | The selector must match the actual rendered page and may time out when the state never appears. |
| Wait for network idle | Content arrives through requests that eventually settle. | Polling, analytics, or long-lived connections may prevent an idle state. |
| Wait for a load event | Assets and document resources need to finish loading. | The event may happen before client-side rendering or later data requests complete. |
| Fixed delay | The site has a known, consistent post-load delay and no reliable selector. | Short delays can still capture early; long delays increase latency and may waste resources. |
Change one variable per retest: first the cache behavior, then the readiness condition. That makes it easier to identify the cause.
4. Check whether the website itself served old content
If a verified fresh render is still old, compare it with the page delivered outside the screenshot workflow. Fetch the target URL directly and inspect the returned HTML and the assets or API responses that contain the changing content. If possible, match the renderer’s cookies, authentication, user agent, locale, geography, and other relevant request conditions.
If a direct fetch is also old, the screenshot provider may simply be rendering what it received. Investigate the website’s deployment, CDN, origin, and other delivery caches. If the direct response is current but a fresh screenshot remains old, examine the screenshot provider’s cache key, output URL, request options, and renderer behavior.
Browser HTTP caching is another distinct layer. The Fetch API’s Request.cache setting describes how a browser request interacts with its HTTP cache; it does not automatically control a screenshot API’s stored-image cache. Treat browser cache, screenshot cache, and site delivery as separate things to investigate.
5. A repeatable troubleshooting workflow
- Capture evidence: Save the full screenshot request, response status and headers, returned image or image URL, and the screenshot itself.
- Confirm the response type: Determine whether you received newly rendered image data, a stored result, or a URL to stored output.
- Use the documented freshness control: Disable screenshot caching or request a fresh render using that provider’s current parameter. Check the cache TTL and cache-key rules.
- Wait for the expected page state: Add a selector wait if possible; otherwise choose a suitable network-idle condition or a measured delay.
- Compare direct delivery: Fetch the target page and relevant data or assets under comparable conditions.
- Change one setting at a time: Retest after each change and note which change corrected the image.
6. Provider controls and what to compare
When evaluating screenshot API behavior, check the provider’s current documentation for these points. The examples below describe documented vendor controls; they are not interchangeable.
| Provider documentation | Documented controls or behavior | Reference |
|---|---|---|
| Screenshot API | cache, cacheTTL, staleTTL, waitUntil, waitForSelector, and delayMs. |
REST API documentation |
| ScreenshotAPI.net | fresh=true requests a fresh result instead of its stored screenshot. |
Cached and fresh screenshot documentation |
| ScreenshotOne | Cache TTL, request-option cache keys, cache URL behavior, and regeneration after expiration. | Caching documentation |
| Cloudflare Browser Run | Screenshot and page-loading behavior, including SPA timing and selector or network-idle waits. | Screenshot endpoint documentation |
| Cloudflare Browser Rendering | HTML snapshot and screenshot API reference with page-loading controls. | Snapshot API reference |
| MDN | Browser Request.cache modes for HTTP requests. |
Request.cache reference |
7. Common errors and fixes
The image is always identical even after changing the page
Likely cause: The screenshot service reused a cached image, or the request still points to the same stored output URL.
Fix: Make a new capture request with the provider’s documented fresh or cache-bypass control. Check whether changed request options participate in its cache key.
The API says the page loaded, but the changed text is missing
Likely cause: Navigation completed before JavaScript rendered the updated state.
Fix: Wait for the updated element or a suitable network-idle condition. Use a delay only when the page’s behavior justifies it.
A “fresh” parameter has no effect
Likely cause: The parameter belongs to another provider, is misspelled, or is not part of the endpoint being called.
Fix: Check the exact endpoint’s current API reference and verify how it defines freshness and cache keys.
The direct page and screenshot both show old content
Likely cause: The target site, its CDN, or its origin is serving an older version, or the request context selects different content.
Fix: Inspect direct HTML and data responses, then check deployment and delivery caches. Compare authentication, cookies, region, locale, and user agent.
The selector wait times out
Likely cause: The selector does not exist in that page state, the page needs different request context, or the updated content never loaded.
Fix: Inspect the rendered HTML, choose a stable selector, and confirm the content appears in a normal browser under equivalent conditions.
8. Performance, reliability, and cost
Fresh rendering and longer waits can increase capture time. A selector wait usually expresses the intended condition more clearly than an arbitrary long delay, while network-idle waits can be unreliable on pages with ongoing requests. The right choice depends on the page’s loading behavior.
Caching can reduce repeated work when the page is expected to remain unchanged, but it can also return an image that is too old for a time-sensitive workflow. Set freshness and TTL according to how often the page changes and how quickly your application needs to reflect those changes. Do not assume a bypass is free or has the same billing effect across providers; check the service’s pricing and response metadata.
For reliable monitoring or visual comparisons, retain the request settings and response metadata alongside each image. That helps distinguish a genuinely changed page from a changed wait condition, cache policy, locale, or authentication state.
9. Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. Its screenshot call accepts a URL and returns an image or PDF; 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.webpimport 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 accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, and failed loads are never billed, and cache hits cost nothing. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Does adding a timestamp to the page URL always force a new screenshot?
No. It only works if that provider uses the changed URL in its cache key or documents that method. Use its documented freshness control.
Is a browser cache the same as a screenshot API cache?
No. Browser HTTP caching applies to browser requests; a screenshot service may separately cache rendered images, and the target site may serve cached content too.
Should I use a longer delay to guarantee fresh content?
No fixed delay guarantees that the desired state loaded. Wait for a meaningful selector when possible, and use a delay only for a known page-specific timing issue.
Why is the same URL fresh in my browser but old in the screenshot?
The browser and renderer may have different cookies, authentication, location, locale, or user agent. They may also differ in cache state or in how long they wait for JavaScript updates.
