The OpenDNS Network Devices API Developer Hub

Welcome to the OpenDNS Network Devices API developer hub. You'll find comprehensive guides and documentation to help you start working with OpenDNS Network Devices API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Destinations: Most recent requests

Reporting: Destinations - Most recent requests

The Destination "Most recent requests" endpoint provides the most recent DNS requests for a particular destination from all identities in your organization.

All requests require your organization ID and a destination as the parameters.

You organization id can be located easily when you log into the Umbrella dashboard. It’s in the URL, for example: https://dashboard.umbrella.com/o/#####/

You must specify a destination. A destination can be a domain or an IP address and should be specified without any protocol or delimiters. For instance, "www.cisco.com" is valid, but "https://cisco.com" is not valid, nor is "cisco.com/index.html".

Optional parameters are the ability to limit the number of results, and an offset pagination parameter to obtain the next set of results. The maximum number of viewable results is 500 per query.

Request Parameters

The "Most recent requests" endpoint accepts the following parameters:

Field
Type
Description

limit

integer

changes the number of requests for the specified destination returned, default is 100.

offset

integer

changes which index the list of returned orgs starts at. Default is 0, and orgs are listed in reverse alphabetical order. Offset essentially allows for pagination. If the first set of results shows 50, then offset=50 shows the next fifty and offset=100 shows the next fifty after that.

Example query:

This query will return the first ten results for the destination specified in the query string:

curl -i -X GET --url https://reports.api.umbrella.com/v1/organizations/{organizationID}/destinations/{destination}/activity?limit=10 --header 'Authorization: Basic %base64string%'

This query specifies an offset of 10 to show the next ten results (from 11 to 20):

curl -i -X GET --url https://reports.api.umbrella.com/v1/organizations/{organizationID}/destinations/{destination}/activity?limit=10&offset=10 --header 'Authorization: Basic %base64string%'

Example response:

GET https://reports.api.umbrella.com/v1/organizations/{orgID}/destinations/{destination}/activity?limit=10
REQUEST
curl --include \
     --header "Authorization: Basic %base64string%" \
https://reports.api.umbrella.com/v1/organizations/{organizationID}/destinations/{destination}/activity?limit=10
    
RESPONSE (HTTP 200, Content-Type: application/json)
{
            "originId": 81185341,
            "internalIp": "67.215.89.252",
            "externalIp": "67.215.89.252",
            "originLabel": "YVR test",
            "categories": [
                "Software/Technology",
                "Business Services"
            ],
            "originType": "Networks",
            "actionTaken": "ALLOWED",
            "datetime": "2017-12-05T21:45:14.897Z",
            "destination": "casper-dp.esl.cisco.com"
        },
        {
            "originId": 15703560,
            "internalIp": "67.215.89.170",
            "externalIp": "67.215.89.170",
            "originLabel": "VPN Range",
            "categories": [
                "Software/Technology",
                "Business Services"
            ],
            "originType": "Networks",
            "actionTaken": "ALLOWED",
            "datetime": "2017-12-05T21:45:14.529Z",
            "destination": "wwwin.cisco.com"
        }
    ]
}
    

Returned Value For Output If Success 200

Field
Type
Description

originid

integer

the numerical identifier for the identity making the request

internalIp

string

the internal IP address of the identity making the request (if available)

externalIp

string

the external IP address of the identity making the request.

originLabel

string

the human readable name for the identity, matches the one seen in the dashboard

categories

array of strings

which categories, if any, the destination for which this request was made falls into

originType

string

identity type (such as network, roaming computer, AD User, etc)

actionTaken

boolean

either Blocked or Allowed

datetime

string

the time at which the event occurred, in UTC.

destination

string

the destination to which this request was made