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.

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 wil be running these queries from.

Location	Endpoint URL
San Francisco, USA	https://production-sfo.browserless.io/
London, England	https://production-lon.browserless.io/
Amsterdam, Netherlands	https://production-ams.browserless.io/

Copy one of the links above and paste them into the editor, as well as your API token from the account page like so:

Now that you have everything set up, you can 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 BrowserQL that typically apply to GraphQL. Since BrowserQL 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 Copy Button Icon

Clicking this button will copy a cURL formatted export. This will include headers, variables and tokens in it, so be careful with sharing this information.

2. Selecting and copying the query

You can, also, select the entire query and copy-and-paste it wherever needed. This is useful if you want to store queries in a .gql file where further processing or fetching can occur. Refer to your libraries documentation with this approach. This method will not copy any relevant variables, headers or API-tokens, so be sure to apply those properly before executing your query.

There's a lot more to BrowserQL than just this! Our Editor comes with built-in documentation, a live Viewer and Devtools to get you started.