Query your data

How to interactively fetch your SEO data

Introduction to data querying

In this section, we will cover how to query SEO data from Botify.
To know when you should use exports instead of queries, see the related guide.


Any SEO data at Botify is retrieved through our own query language: BQL, short for Botify Query Language, a custom JSON DSL.
Querying data is no exception and uses BQL to express what data you are trying to fetch. BQL and its possibilities are documented exhaustively in this section.

Querying through this API allows you to fetch up to 2000 rows of data in one call in just a few seconds. The API can be used to test out your BQL query before making an export out of it, or to fetch data quickly without overhead.

The most important aspects are:

  • get access credentials: your username, project slug and API token. Getting started will explain you how to get your information.
  • do POST query to the URL https://api.botify.com/v1/projects/<username>/<project_slug>/query
  • write your BQL query

And you should be good to go.
To make your first BQL API call, see the How-to: BQL API call.


POST https://api.botify.com/v1/projects/<username>/<project_slug>/query

The BQL endpoint takes two headers:

  • Authentication: Token <YOUR_TOKEN>
  • Content-Type: application/json

The endpoint also takes three optional query params:

  • size: the number of results by page. By default 500
  • page: the number page. By default 1
  • count: the total number of results. If specified, the API response will contain a count key with the total number of results. By default not specified.

What’s Next

Learn how to do your first BQL API call