Kentik APIs

This article provides an introduction to Kentik APIs, which enable programmatic control of Kentik.

Note: For assistance using a Kentik API, see Customer Care.

About Kentik APIs

Kentik APIs enable programmatic control over Kentik setup (administrative functions), querying of network data stored in Kentik, and alerting/mitigations based on user-defined conditions.

API Versions

Kentik supports two sets of APIs:

• V5: A set of REST APIs for administrative functions, querying, and alerting (see About the V5 APIs).

• V6: A set of gRPC APIs that do not directly extend V5 but do have some overlap in functionality (e.g., Users and Sites). V6 APIs are more frequently updated and are useful for high throughput operations due to their increased efficiency compared to REST (see About the V6 APIs).

Notes:

• The V5 API tester was discontinued in January 2025.

• We do not recommend using Kentik APIs for full data extraction. Instead, Kentik Firehose is recommended for that use case (see Using Kentik Firehose).

About the V6 APIs

Kentik’s V6 (gRPC) APIs aim to:

• Offer a more performant alternative to the V5 (REST) APIs

• Offer functionality not covered by the V5 APIs

• Serve as a foundation for expanding capabilities, including areas already covered by the V5 APIs (e.g., Users and Sites).

For a list of available v6 APIs, see V6 APIs.

Note: KB articles cover each API listed in the v6 API Tester’s landing page. APIs marked in the KB as Alpha or Beta versions are not supported or recommended for production use.

V6 API Tester

The V6 API Tester allows you to test V6 API methods using your Kentik account data.

Note: All V6 API reference files are also available in Kentik’s api-schema-public repo on GitHub.

V6 API Client Stubs

Kentik provides API client stubs in the following languages in its api-schema-public repo on GitHub:

• C

• C++

• Go

About the V5 APIs

The Kentik V5 (REST) APIs enable programmatic management of Kentik and are categorized as follows:

• V5 Admin APIs: Manage your company's Kentik settings, including users, devices, sites, and tags. These APIs support methods to read/write backend information, returning data in JSON key/value pairs. For more details, refer to the V5 Admin APIs documentation and the list of V5 Admin Methods.

• V5 Query API: Enables querying of your network data stored in Kentik, returning data or visualizations (see the V5 Query API documentation and the list of V5 Query Methods).

• V5 Alerting APIs: Provides notifications of anomalous conditions (DDoS attacks, blocked routes, etc.) on Kentik-monitored network infrastructure, and supports mitigation management. Returns data on current or historical deviations. See the V5 Alerting API documentation and the list of V5 Alerting Methods.

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

API Rate Limiting

API calls are rate-limited to ensure fair resource distribution among Kentik customers. The limits allow for reasonable activity bursts and prevent abrupt failures. Key points to consider when developing with Kentik APIs:

• Separate Counting: Requests from the V5 Query API and V5 Admin APIs are counted separately, each with distinct limits.

• Rolling Time Windows: Rate limits are calculated over a rolling minute and hour, with each request counted for 60 seconds and 3600 seconds, respectively, from receipt.

• Server Response Delay: Applied to requests exceeding the per-minute soft limit (see table below).

• HTTP 429 Error: Triggered when requests exceed the per-minute hard limit or the hourly limit.

• Concurrent Request Limit: Adhering to this ensures the per-minute count does not exceed the hard limit, and the hourly limit is not exceeded for non-query APIs.

The following table shows the limits for query and non-query API calls.

API Access Via cURL

To access Kentik APIs using cURL, you can generate HTTP requests to the Kentik API server.

API V6 cURL Example

curl --location --request GET 'https://grpc.api.kentik.com/device/v202504beta2/device/' \
-H 'X-CH-Auth-Email: <[email protected]>' \
-H 'X-CH-Auth-API-Token: <user API token>'

API V5 cURL Structure

Here’s the structure of an HTTP request to Kentik via cURL for the V5 User API:

Note: For organizations registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the API v5 URL.

API V5 cURL Command

The structure elements can be used to form a cURL command, for example to create a new user (the backslashes are for line breaks for readability):

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 '{
"user": {
     "user_name": "New_Username",
     "user_full_name": "New Username",
     "user_email": "[email protected]",
     "user_password": "newUser_password",
     "role": "Member",
     "email_service": true,
     "email_product": true
   }
 }' \
 https://api.kentik.com/api/v5/user | python -m json.tool

Notes:

• Find a user's API token on the User Information pane of the User Profile page in Kentik (accessible via the username link in the main navbar).

• For organizations registered on Kentik's EU cluster, use api.kentik.eu in place of api.kentik.com in the API v5 URL.

Using a single data (-d) parameter in cURL to pass a JSON object simplifies passing field values to Kentik:

• Create Call: The -d parameter includes the entire JSON object for the API (e.g., the user object for the User API).

• Update Call: The -d parameter includes only the fields to be updated in the JSON structure for the API.

Notes:

• In some contexts, a -d parameter with single quotes may cause a call to fail. Use the Unicode equivalent \u0027 to escape them in cURL.

• Examples of JSON objects returned by V5 APIs are shown in V5 Admin APIs and V5 Query API.

• For details on dimensions and corresponding JSON name/value pairs in V5 APIs, see Dimensions Reference.