Protected requests

Use browser or residential_browser when a target needs JavaScript execution, cookies, dynamic DOM content, or a browser workflow. Request cookies and headers are accepted as input, but credentials should be scoped to the target and never written to logs.

For reusable multi-step automation, use Browser Workflows. A Data API request's browser_actions field is intentionally smaller and is meant for page readiness, lazy loading, or a consent overlay—not general browser automation.

Data API browser actionsCopy Anchor Link

The actions run in order after initial navigation and challenge handling, before the final waits and result capture. There can be at most 20 actions; each CSS selector must be 1–500 characters.

{
  "browser_actions": [
    { "type": "scroll", "delta_y": 900, "steps": 3, "interval_ms": 200 },
    { "type": "click", "selector": "button[data-load-more]", "timeout_ms": 10000 },
    {
      "type": "wait_for_selector",
      "selector": "article[data-loaded]",
      "state": "visible",
      "timeout_ms": 10000
    }
  ]
}

Browser actions do not support arbitrary JavaScript, navigation, form submission, keyboard events, uploads, downloads, coordinate clicks, or arbitrary sleeps. A click that changes the URL, opens a popup, or starts a download is blocked. Per-action timeouts cannot extend the request's overall timeout_ms.

Any non-empty browser_actions list enables JavaScript, promotes http to browser and residential to residential_browser, and bypasses the result cache. The request is billed as the effective browser route. Action failures are reported through user_error; common codes include BROWSER_ACTION_FAILED, BROWSER_ACTION_TIMEOUT, and BROWSER_ACTION_NAVIGATION_BLOCKED.

Waiting for dynamic contentCopy Anchor Link

wait_for_selector fails the request if the selector does not appear before the request deadline. Use wait_for_text when content is streamed or changes over time: it can wait for a minimum length, stable text, or a literal end_text marker. With on_timeout: "return_last" (the default), the last non-empty text is returned and the result metadata records that the wait was not satisfied; on_timeout: "fail" returns WAIT_FOR_TEXT_TIMEOUT.

Use result_text_selector to choose which element supplies result.text. Without it, the API returns the waited text when configured, or the page's body text.

Do not send credentials or secrets in a URL unless the target contract explicitly requires it. Redact protected data from logs and support tickets.

CAPTCHA and CloudflareCopy Anchor Link

CAPTCHA detection and solving are controlled by the service; clients do not submit provider keys, site keys, challenge tokens, or solutions. Browser requests can enter solving_captcha while the service handles a supported challenge.

Built-in Cloudflare protection is included in the selected route mode. A paid external CAPTCHA attempt may add a surcharge under the active pricing configuration; for new Data API requests, it counts toward a supplied max_credits_per_request cap. See Billing for charge behavior and Errors for retry decisions.