Element capture

Capture one element instead of the whole page

A chart in an image is a chart. A chart inside a full-page screenshot is a chart plus a navigation bar, a cookie notice and a footer.

selectorselector_algorithmselector_scroll_into_viewerror_on_selector_not_foundcapture_beyond_viewport

curl --fail-with-body "https://api.pagecapture.dev/v1/take" \
  -H "X-Access-Key: $PAGECAPTURE_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com","format":"png","selector":"main","selector_scroll_into_view":true}' \
  -o capture.png

Verified 2026-08-13 by running the published code against a fixture.

Configure it in the playground

What it does

Captures the bounding box of the matched element, scrolling it into view first by default.
Offers two strategies through `selector_algorithm`: `default` uses the browser's element capture API, `clip` converts the bounding box into a clip rectangle.
Falls back to a viewport capture when the selector misses — unless you ask for the opposite.

What it does not do

Does not accept XPath. The selector is always CSS.
Does not fail by default on a missing selector. That default is asymmetric with `click` and `hover`, which do fail, and copying the wrong one breaks a migration silently.
Does not compose with `clip`: the element defines the rectangle, so a manual one would have to win or lose, and neither is a good surprise.

The contract

Every limit on this page is the one the API enforces

These rows are read from the same parameter table that validates your request. Nothing here is transcribed, so a number cannot drift from the behaviour it describes.

Parameter	Type	Default	Range	Endpoints	Cache key
`selector` Capture only the element matching this CSS selector.	string	—	—	/v1/take	In
`selector_algorithm` How the element is captured: `default` uses the browser element API, `clip` converts the bounding box into a clip rectangle. The selector is always CSS.	enum	default	—	/v1/take	In
`selector_scroll_into_view` Scroll the selected element into view before capturing.	boolean	true	—	/v1/take	In
`error_on_selector_not_found` Fail when the capture, hide or wait selector does not match, instead of skipping it.	boolean	false	—	/v1/take, /v1/animate	In
`capture_beyond_viewport` Allow the capture to extend past the viewport bounds.	boolean	true	—	/v1/take	In

Group: EssentialsValues outside a documented range are rejected before a browser opens.

How it behaves next to the rest of the request

selector_algorithm

How the element is captured: `default` uses the browser element API, `clip` converts the bounding box into a clip rectangle. The selector is always CSS.

`clip` is the escape hatch for elements the browser's own element capture handles badly — transformed containers, elements inside a scroll region. Same selector, different mechanics.

error_on_selector_not_found

Fail when the capture, hide or wait selector does not match, instead of skipping it.

Set it to `true` in a pipeline. A viewport capture standing in for a missing chart is worse than a failure, because the failure costs nothing and the wrong image gets published.

wait_for_selector

Wait until this CSS selector appears.

If the element is rendered by client-side code, wait for it with the same selector. Otherwise the capture starts before it exists and the fallback quietly takes over.

Errors this option can produce

selector_not_foundHTTP 400

The requested selector was not found.

resulting_image_too_largeHTTP 400

The resulting image exceeds the maximum allowed size.

None of them is billable. No error code in the catalog is.

Questions this raises

What happens when the selector matches several elements?

The first match is captured. Narrow the selector when that is not the one you meant — there is no index parameter, because a positional index is the first thing a redesign breaks.

Can I capture an element taller than the viewport?

Yes. `capture_beyond_viewport` is on by default, so the capture can extend past the visible area.

Should I use selector or clip?

Selector when the target is a component: it survives layout changes. Clip when the target is a region of the page that no element describes.