BQL Language Basics

This guide covers BQL script structure, core actions, aliases, and response fields with working examples.

Prerequisites

• A Browserless API token from your account dashboard
• Familiarity with GraphQL syntax

BQL script structure

A BQL script is one mutation block containing one or more actions. Actions run in order, top to bottom. Each action has a name, optional arguments that configure it, and response fields that define what data it returns.

mutation ScriptName {
  goto(url: "https://example.com", waitUntil: domContentLoaded) {
    status
  }
  text(selector: "h1") {
    text
  }
  screenshot(type: png) {
    base64
  }
}

• goto, text, and screenshot are the action names.
• url, waitUntil, selector, and type are arguments. They configure how the action runs.
• status, text, and base64 are response fields. They define what data gets returned.

Find all available actions, arguments, and response fields in the BQL API Reference or the Built-in Documentation in the IDE.

Aliases

Because a BQL script is a single mutation block, every action name must be unique. If you use the same action twice, BQL cannot distinguish them in the response.

This fails:

mutation LoginForm {
  goto(url: "https://practicetestautomation.com/practice-test-login/") {
    status
  }
  type(selector: "#username", text: "student") {
    time
  }
  type(selector: "#password", text: "Password123") {  # ❌ duplicate action name
    time
  }
  click(selector: "#submit") {
    time
  }
}

Fix it by prefixing each duplicate action with an alias:

mutation LoginForm {
  goto(url: "https://practicetestautomation.com/practice-test-login/") {
    status
  }
  typeUsername: type(selector: "#username", text: "student") {
    time
  }
  typePassword: type(selector: "#password", text: "Password123") {
    time
  }
  click(selector: "#submit") {
    time
  }
}

Aliases also become the keys in the JSON response, making the result easier to parse.

For GraphQL readers

In GraphQL terms, each action is a mutation field on the root mutation type. Aliases are required because GraphQL does not allow duplicate field names within the same selection set.

Core Actions

Action	What it does	Returns
goto	Navigate to a URL	status, time
click	Click an element	x, y, time
type	Type text into an element	time, selector
select	Select an option from a dropdown	value, selector
text	Extract visible text from an element	text
html	Extract raw HTML from an element	html
screenshot	Capture a screenshot	base64
solve	Solve a CAPTCHA	found, solved, time

For the full list of available actions and their arguments, see the BQL API Reference.

FAQ & Troubleshooting

What query language does BrowserQL use?

BrowserQL uses GraphQL. Queries are structured as mutations that navigate, click, type, wait, and extract data from web pages. Each mutation runs sequentially against a live browser session.

How do I navigate to a page in BQL?

Use the goto mutation with a url parameter and a waitUntil condition such as load, domContentLoaded, or networkIdle. This ensures the page is ready before running subsequent mutations.

My mutation returns null for response fields

You need to request the specific response fields you want. BQL only returns fields you explicitly include in your query. Add fields like status, text, or html inside the mutation's selection set.

Next steps

Conditional logic

create "do A or do B" workflows that adapt to page conditions

Wait conditions

wait for elements, navigation, and network responses

Exporting scripts

convert BQL queries to code in multiple languages

BQL API reference

full list of available mutations and arguments