Documentation Index
Fetch the complete documentation index at: https://docs.optexity.com/llms.txt
Use this file to discover all available pages before exploring further.
Web automation requires careful timing. Pages load at different speeds, elements appear dynamically, and networks can be slow.
Timing Controls
| Level | Properties |
|---|
| Automation | max_retries |
| Action Node | before_sleep_time, end_sleep_time, expect_new_tab, max_new_tab_wait_time |
| Interaction Action | max_tries, max_timeout_seconds_per_try |
Sleep Times
before_sleep_time
Wait before executing the action. Use when page needs to load or settle.
{
"type": "action_node",
"interaction_action": { ... },
"before_sleep_time": 3.0
}
end_sleep_time
Wait after action completes. Use when subsequent actions depend on this action’s effects.
{
"type": "action_node",
"interaction_action": { ... },
"end_sleep_time": 2.0
}
Default Values
| Action Type | before_sleep_time | end_sleep_time |
|---|
| Interaction | 0.0 | 1.0 |
| Extraction | 3.0 | 0.0 |
| Assertion | 0.0 | 0.0 |
| 2FA | 0.0 | 0.0 |
Sleep times must be between 0 and 10 seconds.
Automation-Level Retries
max_retries on the automation reruns the entire automation when an unexpected error occurs (e.g. browser crash, network failure).
| Property | Type | Default | Description |
|---|
max_retries | int | 0 | Total run attempts. 1 = no retry, 1 = one retry, etc. |
{
"url": "https://example.com",
"max_retries": 3,
"nodes": [ ... ]
}
AssertionError failures (e.g. failed assertions) are never retried regardless of max_retries. Retries only apply to unexpected runtime errors.
Element-Level Retry Configuration
Control how Optexity retries finding elements.
| Property | Type | Default | Description |
|---|
max_tries | int | 10 | Maximum retry attempts |
max_timeout_seconds_per_try | float | 1.0 | Timeout per attempt |
{
"interaction_action": {
"max_tries": 15,
"max_timeout_seconds_per_try": 2.0,
"click_element": { ... }
}
}
How Retries Work
- Attempt to find element using
command or xpath
- If not found within timeout, retry
- After all tries exhausted, use AI with
prompt_instructions
- If AI can’t find it, action fails
Increase max_tries rather than timeout per try. This finds elements faster when they appear while still handling slow pages.
Handling New Tabs
expect_new_tab
Set when action opens a new browser tab:
{
"type": "action_node",
"interaction_action": {
"click_element": {
"command": "get_by_role(\"link\", name=\"Open Report\")"
}
},
"expect_new_tab": true
}
expect_new_tab=True:
max_new_tab_wait_time automatically set to 10.0- Automation waits for new tab
- Focus switches to new tab
Common Patterns
Slow-Loading Pages
{
"type": "action_node",
"interaction_action": {
"click_element": {
"command": "get_by_role(\"button\", name=\"Search\")"
}
},
"end_sleep_time": 5.0
}
Dynamic AJAX Content
{
"type": "action_node",
"interaction_action": {
"max_tries": 15,
"max_timeout_seconds_per_try": 1.0,
"click_element": {
"command": "get_by_text(\"Results loaded\")"
}
},
"before_sleep_time": 2.0
}
Optional Elements
{
"type": "action_node",
"interaction_action": {
"max_tries": 3,
"click_element": {
"command": "get_by_role(\"button\", name=\"Dismiss\")",
"skip_prompt": true,
"assert_locator_presence": true
}
}
}
Troubleshooting
| Symptom | Likely Cause | Solution |
|---|
| ”Element not found” | Page not loaded | Increase before_sleep_time |
| Clicking wrong element | Page still loading | Increase before_sleep_time |
| Missing extracted data | Content not rendered | Increase wait before extraction |
| Next action fails | Previous effect not ready | Increase end_sleep_time |
| Random failures | Race conditions | Increase retries and timeouts |
Best Practices
| Practice | Recommendation |
|---|
| Start conservative | Use longer waits initially, optimize later |
| Use defaults | Let action-type defaults handle most cases |
| Wait before extraction | Ensure page stability |
| Wait after navigation | Give pages time to load |
| Increase retries | Prefer more tries over longer timeouts |
