How to set a screenshot API to click a button before capturing a page

To click a button before a screenshot API captures a page, pass the button’s CSS selector using the provider’s documented click option, then wait for the interaction to finish before capture. Screenshot APIs do not share a universal click parameter: for example, Screenshot Machine documents click, Crawlbase documents css_click_selector, and ScreenshotCenter uses an ordered steps list. Check the selected provider’s current documentation for its endpoint, authentication, and request format.

1. Identify the button and its selector

Choose a selector that matches the intended control uniquely. An ID such as #open-details is often more stable than a broad selector such as button, which may match several controls. Confirm the selector against the page’s current markup; a selector that matches nothing, or matches the wrong button, cannot produce the desired state.

Consider what the click does before choosing a wait strategy:

Dismisses an overlay: wait until the overlay is gone or the underlying page is visible.
Opens a menu or panel: wait for that element to appear.
Loads new content: wait for a page-specific condition if the provider supports it, or use a delay long enough for the observed behavior.
Navigates to another page: allow the navigation to finish and verify the resulting URL or page state if your workflow can.

2. Use the click option documented by your provider

The parameter name and request shape depend on the service. These examples show the documented patterns in the research sources; use the current provider documentation to confirm endpoint paths, authentication, and any required parameters before running them.

Screenshot Machine: click query parameter

Screenshot Machine documents a click query parameter that accepts a CSS selector. Its example uses click=#button-close. Since # has a special meaning in a URL, encode it as %23 when constructing a raw query string.

https://api.screenshot-machine.com/?key=YOUR_API_KEY&url=https%3A%2F%2Fexample.com&click=%23button-close

The URL above illustrates the parameter pattern; confirm the correct endpoint and required parameters in Screenshot Machine’s API documentation. Prefer your HTTP client’s query-parameter encoder over hand-building the query string.

Crawlbase: selector plus page wait

Crawlbase documents css_click_selector and page_wait in milliseconds. Its example uses a 1500 ms wait after the click. That is an example value, not a guarantee that every page will finish updating in that time.

curl -G 'https://api.crawlbase.com/screenshot' \
  --data-urlencode 'token=YOUR_TOKEN' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'css_click_selector=button.show-details' \
  --data-urlencode 'page_wait=1500'

Check Crawlbase’s Screenshots API documentation for current request details. The documentation says standalone Screenshots API sign-ups have been closed to new users since 2024-11-01, while existing integrations continue to work; check availability before choosing it for a new project.

ScreenshotCenter: ordered steps

ScreenshotCenter documents a sequence of actions, so the click and wait occur before the screenshot step. The following shows the documented step shape; supply the endpoint, authentication, and surrounding request fields required by its current API documentation.

{
  "steps": [
    {"command": "click", "selector": "#login-btn"},
    {"command": "wait", "duration": 1500},
    {"command": "screenshot"}
  ]
}

See the ScreenshotCenter documentation for its current API request and authentication requirements.

3. Encode selectors and wait for the resulting state

When a selector is sent as a URL query parameter, encode it as a query value. A raw #button-close in a URL can be interpreted as a fragment rather than as part of the parameter, so encode the hash as %23. Characters such as spaces and quotes also need encoding. HTTP libraries that accept a parameter object usually do this correctly.

Do not treat a fixed delay as proof that the interaction succeeded. A click can trigger animation, client-side rendering, a network request, or navigation. Where supported, wait for the specific element or state that signals completion. Otherwise, adjust the delay based on the target page’s behavior and inspect the returned screenshot. Cloudflare’s browser rendering guide notes that JavaScript-heavy pages and single-page applications may still be rendering after the browser’s default page-load behavior finishes; page-load completion and interaction completion are separate concerns.

4. Verify the captured state

During implementation, inspect both the image and the response. Confirm that the expected panel opened, overlay disappeared, or destination loaded. An accepted API request only establishes that the service received the request; it does not establish that the selector matched or the page reached the desired state.

5. Run the interaction locally when you need browser control

A hosted screenshot API is convenient when you want a remote capture endpoint, but local browser automation gives your own code control over the page interaction and waits. The shot-scraper documentation describes running custom JavaScript after the page load event and before the screenshot, including clicking links and waiting on a Promise.

A generic Playwright example illustrates the browser-side sequence. Install Playwright and its browser according to the official Playwright documentation, save this as capture.mjs, then run it with Node.js. Set TARGET_URL to the page you control and BUTTON_SELECTOR to its selector.

import { chromium } from 'playwright';

const url = process.env.TARGET_URL ?? 'https://example.com';
const selector = process.env.BUTTON_SELECTOR ?? '#open-details';
const browser = await chromium.launch({ headless: true });

try {
  const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
  await page.goto(url, { waitUntil: 'domcontentloaded' });
  await page.locator(selector).click();
  // Replace with a condition that represents the desired state on your page.
  await page.waitForTimeout(1000);
  await page.screenshot({ path: 'shot.png', fullPage: true });
} finally {
  await browser.close();
}

For a known result element, a condition is generally more dependable than a guessed delay. For example, after clicking a control that reveals #details-panel, use await page.locator('#details-panel').waitFor({ state: 'visible' }); before capturing. Use selectors and conditions appropriate to the page you control.

6. Troubleshoot common problems

Symptom	Likely cause	What to do
The screenshot looks unchanged	The selector matched no element, matched a different control, or the click did not take effect.	Check the selector against the live page, make it more specific, and inspect the screenshot and API response.
The response arrives but the image shows the old state	The capture happened before an animation, asynchronous update, or navigation finished.	Wait for a page-specific condition if available; otherwise adjust the delay and verify the resulting state.
An ID selector appears truncated or ignored	The `#` was not encoded and was treated as a URL fragment.	Use a query parameter encoder or encode `#` as `%23`.
The wrong button is clicked	A broad selector matched more than one element or the page markup changed.	Use a unique ID, a more specific CSS selector, or a supported locator strategy; verify against the current page.
The click fails on a JavaScript-heavy page	The page load event occurred before the client-rendered control became available.	Wait for the control or another page-specific readiness condition before clicking; then wait for the post-click state.
A provider rejects the request or ignores an option	The parameter name, endpoint, authentication, or encoding does not match that provider’s current API.	Compare the request with the provider’s current docs. Click options are provider-specific, not a common standard.
A service is unavailable for a new account	Its onboarding or product availability changed.	Check current provider status and sign-up availability before building a new integration. Crawlbase’s docs report that standalone Screenshots API sign-ups closed to new users on 2024-11-01.

7. Performance, reliability, and cost considerations

Every interaction and wait adds work before capture. Use the shortest wait that reliably represents the desired page state, and prefer a condition-based wait where the provider offers one. A fixed delay can waste time on quick pages and still be too short on slow ones. JavaScript-heavy pages may need explicit readiness handling even after their initial page-load event.

For reliability, keep selectors tied to stable page markup, check the captured result, and handle API errors and timeouts in the calling application. Recheck current endpoint behavior, plan limits, and onboarding with the provider: the cited documentation does not establish comparable prices, performance benchmarks, or guarantees across these services.

Or skip the browser setup

ScreenshotNeo is a screenshot API and MCP server. Its click option can click a CSS selector before capture. Use this one-call request for a target page, then add the click option and selector described in 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.webp

import 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}`);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a 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

Is there one click parameter that works with every screenshot API?

No. Providers use different parameter names and request formats. Use the selected provider’s documentation.

Does a successful API response prove the button was clicked?

No. Inspect the resulting image or response details and confirm the expected state is visible.

Should I use a delay or wait for an element?

Wait for a specific resulting element or state when supported. A delay is a fallback when there is no suitable condition.

Can I avoid a hosted screenshot API?

Yes. Local browser automation can perform the click and wait in your own runtime before saving the screenshot.