> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt > Use this file to discover all available pages before exploring further. # browser-automation > AI-powered browser automation using natural language and Playwright code execution **Server path:** `/browser-automation` | **Type:** Embedded | **PCID required:** No ## Tools | Tool | Description | | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`browser-automation_operator_run`](#browser-automation_operator_run) | Start a browser automation task using natural language. Returns sessionId, collectionId, logFileName.
BROWSER AUTOMATION PATTERN: Put run + poll loop + file saving in ONE node function. Do NOT create separate nodes.
Call capability\_details for 'browser-automation' to get the full workflow code pattern. | | [`browser-automation_operator_run_continue`](#browser-automation_operator_run_continue) | Check status of a running Browser Operator task. Call in a loop after browser-automation\_operator\_run until status is "completed" or "failed". Returns current status and log content. Poll every 3-5 seconds. | | [`browser-automation_playwright_run`](#browser-automation_playwright_run) | Run Playwright code in a remote cloud browser. Returns sessionId, collectionId, logFileName.
BROWSER AUTOMATION PATTERN: Put run + poll loop + file saving in ONE node function. Do NOT create separate nodes.
Call capability\_details for 'browser-automation' to get the full workflow code pattern. | | [`browser-automation_playwright_run_continue`](#browser-automation_playwright_run_continue) | Check status of a running Playwright task. Call in a loop after browser-automation\_playwright\_run until status is "completed" or "failed". Poll every 3-5 seconds. | | [`browser-automation_logins_list`](#browser-automation_logins_list) | List saved browser login contexts. These are pre-authenticated browser sessions that can be reused for automation tasks. Use the context ID with useContextService parameter in browser-automation\_operator\_run or browser-automation\_playwright\_run. | *** ## browser-automation\_operator\_run Start a browser automation task using natural language. Returns sessionId, collectionId, logFileName. BROWSER AUTOMATION PATTERN: Put run + poll loop + file saving in ONE node function. Do NOT create separate nodes. Call capability\_details for 'browser-automation' to get the full workflow code pattern. **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------- | --------- | -------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `task` | string | Yes | — | REQUIRED: Natural language description of the browser task. Write as a SINGLE LINE without line breaks. Be SPECIFIC - include: (1) Starting URL, (2) What action to take (click, fill, extract, navigate, download), (3) Which elements (button text, field labels), (4) Sample data to use for form filling, (5) What NOT to do if needed. GOOD EXAMPLES: "Navigate to [https://example.com/contact](https://example.com/contact), fill out the contact form with name=John Doe, email=[john@example.com](mailto:john@example.com), message=Test inquiry, then submit the form" or "Go to [https://example.com/products](https://example.com/products), scroll through all pages, extract product name, price, and description for each product, save as products.json". BAD EXAMPLES: "Register on the site" (too vague), "Get the data" (what data? from where?). | | `model` | string | No | `"google/gemini-3-flash-preview"` | AI model for browser automation. Default: 'google/gemini-3-flash-preview'. Only change if explicitly requested by the user. | | `agentMode` | string | No | `"hybrid"` | Agent interaction mode. 'dom': DOM-based tools using CSS selectors (works with any model). 'hybrid': Coordinate-based + DOM tools (DEFAULT, visual interactions). 'cua': Computer Use Agent mode (CUA-specific models only). | | `maxSteps` | number | No | `30` | Maximum actions the agent can take. Default: 30. Increase for complex multi-page tasks. | | `systemPrompt` | string | No | — | Role/context for the agent (e.g., "You are a helpful assistant filling out medical forms"). | | `cacheKey` | string | Yes | — | REQUIRED: Cache identifier string. Generate a unique random 8-character alphanumeric string, e.g. "a1b2c3d4" or "xK9mP2qL". Must be a hardcoded string literal, NOT a runtime variable. IMPORTANT: Generate a NEW unique value every time you update the code. | | `disableCache` | boolean | No | `false` | Whether to bypass caching. Default: false (caching ON). Always leave as false unless the user explicitly asks to disable caching. | | `cacheDurationDays` | number | No | `7` | Cache expiration in days. Default: 7. Use 30 for stable sites, 1 for frequently changing sites. | | `region` | string | No | `"us-west-2"` | Server region for browser execution. Default: us-west-2 (Oregon). Options: us-east-1 (Virginia), eu-central-1 (Frankfurt), ap-southeast-1 (Singapore). | | `proxies` | boolean | No | `false` | Enable residential proxies. Default: false. Set to true for sites that block datacenter IPs. | | `viewportWidth` | number | No | `1288` | Browser viewport width in pixels. Default: 1288. | | `viewportHeight` | number | No | `711` | Browser viewport height in pixels. Default: 711. | | `advancedStealth` | boolean | No | `false` | Enable advanced anti-detection. Default: false. Set to true for bot-protected sites. | | `blockAds` | boolean | No | `true` | Block ads for faster page loads. Default: true. | | `solveCaptchas` | boolean | No | `true` | Auto-solve CAPTCHAs when encountered. Default: true. | | `recordSession` | boolean | No | `true` | Enable session recording for replay/debugging. Default: true. | | `filesToUpload` | object\[] | No | — | Files to upload to browser before execution. Just say "upload filename" in task - the agent will handle file input clicking. Files must be publicly accessible URLs. | | `collectionId` | string | No | — | Filestorage collection ID to save output files (extracted data, screenshots, downloads). If not provided, uses default collection. | | `useContextService` | string | No | — | Saved login context ID (from browser\_logins\_list) to use pre-authenticated session. NOTE: Cookie injection not yet fully implemented - include login steps in task if authentication is needed. | ```json theme={null} { "type": "object", "properties": { "task": { "type": "string", "description": "REQUIRED: Natural language description of the browser task. Write as a SINGLE LINE without line breaks. Be SPECIFIC - include: (1) Starting URL, (2) What action to take (click, fill, extract, navigate, download), (3) Which elements (button text, field labels), (4) Sample data to use for form filling, (5) What NOT to do if needed. GOOD EXAMPLES: \"Navigate to https://example.com/contact, fill out the contact form with name=John Doe, email=john@example.com, message=Test inquiry, then submit the form\" or \"Go to https://example.com/products, scroll through all pages, extract product name, price, and description for each product, save as products.json\". BAD EXAMPLES: \"Register on the site\" (too vague), \"Get the data\" (what data? from where?)." }, "model": { "type": "string", "enum": [ "google/gemini-3-flash-preview", "google/gemini-2.5-flash", "google/gemini-2.5-pro", "openai/gpt-4o", "openai/gpt-4o-mini", "anthropic/claude-sonnet-4" ], "default": "google/gemini-3-flash-preview", "description": "AI model for browser automation. Default: 'google/gemini-3-flash-preview'. Only change if explicitly requested by the user." }, "agentMode": { "type": "string", "enum": [ "dom", "hybrid", "cua" ], "default": "hybrid", "description": "Agent interaction mode. 'dom': DOM-based tools using CSS selectors (works with any model). 'hybrid': Coordinate-based + DOM tools (DEFAULT, visual interactions). 'cua': Computer Use Agent mode (CUA-specific models only)." }, "maxSteps": { "type": "number", "default": 30, "description": "Maximum actions the agent can take. Default: 30. Increase for complex multi-page tasks." }, "systemPrompt": { "type": "string", "description": "Role/context for the agent (e.g., \"You are a helpful assistant filling out medical forms\")." }, "cacheKey": { "type": "string", "description": "REQUIRED: Cache identifier string. Generate a unique random 8-character alphanumeric string, e.g. \"a1b2c3d4\" or \"xK9mP2qL\". Must be a hardcoded string literal, NOT a runtime variable. IMPORTANT: Generate a NEW unique value every time you update the code." }, "disableCache": { "type": "boolean", "default": false, "description": "Whether to bypass caching. Default: false (caching ON). Always leave as false unless the user explicitly asks to disable caching." }, "cacheDurationDays": { "type": "number", "default": 7, "description": "Cache expiration in days. Default: 7. Use 30 for stable sites, 1 for frequently changing sites." }, "region": { "type": "string", "enum": [ "us-west-2", "us-east-1", "eu-central-1", "ap-southeast-1" ], "default": "us-west-2", "description": "Server region for browser execution. Default: us-west-2 (Oregon). Options: us-east-1 (Virginia), eu-central-1 (Frankfurt), ap-southeast-1 (Singapore)." }, "proxies": { "type": "boolean", "default": false, "description": "Enable residential proxies. Default: false. Set to true for sites that block datacenter IPs." }, "viewportWidth": { "type": "number", "default": 1288, "description": "Browser viewport width in pixels. Default: 1288." }, "viewportHeight": { "type": "number", "default": 711, "description": "Browser viewport height in pixels. Default: 711." }, "advancedStealth": { "type": "boolean", "default": false, "description": "Enable advanced anti-detection. Default: false. Set to true for bot-protected sites." }, "blockAds": { "type": "boolean", "default": true, "description": "Block ads for faster page loads. Default: true." }, "solveCaptchas": { "type": "boolean", "default": true, "description": "Auto-solve CAPTCHAs when encountered. Default: true." }, "recordSession": { "type": "boolean", "default": true, "description": "Enable session recording for replay/debugging. Default: true." }, "filesToUpload": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Public URL to the file to upload." }, "fileName": { "type": "string", "description": "Filename to use when uploading (e.g., \"data.csv\")." } } }, "description": "Files to upload to browser before execution. Just say \"upload filename\" in task - the agent will handle file input clicking. Files must be publicly accessible URLs." }, "collectionId": { "type": "string", "description": "Filestorage collection ID to save output files (extracted data, screenshots, downloads). If not provided, uses default collection." }, "useContextService": { "type": "string", "description": "Saved login context ID (from browser_logins_list) to use pre-authenticated session. NOTE: Cookie injection not yet fully implemented - include login steps in task if authentication is needed." } }, "required": [ "task", "cacheKey" ] } ``` *** ## browser-automation\_operator\_run\_continue Check status of a running Browser Operator task. Call in a loop after browser-automation\_operator\_run until status is "completed" or "failed". Returns current status and log content. Poll every 3-5 seconds. **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------- | | `sessionId` | string | Yes | — | Required: The sessionId returned by browser-automation\_operator\_run | | `logFileName` | string | No | — | The logFileName returned by browser-automation\_operator\_run. Enables live log streaming. | | `collectionId` | string | No | — | The collectionId returned by browser-automation\_operator\_run. Required with logFileName for log content. | ```json theme={null} { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Required: The sessionId returned by browser-automation_operator_run" }, "logFileName": { "type": "string", "description": "The logFileName returned by browser-automation_operator_run. Enables live log streaming." }, "collectionId": { "type": "string", "description": "The collectionId returned by browser-automation_operator_run. Required with logFileName for log content." } }, "required": [ "sessionId" ] } ``` *** ## browser-automation\_playwright\_run Run Playwright code in a remote cloud browser. Returns sessionId, collectionId, logFileName. BROWSER AUTOMATION PATTERN: Put run + poll loop + file saving in ONE node function. Do NOT create separate nodes. Call capability\_details for 'browser-automation' to get the full workflow code pattern. **Parameters:** | Parameter | Type | Required | Default | Description | | ------------------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | string | Yes | — | REQUIRED: Playwright JavaScript code. The `page` variable is pre-configured.
TO SAVE RESULTS - return this structure:
\{ writeToCollection: true, fileName: 'data.json', fileContent: JSON.stringify(yourData, null, 2) }
MULTIPLE FILES:
\{ writeToCollection: true, files: \[\{ fileName: 'a.json', fileContent: '...' }, \{ fileName: 'b.png', fileContent: buffer, contentType: 'image/png' }] }
EXAMPLE - Get page HTML (most reliable for unfamiliar sites):
await page.goto('[https://example.com](https://example.com)');
const html = await page.content();
return \{ writeToCollection: true, fileName: 'page.html', fileContent: html };
EXAMPLE - Extract data with selectors:
const items = await page.evaluate(() => Array.from(document.querySelectorAll('.item')).map(el => (\{ name: el.textContent })));
return \{ writeToCollection: true, fileName: 'items.json', fileContent: JSON.stringify(items, null, 2) };
EXAMPLE - Screenshot:
const buffer = await page.screenshot(\{ fullPage: true });
return \{ writeToCollection: true, fileName: 'screenshot.png', fileContent: buffer, contentType: 'image/png' };
BROWSER DOWNLOADS: Files downloaded by clicking links are automatically captured and saved. No special return value needed. | | `bindingData` | object | No | — | Object with key-value pairs to inject into Playwright code. MUST be an object like \{ url: "https\://..." }, NEVER a string. Access variables directly by name in code. | | `buildId` | string | No | — | For predictable file naming. Files become: \{buildId}-filename.json. Recommended: "playwright-\{timestamp}" or descriptive like "scrape-products". | | `collectionId` | string | No | — | Filestorage collection ID to save output files. Default: MultimediaArtifact collection. | | `useContextService` | string | No | — | Saved login context ID (from browser\_logins\_list) for pre-authenticated sessions. | ```json theme={null} { "type": "object", "properties": { "code": { "type": "string", "description": "REQUIRED: Playwright JavaScript code. The `page` variable is pre-configured.\n\nTO SAVE RESULTS - return this structure:\n{ writeToCollection: true, fileName: 'data.json', fileContent: JSON.stringify(yourData, null, 2) }\n\nMULTIPLE FILES:\n{ writeToCollection: true, files: [{ fileName: 'a.json', fileContent: '...' }, { fileName: 'b.png', fileContent: buffer, contentType: 'image/png' }] }\n\nEXAMPLE - Get page HTML (most reliable for unfamiliar sites):\nawait page.goto('https://example.com');\nconst html = await page.content();\nreturn { writeToCollection: true, fileName: 'page.html', fileContent: html };\n\nEXAMPLE - Extract data with selectors:\nconst items = await page.evaluate(() => Array.from(document.querySelectorAll('.item')).map(el => ({ name: el.textContent })));\nreturn { writeToCollection: true, fileName: 'items.json', fileContent: JSON.stringify(items, null, 2) };\n\nEXAMPLE - Screenshot:\nconst buffer = await page.screenshot({ fullPage: true });\nreturn { writeToCollection: true, fileName: 'screenshot.png', fileContent: buffer, contentType: 'image/png' };\n\nBROWSER DOWNLOADS: Files downloaded by clicking links are automatically captured and saved. No special return value needed." }, "bindingData": { "type": "object", "additionalProperties": true, "description": "Object with key-value pairs to inject into Playwright code. MUST be an object like { url: \"https://...\" }, NEVER a string. Access variables directly by name in code." }, "buildId": { "type": "string", "description": "For predictable file naming. Files become: {buildId}-filename.json. Recommended: \"playwright-{timestamp}\" or descriptive like \"scrape-products\"." }, "collectionId": { "type": "string", "description": "Filestorage collection ID to save output files. Default: MultimediaArtifact collection." }, "useContextService": { "type": "string", "description": "Saved login context ID (from browser_logins_list) for pre-authenticated sessions." } }, "required": [ "code" ] } ``` *** ## browser-automation\_playwright\_run\_continue Check status of a running Playwright task. Call in a loop after browser-automation\_playwright\_run until status is "completed" or "failed". Poll every 3-5 seconds. **Parameters:** | Parameter | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ----------------------------------------------------------------------- | | `sessionId` | string | Yes | — | Required: The sessionId returned by browser-automation\_playwright\_run | ```json theme={null} { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Required: The sessionId returned by browser-automation_playwright_run" } }, "required": [ "sessionId" ] } ``` *** ## browser-automation\_logins\_list List saved browser login contexts. These are pre-authenticated browser sessions that can be reused for automation tasks. Use the context ID with useContextService parameter in browser-automation\_operator\_run or browser-automation\_playwright\_run. **Parameters:** None ```json theme={null} { "type": "object", "properties": {} } ```