> For the complete documentation index, see [llms.txt](https://gaffa.dev/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gaffa.dev/docs/features/browser-requests/actions/wait.md). # Wait **Type**: `wait` The wait action tells the browser to pause for a specified time or until a particular element appears on the page.
Tips for using wait action * Wait for a [`selector`](/docs/features/browser-requests/selectors.md) rather than a fixed `time` wherever you can. It moves on as soon as the element appears. * Never set both `time` and [`selector`](/docs/features/browser-requests/selectors.md). If you do, time wins and the timeout is ignored completely. * Set `continue_on_fail: true` when the element you're waiting for might not appear. * You don't need a `wait` before [`click`](/docs/features/browser-requests/actions/click.md), [`capture_element`](/docs/features/browser-requests/actions/capture-element.md) or [`parse_table`](/docs/features/browser-requests/actions/parse-table.md), since they wait for their own selectors. * A fixed `time` is still the right choice for animations settling or for slowing a sequence down on purpose.
### Parameters {% hint style="info" %} **Parameter Requirements:** You must provide either `time` or `selector`. When using `selector`, `timeout` is required. {% endhint %}
NameTypeDescription
timeintegerThe time in milliseconds the browser should wait.
selectorstringThe selector for the element to wait for. You must provide a timeout when using selector.
timeoutintegerThe maximum time in milliseconds to wait for selector to appear. Default: 5,000 (5s). Required when using selector.
See [universal parameters](/docs/features/browser-requests/actions.md#universal-parameters). ### Usage #### Wait for a particular amount of time The following code will wait 1 second, then continue to the next action. **Wait 1 second:** ```json "actions": [ { "type": "wait", "time": 1000 } ] ``` #### Wait for a particular element to appear The following code will wait for a table to appear on the page for up to 5 seconds. If the table has not appeared after 5 seconds, the next action will be executed. **Wait for table to appear:** ```json "actions": [ { "type": "wait", "selector": "table", "timeout": 5000, "continue_on_fail": true } ] ``` {% hint style="warning" %} Using both `time` and `selector` + `timeout` together does not result in an error. But note that when both are provided, `time` takes priority and the browser will proceed after the `time` duration expires, regardless of whether `selector` has appeared, and the `timeout` is ignored. {% endhint %} ### FAQs #### When do I use the wait action? Use it when you need to pause between actions — waiting for content to load after a click, for an animation to finish, or for a slow page to finish rendering before you capture it. #### How do I wait for an element to appear? Add a wait action with a [`selector`](/docs/features/browser-requests/selectors.md) for the element and a `timeout` in milliseconds. Gaffa continues as soon as the element appears or when the timeout expires. #### How do I pause for a fixed amount of time? Add a `wait` action with `time` set in milliseconds. Use this for animations or deliberate pacing, rather than for content that might take a variable amount of time to load. #### What happens if I set both time and selector? `time` takes over and `timeout` is ignored. The browser moves on once the time is up, whether or not the element appeared. Use one or the other, never both. #### Should I wait for a selector or a fixed time? Wait for a [`selector`](/docs/features/browser-requests/selectors.md) where you can. It moves on as soon as the element exists, instead of always using the full time, which makes sequences quicker and more reliable. #### What if the element never appears? The action fails once the timeout is up, and by default the request stops. Set `continue_on_fail: true` if the element is optional and the rest should still run. #### Do I need a wait before every capture? No. Add one only when the content loads after the previous action finishes. [`click`](/docs/features/browser-requests/actions/click.md), [`capture_element`](/docs/features/browser-requests/actions/capture-element.md) and [`parse_table`](/docs/features/browser-requests/actions/parse-table.md) already wait for their own [`selectors`](/docs/features/browser-requests/selectors.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gaffa.dev/docs/features/browser-requests/actions/wait.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.