Quickstart

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.

FAQ & Troubleshooting

What do I need to get started with BrowserQL?

A Browserless API token from a free account at browserless.io. No local browser installation is required. BQL runs entirely in the cloud.

My query returns a connection error

Verify your API token is valid and your plan is active in the dashboard. Check that you're using the correct endpoint URL format: wss://production-sfo.browserless.io/chromium/bql?token=YOUR_TOKEN.

Can I hand off a BQL session to Puppeteer or Playwright?

Yes. Use the reconnect mutation to get a WebSocket endpoint you can pass to Puppeteer or Playwright. See Puppeteer & Playwright handoff.

Next steps

Writing BQL

learn mutations, aliases, and BQL syntax

BQL IDE

built-in docs, query history, and code export

Launch parameters

configure browser launch options