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.

Notes:

• For an overview of all Kentik APIs, see Kentik APIs.

• For information on using the Kentik V5 Query API with cURL, see API Access Via cURL.

• For help using any API version, contact [email protected].

• As of May 1st, 2025, the Query SQL Method has been deprecated and is no longer supported.

About V5 Query API

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.

V5 Query Methods

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

Note: Endpoint URLs are region-specific, https://api.kentik.com/api/v5 for US and https://api.kentik.eu/api/v5 for EU.

Query API JSON

The JSON for requests and responses in V5 Query API methods is detailed here.

Query API Request JSON

The Query Chart, Query Data, and Query URL methods of the V5 Query API use JSON in the request body. 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:

{
  "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 describe the objects in detail.

Query JSON Object

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

Queries Array

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.

Query Object

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

Filters_obj Object

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.

FilterGroups Array

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:

Filters Array

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:

Saved_filters Array

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

Aggregates Array

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.

Kentik Sort-by Options

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:

Query JSON as cURL

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

curl -X POST \
-H 'X-CH-Auth-Email: [email protected]' \
-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 ([email protected]), 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.

Query API Response JSON

The Query Data method returns 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.

Query Chart 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:

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"
}

Query URL Method

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:

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

Query Data Method

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

HTTP Request

The following table shows the path and HTTP request for the Query Data method:

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
         }
      ]
    }
  ]
}

Query SQL Method

As of May 1st, 2025, the Query SQL Method (API endpoint) has been deprecated and is no longer supported.