Cisco Umbrella for Government Reporting API

Reporting

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

Use Cases and Best Practices

The 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 need to export all of 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 for Government SIG User Guide.

Request Path Parameters

The Reporting API endpoints require various path parameters.

Request Query Parameters

You can customize and filter 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.

Categories Query Parameter

The Umbrella for Government 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 Reporting API /categories endpoint. The category object includes the category ID. For more information about the Reporting API /categories endpoint, see Get Categories.

Umbrella for Government Reporting API Categories with IDs

Umbrella for Government Reporting API Categories with Legacy IDs

Umbrella for Government Reporting API Categories with Deprecated Legacy IDs

Request Data by Time Range

Many 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 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.

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

Note: If an HTTP request does not originate from the same continent as the Umbrella data center, the 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 --location --location-trusted \
   --request GET --url 'https://api.umbrellagov.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 for Government 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

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

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