Quick Start

Follow these steps to run your first BrowserQL query:

1. Get Your API Token

   • Go to the Browserless dashboard
   • Sign up or log in to your account
   • Copy your API token from the dashboard

   

2. Access IDE

   Access the BQL web editor. Learn more about using the IDE.

3. Run Your First Query

   Copy and paste this example query into the IDE to scrape the first headline from Hacker News, and click play:

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

   Click Run in the IDE to execute this query.

   Here's what each part does:

   • mutation names the script and defines it as a browser action
   • goto navigates to the URL and waits for firstMeaningfulPaint to fire
   • status and time are returned once the wait condition is met
   • firstHeadline is an alias for the text action
   • text(selector) extracts the text content of the matched element

   Response

   {
   "data": {
   "viewport": {
     "width": 1366,
     "height": 768,
     "time": 2
   },
   "goto": {
     "status": 200,
     "time": 1467
   },
   "firstHeadline": {
     "text": "Browserless is awesome! (https://github.com/browserless)"
   }
   }
   }

tip

New to GraphQL? The Language Basics page covers the key concepts.

Exporting Your Query

Once you've written a query in the IDE, you can export it to run programmatically from your own code, in whatever language you use. Here's what the Hacker News example looks like as an HTTP request:

cURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{"query":"mutation ScrapeHN {\n  goto(url: \"https://news.ycombinator.com\", waitUntil: firstMeaningfulPaint) {\n    status\n    time\n  }\n  firstHeadline: text(selector: \".titleline\") {\n    text\n  }\n}"}'

Axios

import axios from 'axios';

const response = await axios.post(
  'https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE',
  {
    query: `mutation ScrapeHN {
  goto(url: "https://news.ycombinator.com", waitUntil: firstMeaningfulPaint) {
    status
    time
  }
  firstHeadline: text(selector: ".titleline") {
    text
  }
}`,
  },
  { headers: { 'Content-Type': 'application/json' } }
);

console.log(response.data);

Fetch

const response = await fetch(
  'https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: `mutation ScrapeHN {
  goto(url: "https://news.ycombinator.com", waitUntil: firstMeaningfulPaint) {
    status
    time
  }
  firstHeadline: text(selector: ".titleline") {
    text
  }
}`,
    }),
  }
);

const data = await response.json();
console.log(data);

The IDE can generate these export snippets for you automatically. Learn how to export and use queries in your code.

Next Steps

Where to go next:

Writing BrowserQL

Master GraphQL mutations, aliases, and BQL syntax to create browser automation scripts

Using the IDE

Explore built-in documentation, query history, code export, and keyboard shortcuts in the BQL Editor

Launch Parameters

Configure browser launch options and settings to customize your automation environment

Frequently Asked Questions

What do I need to get started with BrowserQL?

You need a Browserless API token, which you can get by signing up for a free account at browserless.io. No local browser installation is required. BrowserQL runs entirely in the cloud against managed browsers.

Can I test BQL queries before writing code?

Yes. The BrowserQL IDE at account.browserless.io lets you write, run, and debug queries interactively with a live browser preview. You can then export working queries as API calls in multiple languages.

Does BrowserQL support Playwright or Puppeteer?

BrowserQL is its own GraphQL-based API, but you can hand off a BQL session to Puppeteer or Playwright mid-query using the reconnect mutation. This lets you combine BQL's stealth features with your existing automation code.

What languages can I use with BrowserQL?

BrowserQL queries are sent as HTTP POST requests, so any language that can make HTTP calls works: Python, Node.js, Go, Java, PHP, and more. The IDE also exports ready-to-use code snippets in popular languages.