Supermetrics Support Forum

Using the Query Builder for Supermetrics API

The Supermetrics API has a Query Builder tool that lets you easily construct the queries needed to get data into your other reporting systems. It looks and feels a lot like our other Supermetrics for Google Sheets product, so if you are familiar with that tool, using this will be a breeze! If you haven't used that tool before though, this guide is to help you through the basic usage of the Query Builder.

Query Setup Workflow

Here is a walk-through for setting up an example query configuration to generate the Query URL needed for connecting to other systems. This is a general workflow to set up a query and some of the steps may be different based on which data source you are using. It also will not cover all the features available, though they should be explained in the Google Sheets documentation if you want to know more.

  1. Go to, log in and then click on the Query builder section.
  2. Expand the Data Source section. You will see a list of all the different data sources we support. Select the source you wish to use by clicking on its name

    Data Source menu from the Query Builder showing an array of different data sources and their brand icons

  3. If the connector requires that you log it, it will then redirect you to a page to do so. Log in using your user credentials for that data source platform (Facebook user, Google account, Microsoft account, etc).
  4. When the login process is complete, it will come back to the Query Builder page and show you logged in to that source. For example:

    Blue box showing user logged into Facebook Insights data source

  5. Next expand the Select Accounts section (Accounts may also be called Views, Pages, Videos, etc., based on the type of connector). Select one or more accounts/pages/etc. to use for this query.
  6. Expand the Select Dates section and pick a date range you wish to use for your query. There are options for common ranges that dynamically update, as well as the option to select a custom date range.
  7. Expand the Select fields section and click in the box to get a drop-down of all available metrics. You can also start to type the name out to quick find the metric that start with those characters.

    Select metrics section with an example of typing the metric name to find it

  8. Expand the Split by section. Here can select which dimensions you want to split by. You can also pick if they are splitting by rows or by columns, depending on which box you place them in. This section also will define any sorting and maximum number of rows to fetch.

    Example of the Split by Rows option set to find the campaign name

  9. You can also apply filters to some fields under Filter, or set additional parameters in the advanced settings under the Options. These are optional though, and not required to make the query work.
  10. Now you should have a completed query, which is represented to the right as the Query URL. 
  11. Before you start to use this URL though, you should test it to make sure that it has no errors and pulls the information you were expecting!
  12. Click Run query to test the configuration. You should get JSON-formatted data in return in the Results Preview. Verify the data to ensure it is the right items and the right values.

    Example JSON output from testing the query configuration

  13. If the query passes the test and runs without errors, you can proceed to use the Query URL in your other reporting or data warehousing systems. If it does not work as expected, you can modify the query in the UI to adjust it and test again.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.