CaptureKit Wait for Selector vs Wait for Timeout for Dynamic Pages

Short answer: Use CaptureKit’s wait_for_selector when a stable element on the page appears only after the content you need is ready. Use delay for a fixed pause when you have no dependable selector or need a small settling interval. The Capture API documents the fixed-wait parameter as delay, measured in seconds from 0 to 10 with a default of 0; it does not document a parameter named wait_for_timeout. CaptureKit Capture API reference.

1. Choose the readiness signal

Option	What it waits for	Use it when	What it does not establish
`wait_for_selector`	A specified page element appears.	A stable selector identifies the exact content needed.	It does not prove every script, request, animation, or lazy-loaded section has finished.
`delay`	A fixed amount of elapsed time, in seconds (0–10; default 0).	A short pause is enough, or no reliable selector exists.	It does not check that content is ready.
`wait_until`	A documented page lifecycle or network condition.	The required signal is broader than one element.	It does not necessarily mean the particular content you care about is visible.

A selector wait ties capture to a page condition; a delay ties it to a duration. If page speed varies, a fixed delay can be too short on a slow load and unnecessarily long on a fast one. That is a consequence of what the controls measure, not a published CaptureKit performance comparison.

2. Use the CaptureKit Capture endpoint

The endpoint is GET /v1/capture. The API reference documents a webpage URL, output and capture options, wait_for_selector, delay, and wait_until. It lists one credit per call. Consult the CaptureKit introduction for authentication details and the Capture API reference for the current parameter schema. The example below shows the wait parameters; provide credentials using the authentication method required by your account and the current reference.

Selector wait

curl -G "https://api.capturekit.dev/v1/capture" \
  --data-urlencode "url=https://example.com/products" \
  --data-urlencode "wait_for_selector=.product-grid" \
  --output capture.png

Replace .product-grid with a selector for the content whose presence signals readiness. The dossier does not establish the exact API response if a selector never appears, so check the live reference and handle unsuccessful responses explicitly in production.

Fixed delay

curl -G "https://api.capturekit.dev/v1/capture" \
  --data-urlencode "url=https://example.com/products" \
  --data-urlencode "delay=2" \
  --output capture.png

The value is seconds and must stay in the documented 0–10 range. A delay of two seconds is only an example; it is not a universal recommendation.

Python request pattern

import requests

endpoint = "https://api.capturekit.dev/v1/capture"
params = {
    "url": "https://example.com/products",
    "wait_for_selector": ".product-grid",
}
# Add authentication according to CaptureKit's current API documentation.
response = requests.get(endpoint, params=params, timeout=70)
response.raise_for_status()
with open("capture.png", "wb") as image_file:
    image_file.write(response.content)

For a fixed pause, replace the selector entry with "delay": 2. The 70-second client timeout here is an illustrative client setting, not a CaptureKit guarantee. CaptureKit documents a hard 60-second server-side timeout for real-time API calls; a longer client timeout cannot extend that server limit.

Node.js request pattern

const endpoint = new URL('https://api.capturekit.dev/v1/capture');
endpoint.searchParams.set('url', 'https://example.com/products');
endpoint.searchParams.set('wait_for_selector', '.product-grid');
// Add authentication according to CaptureKit's current API documentation.

const response = await fetch(endpoint);
if (!response.ok) {
  throw new Error(`CaptureKit request failed: ${response.status} ${response.statusText}`);
}
const image = new Uint8Array(await response.arrayBuffer());
await import('node:fs/promises').then(({ writeFile }) => writeFile('capture.png', image));

For a fixed pause, set delay to a number from 0 through 10 instead. Node’s built-in fetch does not impose a request timeout by default; configure an abort signal if your application needs a client-side deadline, while accounting for CaptureKit’s server-side limit.

3. Select the right selector or lifecycle condition

Make the selector meaningful

Target the component or content that matters, such as a results container, not an unrelated header that renders immediately.
Prefer a stable class, ID, or other selector your application can keep consistent. A selector that changes with generated markup is brittle.
Check that element presence corresponds to the needed state. A container can exist before its data arrives; if so, use an application-specific ready marker or another signal documented for your page.
Consider visibility and content correctness separately. The reference says the option waits for an element to appear; it does not promise the element is visible, populated, or settled.

Use `wait_until` for broader page states

CaptureKit documents domcontentloaded, load, networkidle0, and networkidle2 as wait_until values. These are separate from a page-specific selector check. Choose a lifecycle or network condition when that is the readiness signal you need; combine controls only when the API supports the combination and the extra waiting serves a clear purpose. CaptureKit’s monitoring example combines networkidle2 with a two-second delay, but that example is not proof that the combination suits every site: CaptureKit monitoring example.

4. Handle edge cases and failures

Selector never appears: The selector may be incorrect, the page may have failed, or the content may be conditional. Verify it in the rendered page and select a reliable readiness marker. The reviewed reference does not specify the exact missing-selector behavior.
Selector appears too early: Element existence may precede data rendering. Target a more specific ready element or use an appropriate lifecycle condition; do not assume presence means the whole page is settled.
Delay is too short: Slow or variable page loads can outlast a fixed pause. Prefer a meaningful selector or lifecycle signal when available.
Delay wastes time: A fixed pause is paid in waiting time even if the page is ready sooner. Reduce it carefully or switch to a dependable readiness condition.
Invalid delay: Keep the value within 0–10 seconds, the documented range.
Request hits a timeout: Real-time CaptureKit calls have a hard server-side timeout of 60 seconds. The timeout page recommends async mode for requests expected to take longer. This limit is separate from page readiness settings. See CaptureKit timeouts.
Authentication or parameter error: Confirm the current auth method, endpoint path, parameter spelling, and URL encoding against the official introduction and Capture reference.

5. Performance, reliability, and cost

Neither the API reference nor the reviewed example publishes comparative measurements for selector waits versus delays. A selector can avoid waiting for an arbitrary full interval when the target element becomes available, while a delay offers a simple bounded pause; actual request time depends on the page and service. Treat these as operational implications, not benchmark claims.

CaptureKit lists one credit per Capture call. The sources do not say that choosing one wait option changes the credit cost. A real-time call also has a 60-second hard server timeout; use async mode for work expected to exceed it. For reliability, choose a signal that matches the content you need, validate status and response data, and track failures in your own integration.

6. Troubleshooting checklist

Confirm the request uses /v1/capture and the correct documented authentication.
Use wait_for_selector exactly as named; use delay for fixed seconds, not an assumed wait_for_timeout parameter.
Check the selector against the rendered page and ensure it identifies the needed content.
Keep delay between 0 and 10 seconds.
Choose wait_until only when its documented page lifecycle/network condition matches the requirement.
Distinguish client timeout settings from CaptureKit’s 60-second real-time server limit; use async mode for longer work.
Review the official reference for current response and missing-selector behavior before relying on undocumented assumptions.

7. Or skip the browser setup

If you want a screenshot API without configuring browser waits and page cleanup yourself, ScreenshotNeo provides a one-request screenshot API and MCP server. Cookie banners are accepted and removed before capture, along with 60+ known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and responses identify the page verdict and billing status in headers. AI agents can use its MCP tools, including take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots monthly with no card; paid plans start at $5 for 3,000.

See the ScreenshotNeo API documentation. This runnable cURL call saves a WebP screenshot:

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com/products \
  -o shot.webp

Equivalent Python request:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com/products"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Equivalent Node.js request:

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com/products',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo request failed: ${res.status}`);
await import('node:fs/promises').then(({ writeFile }) =>
  writeFile('shot.webp', new Uint8Array(await res.arrayBuffer()))
);

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

8. Frequently asked questions

Is `wait_for_timeout` a CaptureKit parameter?

The reviewed Capture API reference documents delay for a fixed pause and wait_for_selector for an element wait. It does not show wait_for_timeout.

Does finding the selector mean the page is fully loaded?

No. It indicates the specified element appeared. Scripts, requests, animations, and other regions may still be active.

Can I use these wait settings on CaptureKit’s Content endpoint?

The Content API reference also documents wait_for_selector, delay, and wait_until, alongside its content extraction options. Its purpose is extracting page data rather than returning a screenshot: CaptureKit Content API reference.