This is the specification for the Control D Analytics API.

Endpoints

The API is served from various endpoints, depending on account type and region.

Region	Account Type	Endpoint
America	User	us-east1-usr01.analytics.controld.com
America	Org	us-east1-org01.analytics.controld.com
Asia	User	asia-southeast1-usr01.analytics.controld.com
Asia	Org	asia-southeast1-org01.analytics.controld.com
Europe	User	europe-west4-usr01.analytics.controld.com
Europe	Org	europe-west4-org01.analytics.controld.com

Authentication

Requests are authenticated with "pseudo-bearer" authentication (via HTTP headers):

Authorization: Bearer <token>

You can generate your API tokens here. See here for more information.

Authentication is not required for endpoints tagged as Public.

Activity Log

The actual DNS queries of a user can be obtained via the Activity Log API if they are at most 33 days old.

Admin Actions

Audit logs (admin actions) can be accessed through the Admin Actions API.

Clients

The Clients API allows reading data about clients and endpoints, such as when they were last active, or client metadata.

It also allows adding custom aliases for clients.

Statistics API

Processed and aggregated information about DNS queries, can be retrieved through the Statistics API.

This API uses pre-aggregated data with varying granularity.

Columns

The Statistics and Activity Log APIs support filtering based on the following dimensions.

Important: Filtering and grouping by columns marked "no" in the year column is not possible for data older than 33 days.

name	meaning	type	year	example
endpointId	the id of the endpoint to which the query was made	string	yes	abc123
clientId	the id of the client which made the request	string	yes	abc123
profileId	the id of the active profile	string	yes	abc123
action	action taken by ROBERT	enum, see below	yes	0
trigger	the category of the trigger for action	enum, see below	yes	filter
triggerValue	the name of the trigger for action	string	yes	ads
spoofTarget	in the event of a redirect, the target. Can be an IP, another domain, or an IATA code	string	yes	YYZ
question	the domain name of the request	string	yes	subdomain.windscribe.com
protocol	the DNS protocol used for the request	enum, see below	no	doh
statusCode	the DNS status code	number	no	0
rrType	the response record type	string	no	AAAA
srcCountry	country code of the country of the source IP	string	yes	CA
dstCountry	country code of the country of the destination IP	string	yes	DE
srcIsp	source ISP name	string	yes	Windscribe
dstIsp	destination ISP name	string	yes	AT&T
srcAsn	ASN of the source ISP	string	no	15169
dstAsn	ASN of the destination ISP	string	no	15169

Enums

Action

-1: failed

0: blocked

1: bypassed

2: redirected by IP

3: redirected by Location

Trigger

default: default rule

grule: global (Control D) rule

filter: a block made by a filter

service: a service

custom: a custom rule

rebind: action taken due to optional rebind protection

Protocol

legacy: legacy DNS

doh: DNS-over-HTTPS

dot: DNS-over-TLS

doh3: DNS-over-HTTPS3

doq: DNS-over-QUIC

Impersonating a Sub-Organization

An Organization admin can impersonate a Sub-Organization by including a X-Force-Org-Id header. Single-use tokens obtained this way are scoped to the specified Sub-Organization.

Dynamically Determining Endpoint

If you're building an application, you may wish to determine the analytics endpoint at runtime.
This allows you to change storage regions without necessarily breaking clients.

stats_endpoint is served over the User Data Endpoint
a. For users, this will be under body > stats_endpoint
b. For Organizations, this will be under body > org > stats_endpoint

The Analytics Endpoint will be concat(stats_endpoint, ".analytics.controld.com")

Maintenance mode

When Analytics is in maintenance mode, all calls will return a 503 Service Unavailable with the regular Error Response containing a code 50303.

Docs

Endpoints#

Authentication#

Activity Log#

Admin Actions#

Clients#

Statistics API#

Columns#

Enums#

Action#

Trigger#

Protocol#

Impersonating a Sub-Organization#

Dynamically Determining Endpoint#

Maintenance mode#