Skip to main content
Version: v2

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 cloud plan and get your API Key as well as our Desktop editor -- all of which are available via the account portal.

Installation Guide

Check the BrowserQL Editor Installation Guide for instructions on how to download and configure the editor.

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.

Set up​

Once you have your API key and downloaded our editor, the first thing to do is pick a location from which to run your queries on. We have the following locations available, and it's important to choose one that's closest to where you will be running these queries from.

LocationEndpoint URL
San Francisco, USAhttps://production-sfo.browserless.io/
London, Englandhttps://production-lon.browserless.io/
Amsterdam, Netherlandshttps://production-ams.browserless.io/

You can change the endpoint in the BrowserQL Editor Settings panel:

Now, you need to add your API Token, and you'll be ready to start writing your first queries!

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: