# Scrapfly Documentation ## Table of Contents ### Dashboard - [Intro](https://scrapfly.io/docs) - [Project](https://scrapfly.io/docs/project) - [Account](https://scrapfly.io/docs/account) - [Workspace & Team](https://scrapfly.io/docs/workspace-and-team) - [Billing](https://scrapfly.io/docs/billing) ### Products #### MCP Server - [Getting Started](https://scrapfly.io/docs/mcp/getting-started) - [Tools & API Spec](https://scrapfly.io/docs/mcp/tools) - [Authentication](https://scrapfly.io/docs/mcp/authentication) - [Examples & Use Cases](https://scrapfly.io/docs/mcp/examples) - [FAQ](https://scrapfly.io/docs/mcp/faq) ##### Integrations - [Overview](https://scrapfly.io/docs/mcp/integrations) - [Claude Desktop](https://scrapfly.io/docs/mcp/integrations/claude-desktop) - [Claude Code](https://scrapfly.io/docs/mcp/integrations/claude-code) - [ChatGPT](https://scrapfly.io/docs/mcp/integrations/chatgpt) - [Cursor](https://scrapfly.io/docs/mcp/integrations/cursor) - [Cline](https://scrapfly.io/docs/mcp/integrations/cline) - [Windsurf](https://scrapfly.io/docs/mcp/integrations/windsurf) - [Zed](https://scrapfly.io/docs/mcp/integrations/zed) - [Roo Code](https://scrapfly.io/docs/mcp/integrations/roo-code) - [VS Code](https://scrapfly.io/docs/mcp/integrations/vscode) - [LangChain](https://scrapfly.io/docs/mcp/integrations/langchain) - [LlamaIndex](https://scrapfly.io/docs/mcp/integrations/llamaindex) - [CrewAI](https://scrapfly.io/docs/mcp/integrations/crewai) - [OpenAI](https://scrapfly.io/docs/mcp/integrations/openai) - [n8n](https://scrapfly.io/docs/mcp/integrations/n8n) - [Make](https://scrapfly.io/docs/mcp/integrations/make) - [Zapier](https://scrapfly.io/docs/mcp/integrations/zapier) - [Vapi AI](https://scrapfly.io/docs/mcp/integrations/vapi) - [Agent Builder](https://scrapfly.io/docs/mcp/integrations/agent-builder) - [Custom Client](https://scrapfly.io/docs/mcp/integrations/custom-client) #### Web Scraping API - [Getting Started](https://scrapfly.io/docs/scrape-api/getting-started) - [API Specification]() - [Monitoring](https://scrapfly.io/docs/monitoring) - [Customize Request](https://scrapfly.io/docs/scrape-api/custom) - [Debug](https://scrapfly.io/docs/scrape-api/debug) - [Anti Scraping Protection](https://scrapfly.io/docs/scrape-api/anti-scraping-protection) - [Proxy](https://scrapfly.io/docs/scrape-api/proxy) - [Proxy Mode](https://scrapfly.io/docs/scrape-api/proxy-mode) - [Proxy Mode - Screaming Frog](https://scrapfly.io/docs/scrape-api/proxy-mode/screaming-frog) - [Proxy Mode - Apify](https://scrapfly.io/docs/scrape-api/proxy-mode/apify) - [(Auto) Data Extraction](https://scrapfly.io/docs/scrape-api/extraction) - [Javascript Rendering](https://scrapfly.io/docs/scrape-api/javascript-rendering) - [Javascript Scenario](https://scrapfly.io/docs/scrape-api/javascript-scenario) - [SSL](https://scrapfly.io/docs/scrape-api/ssl) - [DNS](https://scrapfly.io/docs/scrape-api/dns) - [Cache](https://scrapfly.io/docs/scrape-api/cache) - [Batch (Multi-URL Scraping)](https://scrapfly.io/docs/scrape-api/batch) - [Session](https://scrapfly.io/docs/scrape-api/session) - [Webhook](https://scrapfly.io/docs/scrape-api/webhook) - [Schedule](https://scrapfly.io/docs/scrape-api/schedule) - [Screenshot](https://scrapfly.io/docs/scrape-api/screenshot) - [Errors](https://scrapfly.io/docs/scrape-api/errors) - [Timeout](https://scrapfly.io/docs/scrape-api/understand-timeout) - [Throttling](https://scrapfly.io/docs/throttling) - [Troubleshoot](https://scrapfly.io/docs/scrape-api/troubleshoot) - [Billing](https://scrapfly.io/docs/scrape-api/billing) - [FAQ](https://scrapfly.io/docs/scrape-api/faq) #### Crawler API - [Getting Started](https://scrapfly.io/docs/crawler-api/getting-started) - [API Specification]() - [Retrieving Results](https://scrapfly.io/docs/crawler-api/results) - [WARC Format](https://scrapfly.io/docs/crawler-api/warc-format) - [Data Extraction](https://scrapfly.io/docs/crawler-api/extraction-rules) - [Webhook](https://scrapfly.io/docs/crawler-api/webhook) - [Schedule](https://scrapfly.io/docs/crawler-api/schedule) - [Billing](https://scrapfly.io/docs/crawler-api/billing) - [Errors](https://scrapfly.io/docs/crawler-api/errors) - [Troubleshoot](https://scrapfly.io/docs/crawler-api/troubleshoot) - [FAQ](https://scrapfly.io/docs/crawler-api/faq) #### Screenshot API - [Getting Started](https://scrapfly.io/docs/screenshot-api/getting-started) - [API Specification]() - [Accessibility Testing](https://scrapfly.io/docs/screenshot-api/accessibility) - [Webhook](https://scrapfly.io/docs/screenshot-api/webhook) - [Schedule](https://scrapfly.io/docs/screenshot-api/schedule) - [Billing](https://scrapfly.io/docs/screenshot-api/billing) - [Errors](https://scrapfly.io/docs/screenshot-api/errors) #### Extraction API - [Getting Started](https://scrapfly.io/docs/extraction-api/getting-started) - [API Specification]() - [Rules Template](https://scrapfly.io/docs/extraction-api/rules-and-template) - [LLM Extraction](https://scrapfly.io/docs/extraction-api/llm-prompt) - [AI Auto Extraction](https://scrapfly.io/docs/extraction-api/automatic-ai) - [Webhook](https://scrapfly.io/docs/extraction-api/webhook) - [Billing](https://scrapfly.io/docs/extraction-api/billing) - [Errors](https://scrapfly.io/docs/extraction-api/errors) - [FAQ](https://scrapfly.io/docs/extraction-api/faq) #### Data API #### Proxy Saver - [Getting Started](https://scrapfly.io/docs/proxy-saver/getting-started) - [Fingerprints](https://scrapfly.io/docs/proxy-saver/fingerprints) - [Optimizations](https://scrapfly.io/docs/proxy-saver/optimizations) - [SSL Certificates](https://scrapfly.io/docs/proxy-saver/certificates) - [Protocols](https://scrapfly.io/docs/proxy-saver/protocols) - [Pacfile](https://scrapfly.io/docs/proxy-saver/pacfile) - [Secure Credentials](https://scrapfly.io/docs/proxy-saver/security) - [Billing](https://scrapfly.io/docs/proxy-saver/billing) #### Cloud Browser API - [Getting Started](https://scrapfly.io/docs/cloud-browser-api/getting-started) - [Proxy & Geo-Targeting](https://scrapfly.io/docs/cloud-browser-api/proxy) - [Unblock API](https://scrapfly.io/docs/cloud-browser-api/unblock) - [Captcha Solver](https://scrapfly.io/docs/cloud-browser-api/captcha-solver) - [File Downloads](https://scrapfly.io/docs/cloud-browser-api/file-downloads) - [Session Resume](https://scrapfly.io/docs/cloud-browser-api/session-resume) - [Human-in-the-Loop](https://scrapfly.io/docs/cloud-browser-api/human-in-the-loop) - [Debug Mode](https://scrapfly.io/docs/cloud-browser-api/debug-mode) - [Browser Extensions](https://scrapfly.io/docs/cloud-browser-api/extensions) - [Native Browser MCP](https://scrapfly.io/docs/cloud-browser-api/mcp) - [DevTools Protocol](https://scrapfly.io/docs/cloud-browser-api/cdp-reference) ##### Integrations - [Puppeteer](https://scrapfly.io/docs/cloud-browser-api/puppeteer) - [Playwright](https://scrapfly.io/docs/cloud-browser-api/playwright) - [Selenium](https://scrapfly.io/docs/cloud-browser-api/selenium) - [Vercel Agent Browser](https://scrapfly.io/docs/cloud-browser-api/agent-browser) - [Browser Use](https://scrapfly.io/docs/cloud-browser-api/browser-use) - [Stagehand](https://scrapfly.io/docs/cloud-browser-api/stagehand) - [Billing](https://scrapfly.io/docs/cloud-browser-api/billing) - [Errors](https://scrapfly.io/docs/cloud-browser-api/errors) ### Tools - [Antibot Detector](https://scrapfly.io/docs/tools/antibot-detector) ### SDK - [Golang](https://scrapfly.io/docs/sdk/golang) - [Python](https://scrapfly.io/docs/sdk/python) - [Rust](https://scrapfly.io/docs/sdk/rust) - [TypeScript](https://scrapfly.io/docs/sdk/typescript) - [Scrapy](https://scrapfly.io/docs/sdk/scrapy) ### Integrations - [Getting Started](https://scrapfly.io/docs/integration/getting-started) - [LangChain](https://scrapfly.io/docs/integration/langchain) - [LlamaIndex](https://scrapfly.io/docs/integration/llamaindex) - [CrewAI](https://scrapfly.io/docs/integration/crewai) - [Zapier](https://scrapfly.io/docs/integration/zapier) - [Make](https://scrapfly.io/docs/integration/make) - [n8n](https://scrapfly.io/docs/integration/n8n) ### Academy - [Overview](https://scrapfly.io/academy) - [Web Scraping Overview](https://scrapfly.io/academy/scraping-overview) - [Tools](https://scrapfly.io/academy/tools-overview) - [Reverse Engineering](https://scrapfly.io/academy/reverse-engineering) - [Static Scraping](https://scrapfly.io/academy/static-scraping) - [HTML Parsing](https://scrapfly.io/academy/html-parsing) - [Dynamic Scraping](https://scrapfly.io/academy/dynamic-scraping) - [Hidden API Scraping](https://scrapfly.io/academy/hidden-api-scraping) - [Headless Browsers](https://scrapfly.io/academy/headless-browsers) - [Hidden Web Data](https://scrapfly.io/academy/hidden-web-data) - [JSON Parsing](https://scrapfly.io/academy/json-parsing) - [Data Processing](https://scrapfly.io/academy/data-processing) - [Scaling](https://scrapfly.io/academy/scaling) - [Walkthrough Summary](https://scrapfly.io/academy/walkthrough-summary) - [Scraper Blocking](https://scrapfly.io/academy/scraper-blocking) - [Proxies](https://scrapfly.io/academy/proxies) --- 1. [DevTools Protocol](https://scrapfly.io/docs/cloud-browser-api/cdp-reference) 2. Antibot # Antibot Experimental Scrapfly **Dependencies:** [Accessibility](https://scrapfly.io/docs/cloud-browser-api/cdp-reference/Accessibility), [Page](https://scrapfly.io/docs/cloud-browser-api/cdp-reference/Page) - [Commands (28)](#commands) - [Events (4)](#events) - [Types (7)](#types) No symbols match your filter. ## Commands #### `Antibot.performAction` Scrapfly Performs an accessibility action on a node identified by AXNodeId. Retries automatically (up to 10 times at 200ms intervals) for OOPIFs where the browser-side AX tree may take time to populate. ###### Parameters | Name | Type | Description | |---|---|---| | `axNodeId` | `Accessibility.AXNodeId` | | | `action` | `string` | AX action to perform. Currently only "doDefault" is implemented. | | `frameId` (optional) | `Page.FrameId` | Frame containing the target node. If omitted, uses the main frame. | | `metadata` (optional) | `string` | | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.findAndPerformAction` Scrapfly Searches the browser-side AX tree across ALL frames (including OOPIFs) for a node matching the selector, then performs the specified action. Only "role" and "axNodeId" selector types are supported. For "role" type, query is the AX role (e.g. "checkbox", "button") and the browser walks all frames' AX trees. This works for OOPIF frames where CDP Accessibility.getFullAXTree cannot reach cross-process nodes. Retries up to 40 times at 300ms intervals (~12s) if no match found. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | Only "role" and "axNodeId" selector types are supported. | | `action` | `string` | AX action to perform. Currently only "doDefault" is implemented. | | `name` (optional) | `string` | Optional AX accessible name substring to match. Filters matched nodes by their accessible name. Works with both role and axNodeId. | | `frameUrl` (optional) | `string` | Optional frame URL glob pattern to restrict search (e.g. "\*cloudflare.com\*"). | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | | `foundNodeId` (optional) | `string` | The AX node ID that was found and acted upon. | | `foundRole` (optional) | `string` | The role of the found node. | | `foundName` (optional) | `string` | The name of the found node. | #### `Antibot.moveTo` Scrapfly Moves mouse to target with human-like Bezier curve trajectory. Includes natural jitter and distortion to mimic hand tremor. For non-steady moves greater than 50px, there is a 30% chance of overshooting by 3-12px then correcting back. Supports all selector types except bottom. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | | | `relativePosition` (optional) | `Coordinate` | Position within element bounds as ratio \[0-1\] for each axis. Default: random position within 0.2-0.8 of bounds. | | `absoluteOffset` (optional) | `boolean` | For "coord" selector type only: if true, treat the query coordinates as an offset from the current mouse position rather than absolute viewport coordinates. Default: false. | | `steady` (optional) | `boolean` | If true, reduces curve deviation and distortion, and disables overshoot. Use for small or precise targets where accuracy matters. Default: false. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.clickOn` Scrapfly Moves to target then clicks with human-like timing. Supports all selector types except bottom. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | | | `relativePosition` (optional) | `Coordinate` | | | `button` (optional) | `string` | Mouse button: "left", "right", or "middle". Default: "left". | | `clickDuration` (optional) | `number` | Hold duration in seconds between mousedown and mouseup. Default: random between 0.1 and 0.4 seconds. | | `clickCount` (optional) | `integer` | Number of clicks (e.g. 2 for double-click). Default: 1. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.dragAndDrop` Scrapfly Drag from source to destination with human-like Bezier movement. Supports all selector types except bottom. ###### Parameters | Name | Type | Description | |---|---|---| | `from` | `Selector` | | | `to` | `Selector` | | | `fromRelativePosition` (optional) | `Coordinate` | Position within source element bounds as ratio \[0-1\]. Default: center area. | | `toRelativePosition` (optional) | `Coordinate` | Position within destination element bounds as ratio \[0-1\]. Default: center area. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.clickAndHold` Scrapfly Moves to target element, presses mouse down, holds for a minimum time, then releases. Used for captcha puzzles requiring long-press interactions. Supports all selector types except bottom. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | | | `relativePosition` (optional) | `Coordinate` | | | `holdTime` (optional) | `number` | Minimum hold duration in seconds. Default: random between 1.0 and 3.0. | | `button` (optional) | `string` | Mouse button: "left", "right", or "middle". Default: "left". | | `frameUrl` (optional) | `string` | Frame URL glob pattern to restrict element search to matching frames. Uses shell-style wildcards (e.g. "\*cloudflare.com\*", "\*recaptcha\*"). | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.clickAndSlide` Scrapfly Moves to target element, presses mouse down, slides the mouse to a target position, then releases. Used for slider captcha puzzles. Supports all selector types except bottom. Two modes: 1\. Fixed distance: provide "distance" in CSS pixels. 2\. Target selector: provide "target" selector — the command resolves both source and target positions and computes the slide distance automatically with slight human-like imprecision. At least one of "distance" or "target" must be provided. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | | | `relativePosition` (optional) | `Coordinate` | | | `distance` (optional) | `number` | Horizontal slide distance in CSS pixels (positive = right, negative = left). | | `target` (optional) | `Selector` | Target element selector — the command slides from "selector" to "target". Distance is computed automatically with human-like imprecision. | | `targetRelativePosition` (optional) | `Coordinate` | Position within target element bounds as ratio \[0-1\]. | | `verticalOffset` (optional) | `number` | Vertical slide offset in CSS pixels. Default: 0 (horizontal only). | | `button` (optional) | `string` | Mouse button: "left", "right", or "middle". Default: "left". | | `frameUrl` (optional) | `string` | Frame URL glob pattern to restrict element search to matching frames. Uses shell-style wildcards (e.g. "\*captcha\*"). | | `overshoot` (optional) | `boolean` | If true, overshoot past the destination on the X axis by 5-15px then correct back. Simulates a human dragging past the slider endpoint (captcha sites typically clamp the slider position). Default: false. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.scroll` Scrapfly Human-like scroll. Three modes: 1\. Element into view: provide selector (css/xpath/axNodeId/coord/role). Scrolls until element is within 20% of viewport center, using wheel events in 3-8 steps. Skips if already visible near center. 2\. Scroll to bottom: provide selector {type:"bottom", query:""}. Scrolls 0.5-0.9x viewport height per step, 3-8 wheel events with 50-150ms delays. If mouse is near origin, first moves it to a random position with a Bezier curve. Returns atBottom=true when scrollY is within 5px of the maximum scroll offset. 3\. Manual delta: provide delta (no selector). Scrolls by the given pixel offset using 3-8 wheel steps. Supports all selector types including bottom. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` (optional) | `Selector` | Target element to scroll into view, or {type:"bottom", query:""} to scroll toward page bottom. | | `delta` (optional) | `Coordinate` | Manual scroll delta in CSS viewport pixels. Follows the DOM window.scrollBy(x, y) convention: positive y = scroll DOWN (toward the bottom of the page), positive x = scroll RIGHT. The handler flips signs internally when the session is fingerprinted as macOS/iOS (which enable natural-scroll by default), so the external contract is consistent across all spoofed OSes. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | | `atBottom` (optional) | `boolean` | True when the page is at or near the bottom (within 5px of max scroll). Only set when selector type is "bottom". | #### `Antibot.typeText` Scrapfly Types text character by character with human WPM timing model. Uses profile-aware keyboard mapping for correct key codes. Timing: base\_delay = 60 / (wpm \* 5) seconds per keystroke, with per-character random variation, common bigram speedup, space pauses, and shift penalty for uppercase characters. ###### Parameters | Name | Type | Description | |---|---|---| | `text` | `string` | | | `wpm` (optional) | `number` | Words per minute. Default: 60. Typical human range: 30-80. At 60 WPM: ~200ms base delay between keystrokes. At 30 WPM: ~400ms. At 120 WPM: ~100ms. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.fill` Scrapfly Clicks on element, optionally clears it, then types text with human timing. Supports all selector types except bottom. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | | | `text` | `string` | | | `relativePosition` (optional) | `Coordinate` | | | `clear` (optional) | `boolean` | Clear existing content first by sending Ctrl+A then Backspace. Default: false. | | `wpm` (optional) | `number` | Words per minute for typing. Default: 60. See typeText for timing details. | | `paste` (optional) | `boolean` | Simulate paste instead of keystroke typing. When true, writes the text to the system clipboard then fires Ctrl+V (Cmd+V on macOS) with real keyboard events (kFromDebugger = isTrusted true) so the browser treats it as genuine user input and dispatches paste + input events with the expected clipboardData. Much faster than typing for long strings; useful for passwords, tokens, or pre-filled data. Default: false. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.showCursor` Scrapfly Injects a debug cursor overlay (red dot + trail) for visual testing. Persists across navigations — re-injected automatically on page load. ###### Parameters | Name | Type | Description | |---|---|---| | `keepHistory` (optional) | `boolean` | When true, the cursor trail retains its FULL movement history at constant opacity instead of the default rolling ~60-point fading trail. This makes a single screenshot show the entire path the cursor took (approach + tremor), not just its current position — use it to debug movement trajectories. Default: false. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.highlightTarget` Scrapfly Highlights a target element on the debug cursor overlay: four corner brackets painted around the element's bounding box in a kind-specific color, auto-expiring after ttlMs. Use to signal what the agent is ABOUT to interact with (focus paint before dispatch) so an operator replaying the screencast can see intent, not just outcome. No-op when showCursor hasn't been called for this session — the paint pipeline only runs while the cursor overlay is enabled. Bounds resolution is the same Mojo path QuerySelectorBounds uses (no JS execution, no DOM mutation). Out-of-viewport or hidden elements still receive a paint when their layout box is non-empty — the corner brackets may sit off-screen in that case, which is the truthful representation of where the element is. Selector types: same set as moveTo (css / xpath / axNodeId / coord / backendNodeId). For backendNodeId, the query is the integer BackendNodeId as a decimal string. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | | | `kind` (optional) | `string` | Color kind. Single ASCII character. Recognized: "C" — click hint (amber, about-to-act) "T" — type / fill hint (blue) "V" — vault-resolved credential fill (teal-cyan) "H" — hover hint (lavender) "S" — scroll-into-view hint (purple) "O" — outcome: success (green, post-action flash) "X" — outcome: failure (red, post-action flash) Unknown values fall back to amber. Pass "" or omit to clear. | | `ttlMs` (optional) | `integer` | Time in milliseconds the brackets remain visible before fading. Default 1500ms. Clamped server-side to \[0, 30000\]. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.previewMousePath` Scrapfly Paints a "going there next" preview line on the cursor overlay: a thin semi-transparent straight segment from the current tracked cursor position to the target element's center. Use just before firing a click/move to telegraph intent — the operator sees WHERE the cursor is about to travel before any motion begins. The straight line is intentional: it represents intent, not the actual Bezier trajectory the human-input model will draw (which is randomized per-call and shouldn't be teased before it runs). No-op when showCursor isn't enabled. Fire-and-forget — agents call this in parallel with the real click/move dispatch and never await the response. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | | | `ttlMs` (optional) | `integer` | Time in milliseconds the preview line remains visible before fading. Should be slightly longer than the expected mouse-move duration so the line is still visible while the cursor is in transit. Default 500ms. Clamped server-side to \[0, 5000\]. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.getFrames` Scrapfly Returns all frames including OOPIFs with their metadata. Uses ForEachRenderFrameHost to enumerate every frame in the page, including cross-origin out-of-process iframes. ###### Return Object | Name | Type | Description | |---|---|---| | `frames` | `array<FrameInfo>` | | #### `Antibot.locateElement` Scrapfly Locates an element in a specific frame and returns its bounding box in main-frame viewport coordinates (CSS pixels). This allows clicking on elements inside OOPIFs with correct screen-space coordinates. Only "css", "xpath", and "axNodeId" selector types are supported. ###### Parameters | Name | Type | Description | |---|---|---| | `frameId` | `Page.FrameId` | | | `selector` | `Selector` | Only css, xpath, and axNodeId selector types are supported. | | `relativePosition` (optional) | `Coordinate` | | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | | `pointX` (optional) | `number` | Resolved click point in viewport coordinates. | | `pointY` (optional) | `number` | | | `boundsX` (optional) | `number` | Element bounding box in viewport coordinates. | | `boundsY` (optional) | `number` | | | `boundsWidth` (optional) | `number` | | | `boundsHeight` (optional) | `number` | | #### `Antibot.locateElementAcrossFrames` Scrapfly Locates an element across ALL frames (main + iframes/OOPIFs). Tries main frame first, then walks child frames until found. Returns bounding box in main-frame CSS viewport coordinates. Supports css, xpath, axNodeId, coord, and role selector types (not bottom). ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | Supports css, xpath, axNodeId, coord, and role types. Not bottom. | | `relativePosition` (optional) | `Coordinate` | | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | | `pointX` (optional) | `number` | | | `pointY` (optional) | `number` | | | `boundsX` (optional) | `number` | | | `boundsY` (optional) | `number` | | | `boundsWidth` (optional) | `number` | | | `boundsHeight` (optional) | `number` | | #### `Antibot.waitForElement` Scrapfly Waits for a selector to appear in any frame (main + iframes/OOPIFs). Polls natively via Mojo every 200ms (no JS execution). Searches main frame first, then child frames on each poll cycle. Supports css, xpath, axNodeId, coord, and role selector types (not bottom). ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | | | `timeout` (optional) | `integer` | Timeout in milliseconds. Default: 10000 (10s). | | `visible` (optional) | `boolean` | If true, also checks that the element has non-zero bounding box dimensions (width > 0 and height > 0). Note: does NOT check CSS visibility, display, or opacity properties. Default: false (just checks existence in the DOM). | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | | `frameId` (optional) | `Page.FrameId` | Reserved for future use. Currently always null. | #### `Antibot.getMousePosition` Scrapfly Returns the current tracked mouse position in CSS viewport pixels. ###### Return Object | Name | Type | Description | |---|---|---| | `x` | `number` | | | `y` | `number` | | #### `Antibot.isElementVisible` Scrapfly Checks whether an element is visible in the viewport. Only "css" and "xpath" selector types are supported. Searches main frame first, then child frames (iframes/OOPIFs). Visibility is determined by the renderer (checks display, opacity, dimensions, and viewport intersection). ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | Only css and xpath selector types are supported. | ###### Return Object | Name | Type | Description | |---|---|---| | `visible` | `boolean` | | | `exists` (optional) | `boolean` | True if element exists in the DOM but is hidden (not visible). | | `reason` (optional) | `string` | Human-readable reason when not visible (e.g. "zero size", "off viewport"). | #### `Antibot.isFocused` Scrapfly Checks whether the currently focused element matches the selector. Only "css" and "xpath" selector types are supported. Searches the main frame first, then iframes/OOPIFs — focus may be inside an OOPIF. Useful as a pre-flight check before sending keystrokes blindly to the focused element: e.g. PasswordManager.prefillChoice uses this to confirm the password field is still focused before typing. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | Only css and xpath selector types are supported. | ###### Return Object | Name | Type | Description | |---|---|---| | `focused` | `boolean` | True iff `document.activeElement` (or the focused element in one of the iframes) matches the selector. | | `reason` (optional) | `string` | Human-readable reason when not focused (e.g. "no active element", "focused element does not match selector"). | #### `Antibot.pressKey` Scrapfly Sends a single key press with human-like timing (keyDown + keyUp, 30-70ms hold duration). Special key names (case-insensitive): "Enter", "Tab", "Escape" (or "Esc"), "Backspace", "Delete", "Space", "Home", "End", "PageUp", "PageDown", "ArrowUp" (or "Up"), "ArrowDown" (or "Down"), "ArrowLeft" (or "Left"), "ArrowRight" (or "Right") Single characters: any single character (e.g. "a", "A", "1", "@"). Shift is applied automatically when the character requires it. Modifier combos: prefix with "Ctrl+", "Shift+", "Alt+", or "Meta+" (case-insensitive). One modifier prefix per call. Examples: "Ctrl+a", "Ctrl+c", "Ctrl+v", "Shift+Tab", "Alt+F4" ###### Parameters | Name | Type | Description | |---|---|---| | `key` | `string` | Key name, single character, or modifier combo. See above for accepted values. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.hover` Scrapfly Moves mouse to element with human-like trajectory and pauses briefly to trigger hover states (CSS :hover, tooltips, menus). Supports all selector types except bottom. ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | | | `relativePosition` (optional) | `Coordinate` | | | `holdTime` (optional) | `integer` | How long to hold the hover position in milliseconds. Default: random between 500 and 1500ms. | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | #### `Antibot.selectOption` Scrapfly Selects an option in a <select> or custom dropdown. Only "css" and "xpath" selector types are supported. For native <select>: clicks the element, then selects the option via the browser's native popup. Fires change/input events. For custom dropdowns (Bootstrap, React Select, MUI, etc.): provide optionSelector — the command will click the trigger to open the dropdown, find the matching option element, and click it. Matching: provide exactly one of value, text, or index. For native <select>: \- "value" matches the <option> value attribute \- "text" matches the <option> text content (whitespace-stripped) \- "index" matches by 0-based position For custom dropdowns with optionSelector: \- "text" matches against option element's textContent \- "index" matches by 0-based position among matched elements \- If optionSelector already includes an attribute filter (e.g. ".dropdown-item\[data-value='US'\]"), the first match is clicked ###### Parameters | Name | Type | Description | |---|---|---| | `selector` | `Selector` | Only css and xpath selector types are supported. | | `value` (optional) | `string` | Select by option value attribute. Native <select> only. | | `text` (optional) | `string` | Select by visible text content (whitespace-stripped comparison). | | `index` (optional) | `integer` | Select by 0-based index among options. | | `optionSelector` (optional) | `string` | CSS selector for option elements in a custom dropdown. When provided, triggers click-based selection flow: 1. Click the trigger element (selector) to open the dropdown 2. Wait for elements matching optionSelector to appear in the DOM 3. Find the option matching text/index, or click the first match if the selector already includes an attribute filter 4. Click the matching option element Examples: ".dropdown-item", "\[role=option\]", "li\[data-value='US'\]" | ###### Return Object | Name | Type | Description | |---|---|---| | `success` | `boolean` | | | `errorMessage` (optional) | `string` | | | `selectedValue` (optional) | `string` | The value of the selected option. | | `selectedText` (optional) | `string` | The text of the selected option. | #### `Antibot.captchaEnable` Scrapfly Enables automatic captcha detection AND solving. While enabled, the browser scans the frame tree after each navigation, emits captchaDetected for recognized challenges, and then immediately drives the solve (slider / checkbox interaction, or remote solver for token types) serialized one-at-a-time. Clients observe progress via the captchaSolvingStarted / captchaSolved / captchaError events. No-op if already enabled. Disable with captchaDisable. #### `Antibot.captchaDisable` Scrapfly Disables captcha detection. The session history of detected captchas (and their solve/error outcomes) is preserved — retrieve it with getSolvedCaptchas. Events already in flight (from captchaEnable) may still arrive. #### `Antibot.getSolvedCaptchas` Scrapfly Returns the full list of captchas seen this session, including ones that failed and ones still pending. Preserved across captchaDisable so billing / telemetry can retrieve it at shutdown. ###### Return Object | Name | Type | Description | |---|---|---| | `records` | `array<CaptchaRecord>` | | #### `Antibot.solveCaptcha` Scrapfly Requests the browser to solve a previously detected captcha. The remote solver API key is read from the bot profile via variables.captchaSolverApiKey (not passed through CDP). Types that require the remote solver (turnstile token, datadome token, recaptcha, geetest) will fail with captchaError if the key is missing. The upstream proxy used by the remote solver is read from the bot profile via variables.captchaProxy (http://user:pass@host:port). Chromium itself egresses via a local soxy SOCKS5 proxy, but the remote solver needs direct HTTP-proxy access to the same upstream egress for IP-bound solves. Not passed through CDP to avoid leaking upstream creds on the wire. For turnstile\_checkbox and datadome\_slider no key is needed — the browser solves these via the existing Antibot interaction primitives. ###### Parameters | Name | Type | Description | |---|---|---| | `detectionId` (optional) | `string` | detectionId from a prior captchaDetected event. If omitted the browser picks up the most recent unsolved detection. | | `timeout` (optional) | `integer` | Seconds to wait for the remote solve (default 120). | ###### Return Object | Name | Type | Description | |---|---|---| | `detectionId` | `string` | | | `type` | `CaptchaType` | | | `method` | `string` | | | `token` (optional) | `string` | | #### `Antibot.disable` Scrapfly Disables the Antibot domain. ## Events #### `Antibot.captchaDetected` Scrapfly Emitted when the browser detects a captcha challenge on the page (Turnstile widget, DataDome slider/interstitial, reCAPTCHA, GeeTest). Once captchaEnable has been called, the browser autonomously solves the challenge (interaction for slider/checkbox, remote solver delegation for token types) and then emits captchaSolvingStarted / captchaSolved (or captchaError on failure) — the client does not need to call solveCaptcha. solveCaptcha remains available as an explicit escape hatch for manual re-trigger. ###### Parameters | Name | Type | Description | |---|---|---| | `detectionId` | `string` | Identifier the client passes back to solveCaptcha. | | `type` | `CaptchaType` | | | `frameUrl` | `string` | URL of the frame the captcha was detected in (may be an OOPIF). | | `siteKey` (optional) | `string` | Site key (Turnstile, reCAPTCHA, hCaptcha) or GeeTest gt value. | | `captchaUrl` (optional) | `string` | Challenge URL for types that need it (DataDome captcha delivery URL). | #### `Antibot.captchaSolvingStarted` Scrapfly Emitted when the browser starts solving a captcha (either via direct interaction or by dispatching a job to the remote solver). Useful for UI spinners / timing instrumentation on the client side. ###### Parameters | Name | Type | Description | |---|---|---| | `detectionId` | `string` | | | `type` | `CaptchaType` | | | `method` | `string` | How the browser will solve: "slider" \| "checkbox" \| "token". | #### `Antibot.captchaSolved` Scrapfly Emitted when a captcha is solved. For interaction-based solves (slider, checkbox) the token field is empty; for token solves delegated to a remote solver it contains the response token. ###### Parameters | Name | Type | Description | |---|---|---| | `detectionId` | `string` | | | `type` | `CaptchaType` | | | `method` | `string` | How the captcha was solved: "slider" \| "checkbox" \| "token". | | `token` (optional) | `string` | Solution token for remote-solver-backed solves. Empty/missing for interaction-based solves (slider, checkbox). | #### `Antibot.captchaError` Scrapfly Emitted when a captcha cannot be solved (timeout, missing API key, remote solver API error, DOM element not found, etc.). ###### Parameters | Name | Type | Description | |---|---|---| | `detectionId` | `string` | | | `type` | `CaptchaType` | | | `errorMessage` | `string` | | ## Types #### `SelectorType` (string) Scrapfly How to locate an element. Not all commands support all types; see each command's documentation for supported selector types. ###### Allowed Values - `css` - `xpath` - `axNodeId` - `backendNodeId` - `coord` - `role` - `bottom` #### `Selector` (object) Scrapfly Element selector — a type + query pair. The query format depends on the type: css — CSS selector, e.g. "#btn", "input\[name='email'\]" xpath — XPath expression, e.g. "//div\[@id='main'\]" axNodeId — integer AX node ID as string, e.g. "42" coord — "x,y" comma-separated CSS viewport pixels, e.g. "450,600" role — AX role name (case-insensitive), e.g. "checkbox", "button" bottom — no query needed (pass ""). Only valid for scroll. Not all commands support all selector types; see each command's docs. ###### Properties | Name | Type | Description | |---|---|---| | `type` | `SelectorType` | | | `query` | `string` | | #### `Coordinate` (object) Scrapfly A point in CSS viewport pixels. ###### Properties | Name | Type | Description | |---|---|---| | `x` | `number` | | | `y` | `number` | | #### `Rect` (object) Scrapfly A rectangle in CSS viewport pixels. ###### Properties | Name | Type | Description | |---|---|---| | `x` | `number` | | | `y` | `number` | | | `width` | `number` | | | `height` | `number` | | #### `FrameInfo` (object) Scrapfly Frame metadata returned by getFrames. ###### Properties | Name | Type | Description | |---|---|---| | `frameId` | `Page.FrameId` | | | `url` | `string` | | | `origin` | `string` | | | `frameName` | `string` | | | `isMainFrame` | `boolean` | Whether this is the main frame. | | `isOopif` | `boolean` | Whether this frame is an out-of-process iframe (OOPIF). | #### `CaptchaType` (string) Scrapfly \--- Captcha detection & solving --- Captcha challenge type surfaced by captchaDetected / captchaSolved / captchaError events. New types are added over time. ###### Allowed Values - `turnstile_checkbox` - `turnstile` - `datadome_slider` - `datadome` - `recaptcha` - `geetest` - `perimeterx_hold` - `aws_waf` #### `CaptchaRecord` (object) Scrapfly Per-detection record returned by getSolvedCaptchas. ###### Properties | Name | Type | Description | |---|---|---| | `detectionId` | `string` | UUID assigned by captchaDetected. | | `type` | `CaptchaType` | | | `frameUrl` | `string` | URL of the frame the captcha was detected in (or a `perimeterx-dom:<page-url>` synth URL for DOM-probed PX detections). | | `status` | `string` | "solved" \| "failed" \| "pending" — reflects the final state the browser reached for this detection at the time of the call. | | `detectedAt` | `number` | Unix-ms timestamp when captchaDetected fired for this record. | | `method` (optional) | `string` | How the browser solved (or attempted to solve) this captcha — one of: "slider" \| "checkbox" \| "managed" \| "hold" \| "token" \| "coords". Empty string while pending. | | `resolvedAt` (optional) | `number` | Unix-ms timestamp when the record transitioned to solved/failed. Unset while pending. | | `errorMessage` (optional) | `string` | Populated when status == "failed" — human-readable failure reason (timeout, missing API key, SDK error, etc.). |