Skip to main content

BrowserQL Quick Start

BrowserQL is our first-class browser automation API, and includes powerful options like human-like, reconnecting and proxying. It's a full rethink of how to do browser automation with a minimalistic stealth-first approach. It combines many decades of development and research, and includes a fully-featured editor, with a live view of the session, and built-in docs. No more context switching!

In order to get started, you'll need to sign up for a Browserless account (free plans available) and get your API Key, then visit the editor at https://account.browserless.io/bql -- all of which are available via the account portal.

Requirements​

BrowserQL requires no CLI, programming language, or libraries to be installed on your computer. You simply need an account on our cloud which will allow you to download an API-Key and our editor.

Your First Query​

BrowserQL is purely a GraphQL server under the hood. This means that all of the same concepts apply to BQL that typically apply to GraphQL. Since BQL uses GraphQL as a protocol, all of the things you wish to control the browser are called Mutations. Here's an example first query with that in mind:

mutation ScrapeHN {
  goto(url: "https://news.ycombinator.com", waitUntil: firstMeaningfulPaint) {
    status
    time
  }
  firstHeadline: text(selector: ".titleline") {
    text
  }
}

Breaking this down, we're:

  • Defining we want to run a mutation and naming our script as ScrapeHN.
  • Instructing a browser to goto the Hacker News site, and wait for the firstMeaningfulPaint event to fire.
  • Asking to return both the time it took and the HTTP-code's status once the waitUntil has fired.
  • Giving our action an alias, in this case firstHeadline.
  • Extracting the text of a specified selector.

The result will return be a JSON response that matches our query, a core part of how GraphQL works:

{
  "data": {
    "goto": {
      "status": 200,
      "time": 222
    },
    "text": {
      "text": "Hacker News new | past | comments | ask | show | jobs | submitlogin..."
    }
  }
}

Exporting Your Query​

BrowserQL can be exported and run programmatically just like with any other kind of GraphQL server. You can export queries via two means:

1. Clicking the Export Query as Code button: This option will open a tab with multiple available code languages you can select and copy the code. For more details on this feature, refer to the Query as Code section of the documentation.

Keep your Token Safe

The codes copied with the Export Query as Code feature will include headers, variables and API tokens in it. Be careful not to share your private information in public places like Github, Bitbucket, etc. This opens space for malicious API calls.

2. Selecting and copying the query: Similar to other IDEs, you can select an entire query and copy it to paste wherever necessary. This is helpful if you want to store queries in a .gql file for further processing or fetching. Be sure to consult your library's documentation when using this approach.

note

This method does not copy any associated variables, headers, or API tokens, so make sure to apply those correctly before executing your query.

What's Next?​

If you already have an automation library that works over WebSockets, you can mix-and-match BrowserQL with the library of your choice. To learn how to integrate BQL, check the guides below:

There's a lot more to BQL than just this. Our Editor comes with built-in documentation, a live Viewer and Devtools to get you started. Refer to the following pages to learn more about BQL: