How to capture a specific element with the ScreenshotOne API

Use ScreenshotOne’s selector option to capture a specific page element. Send the page URL, your access key, and a CSS-like selector to the /take endpoint. By default, ScreenshotOne scrolls the element into view and captures it beyond the viewport, so the result can include the whole element.

This guide uses .content as an example selector. Replace it with a selector that uniquely identifies the element you want. The examples use a placeholder access key; keep your real key private.

1. Find a stable selector

Inspect the page’s live DOM and choose a selector that identifies the intended element. A unique ID, a stable data attribute, or a sufficiently specific class-based selector can work. Avoid broad selectors such as div if many elements match.

When a selector matches multiple elements, ScreenshotOne selects the first visible match in DOM order. If the page changes its markup dynamically, verify the match against the rendered page rather than relying only on the source HTML.

2. Capture the element with cURL

curl -G "https://api.screenshotone.com/take" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "selector=.content" \
  --data-urlencode "access_key=YOUR_ACCESS_KEY" \
  -o element.png

--data-urlencode safely encodes query values. For example, an ID selector such as #target contains a hash character, which must be encoded as %23 in a manually constructed query string.

3. Capture the element with Python

import requests

response = requests.get(
    "https://api.screenshotone.com/take",
    params={
        "url": "https://example.com",
        "selector": ".content",
        "access_key": "YOUR_ACCESS_KEY",
    },
    timeout=90,
)
response.raise_for_status()

with open("element.png", "wb") as image_file:
    image_file.write(response.content)

Passing parameters as a dictionary lets the HTTP library encode the selector and URL. Check the HTTP response before saving its body as an image so an API error is not mistaken for a screenshot.

4. Capture the element with Node.js

const params = new URLSearchParams({
  url: 'https://example.com',
  selector: '.content',
  access_key: 'YOUR_ACCESS_KEY',
});

const response = await fetch(
  `https://api.screenshotone.com/take?${params}`
);

if (!response.ok) {
  throw new Error(`Screenshot request failed: ${response.status} ${await response.text()}`);
}

const image = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('element.png', image));

Run this in an environment with a Node.js version that supports the built-in fetch API. Keep the access key on the server; do not embed it in browser JavaScript or a public page.

5. Choose what part of the element to capture

Option or behavior	What it does	When to use it
selector	Targets an element using a CSS-like selector.	When the region corresponds to a dependable page element.
capture_beyond_viewport	With a selector, defaults to true, allowing capture of the whole element beyond the visible viewport.	Keep the default for a full element; set false for only its visible portion.
selector_scroll_into_view	Defaults to true; scrolls the target into view before capture.	Useful when the target is off-screen or scrolling may trigger lazy-loaded content.
selector_algorithm	Can be set to clip to try a different selector-capture approach.	Try it if the default does not capture a partially visible element as expected.
error_on_selector_not_found	Controls whether a missing visible selector produces an error.	Enable it when a missing target should fail the request; otherwise a page screenshot may be returned.

These options and selector behavior are documented in ScreenshotOne’s screenshot options. The exact behavior can depend on the page’s rendered state, visibility, and layout.

6. Use coordinate clipping for a fixed rectangle

If the region is a fixed rectangle rather than a dependable DOM element, use coordinate clipping. Provide all four values: clip_x, clip_y, clip_width, and clip_height. A selector is generally the more direct choice when you mean a particular page element; coordinates describe a position and size.

See ScreenshotOne’s area-capture guide for its documented selector-versus-coordinate guidance.

7. Authentication and key handling

Make requests over HTTPS. ScreenshotOne documents GET and POST requests and supports an access key in the query string, a POST JSON body, or the X-Access-Key header. The examples here use a GET query parameter for brevity. For server applications, load the key from an environment variable or secrets manager and keep it out of source control.

A URL containing an access key should not be exposed as a public screenshot link. ScreenshotOne documents signed links for cases where screenshot URLs need to be shared publicly. See Getting Started for authentication and request details.

8. Troubleshoot selector captures

Symptom	Likely cause	What to try
selector_not_found	The selector is incorrect, the element is not visible, it has zero height, it has not rendered yet, or the page state needed to show it is missing.	Inspect the live DOM, verify visibility and dimensions, check whether interaction is needed, and allow more render time where appropriate. See ScreenshotOne’s selector-not-found guidance.
The wrong matching element is captured	The selector matches multiple visible elements; the first visible one in DOM order is selected.	Use a more specific selector and confirm which element appears first in the rendered DOM.
The capture contains only part of the element	Beyond-viewport capture may have been disabled, or the element may be partially visible and not handled as expected by the default algorithm.	Check capture_beyond_viewport; try selector_algorithm=clip for the partially visible element.
The target is missing after scrolling	The page may render content only after a delay or a state change.	Confirm the target exists after the page has rendered and that scrolling alone is enough to reveal it. Allow more render time where appropriate.
The saved file is not an image	The response may be an HTTP error or an API error body.	Check the HTTP status and inspect the response before writing it as an image.
Authentication fails or a key appears in a public URL	The key may be invalid, sent incorrectly, or exposed through client-side code or a shared URL.	Verify authentication using HTTPS, keep the key server-side, and use signed links for public sharing where applicable.

There is also a separate scroll_into_view option for positioning a selected element in the viewport. Its behavior is distinct from selector, which targets the capture. If no matching element exists, the documented behavior is to render the viewport at the top unless error_on_selector_not_found is enabled.

9. Performance, reliability, and cost considerations

• Keep selectors specific. This reduces ambiguity when several elements match, especially on pages whose markup changes.
• Account for rendering time. A target created asynchronously may not exist when capture begins. Allow time for it to appear and confirm any required page state.
• Consider scrolling effects. Scrolling the target into view can trigger lazy-loaded images or other off-screen content, which may affect what is captured and how long rendering takes.
• Handle failures explicitly. Check the HTTP status and API error response, and decide whether a missing target should fail or return a page screenshot.
• Protect credentials. Use HTTPS and do not publish a live key in source code, browser code, or an unsigned public URL.
• Confirm current service pricing and limits. The cited documentation establishes the request behavior, but this guide does not claim a benchmark, uptime level, or price for ScreenshotOne. Consult its current service documentation for those details.

Or skip the browser setup

If you need element capture as part of a broader screenshot workflow, ScreenshotNeo is a website screenshot API and MCP server. Its API supports CSS-selector element capture, along with full-page screenshots and other capture options. See the ScreenshotNeo API docs for request parameters.

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

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

FAQ

Can I capture the whole element when it extends below the viewport?

Yes. With selector specified, capture_beyond_viewport defaults to true. Set it to false when you only want the visible portion.

What happens if my selector matches more than one element?

ScreenshotOne selects the first visible match in DOM order. Narrow the selector to make the intended target unambiguous.

Should I use a selector or coordinates?

Use a selector for a page element whose structure gives you a dependable target. Use coordinate clipping for a fixed rectangle, supplying x, y, width, and height.

Can I put my access key in frontend code?

Keep it private and server-side. A key exposed in a public page or URL can be copied and reused; use a signed link when a screenshot URL must be public.