Step-by-step guide to your first API call

1. Identify your target project

As explained in Getting started, you will need to find your username and project slug which are used to identify the project.
You will also need your API token, which you should be able to find following the instructions on the same page.

In the rest of this example, we will consider these values:

• Username: botify-team
• Project slug: botify-blog
• API token: 123

2. Identify the data you want to query

For our first BQL query, we will retrieve a handful of metrics for the main URLs of the latest crawl on the project. First, we need to retrieve the slug of the last analysis. Here you can find instructions to find this slug. For the purpose of the example, let's consider the last crawl occurred on February 5, 2021:

• Analysis slug: 20210205

The BQL query would look like this:

{
  "collections": ["crawl.20210205"],
  "query": {
    "dimensions": [
      "url",
      "crawl.20210205.depth",
      "crawl.20210205.http_code",
      "crawl.20210205.byte_size"
    ],
    "metrics": [],
    "sort": [1]
  }
}

We define the different dimensions we want to query and sort on the URL depth in an ascending order. Meaning that we will fetch the URLs in more or less the order in which Botify crawled them.

3. Prepare your API call

We need to prepare an API call that is a POST to the URL https://api.botify.com/v1/projects/botify-team/botify-blog/query.

🚧

Use your configuration

Don't forget to replace the cURL with your:

• username, in the URL
• project slug, in the URL
• analysis slug, in the BQL collections
• API token, in the HTTP headers

Additionally, set the HTTP headers and you should end up with something like:

curl --location --request POST 'https://api.botify.com/v1/projects/botify-team/botify-blog/query' \
--header 'Authorization: Token 123' \
--header 'Content-Type: application/json' \
--data-raw '{
  "collections": ["crawl.20210205"],
  "query": {
    "dimensions": [
      "url",
      "crawl.20210205.depth",
      "crawl.20210205.http_code",
      "crawl.20210205.byte_size"
    ],
    "metrics": [],
    "sort": [1]
  }
}'

4. Run the API call

Using your favorite tool (command line cURL, Postman, Insomnia, etc.) send this request to our servers. If everything went fine, you will get back a response with a 200 OK status and a response body what will look like this:

{
  "results": [
    {
      "metrics": [],
      "dimensions": [
        "https://www.botify.com/blog",
        0,
        200,
        109628
      ]
    },
    {
      "metrics": [],
      "dimensions": [
        "https://www.botify.com/blog/beginners-guide-botify",
        1,
        200,
        78229
      ]
    },
    ...
  ],
  "previous": null,
  "next": "https://api.botify.com/v1/projects/botify-team/botify-blog/query?page=2",
  "page": 1,
  "size": 500
}

Containing a result list, where each item is a row of result data, separating the queried metrics and dimensions, each field being at the specified position.

Congrats, you just executed your first BQL query 🎉