Timing & Retries - Optexity Documentation

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
}

When 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

​Timing Controls

​Sleep Times

​before_sleep_time

​end_sleep_time

​Default Values

​Automation-Level Retries

​Element-Level Retry Configuration

​How Retries Work

​Handling New Tabs

​expect_new_tab

​Common Patterns

​Slow-Loading Pages

​Dynamic AJAX Content

​Optional Elements

​Troubleshooting

​Best Practices

Timing Controls

Sleep Times

before_sleep_time

end_sleep_time

Default Values

Automation-Level Retries

Element-Level Retry Configuration

How Retries Work

Handling New Tabs

expect_new_tab

Common Patterns

Slow-Loading Pages

Dynamic AJAX Content

Optional Elements

Troubleshooting

Best Practices