Skip to main content

Wait Conditions

Use these waiters to pause execution until a specific page condition is met:

For all available return fields, see the BQL schema reference.

waitForNavigation​

Waits for a navigation event to fire. Use this after triggering an action, such as a click, that causes a page load.

Parameters:

  • timeout: Float, optional. Maximum milliseconds to wait. Default is 30000.
  • waitUntil: WaitUntilGoto enum, optional. When to consider the page fully loaded.
mutation waitingForNavigation {
  goto(url: "https://example.com/") {
    status
  }

  waitForNavigation(waitUntil: load) {
    status
    time
  }
}

waitForRequest​

Waits for the browser to make a particular outgoing request.

Parameters:

  • method: Method, optional. The HTTP method of the request to wait for.
  • timeout: Float, optional. Maximum milliseconds to wait before timing out. Default is 30000.
  • url: String, optional. Glob-style pattern to match the request URL.

The example navigates to a page and waits for an outgoing POST request to any URL containing api. It returns the matched URL and how long the request took to appear.

mutation waitingForARequest {
  goto(url: "https://www.cnn.com", waitUntil: domContentLoaded) {
    status
    time
  }

  waitForRequest(
    url: "**api**"
    method: POST
    timeout: 10000
  ) {
    time
    url
  }
}

waitForResponse​

Waits for a particular network response to be received by the browser.

Parameters:

  • statuses: [Int] list, optional. HTTP status code(s) to wait for. Accepts a single code or a list.
  • url: String, optional. Glob-style pattern to match the response URL.

The example navigates to a page and waits for a successful response from any URL containing api. It returns the status code, elapsed time, and the matched URL.

mutation waitingForAResponse {
  goto(url: "https://www.cnn.com", waitUntil: domContentLoaded) {
    status
    time
  }

  waitForResponse(
    url: "**api**"
    statuses: [200]
  ) {
    status
    time
    url
  }
}

waitForSelector​

Waits for a CSS selector to appear in the DOM. If the selector already exists when this runs, it returns immediately. If the selector does not appear before the timeout, the mutation throws.

Parameters:

  • selector: String, required. A valid CSS selector.
  • timeout: Float, optional. Maximum milliseconds to wait before failing.
  • visible: Boolean, optional. When true, also waits for the element to be visible (not display: none or visibility: hidden).
mutation waitingForASelector {
  goto(url: "https://example.com/") {
    status
  }

  waitForSelector(selector: "h1", timeout: 5000) {
    selector
    time
  }
}

waitForTimeout​

Pauses execution for a fixed number of milliseconds. Use this for rate-limiting, pacing between actions, or throttling requests to avoid overloading a target. Prefer condition-based waiters when possible. They respond to actual page state rather than an arbitrary delay.

Parameters:

  • time: Float, required. Milliseconds to wait.
mutation waitingForAHardcodedTimeout {
  goto(url: "https://example.com/") {
    status
  }

  waitForTimeout(time: 1000) {
    time
  }
}

Next Steps​

Using Exports

Save and use dynamic data in later actions for better flexibility and reuse

Exporting Scripts

Export your waiting-enabled BQL queries to integrate with your development workflow

Data Extraction

Extract structured data from web pages using mapSelector, querySelectorAll, and network response interception.