Kentik Synthetics Monitoring API (v6)
Create and manage synthetic tests (HTTP, ping, traceroute, DNS, BGP, transaction) and query their results and agents.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Synthetics Monitoring API",
"description": "# Overview\nThe Synthetics Monitoring API provides programmatic access to Kentik's [synthetic monitoring system](https://kb.kentik.com/v4/Ma00.htm). The API consists of two endpoints:\n| Endpoint | Purpose |\n|-----------|---------|\n| SyntheticsAdminService | CRUD operations for synthetic tests, agents, and offline agent alerts |\n| SyntheticsDataService | Retrieval of synthetic test results and network traces |\n\nBoth REST endpoint and gRPC RPCs are provided.\nNote: API version v202309 is the same as v202202 except that the timestamps returned for synthetic test results are closer to when the test was actually run.\n### Known Limitations\nThe API currently does not support the following [Synthetic Test Types](https://kb.kentik.com/v4/Ma00.htm#Ma00-Synthetic_Test_Types):\n* BGP Monitor tests, which are supported in a [separate API](https://github.com/kentik/api-schema-public/blob/master/proto/kentik/bgp_monitoring/v202205beta1/bgp_monitoring.proto)\n* Transaction tests.\n\n### Additional Public Resources\nKentik community [Python](https://github.com/kentik/community_sdk_python) and [Go](https://github.com/kentik/community_sdk_golang) SDKs provide language-specific support for using this and other Kentik APIs. These SDKs can be also used as example code for development. \n A [Terraform provider](https://registry.terraform.io/providers/kentik/kentik-synthetics) is available for configuring tests and agents for Kentik synthetic monitoring.\n# Anatomy of a Synthetic Test\nEach `Test` consists of one or more tasks. Tasks are executed by monitoring `Agents` that send synthetic traffic (probes) over the network. The API currently supports following tasks:\n| Task name | Purpose |\n|------------|---------|\n| ping | Test basic address, and optionally TCP port reachability |\n| traceroute (a.k.a. trace)| Discover unidirectional network path |\n| http | Perform a simple HTTP/HTTPS request |\n| page-load | Use headless Chromium to execute an HTTP/HTTPS request |\n| dns | Execute a DNS query|\n| throughput | Execute a throughput task to determine bandwidth |\n\nThe set of tasks executed on behalf of a given test depends on the `type` of that test. The following test types are currently supported by the API:\n| API type | Portal (UI) equivalent | Tasks |\n|---------------|--------------|-------|\n| ip | IP Address | ping, traceroute |\n| hostname | Hostname | ping, traceroute |\n| network_grid | Network Grid | ping, traceroute |\n| agent | Agent-to-Agent | ping, traceroute, throughput |\n| network_mesh | Network Mesh | ping, traceroute |\n| flow | Autonomous Tests (5 variants) | ping, traceroute |\n| url | HTTP(S) or API | http, ping (optional), traceroute (optional) |\n| page_load | Page Load | page-load, ping (optional), traceroute (optional) |\n| dns | DNS Server Monitor | dns |\n| dns_grid | DNS Server Grid | dns |\n\n***Note:*** `ping` and `traceroute` tasks are always run together (never one without the other).\n\n# Test Attributes and Settings\nThe attributes of the test object enable configuration of test settings, access to test metadata, and access to runtime state information.\n### State and Metadata Attributes\n The following table lists the metadata and state attributes:\n| Attribute | Access | Purpose |\n|-----------|--------|---------|\n| id | RO | System-generated unique identifier of the test |\n| name | RW | User specified name for the test (need not be unique) |\n| type | RO (after creation) | Type of the test (set on creation; read-only thereafter) |\n| status | RW | Life-cycle status of the test |\n| cdate | RO | Creation timestamp |\n| edate | RO | Last-modification timestamp |\n| created_by | RO | Identity of the user that created the test |\n| last_updated_by | RO | Identity of the latest user to modify the test |\n| labels | RW | List of names of labels applied to the test |\n\nTest configuration is performed via the test's `settings` attribute. Some settings are common to all tests while others are specific to tests of a given type.\n### Common Test Settings\nThe following settings are used for tests of all types:\n| Attribute | Purpose | Required |\n|-----------|---------|----------|\n| agentIds | IDs of agents to execute tasks for the test | YES |\n| period | Test execution interval in seconds | NO (default 60s) |\n| family | IP address family. Used only for tests whose type is url or dns. Selects which type of DNS resource is queried for resolving hostname to target address | NO (default IP_FAMILY_DUAL) |\n| notificationChannels | List of notification channels for the test | NO (default empty list) |\n| healthSettings | A HealthSettings object that configures health settings for this test, which includes metric thresholds that define health status (warning and critical) and trigger associated alarms. | YES |\n| ping | A TestPingSettings object that configures the ping task of the test | NO (default depends on test type) |\n| trace | A TestTraceSettings object that configures the trace task of the test | NO (default depends on test type) |\n| throughput | A TestThroughputSettings object that configures the throughput task of the test | NO (default depends on test type) |\n| tasks | List of names of the tasks that will be executed for this test | YES |\n\n### Type-specific Settings\nEach test type has its own configuration object that represents the settings for that type. These type-specific objects are referenced by the attributes in `Test.settings`:\n| Test type | Settings attribute | Configuration object |\n|--------------|-------------------------|---------------------------|\n| ip | ip | IpTest |\n| hostname | hostname | HostnameTest |\n| network_grid | networkGrid | IpTest |\n| agent | agent | AgentTest |\n| network_mesh | networkMesh | NetworkMeshTest |\n| flow | flow | FlowTest |\n| url | url | UrlTest |\n| page_load | pageLoad | PageLoadTest |\n| dns | dns | DnsTest |\n| dns_grid | dnsGrid | DnsTest |\n\n# Test Results\nResults of synthetic tests are returned as a sequence of `TestResults` objects. Each such object represents measurements and health evaluation for a single test at specific point in time. Measurements and health evaluation are grouped by agent and by task.\nGranularity of timestamps in test results depends on the frequency (period) of the test and on the requested time range. The minimum granularity is 1 minute (even when period < 1 minute). The longer the time range, the lower the granularity.\n# Network Traces\nSynthetic tests that include the `traceroute` task collect the unidirectional network path from the agent to the target for each agent/target pair. The trace data are returned in the `GetTraceForTestResponse` object. The `paths` attribute of this object contains the collected network path for each agent/target pair and the round-trip time (RTT) to each hop.\nHops in actual network traces are identified by a `nodeId`. The mapping of node IDs to address, name, location, and other attributes of the hop is provided in a map that is stored in the `nodes` attribute of the `GetTraceForTestResponse` object.\n# Agents\nThe Kentik synthetic monitoring system recognizes 2 types of agents:\n* **Global** (public): Managed by Kentik and available to every Kentik user. All information about global agents in this API is read-only.\n* **Private**: Deployed by each customer and available only to that customer.\nTo be visible in this API, a private agent must first associate itself with a customer account by contacting the Kentik system (via private API). Once the agent is associated it can be authorized via the API by changing its `status` to `AGENT_STATUS_OK`. For more information about private agent deployment, see [**Synthetic Agent Deployments**](https://kb.kentik.com/v4/Ma01.htm#Ma01-Synthetic_Agent_Deployments).\n",
"version": "v202309",
"contact": {
"name": "Kentik API Engineering",
"url": "https://github.com/kentik/api-schema-public"
}
},
"tags": [
{
"name": "SyntheticsDataService"
},
{
"name": "SyntheticsAdminService"
}
],
"paths": {
"/synthetics/v202309/agentAlerts": {
"get": {
"summary": "List agent alert configurations",
"description": "Lists all agent alert configurations, optionally filtered by a list of agent ids.",
"operationId": "ListAgentAlerts",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309ListAgentAlertsResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "agentIds",
"description": "Optional list of agent ids to retrieve alert configurations for",
"in": "query",
"required": false,
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"tags": [
"SyntheticsAdminService"
]
},
"post": {
"summary": "Create an agent alert configuration",
"description": "Creates a new agent alert configuration.",
"operationId": "CreateAgentAlert",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309CreateAgentAlertResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309CreateAgentAlertRequest"
}
}
},
"required": true
},
"tags": [
"SyntheticsAdminService"
]
}
},
"/synthetics/v202309/agentAlerts/{id}": {
"get": {
"summary": "Get an agent alert configuration",
"description": "Retrieves an existing agent alert configuration.",
"operationId": "GetAgentAlert",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309GetAgentAlertResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"SyntheticsAdminService"
]
},
"delete": {
"summary": "Delete an agent alert configuration",
"description": "Deletes an existing agent alert configuration.",
"operationId": "DeleteAgentAlert",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309DeleteAgentAlertResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"SyntheticsAdminService"
]
},
"put": {
"summary": "Update an agent alert configuration",
"description": "Updates an existing agent alert configuration with the time threshold and notification channels provided.",
"operationId": "UpdateAgentAlert",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309UpdateAgentAlertResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyntheticsAdminServiceUpdateAgentAlertBody"
}
}
},
"required": true
},
"tags": [
"SyntheticsAdminService"
]
}
},
"/synthetics/v202309/agents": {
"get": {
"summary": "List available agents",
"description": "Returns list of all synthetic agents available in the account.",
"operationId": "ListAgents",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309ListAgentsResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"tags": [
"SyntheticsAdminService"
]
}
},
"/synthetics/v202309/agents/{agent.id}": {
"put": {
"summary": "Update configuration of an agent",
"description": "Update configuration of a synthetic agent.",
"operationId": "UpdateAgent",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309UpdateAgentResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "agent.id",
"description": "Unique identifier of the agent",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyntheticsAdminServiceUpdateAgentBody"
}
}
},
"required": true
},
"tags": [
"SyntheticsAdminService"
]
},
"get": {
"summary": "Get information about an agent",
"description": "Returns information about the requested synthetic agent.",
"operationId": "GetAgent",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309GetAgentResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "agent.id",
"description": "ID of the requested agent",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"SyntheticsAdminService"
]
},
"delete": {
"summary": "Delete an agent",
"description": "Deletes the requested agent. The deleted agent is removed from configuration of all tests.",
"operationId": "DeleteAgent",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309DeleteAgentResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "agent.id",
"description": "ID of the agent to be deleted",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"SyntheticsAdminService"
]
}
},
"/synthetics/v202309/results": {
"post": {
"summary": "Get results for tests",
"description": "Returns probe results for a set of tests for specified period of time.",
"operationId": "GetResultsForTests",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309GetResultsForTestsResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309GetResultsForTestsRequest"
}
}
},
"required": true
},
"tags": [
"SyntheticsDataService"
]
}
},
"/synthetics/v202309/results/csv": {
"post": {
"summary": "Get test results in CSV format",
"description": "Returns probe results for tests in CSV format.",
"operationId": "GetResultsForTestsCsv",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309GetResultsForTestsCsvResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309GetResultsForTestsCsvRequest"
}
}
},
"required": true
},
"tags": [
"SyntheticsDataService"
]
}
},
"/synthetics/v202309/tests": {
"get": {
"summary": "List all tests",
"description": "Returns a list of all configured active and paused synthetic tests.",
"operationId": "ListTests",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309ListTestsResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"tags": [
"SyntheticsAdminService"
]
},
"post": {
"summary": "Create a test",
"description": "Create synthetic test based on configuration provided in the request.",
"operationId": "CreateTest",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309CreateTestResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309CreateTestRequest"
}
}
},
"required": true
},
"tags": [
"SyntheticsAdminService"
]
}
},
"/synthetics/v202309/tests/{id}": {
"get": {
"summary": "Get information about a test",
"description": "Returns configuration and status for the requested synthetic test.",
"operationId": "GetTest",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309GetTestResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rpcStatus"
}
}
}
}
},
"parameters": [
{
"name": "id",
"description": "ID of requested test",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"tags": [
"SyntheticsAdminService"
]
},
"delete": {
"summary": "Delete a synthetic test.",
"description": "Deletes the synthetics test. All accumulated results for the test cease to be accessible.",
"operationId": "DeleteTest",
"responses": {
"200": {
"description": "A successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/v202309DeleteTestResponse"
}
}
}
},
"default": {
"description": "An unexpected error response.",
"content": {
"application/json": {
# --- truncated at 32 KB (121 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kentik/refs/heads/main/openapi/kentik-synthetics-openapi.json