Kentik APIs

Kentik APIs provide programmatic access to configure your Kentik environment, query stored network data, and automate alerting and mitigation workflows.

Notes:
See V6 APIs for the full list of articles about Kentik’s latest generation APIs.
For assistance using a Kentik API, reach out to Customer Care.

API Versions

Kentik supports two sets of 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).
V5 (Deprecated): A set of REST APIs for administrative functions, querying, and alerting (see About the V5 APIs).

Notes:
Kentik’s V5 APIs and V5 API tester are deprecated/discontinued as of January 2025.
Kentik does not recommend using its APIs for full data extraction. Instead, Kentik Firehose is recommended for that purpose (see Using Kentik Firehose).

Authentication & Base URLs

All Kentik API requests require authentication using standard HTTP headers.

Authentication Headers

Include the following headers with your API requests:

X-CH-Auth-Email: Your registered Kentik email address.
X-CH-Auth-API-Token: Your unique API token.

Getting Your API Token

Log in to the Kentik Portal.
Navigate to User Profile (top-right menu).
Go to the Authentication tab.
Copy your API Token.

Kentik API Base URLs

Your base URL depends on the API version and your region's cluster:

V6 (gRPC) Base URLs

US Cluster: https://grpc.api.kentik.com
EU Cluster: https://grpc.api.kentik.eu

V5 (REST) Base URLs

US Cluster: https://api.kentik.com/api/v5
EU Cluster: https://api.kentik.eu/api/v5

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.

Per-customer limit	Non-query APIs	Query API	Description
Maximum concurrent requests	1	4	A request is deemed concurrent if received before the server responds to the previous request.
Soft limit (per minute)	20	30	Maximum requests per rolling minute without triggering server response delay.
Server response delay (seconds)	1.5	1	Delay in server response for requests exceeding the soft limit per minute count.
Hard limit (per minute)	60	100	Maximum requests per rolling minute without triggering HTTP 429 error. Note: Occurs only if concurrent requests exceed maximum.
Hourly limit	3750	1500	Maximum requests per rolling hour without triggering HTTP 429 error.

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: <user@domain.suffix>' \
-H 'X-CH-Auth-API-Token: <user API token>'

API V5 cURL Structure

Example HTTP request structure for V5 User API

Element	Example	Description
Command declaration	`curl`	Declares the following string as a cURL command.
Method	`-X PUT`	HTTP method of the call, e.g., GET, PUT, POST, DELETE
Authorization: API token	`-H 'X-CH-Auth-API-Token: user_api_token'`	Header: passes the user’s Kentik API Token
Authorization: User email	`-H 'X-CH-Auth-Email: user@domain.suffix'`	Header: passes the user’s Kentik email address
Content-Type declaration	`Content-Type: application/json`	Header: specifies the content type of the data.
Data	`-d '{ "user": { "email_service": true, } }'`	JSON: For creating or updating: - Create (POST): Include all required fields. - Update (PUT): Include only fields to be updated; others remain unchanged. For example, updating “email_service” will leave other fields as is.
URL (US)	`https://api.kentik.com/api/v5/user/user_id`	Endpoint path on the Kentik V5 API query server.
Formatter	`\| python -m json.tool`	Optional: appends to cURL command for "pretty" JSON response layout.

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: <user@domain.suffix>' \
 -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": "new_user@domain.suffix",
     "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.

About the V6 APIs

Kentik’s gRPC-based V6 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).

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:

About the V5 APIs

Note: The V5 APIs and API tester are deprecated/discontinued as of January 2025.

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.