JavaScript Scenario
A JavaScript scenario lets you drive a page — clicking, waiting, scrolling, filling inputs, or running custom JavaScript — before the HTML is returned. The scenario is a JSON object passed as the js_scenario parameter. This guide maps every supported instruction, the strict-mode toggle, the debugging report, and the timeout limit, with a decision checklist for choosing the right wait instruction.
Basic usage
Pass a JSON object with an instructions array as the js_scenario parameter. Each entry is one instruction; multiple instructions run one by one on the server side.
Selectors work in either CSS or XPath form. Any selector starting with / is treated as XPath; everything else is treated as CSS.
Because the scenario is JSON, a GET request must carry it stringified. The exact request shapes for each client are provided in the accompanying code modules (code0001, code0005, code0008).
Instruction map
The table below summarizes each instruction, its argument, and what it does. The full canonical syntax for each is in the accompanying code modules referenced in the right column.
Strict mode
Scenarios run in strict mode by default: any error aborts the whole scenario and returns an error. Set the strict key to false to let execution continue past a failing instruction. This is the key failure distinction — in strict mode a single bad selector stops everything; in non-strict mode later instructions still run.
Choosing the right wait
Three instructions cover waiting, and the choice depends on what you know about the page:
- wait — use when you know a fixed delay is enough (duration in ms).
- wait_for — use when an element must exist before the next step, and you only need to observe it.
- wait_for_and_click — use when the element must exist and you also need to click it. This is equivalent to a wait_for followed by a click on the same selector.
If the page loads content on scroll, use infinite_scroll instead of repeated scroll_y calls.
Worked example
The captured scenario below waits for a slow button, clicks it, scrolls horizontally twice with a pause between, then finishes. It demonstrates sequencing, the wait_for_and_click shortcut, and repeated use of the same instruction.
Because the scenario runs in strict mode by default, a missing #slow_button would abort the run. If you want the scrolls to still execute when the button is absent, set strict to false.
Infinite scrolling
infinite_scroll takes a configuration object with three keys:
- max_count — maximum number of scrolls; 0 means infinite.
- delay — pause between scrolls, in ms.
- end_click — optional click instruction fired when the end of the page is reached, typically a "load more" button. Supply selector and selector_type (css, auto, or xpath).
Note: infinite_scroll is not supported when stealth proxies are used.
Executing custom JavaScript
The evaluate instruction runs arbitrary JavaScript on the page. When json_response is true, the results of every evaluate instruction appear under the evaluate_results key in the JSON response — useful for returning computed values rather than scraping the DOM.
Debugging with the scenario report
Set json_response to true to receive a detailed report of scenario execution under the js_scenario_report key. This is the recommended way to diagnose a scenario that aborts or behaves unexpectedly.
Timeout
The whole scenario must complete within 40 seconds; otherwise the API times out. Keep waits and scroll counts within that budget.
| Instruction | Argument | What it does | Canonical syntax module |
|---|---|---|---|
| click | CSS/XPath selector | Click an element | code0011 |
| wait | duration in ms | Fixed pause | code0012 |
| wait_for | CSS/XPath selector | Wait for an element to appear | code0013 |
| wait_for_and_click | CSS/XPath selector | Wait for an element, then click it | code0014 |
| scroll_x | number of pixels | Horizontal scroll | code0016 |
| scroll_y | number of pixels | Vertical scroll | code0017 |
| fill | [selector, value] | Fill an input | code0018 |
| infinite_scroll | configuration object | Scroll to page end (max_count, delay, end_click) | code0019 |
| evaluate | JavaScript code | Run custom JavaScript | code0020 |
Canonical syntax for each instruction is supplied in the referenced code modules; the table summarizes intent only.
Frequently asked questions
How does the API decide between CSS and XPath?
Any selector beginning with / is treated as XPath; all other selectors are treated as CSS. This applies to every instruction that takes a selector.
Why does my GET request fail with a scenario?
The scenario is JSON, so a GET request must carry it stringified. See the accompanying client modules for the exact request shape.
What happens if one instruction fails?
By default strict mode aborts the whole scenario and returns an error. Set strict to false to continue past a failing instruction.
Can I use infinite_scroll with stealth proxies?
No — infinite_scroll is not supported when stealth proxies are used.
Is there a time limit on a scenario?
Yes. The whole scenario must complete within 40 seconds or the API times out.
{
"instructions": [
{"click": "#buttonId"}
]
}
{
"instructions": [
{"click": "#secretButton"}
]
}
{
"instructions": [
{"wait_for": ".slow_div"}
]
}
{
"instructions": [
{"wait_for_and_click": ".slow_div"}
]
}
{
"instructions": [
{"wait_for": ".slow_div"},
{"click": ".slow_div"}
]
}
{
"instructions": [
{"fill": ["input_1", "value_1"]}
]
}
{
"instructions": [
{"evaluate": "console.log('foo')"}
]
}