Domain Volume

The domain volume endpoint shows the number of DNS queries made per hour to the specified domain by users of Umbrella's recursive DNS servers.

This endpoint only supports domains and the most recent hour or two will be blank as the data is still being collected and compiled. The data extends for the last 30 days.

If there is no information about the domain, a blank array is returned. There is no bulk (post request) option at this time. Only get requests are supported.

Sample query:

curl -H "Authorization: Bearer %YourToken%" "https://investigate.api.umbrella.com/domains/volume/domain.com?start=-2days&stop=now&match=component"

Parameter for Input

Field
Type
Description

domain

string

domain name only. This parameter is required.

start

string

Point in time in the past, expressed as a timestamp in milliseconds or relative time. Valid formats:
start=-2days
start=-2hours start=1509332100000
Note the negative sign. The max is 30 days.

stop

string

Point in time in the past expressed as a timestamp in milliseconds or relative time. Also valid is 'now'. Valid formats:
stop=-1days
stop=now
stop=1509642000000
Note the negative sign. The max is 30 days.

match

string

Valid options are: exact, component, or all (default).

Using "cisco.com" as an example, "exact" only gives results for cisco.com.

"Component" gives results for every component of cisco.com, but not cisco.com. Examples are www.cisco.com, mail.cisco.com, wwwin.cisco.com, something.else.cisco.com.

"All" returns the sum of component and exact, this is the default.

Returned Value for Output if Success 200

Field
Type
Description

dates

array of integers

Dates for which the data is returned in Unix epoch time.

queries

array of integers

Number of DNS queries per hour, in ascending order, to the specified domain.

In this example, the volume for the domain is for the previous day up to the current time. The last two hours are 0 because the data set has not yet been counted.

GET https://investigate.api.umbrella.com/domains/volume/{domain.com}?start=-1days&stop=now&match=component
REQUEST
curl --include \
     --header "Authorization: Bearer %YourToken%" \
https://investigate.api.umbrella.com/domains/volume/{domain.com}?start=-1days&stop=now&match=component
    
RESPONSE (HTTP 200, Content-Type: application/json)
{
	dates: [
		1510873200000,
		1510959600000
	]
	queries: [
		1378426,
		1361934,
		1308188,
		1238823,
		1245126,
		1215994,
		1256917,
		1200190,
		1245963,
		1355719,
		1332685,
		1319825,
		1362464,
		1457174,
		1695448,
		1863652,
		1928007,
		2000451,
		1903316,
		1853935,
		1814257,
		1738478,
		1601848,
		0,
		0
	]
}