Skip to main content
JavaScript Instructions enable you to interact with web pages dynamically by automating user actions like clicking buttons, filling forms, waiting for content to load, and executing custom JavaScript code. This powerful feature allows you to scrape content that requires user interaction or appears after specific actions are performed. These instructions are essential for modern web scraping because many websites load content dynamically, hide information behind user interactions, or require form submissions to access data. With JavaScript Instructions, you can automate these interactions to extract the complete content you need.
JavaScript Instructions require js_render=true to function, as they operate within the browser environment during page rendering.

How JavaScript Instructions work

JavaScript Instructions execute sequentially within a real browser environment, simulating genuine user interactions. Each instruction waits for the previous one to complete before executing, ensuring reliable automation of complex user workflows. The process works as follows:
  1. Page loads - The browser renders the initial page content
  2. Wait/Wait_for parameters execute - Global wait conditions are processed first
  3. JavaScript Instructions execute - Each instruction runs in order, waiting for completion
  4. DOM updates - The page responds to interactions, potentially loading new content
  5. Final capture - The complete rendered page is captured after all instructions finish
This sequential execution ensures that dynamic content has time to load and that user interactions trigger the expected page changes.
JavaScript Instructions have a 40-second timeout limit. If your instruction sequence takes longer than 40 seconds to complete (due to many interactions, slow page responses, or redirects), the execution will stop and return whatever content is currently visible on the page. For complex workflows that may exceed this limit, consider using our Browser Sessions which provides up to 15 minutes of execution time and more advanced automation capabilities.

Basic usage

JavaScript Instructions are provided as a JSON array where each instruction is an object specifying the action and its parameters:
Use the Zenrows Playground to create and test your JavaScript Instructions visually, or use an Online URL Encoder to properly encode your instructions for API requests.

Available instructions

Click interactions

Simulates clicking on page elements like buttons, links, or interactive areas. This is one of the most fundamental interactions for web automation, enabling you to trigger actions that reveal hidden content, navigate through interfaces, or activate dynamic functionality.
JSON
Common use cases
  • Expanding collapsed content sections to access full article text
  • Navigating through pagination to scrape multiple pages of results
  • Triggering modal dialogs or popups that contain additional information
  • Activating dropdown menus to access navigation options
  • Loading additional content dynamically (infinite scroll triggers)
  • Accepting cookie consent banners or terms of service
Best practices
  • Always wait for elements to be clickable before clicking
  • Use specific selectors to avoid clicking wrong elements
  • Combine with wait_for to handle dynamic content loading
    JSON

Wait for selector

Pauses execution until a specific element appears in the DOM. This instruction is crucial for handling asynchronous content loading, which is common in modern web applications that use AJAX, React, Vue, or other dynamic frameworks.
JSON
When to use
  • Content loads asynchronously via AJAX or fetch requests
  • Elements appear after animations or CSS transitions
  • Waiting for user-triggered content to become available
  • Ensuring forms are fully rendered before interaction
  • After clicking buttons that trigger content loading
  • When dealing with single-page applications (SPAs)
If the selector doesn’t appear within the timeout period (default: 10 seconds), the instruction will fail and execution will continue to the next instruction. This contributes to the overall 40-second timeout limit for all JavaScript Instructions.

Wait for specific duration

Pauses execution for a fixed amount of time in milliseconds. While less precise than wait_for, this instruction is useful when you need to accommodate processes that don’t have visible indicators or when you need to ensure stability after rapid interactions.
JSON
Use cases
  • Allowing animations to complete before taking screenshots
  • Giving time for slow-loading content when no loading indicator exists
  • Preventing rate limiting by spacing requests appropriately
  • Ensuring page stability after rapid-fire interactions
  • Waiting for third-party widgets or ads to load
  • Accommodating server processing time for form submissions
JSON
The maximum allowed wait time for a single wait instruction is 10 seconds, and the total combined duration of all wait instructions cannot exceed 30 seconds. For example, you could use three {"wait": 10000} instructions (10 seconds each) but not four. This 30-second limit contributes to the overall 40-second timeout for the entire JavaScript Instructions sequence.

Wait for browser events

Waits for specific browser events to occur, providing more sophisticated timing control based on actual browser state rather than arbitrary time delays. This is particularly useful for ensuring that all network activity has completed or that the page has reached a stable state.
JSON
Event descriptions
  • networkidle - No network requests for 500ms (ideal for SPAs with API calls)
  • networkalmostidle - No more than 2 network requests for 500ms (less strict timing)
  • load - Page load event fired (all resources including images loaded)
  • domcontentloaded - DOM parsing completed (faster than load event)
Use cases
  • Ensure all API calls and resource loading have completed
  • Wait for specific browser lifecycle events
  • Avoid unnecessary waiting by responding to actual browser state
  • Use browser events as more accurate timing signals than fixed delays

Fill input fields

Populates form fields with specified values, enabling automation of data entry tasks. This instruction is essential for logging into websites, submitting forms, or providing input data that triggers dynamic content loading.
JSON
Supported input types
  • Text inputs (single-line text fields)
  • Email fields (with built-in validation)
  • Password fields (securely handled)
  • Search boxes (often trigger autocomplete)
  • Textarea elements (multi-line text)
  • Number inputs (numeric data entry)
Common applications
  • Login automation for accessing protected content
  • Search form submission to find specific content
  • Filter application to narrow down results
  • Contact form completion for lead generation
  • Registration form automation for account creation
  • Configuration forms for customizing page content
JSON

Checkbox interactions

Check or uncheck checkbox and radio button elements, allowing you to select options, agree to terms, or configure settings. These interactions are crucial for forms that require user consent or option selection.
JSON
Use cases
  • Accepting cookie consent or privacy policies
  • Selecting payment methods or shipping options
  • Configuring notification preferences
  • Filtering product catalogs by features
  • Agreeing to terms of service during registration
  • Enabling optional services or add-ons
Using check on an already checked element will not uncheck it. Use uncheck specifically to deselect elements. This prevents accidental state changes in your automation.

Select dropdown options

Choose options from dropdown menus by their value, enabling selection from predefined lists of options. This is essential for forms that use select elements for categories, locations, or other structured data.
JSON
Important notes
  • The second parameter must match the value attribute of the option, not the displayed text
  • Use the actual value from the HTML, which may differ from what users see
  • Works with both single and multiple select elements
  • Triggers change events that may load additional content
Common scenarios
  • Selecting countries for shipping calculations
  • Choosing product categories for filtered browsing
  • Setting language preferences for localized content
  • Selecting time zones or date formats
  • Choosing sorting options for search results
  • Configuring display preferences (items per page, view type)

Vertical scrolling

Scroll the page vertically by a specified number of pixels, essential for triggering content that loads based on scroll position or for ensuring elements are visible before interaction.
JSON
Common applications
  • Social media feeds with scroll loading
  • E-commerce sites with lazy-loaded product images
  • News sites with continuous article loading
  • Search results that load more items on scroll
  • Long-form content with progressive disclosure
  • Image galleries with scroll-triggered loading

Horizontal scrolling

Scroll the page horizontally by a specified number of pixels, useful for content that extends beyond the viewport width or for navigating horizontal carousels and galleries.
JSON
Use cases
  • Product image carousels on e-commerce sites
  • Data tables with many columns
  • Horizontal navigation menus
  • Timeline or calendar interfaces
  • Wide charts or graphs
  • Panoramic image viewers

Execute custom JavaScript (evaluate)

Run arbitrary JavaScript code within the page context, providing unlimited flexibility for complex interactions or page modifications that aren’t covered by standard instructions.
JSON
Common JavaScript patterns
JavaScript
Advanced use cases
  • Removing cookie banners or overlay advertisements
  • Triggering complex JavaScript functions specific to the site
  • Modifying page state to reveal hidden content
  • Collecting data from JavaScript variables
  • Simulating complex user interactions
  • Bypassing client-side restrictions

CAPTCHA solving

Automatically solve CAPTCHAs using integrated solving services, enabling automation of forms and processes that are protected by CAPTCHA challenges. CAPTCHA solving requires a 2Captcha API key configured in your Zenrows Integration Settings.
JSON
Supported CAPTCHA types
  • reCAPTCHA v2 - Standard checkbox and image challenges
  • reCAPTCHA v3 - Invisible background verification
  • Cloudflare Turnstile - Cloudflare’s CAPTCHA system
To ensure the CAPTCHA is solved before proceeding, add wait instructions before and after the CAPTCHA-solving step, allowing time for the CAPTCHA to load and be resolved.

Working with iframes

Standard instructions don’t work inside iframe elements due to browser security restrictions. Iframes create isolated contexts that require special handling to access their content and interact with their elements.

Frame instructions

All frame instructions require specifying the iframe selector as the first parameter
JSON

Revealing iframe content

Extract content from iframes for processing:
JSON
This creates a hidden div element with the iframe content encoded in base64:
HTML
For security reasons, iframe content isn’t included in the standard response. Use frame_reveal to explicitly extract iframe content when needed.

Using XPath selectors

In addition to CSS selectors, you can use XPath expressions for more precise element targeting:
JSON
XPath advantages
  • Text-based selection - Select elements by their text content
  • Complex conditions - Use logical operators and functions
  • Hierarchical navigation - Navigate parent/child relationships easily
  • Attribute matching - Complex attribute-based selection

Debugging JavaScript Instructions

Enable detailed execution reporting by adding json_response=true to your request:
Python

Understanding the debug report

The debug report provides comprehensive execution details:
JSON

Common use cases and workflows

Troubleshooting

Common issues and solutions

Debugging selector issues

When selectors aren’t working as expected:
1

Verify selector in browser

Open the target page in your browser and test the selector in DevTools console:
JavaScript
2

Check element timing

Ensure the element exists when the instruction runs:
JSON
3

Use alternative selectors

Try different selector strategies:
JSON
4

Check for dynamic content

Some elements are created dynamically:
JSON

Pricing

The js_instructions parameter doesn’t increase the request cost on its own. Cost still depends on js_render and premium_proxy, exactly as it would for a standard request.
You can monitor your Zenrows usage in multiple ways to stay informed about your account activity and prevent unexpected overages.Dashboard monitoring: View real-time usage statistics, remaining requests, success rates, and request history on your Analytics Page. You can also set up usage alerts in your notification settings to receive notifications when you approach your limits.Programmatic monitoring: For automated monitoring in your applications, call the /v1/subscriptions/self/details endpoint with your API key in the X-API-Key header. This returns real-time usage data that you can integrate into your monitoring systems. Learn more about the usage endpoint.Response header monitoring: Track your concurrency usage through response headers included with each request:
  • Concurrency-Limit: Your maximum concurrent requests
  • Concurrency-Remaining: Available concurrent request slots
  • X-Request-Cost: Cost of the current request

Frequently Asked Questions (FAQ)

When an instruction fails, execution continues with the next instruction. Use json_response=true to get detailed failure information and adjust your instructions accordingly. Critical failures may require adding wait_for instructions to ensure elements are available.
No, JavaScript Instructions require js_render=true because they operate within a browser environment. Static HTML requests cannot execute dynamic interactions or JavaScript code.
Execution time varies based on the complexity of instructions and page responsiveness. Simple clicks take 50-200ms, while waiting for elements can take several seconds. Use the debug report to analyze timing and optimize your instruction sequences.
Standard instructions don’t work with iframe content. Use frame-specific instructions like frame_click, frame_fill, and frame_wait_for to interact with elements inside iframes. You’ll need to specify the iframe selector as the first parameter.
There’s no hard limit on instruction count, but longer sequences increase execution time and potential failure points. For complex workflows, consider breaking them into smaller, focused instruction sets and making multiple requests if needed.
Use the solve_captcha instruction with a configured 2Captcha API key. Add wait instructions before and after CAPTCHA solving to allow time for loading and verification. Different CAPTCHA types require specific configuration options.
Yes, use the evaluate instruction to run custom JavaScript code that can modify page content, styling, or behavior. This is useful for removing overlays, triggering custom events, or preparing the page for data extraction.