Query API

The Kentik V5 Query API allows programmatic querying of Kentik-stored network data (flow records, BGP, selected SNMP OIDs) for your organization's devices, and is covered in the following topics:

• About V5 Query API
• V5 Query Methods
• Query API JSON
• Query Chart Method
• Query URL Method
• Query Data Method
• Query SQL Method

Notes:
- For an overview of all Kentik APIs, see APIs Overview.
- For documentation of the V5 Admin APIs, see V5 Admin APIs.
- For information on using the Kentik V5 Query API with cURL, see API Access Via cURL.
- For documentation of the V5 Alerting APIs, see V5 Alerting APIs.
- For help using any API version, contact support@kentik.com.

The Kentik V5 Query API provides methods to retrieve information from the main tables of the Kentik Data Engine (see KDE Tables) as JSON data or image files for charts similar to those in Data Explorer.

Kentik V5 Query APIs can be accessed via:

• Command line: Use cURL in environments like Terminal. See API Access Via cURL.
• Programmatically: Send a request body to a V5 API endpoint using any application language that supports HTTP.

Note: The V5 API tester was discontinued in January 2025.

The following table lists available methods in the V5 Query API. Click the topic link for more details on each method:

Notes:
- Endpoint URLs are region-specific, https://api.kentik.com/api/v5 for US and https://api.kentik.eu/api/v5 for EU.
- The Query SQL method requires detailed PostgreSQL knowledge and understanding of Kentik's subqueries (see Querying KDE). For JSON data, most users will find the Query Data call more accurate and easier to use.

The JSON for requests and responses in V5 Query API methods is detailed in the following topics:

• Query API Request JSON
• Query JSON as cURL
• Query API Response JSON

The Query Chart, Query Data, and Query URL methods of the V5 Query API use JSON in the request body, while the Query SQL Method uses SQL. The JSON array specifies what data Kentik should return and how. This JSON structure is largely consistent across all three methods.

You can create the JSON array for a Query Chart, Query Data, or Query URL call by:

• Building the JSON from scratch using the information in the tables below.
• Retrieving the JSON from the Kentik portal:
  1. In Data Explorer, define your query with the fields in the sidebar panes and click Apply Changes.
  2. In the results, open the options menu at the upper right of the graph (see Explorer Title Pane), select Show API Call, then choose Data or Chart to open the Query API example dialog.
  3. Click JSON to view the query JSON.
  4. Click Copy to copy the JSON to your clipboard.
  5. Paste the JSON in a Query Data call in cURL or another compatible setting for generating HTTP calls.

The example below demonstrates the objects utilized in the Query Chart, Query Data, and Query URL methods, with placeholder values indicated:

{
  "queries": [
    {
      "query": {
        "viz_type": "matrix",
        "show_overlay": false,
        "overlay_day": -7,
        "sync_axes": false,
        "metric": "bytes",
        "matrixBy": [
          "dst_geo_city"
        ],
        "cidr": 32,
        "cidr6": 128,
        "pps_threshold": 500,
        "topx": 8,
        "depth": 100,
        "fastData": "Auto",
        "outsort": "max_bits_per_sec",
        "lookback_seconds": 3600,
        "time_format": "UTC",
        "hostname_lookup": "false",
        "starting_time": null,
        "ending_time": null,
        "device_name": "device_name_1, device_name_2",
        "all_selected": true,
        "filters_obj": {
          "connector": "All",
          "filterGroups": [
            {
              "connector": "All",
              "filters": [
                {
                  "filterField": "protocol",
                  "operator": "=",
                  "filterValue": "17",
                }
              ],
              "not": false,
            }
          ],
        },
        "saved_filters": [
          {
            "filter_id": 363
            "is_not": true
          }
        ],
        "descriptor": "Total",
        "aggregates": [
          {
            "name": "avg_bits_per_sec",
            "column": "f_sum_both_bytes",
            "fn": "average",
            "sample_rate": 1
          },
          {
            "name": "p95th_bits_per_sec",
            "column": "f_sum_both_bytes",
            "fn": "percentile",
            "rank": 95,
            "sample_rate": 1
          },
          {
            "name": "max_bits_per_sec",
            "column": "f_sum_both_bytes",
            "fn": "max",
            "raw": true,
            "sample_rate": 1
          }
        ],
        "query_title": "Top Source City vs Top Dest City by Max Bits/s",
        "dimension": [
          "src_geo_city"
        ]
      },
      "bucket": "Matrix",
      "bucketIndex": 0,
      "isOverlay": false
    }
  ],
  "imageType": "image_file_format"
}

The following sections describes the objects in detail.

The highest-level object of the V5 Query JSON includes these two members:

The queries array usually includes a single query object and the associated objects shown in the following table. For multi-series data or charts (see Compound Queries), add multiple elements, each representing a desired chart axis.

The query object includes the objects and arrays that specify a query for execution on Kentik:

The filters_obj object contains one of more filter groups for a Query Chart or Query Data query. For more information on query filters, see About Filters.

The filterGroups array defines a group of one or more filters for a Query Chart or Query Data query. For more information on filters in a query see About Filters. Each member of the array contains the following objects:

The filters array defines individual filters in a filter group for a Query Chart or Query Data query (see About Filters). Each array member represents a filter and includes the following objects:

The saved_filters array contains IDs of saved filters (custom or preset) to apply to the query (see Saved Filters).

The aggregates array specifies an aggregate for a table column from a Query Chart query when the display type (viz_type; see Query Object) is Table. An aggregate is the result of basic statistical analyses on a dataset.

If no aggregates are specified in the Query Object, Kentik automatically generates aggregates based on the metric field. These Kentik-generated aggregates can be used in the outsort field to sort results for depth and topx. The table below lists valid Kentik-generated aggregates for each metric:

Here’s a JSON example for a Query Chart call in the data (-d) parameter of a cURL HTTP request (with placeholders highlighted):

curl -X POST \
-H 'X-CH-Auth-Email: user@domain.suffix' \
-H 'X-CH-Auth-API-Token: user_api_token' \
-H 'Content-Type: application/json' \
-d '{ "queries": [ { "query": { "viz_type": "stackedArea", "show_overlay": true, "overlay_day": -7, "sync_axes": false, "metric": "bytes", "matrixBy": [], "cidr": 32, "cidr6": 128, "pps_threshold": 500, "topx": 8, "depth": 25, "fastData": "Auto", "outsort": "max_bits_per_sec", "lookback_seconds": 300, "time_format": "UTC", "starting_time": null, "ending_time": null, "device_name": "device_names", "all_selected": false, "filters_obj": {}, "saved_filters": [], "descriptor": "Total", "query_title": "Top Source Country by Max Bits/s", "time_type": "relative", "device_id": "2951", "num_selected": 0, "sql_string": "", "queryChanged": false, "granularity": "total", "ppsThreshold": "500", "last_run": null, "aggregates": [ { "name": "avg_bits_per_sec", "column": "f_sum_both_bytes", "fn": "average", "sample_rate": 1 }, { "name": "p95th_bits_per_sec", "column": "f_sum_both_bytes", "fn": "percentile", "rank": 95, "sample_rate": 1 }, { "name": "max_bits_per_sec", "column": "f_sum_both_bytes", "fn": "max", "raw": true, "sample_rate": 1 } ], "dimension": [ "Geography_src" ] }, "bucket": "Left +Y Axis", "bucketIndex": 0, "isOverlay": false } ], "imageType": "pdf"}' \
https://api.kentik.com/api/v5/query/topXchart | python -m json.tool

Notes:
- Replace placeholders (in italics) with actual values: your email address (user@domain.suffix), API token (user_api_token), and device names ( device_names, comma-delimited list) for the query.
- The JSON for a Query Data call is similar but omits some fields. See Query API Request JSON for details.
- For more information on using Kentik APIs with cURL, see API Access Via cURL.

The Query Data and Query SQL methods both return JSON data arrays in the HTTP response body, while the Query Chart method returns an image file. The array data comes from the main tables of the Kentik Data Engine (see KDE Tables), which store flow records and related network data (BGP, GeoIP, SNMP). The arrays from the two methods differ, even with the same query settings, because Query Data results are processed for improved accuracy, such as in averaging queries.

Note: Example response JSON is provided in the topic for each method.

The Query Chart POST method queries Kentik's KDE and returns image data for a graph like those in Data Explorer (see Data Explorer Chart). The image data is returned as a JSON object with a dataURI member containing a base64 encoded string.

Supported image types are SVG, PDF, PNG, or JPG. SVG is the default and recommended type because it returns quickly, scales without data loss, and can be easily integrated by injecting it directly into the DOM.

HTTP Request

The following table shows the path and HTTP request for the Query Chart method (with placeholders in italics):

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL.

The request body includes a JSON array with elements containing the information needed by Kentik to perform the query. For details on creating this array and its components, see Query API Request JSON.

HTTP Response

A successful response from the Query Chart method includes the following elements:

• Response headers
• HTTP response code
• JSON response body with a dataURI member

The following example shows the structure of the returned JSON (placeholder highlighted):

{
  "dataUri": "base64_encoded_string"
}

The Query URL POST method provides a URL to open Data Explorer in the Kentik portal, with the sidebar according to the request JSON query parameters and the query results visualized in the display area.

HTTP Request

The following table shows the path and HTTP request for the Query URL method (with placeholders in italics):

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

The request body contains a JSON array with elements detailing the query settings for Data Explorer. For details on creating this array and its components, see Query API Request JSON.

Note: This request body is identical to that of the Query Chart Method, except it excludes the imageType parameter.

HTTP Response

A successful response from the Query URL method includes the following elements:

• Response headers
• HTTP response code
• Response body with a short URL in quotes

The following example shows an example of a URL returned from the Query URL method:

"https://portal.kentik.com/portal/#Charts/shortUrl/d3f24034b386ebf9e8ad6de8f0f715a1"

The Query Data POST method executes a query on Kentik's KDE data (see KDE Tables) and returns results in a JSON results array.

Note: This method is generally more user-friendly and accurate than the Query SQL Method, which requires in-depth PostgreSQL and Kentik subquery knowledge (see Querying KDE).

HTTP Request

The following table shows the path and HTTP request for the Query Data method (with placeholders in italics):

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

The request body contains a JSON array with elements specifying the necessary information for Kentik to execute the query. For details on creating this array and its components, see Query API Request JSON.

HTTP Response

A successful response from the Query Data method includes the following elements:

• Response headers
• HTTP response code
• JSON response body with a results array, which varies based on the query provided.

This example displays a results array from a query on top source country by max bits per second, showing two results (actual results range from 25 to 350, based on the depth field in the request JSON):

• The first result (US) includes five-minute time-series data (lookback_seconds set to 300) and represents top results based on the topx field in the request JSON (see Query API Request JSON).
• The second result (AU) illustrates non-topx results.

{
  "results": [
    {
      "bucket": "Left +Y Axis",
      "data": [
        {
          "Geography_src": "US",
          "avg_bits_per_sec": 130548781.51111111,
          "key": "US",
          "max_bits_per_sec": 153616657.06666666,
          "p95th_bits_per_sec": 150816290.13333333,
          "timeSeries": {
            "both_bits_per_sec": {
              "flow": [
                [
                  1482186900000,
                  128568524.8,
                  60
                ],
                [
                  1482186960000,
                  133069482.66666667,
                  60
                ],
                [
                  1482187020000,
                  115999675.73333333,
                  60
                ],
                [
                  1482187080000,
                  153616657.06666666,
                  60
                ],
                [
                  1482187140000,
                  104022425.6,
                  60
                ],
                [
                  1482187258438,
                  148015923.2,
                  60
                ]
              ]
            }
          }
        },
        {
          "Geography_src": "AU",
          "avg_bits_per_sec": 732114.4888888889,
          "key": "AU",
          "max_bits_per_sec": 1145924.2666666666,
          "p95th_bits_per_sec": 1003315.2
        }
      ]
    }
  ]
}

The Query SQL POST method executes a SQL query on Kentik's KDE data, returning results in a JSON rows array, with each element corresponding to a column in the KDE Tables.

Note: This method requires PostgreSQL and Kentik subquery knowledge (see Querying KDE). Most users get better JSON results with less effort using the Query Data Method.

HTTP Request

The following table shows the path and HTTP request for the Query SQL method (with placeholders in italics):

Note: If your organization is registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the URL above.

The request body contains one parameter: a SQL query. You can create this query by:

• Writing it from scratch. For guidance, see Querying KDE.
• Creating the query in the Kentik portal:
  1. In Data Explorer, define a query by setting fields in the sidebar panes. Click Apply Changes.
  2. Once the query results are displayed, click the Options menu at the top right of the graph (see Explorer Title Pane) and select View SQL. Choose the view type (e.g., "Total") and SQL type (e.g., "Chart SQL"). The Query Editor will open, showing the SQL query in the Enter SQL Query field.
  3. Copy the SQL for use in cURL or another setting that supports programmatic HTTP calls.

Note: Queries from the Query Editor may include single quotes. You might need to escape these quotes based on the programmatic context. In cURL, replace single quotes with the Unicode equivalent \u0027, as shown in the following example WHERE clause.

-- original
WHERE i_sub_limit = 200
  AND i_start_time >= '2016-12-01 21:54'
-- escaped
WHERE i_sub_limit = 200
  AND i_start_time >= \u00272016-12-01 21:54\u0027

The following code sample shows a Query SQL call as a cURL HTTP request (with placeholders highlighted):

curl -X POST \
-H 'X-CH-Auth-Email: user@domain.suffix' \
-H 'X-CH-Auth-API-Token: user_api_token' \
-H 'Content-Type: application/json' \
-d '{
  "query": "SELECT * FROM (SELECT i_start_time, dst_geo, CASE dst_geo WHEN \u0027\u0027 THEN \u0027---\u0027 ELSE dst_geo END AS Geography_dst, sum(both_bytes) AS f_sum_both_bytes, max(i_duration) as i_duration, row_number() OVER (PARTITION BY i_start_time ORDER BY sum(both_bytes) DESC) FROM all_devices WHERE ( ( ( (src_geo = \u0027RU\u0027) ) ) AND ( ( (i_dst_as_name ILIKE \u0027%kentik%\u0027) ) )) AND i_sub_limit = 200 AND i_start_time >= \u00272016-12-01 21:28\u0027 GROUP BY i_start_time, dst_geo ORDER BY f_sum_both_bytes DESC) a WHERE row_number <= 200 ORDER BY i_start_time, f_sum_both_bytes DESC"
  }' \
https://api.kentik.com/api/v5/query/sql | python -m json.tool

Note: For more information on using Kentik APIs with cURL, see API Access Via cURL.

HTTP Response

A successful response from the Query SQL method includes the following elements:

• Response headers
• HTTP response code
• JSON response body with a rows array, which varies based on the query provided.

The following example shows the JSON rows array returned from a query similar to the cURL example above:

{
  "rows": [
    {
      "dst_geo": "US",
      "f_sum_both_bytes": 9856,
      "geography_dst": "US",
      "i_duration": 300,
      "i_start_time": "2016-12-01T21:25:00Z",
      "row_number": 1
    },
    {
      "dst_geo": "US",
      "f_sum_both_bytes": 16000,
      "geography_dst": "US",
      "i_duration": 300,
      "i_start_time": "2016-12-01T21:30:00Z",
      "row_number": 1
    },
    {
      "dst_geo": "US",
      "f_sum_both_bytes": 26400,
      "geography_dst": "US",
      "i_duration": 300,
      "i_start_time": "2016-12-01T21:35:00Z",
      "row_number": 1
    }
  ]
}