Skip to main content

Calling the BrowserQL API

BrowserQL allows you to design queries in the IDE and then export them as ready-to-use API calls in multiple programming languages. This makes it easy to test your logic in the IDE and then integrate it directly into your applications.

Exporting Your Query​

Once your query is working in the IDE, follow these steps to ensure reliable results outside of the BQL IDE:

  1. Click Export as Code.
  2. Select your preferred language.
  3. Copy the generated snippet, which includes the endpoint, token, headers, and payload.

Example BQL Query​

The following query navigates to Hacker News, clicks the Jobs tab, and extracts the HTML of the page:

mutation ExtractJobsHTML {
  goto(url: "https://news.ycombinator.com", waitUntil: firstMeaningfulPaint) {
    status
  }

  click(selector: "span.pagetop > a[href='jobs']") {
    x
    y
  }

  html {
    html
  }
}

Exported Query as API Call​

Here’s what the exported query looks like in different languages:

const url = "https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE";  
const options = {  
  method: "POST",  
  headers: {  
    'Content-Type': 'application/json'  
  },  
  body: '{"query":"mutation ExtractJobsHTML {\\\\n  goto(url: \\\\"https://news.ycombinator.com\\\\", waitUntil: firstMeaningfulPaint) { status }\\\\n  click(selector: \\\\"span.pagetop > a[href=\\'jobs\\']\\\\") { x y }\\\\n  html { html }\\\\n}","variables":null,"operationName":"ExtractJobsHTML"}'  
};  

try {  
  const response = await fetch(url, options);  
  const data = await response.json();  
  console.log(data);  
} catch (error) {  
  console.error(error);  
}

Parsing the API Response​

After calling the API, the response contains raw HTML. You can parse it using libraries like:

const { JSDOM } = require("jsdom");  

async function ExtractJobsHTML() {  
  const url = "https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE";  
  const options = {  
    method: "POST",  
    headers: {  
      'Content-Type': 'application/json'  
    },  
    body: '{"query":"mutation ExtractJobsHTML {\\\\n  goto(url: \\\\"https://news.ycombinator.com\\\\", waitUntil: firstMeaningfulPaint) { status }\\\\n  click(selector: \\\\"span.pagetop > a[href=\\'jobs\\']\\\\") { x y }\\\\n  html { html }\\\\n}","variables":null,"operationName":"ExtractJobsHTML"}'  
  };  

  try {  
    const response = await fetch(url, options);  
    const json = await response.json();  
    const html = json.data.html.html;  

    const dom = new JSDOM(html);  
    const rows = dom.window.document.querySelectorAll("tr.athing");  

    const results = [...rows].map((row) => {  
      const anchor = row.querySelector("a");  
      return anchor ? { title: anchor.textContent.trim(), link: anchor.href } : null;  
    }).filter(Boolean);  

    console.log(results);  
  } catch (error) {  
    console.error(error);  
  }  
}  

ExtractJobsHTML();

Troubleshooting: Different Results Between IDE and API Calls​

If your API calls return different data, miss elements, or behave differently than the IDE, it is very important to use the Export as Code feature. It automatically includes all exact settings from your IDE session, ensuring identical behavior between testing and production.

Next Steps​

Explore these key features to enhance your browser automation:

Session Management

Connect your BQL sessions to puppeteer or playwright.

Writing Your First Query

Start creating BrowserQL automation scripts with step-by-step guidance

Bot Detection

Master advanced techniques to bypass anti-bot measures and access protected sites