Timing & Retries

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

Quickstart

Building Automations

Action Types

Inference

Advanced

FAQs

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

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