For AI agents: a documentation index is available at /llms.txt
Skip to main content

Wait Conditions

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

Prerequisites

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
  }
}

FAQ & Troubleshooting​

My waitForSelector times out even though the element exists

The element may be inside an iframe or shadow DOM that BQL can't reach with a top-level selector. Check the page structure in devtools. Also verify your CSS selector is correct and the element isn't dynamically generated after a user interaction.

What's the difference between waitForSelector and waitForEvent?

waitForSelector waits for a specific DOM element matching a CSS selector. waitForEvent waits for a browser-level event like load or domcontentloaded. Use waitForSelector when you need a specific element; use waitForEvent for page-level readiness.

Next steps​

Variables and exports

save and reuse dynamic data across mutations

Exporting scripts

convert BQL queries to production code

Data extraction

extract structured data with mapSelector and querySelectorAll