Umbrella Reporting API overview

Reporting

The Umbrella Reporting API provides visibility into the traffic, events, and activities of the user devices, resources, and networks in an organization.

This guide provides information about the Reporting API path and query parameters, Umbrella content categories and IDs, and other location-related parameters that are required when making a request to the Reporting API. For questions about setting the location and location-trusted flags and redirecting HTTP requests, see HTTP Redirects and Request Authorization Header.

• Use Cases and Best Practices
• Rate Limits for Reports API Endpoints
• Request Headers
• Request Path Parameters
• Request Query Parameters
• Request Data by Time Range
• Time Range Header
• HTTP Redirects and Request Authorization Header
• Umbrella Reporting API Endpoints

Use Cases and Best Practices

The Umbrella Reporting API enables you to programmatically access logs and reports, and build widgets or custom reports. The Reporting API does not support bulk data retrieval. If you must export all your data or large data collections, you can enable logging to Amazon Simple Storage Service (Amazon S3). For more information about Umbrella logs, see Manage Your Logs in the Umbrella User Guide.

Rate Limits for Reports API Endpoints

Umbrella enables rate limits on the Reporting API endpoints. For more information, see Rate Limits > Reports.

Request Headers

Unless specified, the Umbrella API endpoints use JSON for all requests and responses.

Note: For POST, PUT, and PATCH operations, set the HTTP Content-Type header to application/json in your API request.

Request Path Parameters

The Umbrella Reporting API endpoints require various path parameters.

Request Query Parameters

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

Note: Umbrella uses the timestamp of the events to sort the /activity, /activity/dns, /activity/proxy, /activity/intrusion, /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.

For more information about time-related query parameters, see Timestamp and Relative Time Strings.

Categories Query Parameter

The Umbrella Reporting API categories query parameter accepts a string with a single category ID or list of comma-separated category IDs. Use the categories query parameter to search for events in your reports that are related to the categories. You can get the list of Umbrella categories from the Umbrella Reporting API /categories endpoint. The category object includes the category ID. For more information about the Umbrella Reporting API /categories endpoint, see Get Categories.

Umbrella Reporting API Categories with IDs

Umbrella Reporting API Categories with Legacy IDs

Umbrella Reporting API Categories with Deprecated Legacy IDs

Request Data by Time Range

Many Umbrella Reporting API 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. Also, some Umbrella Reporting API 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 API 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 and 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 that is 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 strings 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. Depending on the location where you make an API request, you must use a base URI in the request that is associated with your location.

The base URIs for reaching the Umbrella Reporting API from Europe (EU) and the United States (US) are:

• EU: api.umbrella.com/reports.eu/v2
• US: api.umbrella.com/reports.us/v2

Note: If an HTTP request does not originate from the same continent as the Umbrella data center, Umbrella responds with 302 Found.

To automatically redirect HTTP requests and preserve the HTTP Authorization header, you can set additional flags on the client and 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 --location --location-trusted \
   --request GET --url 'https://api.umbrella.com/reports/v2/activity?from=-7days&to=now&limit=10' \
   -H 'Authorization: Bearer %YourAccessToken%' \
   -H 'Content-Type: application/json'

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

Umbrella Reporting API Endpoints

You can find the Reporting API endpoints in the reports scope.

Activity

• Get Activities (All)
• Get Activity DNS
• Get Activity Proxy
• Get Activity Firewall
• Get Activity Intrusion
• Get Activity IP
• Get Activity AMP Retrospective

Top Identities

• Get Top Identities (All)
• Get Top Identities

Identity Distribution

• Get Identity Distribution (All)
• Get Identity Distribution By Type

Top Destinations

• Get Top Destinations
• Get Top Destinations By Type
• Get Top URLs

Top Categories

• Get Top Categories (All)
• Get Top Categories By Type

Top Event Types

• Get Top Event Types (All)

Top DNS Query Types

• Get Top DNS Query Types

Organization Requests by Hour

• Get Requests by Hour (All)
• Get Requests by Hour

Organization Requests by Time Range

• Get Requests by Timerange (All)
• Get Requests by Timerange

Organization Requests by Hour and Category

• Get Requests by Hour and Category (All)
• Get Requests by Hour and Category

Organization Requests by Time Range and Category

• Get Requests by Timerange and Category (All)
• Get Requests by Timerange and Category

Deployment and Status

• Get Deployment Status

Provider Deployment Status

• Get Deployment Status by Organization

Provider Requests by Hour

• Get Provider Requests by Hour (All)

Provider Requests by Time Range

• Get Provider Requests by Time Range (All)

Provider Requests by Organization

• Get Provider Requests by Organization

Provider Requests by Category

• Get Provider Requests by Category

Provider Requests by Destination

• Get Provider Requests by Destination

Provider Category Requests by Organization

• Get Provider Category Requests by Organization

Bandwidth by Hour

• Get Bandwidth by Hour (All)

Bandwidth by Time Range

• Get Bandwidth by Timerange (All)

Top Files

• Get Top Files (Proxy)

Total Requests

• Get Total Requests
• Get Total Requests (By Type)

Top Threats

• Get Top Threats (All)
• Get Top Threats (By Type)

Top Threat Types

• Get Top Threat Types (All)
• Get Top Threat Types By Type

Utility

• Get Applications
• Get Categories
• Get Identities
• Post Identities by IDs
• Get Identity
• Get Threat Types
• Get Threat Types by Threat ID
• Get Threat Names
• Get Threat Name by Threat ID

Utility (Providers)

• Get Provider Categories

Top IPs

• Get Top IPs
• Get Top IPs Internal

Summary

• Get Summary (All)
• Get Summary By Type

Summaries by Category

• Get Summaries by Category (All)
• Get Summaries by Category For Type

Summaries by Destination

• Get Summaries by Destination (All)
• Get Summaries by Destination For Type

Summaries by Rule

• Get Summaries by Rule