Request Samples

Request Path Parameters

The Umbrella Reporting v2 API endpoints require various path parameters.

Parameter	Example	Description
organizationId	1234567	An organization ID.
type	dns	Specifies the type of traffic, for example: dns, proxy, firewall, ip, or intrusion. Note: The type of traffic values vary by endpoint.
identityId	42	An identity ID.
threatTypeId	Ransomware	A string that represents a threat type.
threatNameId	WannaCry	A string that represents a threat name.
mspOrganizationId	1234456	A Managed Service Provider (MSP) organization ID.

Request Query Parameters

You can customize and filter the Umbrella Reporting v2 API requests with query parameters. Each Reporting v2 API endpoint defines its required query parameters.

Note: Umbrella uses the timestamp of the events to sort the /activity, /activity/dns, /activity/proxy, /activity/firewall, and /activity/amp-retrospective collections. If multiple events occur in the same second, the order of the collection is not guaranteed to be consistent.

Parameter	Example	Description
from	1639146300000	A timestamp or relative time string (for example: '-1days'). Filter for data that appears after this time. For more information, see Timestamp and Relative Time Strings. Required
to	1640010300000	A timestamp or relative time string (for example: 'now'). Filter for data that appears before this time. For more information, see Timestamp and Relative Time Strings. Required
offset	0	A number that represents an index into the collection.
limit	100	The maximum number of records to return from the collection. Required
domains	cisco.com	A domain name or comma-delimited list of domain name.
urls	https://google.com,facebook.com/help	A URL or comma-delimited list of URL.
categories	148,151,66	A category ID or comma-delimited list of category ID.
policycategories	67,69	A category ID or comma-delimited list of category ID. Filter request by the categories that trigger a policy.
ip	10.10.10.10	An IP address.
order	desc	A string that describes how to order the results (for example: 'asc' or 'desc').
ports	7351,80	A port number or comma-delimited list of port number.
identityids	1,2,3	An identity ID or comma-delimited list of identity ID.
identitytypes	network,roaming	An identity type or comma-delimited list of identity type.
applicationid	1	An application ID.
verdict	allowed,blocked,proxied	A verdict string or comma-delimited list of verdict string.
ruleid	1	A firewall policy rule ID.
filename	myfilename_*	A string that identifies a filename. Filter request by the filename. Supports globbing or use of the wildcard character (). The asterisk () matches zero or more occurrences of any character.
securityoverridden	true	A boolean value. If set to 'true', filter for requests that override security.
bundleid	1	A proxy bundle ID.
threats		A threat name or comma-delimited list of threat name.
threattypes		A threat type or comma-delimited list of threat type.
ampdisposition	clean,malicious,unknown	An AMP disposition string or a comma-delimited list of AMP disposition string.
isolatedstate	isolated	A string that describes the remote browser isolation (RBI) isolation type (for example: 'isolated' or 'not-isolated'.
isolatedFileAction	downloaded-safe-pdf	A string that describes the remote browser isolation (RBI) file action type (for example: 'viewed', 'downloaded-original-file', or 'downloaded-safe-pdf').
datalosspreventionstate	blocked	A string that describes the status of a destination (for example: 'blocked'). Filter data for requests that were blocked to protect data.
sha256		A SHA-256 hash.
antivirusthreats	Trojan.Linux.Generic.144075	A threat name or comma-delimited list of threat name.
tenantcontrols	true	A boolean value. If set to 'true', filter data for requests that are part of a tenant control policy.
search	somelabel	A string that represents a search parameter. Filter data for requests in which the search string appears in the endpoint data.
application	Games	An application name.
filternoisydomains	true	A boolean value. If set to 'true', filter request on domains that generate high volume of insignificant traffic (noise).
httperrors	certificateerror	A string that represents a TLS or certificate error (for example: 'certificateerror' or 'tlserror'). Filter data for requests that resulted in a TLS or certificate error.
exists	'categories,destinationlistids'	Specify a comma-separated list of attributes to filter the Activity Report. Valid values are: categories, policycategories, applicationid, nbarapplicationid, nbarapplicationtypeids, privateapplicationid, applicationgroupids, sha256, filename, threats, threattypes, antivirusthreats, destinationlistids, httperrors.
connectionevent	connected	Specify the type of connection event. Valid values: connected, disconnected, failed.
osversions	linux-64-Ubuntu 20.04.5 LTS (Focal Fossa)	Specify a comma-separated list of OS versions.
anyconnectversions	4.10.05095	Specify a comma-separated list of AnyConnect Roaming Security module versions.

Request Data by Time Range

Many Umbrella Reporting v2 endpoints require that you set a time range to filter the data. You can define a time range with the to and from request query parameters.

Additionally, some Umbrella Reporting v2 endpoints enable a timerange header.

Time Range Header

The timerange header describes how to group data within a 24 hour period. This header accepts the following strings:

minute
hour (default value)
day

Umbrella Reporting v2 resources that group data by hourly intervals do not enable the timerange header. These resources include:

Bandwidth by Hour
Requests by Hour
Requests by Hour and Category

Time Range Example

The Requests by Timerange resource accepts the timerange header as well as the to and from query parameters. For example, you can set the timerange header to minute, the to query parameter to now, and the from query parameter to -1days.

Timestamp and Relative Time Strings

The to and from query parameters accept a timestamp string defined in milliseconds from the Unix epoch. For example: 1619007756000 (converted from 2021-04-21:08:22:36 GMT-04:00).

You can also set other time range string values for these parameters.

Examples of to query parameter values:

now
-1days

Examples of from query parameter values:

-2days
-10minutes
-2weeks

Note: The time range set by the to and from query parameters cannot exceed 30 days.

HTTP Redirects and Request Authorization Header

Umbrella stores the reporting data in geolocated data warehouses.

EU: api.eu.reports.umbrella.com
US: api.us.reports.umbrella.com

Note: If an HTTP client request does not originate from the same continent as the location of the Umbrella data warehouse, the Umbrella server responds with 302 Found.

To automatically redirect HTTP requests and preserve the HTTP Authorization header, you can set additional flags or enable a redirect setting.

curl: You must pass the -L or --location, and --location-trusted flags to redirect the curl HTTP request and retain the Authorization header.

curl -i --location --location-trusted \
GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/activity?from=-7days&to=now&limit=10&offset=0' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Postman: Within the Postman client environment, choose a GET method in an API. Navigate to Settings. Enable Follow Authorization header to preserve the Authorization header for redirect requests.

List Activities

List DNS, proxy, firewall, and IP activities within a time range.

GET /organizations/{organizationId}/activity

Set the required query parameters:

to
from
limit

MSP Child Organizations

Note: For MSP child organizations, you must include the MSP organization ID using the mspId query parameter.

For example:

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/<child-org-id>/activity?mspId=<msp-id>&from=-1&to=now&limit=1' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Request

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/activity?from=-30days&to=now&limit=2&offset=0' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

Click to view the sample response


{
    "data": [
        {
            "applicationprotocols": [],
            "destinationip": "157.240.11.17",
            "allapplications": [],
            "date": "2021-06-25",
            "protocol": {
                "id": 6,
                "label": "TCP"
            },
            "sourceip": "192.168.20.41",
            "rule": {
                "id": 3577394,
                "label": "Default Rule"
            },
            "time": "19:11:45",
            "type": "firewall",
            "sourceport": 44368,
            "verdict": "allowed",
            "destinationport": 80,
            "packetsize": 52,
            "timestamp": 1624648305000,
            "identities": [
                {
                    "id": 528417414,
                    "type": {
                        "id": 40,
                        "type": "tunnel_device",
                        "label": "Network Tunnels"
                    },
                    "label": "UmbrellaHQ Tun (Do not modify)",
                    "deleted": false
                }
            ],
            "direction": "OUTBOUND"
        },
        {
            "applicationprotocols": [],
            "destinationip": "146.112.198.89",
            "allapplications": [],
            "date": "2021-06-25",
            "protocol": {
                "id": 6,
                "label": "TCP"
            },
            "sourceip": "192.168.20.41",
            "rule": {
                "id": 3577394,
                "label": "Default Rule"
            },
            "time": "19:11:45",
            "type": "firewall",
            "sourceport": 53456,
            "verdict": "allowed",
            "destinationport": 443,
            "packetsize": 52,
            "timestamp": 1624648305000,
            "identities": [
                {
                    "id": 528417414,
                    "type": {
                        "id": 40,
                        "type": "tunnel_device",
                        "label": "Network Tunnels"
                    },
                    "label": "UmbrellaHQ Tun (Do not modify)",
                    "deleted": false
                }
            ],
            "direction": "OUTBOUND"
        }
    ]
}

List DNS Activities

Find the DNS activities.

GET /activity/dns

Request

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/activity/dns?from=-30days&to=now&limit=2&offset=0' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

Click to view the sample response


{
    "data": [
        {
            "returncode": 0,
            "externalip": "192.168.221.35",
            "allapplications": [],
            "date": "2021-06-21",
            "internalip": "192.168.221.35",
            "time": "14:36:39",
            "querytype": "A",
            "policycategories": [
                {
                    "id": 71,
                    "type": "customer",
                    "label": "Block List",
                    "integration": false,
                    "deprecated": false
                }
            ],
            "type": "dns",
            "categories": [
                {
                    "id": 71,
                    "type": "customer",
                    "label": "Block List",
                    "integration": false,
                    "deprecated": false
                }
            ],
            "verdict": "blocked",
            "domain": "dnstun.com",
            "timestamp": 1624286199000,
            "blockedapplications": [],
            "allowedapplications": [],
            "identities": [
                {
                    "id": 538217202,
                    "type": {
                        "id": 9,
                        "type": "roaming",
                        "label": "Roaming Computers"
                    },
                    "label": "",
                    "deleted": true
                }
            ]
        }
    ]
}

Get Network Identities

List the network identities for the organization.

GET /organizations/{organizationId}/identities

Request

Specify the limit query parameter.

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/identities?from=-30days&to=now&limit=5' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

If successful, the server returns the list of identity information.

Click to view the sample response


{
    "data":
    [
        {
            "id":537302166,
            "type":
            {
                "id":28,
                "type":"ad_connector",
                "label":"AD Connector"
            },
            "label":"",
            "deleted":false
        },
        {
            "id":520864585,
            "type":
            {
                "id":21,
                "type":"site",
                "label":"Sites"
            },
            "label":"Default Site",
            "deleted":false
        },
        {
            "id":528417414,
            "type":
            {
                "id":40,
                "type":"tunnel_device",
                "label":"Network Tunnels"
            },
            "label":"UmbrellaHQ Tun (Do not modify)",
            "deleted":false
        }
    ]
}

Get Categories

The Umbrella Reporting v2 API includes utility endpoints. Utility endpoints provide access to labels and numerical identifiers for:

Applications
Identities
Threat types and names
Content and security categories

You can use these identifiers to filter API requests.

GET /organizations/{organizationId}/categories

Request

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/categories' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

The following sample response shows a partial list of category information:

Click to view the response


[{"label":"Adware","type":"content","legacyid":1,"integration":false,"deprecated":false,"id":0},
{"label":"Illegal Activities","type":"content","legacyid":347,"integration":false,"deprecated":false,"id":121},
{"label":"Command and Control","type":"security","legacyid":92,"integration":false,"deprecated":false,"id":65},
{"label":"Mobile Threats","type":"security","legacyid":87,"integration":false,"deprecated":false,"id":62},
{"label":"Sinkhole","type":"system","legacyid":178,"integration":false,"deprecated":false,"id":74},
{"label":"Chat and Instant Messaging","type":"content","legacyid":418,"integration":false,"deprecated":false,"id":164},{"label":"Peer File Transfer","type":"content","legacyid":440,"integration":false,"deprecated":false,"id":186},
{"label":"Reference","type":"content","legacyid":442,"integration":false,"deprecated":false,"id":188},
{"label":"DNS Tunneling VPN","type":"security","legacyid":176,"integration":false,"deprecated":false,"id":110},{"label":"Professional Networking","type":"content","legacyid":365,"integration":false,"deprecated":false,"id":130},{"label":"Online Trading","type":"content","legacyid":361,"integration":false,"deprecated":false,"id":128}}]

Find Top Destinations

List the top requested destinations by type.

GET /organizations/{organizationId}/top-destinations/{type}

The accepted type path parameter values are:

dns
firewall
ip
proxy

Set the required query parameters:

from
to
limit
offset

Request

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/top-destinations/dns?from=-30days&to=now&limit=2&offset=0' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

The sample response describes the top requested domains.

{
    "data": [
        {
            "count": 139,
            "bandwidth": null,
            "domain": "wpad.lab.test.local",
            "policycategories": [],
            "categories": [],
            "counts": {
                "requests": 139,
                "allowedrequests": 139,
                "blockedrequests": 0
            },
            "rank": 1
        },
        {
            "count": 96,
            "bandwidth": null,
            "domain": "wpad.abc.inc",
            "policycategories": [],
            "categories": [],
            "counts": {
                "requests": 96,
                "allowedrequests": 96,
                "blockedrequests": 0
            },
            "rank": 2
        }
    ]
}

Find Top Files

List the top requested files (proxy data).

GET /organizations/{organizationId}/top-files

Request

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/top-files?from=-30days&to=now&limit=2&offset=0' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

Click to view the response


{"data":
[
    {
        "requests":1482,
        "identitycount":1,
        "sha256":"3461539270ef7c64e91de3446260132d3fab0c78b8df53ccd3713264cb72b26b",
        "categories":
            [
                {
                    "id":25,
                    "type":"content",
                    "label":"Software/Technology",
                    "integration":false,
                    "deprecated":false
                }
            ],
        "filenames":["myip"],
        "filetypes":[]
    },
    {
        "requests":129,
        "identitycount":1,
        "sha256":"275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f",
        "categories":
            [
                {
                    "id":67,
                    "type":"security",
                    "label":"Malware",
                    "integration":false,
                    "deprecated":false
                },
                {
                    "id":25,
                    "type":"content",
                    "label":"Software/Technology",
                    "integration":false,
                    "deprecated":false
                }
            ],
        "filenames":["eicar.com"],
        "filetypes":[]
    }
]}

Find Top IPs

List the top internal IP addresses.

GET /organizations/{organizationId}/top-ips/internal

Request

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/top-ips/internal?from=-30days&to=now&limit=2&offset=0' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    "data":
    [
        {
            "ip":"192.168.0.112",
            "count":277
        },
        {
            "ip":"192.168.43.4",
            "count":64
        }
    ]
}

Get Total Requests

Find the total number of requests.

GET /organizations/{organizationId}/total-requests

Request

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/total-requests?from=-30days&to=now \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    "data": {
        "count": 77096
    }
}

Find Top Identities

List the top identity information.

GET /organizations/{organizationId}/top-identities

Request

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/top-identities?from=-30days&to=now&limit=2' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

Click to view the sample response


{
    "data": [
        {
            "requests": 67507,
            "bandwidth": 412568811,
            "identity": {
                "id": 528417414,
                "type": {
                    "id": 40,
                    "type": "tunnel_device",
                    "label": "Network Tunnels"
                },
                "label": "UmbrellaHQ Tun (Do not modify)",
                "deleted": false
            },
            "counts": {
                "requests": 67507,
                "allowedrequests": 24499,
                "blockedrequests": 672
            },
            "rank": 1
        },
        {
            "requests": 4199,
            "bandwidth": null,
            "identity": {
                "id": 536964154,
                "type": {
                    "id": 1,
                    "type": "network",
                    "label": "Networks"
                },
                "label": "",
                "deleted": true
            },
            "counts": {
                "requests": 4199,
                "allowedrequests": 4199,
                "blockedrequests": 0
            },
            "rank": 2
        }
    ]
}

Get Identity Distribution

List the identity distribution information.

GET /organizations/{organizationId}/identity-distribution

Request

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/identity-distribution?from=-30days&to=now&limit=2' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

Click to view the sample response


{
"data":[
    {
        "requests":25171,
        "unique_identity_count":1,
        "identity_type":{
            "id":40,
            "type":"tunnel_device",
            "label":"Network Tunnels"
        },
        "counts":{
            "requests":25171,
            "allowedrequests":24499,
            "blockedrequests":672
        }
    },
    {
        "requests":4288,
        "unique_identity_count":2,
        "identity_type":{
            "id":1,
            "type":"network",
            "label":"Networks"
        },
        "counts":{
            "requests":4288,
            "allowedrequests":4199,
            "blockedrequests":89
        }
    },
    {
        "requests":2119,
        "unique_identity_count":3,
        "identity_type":{
            "id":9,
            "type":"roaming",
            "label":"Roaming Computers"
        },
        "counts":{
            "requests":2119,
            "allowedrequests":231,
            "blockedrequests":1888
        }
    }]
}

Get Summary

Find a summarized report of activities, events, and identities.

GET /organizations/{organizationId}/summary

Request

curl -i GET 'https://reports.api.umbrella.com/v2/organizations/{organizationId}/summary?from=-30days&to=now' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json'

Response

Sample response (200, OK):

{
    "data": {
        "applications": 189,
        "domains": 2399,
        "requestsblocked": 2825,
        "filetypes": 0,
        "requests": 77096,
        "policycategories": 4,
        "requestsallowed": 74271,
        "categories": 85,
        "identitytypes": 3,
        "applicationsblocked": 0,
        "files": 1772,
        "identities": 6,
        "policyrequests": 2689,
        "applicationsallowed": 0
    }
}