Umbrella Console Reporting v1 API: request samples

Request Samples

Find Console ID

You can identify your console ID in the Umbrella MSP, MSSP, or Multi-Org console.

  1. Navigate to MSP Settings > Admins or MSSP Settings > Admins or Console Settings > Admins.
  2. View your console ID.

List Detailed Summary

The deployment summary endpoint displays a detailed overview of the deployment status for all child organizations of the console. The deployment status describes the number of active and inactive identities (networks, roaming computers, and virtual appliances) by identity type, in addition to the total number of identities. The Umbrella Console Reporting v1 API lists the deployment status for all child organizations as a total and also for each child organization.

Request

GET /organizations/{consoleId}/detailed-summary

curl -i GET 'https://reports.api.umbrella.com/v1/organizations/{consoleId}/detailed-summary?limit=10&offset=20' \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Click to view the sample response (200, OK) 

{
    "totals": {
        "roamingClients": {
            "active": 917,
            "inactive": 431,
            "total": 1348
        },
        "networks": {
            "active": 2,
            "inactive": 0,
            "total": 2
        },
        "virtualAppliances": {
            "active": 3,
            "inactive": 0,
            "total": 3
        }
    },
    "organizations": [
        {
          "name": "Your Customer’s Test Org",
          "id": 2071217,
          "roamingClients": {
            "active": 288,
            "inactive": 144,
            "total": 432
          },
          "networks": {
            "active": 2,
            "inactive": 0,
            "total": 2
          },
          "virtualAppliances": {
            "active": 3,
            "inactive": 0,
            "total": 0
          }
        }
    ]
}

List Security Summary

The Security Summary endpoint provides the summary of security data within the last 24 hours for all of your child organizations. The Security Summary endpoint response includes the organization ID of each child organization.

Note: The console Centralized Report is equivalent to the Security Summary endpoint report.

Request

GET /organizations/{consoleId}/security-summary

curl -i GET "https://reports.api.umbrella.com/v1/organizations/{consoleId}/security-summary?start=1513723392&end=1513684800" \
-H 'Authorization: Basic %YourEncodedKeySecret%' \
-H 'Content-Type: application/json'

Response

Click to view the sample response (200, OK) 

{
    "totals": {
        "requests": {
            "total": 79538,
            "security": 56526,
            "prevented": 31588,
            "contained": 29783,
            "blocked": 22867
        },
        "allSecurity":100200
    },
    "customers": [
        {
            "name": "Your child org’s name ",
            "id": 2071217,
            "requests": {
                "prevented": 0,
                "contained": 0,
                "security": 0,
                "blocked": 0,
                "total": 0
            },
            "allSecurity”:0
        }
    ]
}

Response Fields

Field Type Description
total integer The total number of requests listed in a security category or not. The totals refer to the totals of all child organizations, not just the totals from the organizations returned.
security integer The total number of requests that match a security category and were blocked.
prevented integer The numer of requests blocked under the "prevent" categories, such as malware, potentially harmful threats, and DNS tunnelling VPN.
contained integer The number of requests that are blocked under the "contain" categories, such as command and control (botnet) and phishing.
blocked integer The total number of blocked security events.
allSecurity integer The total number of security events (blocked or not).