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 powerful 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