Pendo Aggs: Writing Your First Aggregation

At Pendo we are always looking to enable our customers to gain insights into their products so they can invest in building the right features for their users. One of the key methods for doing this is to dig into the data.  We have a lot of cool tools such as Dashboards, Data Explorer, and Retention to display that data in a meaningful way.

Even with these awesome tools though you might want to dig through the data yourself and supplement it with other information. The same aggregation database that powers the data visualization in Pendo is available to you through an API endpoint.  Let’s take a look at the endpoint and build our first query that will pull in a list of visitors from your Pendo subscription.

The endpoint is a simple POST request to:

https://app.pendo.io/api/v1/aggregation

Access to this endpoint does require an integration key from your subscription which you can get by going to the Integration Keys page on your subscription. Note: Only Pendo admins can view integration keys.

Include the integration key as the value of the header for X-Pendo-Integration-Key as well as the Content-Type header.

X-Pendo-Integration-Key: XXXXX-XXXXX-XXXXX-XXXXX

Content-Type: application/json

We are now  ready to write our first aggregation. Let’s first take a look at the basic structure of an aggregation body. It’s written in JSON so the structure is easy to follow:

{
    "response": {
        "mimeType": "application/json"
    },
    "request": {
        "requestId": "visitor-list",
        "pipeline": []
    }
}

There isn’t a whole lot going on here at the moment. As you can see, we have written out two different fields: a response and request. The response determines the type of output you are looking for. Anything besides JSON is beyond the scope of this article.

The request has a requestId that you can use to name the aggregation. However, the more important field is pipeline. The pipeline is the beating heart of the aggregation system. It enables your data to flow from one step to the next, allowing you to extract, transform, and even load new data along the way. 

We have a problem and that is the fact that we do not have any data yet, so let’s write our first step in the pipeline.

"pipeline": [
    {
        "source": {
            "visitors": null
        }
    }
]

You can see that we added a source step to our pipeline. All pipelines need to start with a source because we need some sort of data to flow through the system. In this instance we are requesting the visitor source which is a list of all the visitors within the given Pendo subscription.

One odd thing that might be standing out is the null value for the source. There are a lot of different sources and some of them can take custom parameters such as the page, feature, and track event sources. We will cover those sources in future articles.

So putting everything together our entire body looks like this:

{
    "response": {
        "mimeType": "application/json"
    },
    "request": {
        "requestId": "visitor-list",
        "pipeline": [
            {
                "source": {
                    "visitors": null
                }
            }
        ]
    }
}

If you hit the endpoint you will get back the following response body:

{
  "results": [
      {
          "metadata": {},
          "visitorId": 1
      },
      {
          "metadata": {},
          "visitorId": 2
      },
  ]
}

Again, super simple structure. You will receive a JSON object with the field results. Each JSON object within results represents one row from the visitor source.

Great work on writing your first aggregation! As you can see, once you know the basic structure there isn’t a whole lot to them. Nevertheless, the capabilities that are offered by the system are far reaching, and we will continue to peel back the layers of this query language in future articles. Until then, you can get more information about the language here.

James Wilson is an Engineering Manager at Pendo.  He has worked in a wide array of fields ranging from a radar & communications technician, to a software engineer building distributed systems.  In his free time, James enjoys spending time with his family, reading non-fiction, and playing video games.