Capture reference · v1

Rich capture, explained field by field

Rich capture is an additive layer on POST /screenshot. Use it when a binary screenshot is not enough: ask for readable Markdown, inspect the rendered DOM, capture diagnostics, clean obstructing UI, extract deterministic fields, or return a durable artifact. All rich analysis belongs in a JSON response.

JSON-first

Set responseType to json whenever you request analysis or actions.

Rendered page

The browser sees the post-JavaScript DOM, not only the original HTML.

Bounded

Output, nodes, diagnostics, actions, and time all have explicit limits.

complete request shape

{
  "url": "https://example.com/product/42",
  "format": "png",
  "responseType": "json",
  "width": 1440,
  "height": 900,
  "deviceScaleFactor": 2,
  "fullPage": true,
  "captureSelector": "main.product",
  "waitForSelector": ".price",
  "delay": 250,
  "extractMarkdown": true,
  "semanticSnapshot": { "detail": "summary", "selectorBundles": true },
  "diagnostics": { "network": true, "pageErrors": true, "maxEntries": 100 },
  "render": { "colorScheme": "light", "locale": "en-US", "reducedMotion": true },
  "cleanup": { "enabled": true, "preserveSelectors": [".product-gallery"] },
  "extract": {
    "fields": {
      "name": { "selector": "h1", "type": "text", "required": true },
      "price": { "selector": "[data-price]", "type": "number" }
    }
  }
}

01 · Request model

Start with the capture controls

A request supplies one source and any combination of output, viewport, rendering, analysis, automation, persistence, and extraction options. Unknown or reserved fields are rejected; use the OpenAPI contract for exact validation.

basic page capture

curl -X POST "$DOMSCOUT_API_BASE/screenshot" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $DOMSCOUT_API_KEY" \
  -d '{
    "url": "https://example.com/article",
    "format": "png",
    "responseType": "json",
    "extractMarkdown": true,
    "captureSelector": "article",
    "hideSelectors": [".cookie-banner", ".newsletter"],
    "waitForSelector": "article",
    "delay": 300
  }'

Source	Provide a public HTTP(S) url or inline html. captureSelector narrows the rendered page; selector remains its deprecated alias.
format	png, jpeg, webp, or pdf. PNG is the default. quality applies to jpeg and webp (1–100, default 80).
responseType	binary returns raw image/PDF bytes regardless of Accept ordering. json returns metadata and all requested Markdown, analysis, actions, or extraction fields.
Viewport	width 100–3840, height 100–2160, deviceScaleFactor 1–3, plus isMobile and hasTouch.
Capture area	fullPage captures the full scrollable page. captureSelector is the preferred selector field; selector remains a deprecated alias.
Timing	waitForSelector waits for a CSS selector; delay adds up to 5,000 ms after navigation/actions.
Output helpers	extractMarkdown, simplifyDom, semanticNodes, links, probe, captureMode, lazyScroll, PDF settings, and captureTimeline are optional. grid preserves inline HTML across responsive frames; skeleton preserves its early DOMContentLoaded frame before bounded hydration settling.
Saved captures	With save: true, JSON metadata includes captureId, retentionDays, and captureExpiresAt. A binary response exposes capture ID/expiry headers. GET /capture/{captureId} returns an owned retained capture's finite expiry or legacy permanent state and short-lived signed downloads. It has no separate S3-key field, but its URL can contain storage-path information and is a secret capability.

URL versus HTML

A URL is navigated and rendered in a browser. Inline html is rendered without navigation and is not slow-promoted by the URL navigation rule. Do not send URL credentials such as https://user:pass@host; use scoped headers or cookies instead.

Headers and cookies

headers are scoped to requests for the target origin. Cookies require name and value and may include domain, path, secure, and sameSite. Sensitive values are not returned in diagnostics or persisted artifacts.

02 · Rendering

Control the page before you read it

Use render for browser emulation and captureMode for alternate visual passes. Applied controls and non-fatal warnings are reported in metadata.

disableAnimations	Stops CSS/Web Animations where possible.
colorScheme / media	Emulates light, dark, or no-preference and screen or print media.
locale / timezone	Sets browser locale and IANA timezone such as en-US and Asia/Kolkata.
devicePreset	desktop, iphone13, pixel7, or ipad.
reducedMotion	Emulates a reduced-motion preference.
geolocation	Sets latitude, longitude, and optional accuracy.
userAgent	Overrides the User-Agent string up to 1,024 characters.
blockResourceTypes	Blocks document, stylesheet, image, media, font, script, xhr, fetch, websocket, or other resources.
blockDomains	Blocks up to 100 domain or subdomain suffixes.
transparentBackground / capturePadding	Makes the background transparent and/or adds 0–1,000 px padding.

Navigation settlingNavigation waits for DOMContentLoaded, then performs a bounded five-second network-idle settling wait. Long-lived background requests may produce warning: "network_idle_timeout" while still returning a capture. A true DOMContentLoaded timeout is terminal. Grid viewport passes retain raw inline HTML rather than resetting to a blank page. Skeleton mode captures its initial DOMContentLoaded frame before this later settling wait. Markdown extraction falls back from an empty main region to the body and then the accessibility tree when available.

03 · Inspect

Use semantic snapshots to understand the DOM

semanticSnapshot can be true for defaults or an options object for a bounded, versioned snapshot. It returns at analysis.semanticSnapshot and is useful for discovering reliable selectors before a later extraction or action.

semantic snapshot options

{
  "url": "https://example.com/checkout",
  "responseType": "json",
  "semanticSnapshot": {
    "detail": "full",
    "maxNodes": 2500,
    "selectorBundles": true,
    "timing": "both",
    "includeIframes": true
  }
}

Identity	Version, tag, role, accessible name, normalized text, approved non-sensitive attributes.
State	Visibility, viewport intersection, checked, disabled, selected, required, read-only, and validation state.
Geometry	CSS pixels, screenshot pixels, normalized coordinates, z-index, and element-from-point hit testing.
Selectors	Ranked CSS, XPath, text, role/name, ID, name, label, and test-ID candidates.
Frames	Accessible metadata for iframes; same-origin frames can also be used by automation actions.

Node IDs are evidence, not locators. IDs only identify nodes in that snapshot. For a future request, use one of the returned selector candidates or a stable locator. Snapshot output can be truncated at maxNodes (1–10,000).

04 · Diagnose

Capture structured diagnostics or a visual debug overlay

diagnostics returns a bounded, redacted HAR-like object. It is intentionally not a standards-compliant HAR and never includes cookies, authorization headers, form values, or request/response bodies.

diagnostics options

{
  "url": "https://example.com",
  "responseType": "json",
  "diagnostics": {
    "console": true,
    "pageErrors": true,
    "network": true,
    "resources": true,
    "timing": true,
    "maxEntries": 100
  },
  "debugOverlay": false
}

console	Console messages emitted by the page.
pageErrors	Unhandled page exceptions.
network	Failed requests, response statuses, redirects, and third-party summaries.
resources	Resource timing and transfer-size information.
timing	Navigation and resource timing data.
maxEntries	Bounds collected arrays; inspect analysis.diagnostics.truncated and summary.
debugOverlay	Draws errors and failed requests onto the captured image instead of returning structured diagnostics. It is capped at 200 entries, 2,048 characters each, and is available on every plan.

05 · Clean

Remove visual noise without losing important content

cleanup: true enables built-in heuristics for likely cookie banners, ads, chat widgets, newsletter popups, modal backdrops, and large sticky headers or footers. It is a heuristic, not a maintained third-party rules database.

Pro+ availability: Cleanup is a Pro+ DOM-intelligence feature. The platform can temporarily pause the product group for everyone; that returns 403 FEATURE_NOT_ENABLED with a platform reason, not an account-rollout requirement.

preserve an important element

{
  "cleanup": {
    "enabled": true,
    "preserveSelectors": [".product-gallery", "[data-domscout-preserve]"]
  }
}

Read the report

The response reports analysis.cleanup.removed, category counts, and removal evidence when available.

When not to use it

Do not enable cleanup when pixel fidelity or the presence of every overlay is the thing you are testing. Prefer hideSelectors when you need an explicit, deterministic hide list.

06 · Extract

Extract deterministic fields from rendered HTML

The extract object is selector-driven, not prompt-based. It works against the rendered DOM, so it can extract content that only appears after JavaScript runs. Use strict to fail the request when a required field is missing.

field extraction

{
  "url": "https://example.com/product/42",
  "responseType": "json",
  "semanticSnapshot": true,
  "extract": {
    "strict": false,
    "fields": {
      "title": { "selector": "h1", "type": "text", "required": true },
      "price": { "selector": ".price", "type": "number" },
      "image": { "selector": "img.hero", "type": "attribute", "attribute": "src" },
      "features": { "selector": ".features li", "type": "list" }
    }
  }
}

text	Normalized text from the first match, or every match when all is true.
number	A numeric value parsed from the selected element.
boolean	A boolean derived from the selected element state/content.
attribute	An attribute value; attribute is required, for example href or src.
html	The selected element's HTML.
url	A resolved URL value from a selected link or resource.
list	Every matching value; list fields always return all matches.

Field statuses

found includes the value and safe evidence. missing means the selector matched nothing. invalid_selector means the selector could not be evaluated. When a semantic snapshot is also requested, extraction evidence can include source node IDs.

07 · Operate

Understand responses, budgets, and automatic async

A successful JSON capture has status: "success". It may include markdown, markdownMeta, analysis, actionResults, tabs, performanceMetrics, base64 artifacts, and metadata.

200	Inline success. Parse the requested response fields.
202	Durable work accepted. Read jobId and pollUrl; rich output can be automatically promoted even without async: true.
206	The action budget ended after partial work. Inspect metadata.partialResult, actionsRemaining, budgetWarning, and any completed timeline frames.
400	Validation, unsafe URL, invalid selector/action, withdrawn upload source, forbidden reserved field, or invalid crawl pattern.
403	Authentication, plan, trusted-JavaScript entitlement, product-pause, or platform safety refusal. Use code and suggestions to distinguish the cause.
413	Request or body too large.
429	Per-second rate limit, quota/credit/overage ceiling, or plan limit.
504	Navigation or action timeout. If a partial result exists, it is included; retry with async: true for the worker budget.

Action budgets

The synchronous action budget is 24 seconds. Async, monitor, batch-child, and crawl-child work receive 52 seconds. A request that stacks multiple whole-DOM passes or combines rich analysis with fullPage/lazyScroll can be auto-promoted to a durable job.

08 · Safety

Handle captured data safely

Credentials

Never put credentials in target URLs. Use x-api-key for domscout auth and scoped headers/cookies for the target.

Redaction

Snapshots, diagnostics, artifacts, job metadata, and webhook payloads omit password/form values, cookies, authorization headers, and raw network bodies.

Retention

New saved artifacts use finite plan-bounded retention: 7, 30, or 90 days; 365 is Enterprise-only. Use the saved result or GET /capture/{captureId} for the effective expiry; the signed download URL is capped at one hour and never outlives that finite expiry. Historic rows with expiresAt null are legacy permanent retention, not a new unlimited option; their signed URLs still expire within one hour. Job metadata has its own operational expiry.

JavaScript

injectJS and waitForFunction are trusted-JavaScript features with plan, account-entitlement, and platform-switch requirements.

Next: use automation for actions or jobs & webhooks for multi-page work.