Cisco Secure Access Reporting API

Reporting

The Cisco Secure Access 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, Secure Access 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.

Overview

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

Walkthrough: Secure Access Reporting API

Rate Limits for Reporting

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

Request Headers

Unless specified, the Secure Access 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.

Use Cases and Best Practices

The Secure Access 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 the Secure Access logs, see Manage Logging in the Cisco Secure Access Help.

Request Path Parameters

The Secure Access Reporting API endpoints require various path parameters.

Request Query Parameters

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

Note: Secure Access uses the timestamp of the events to sort the /activity, /activity/dns, /activity/proxy, /activity/decryption, /activity/intrusion, /activity/firewall, /activity/ztna, 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 Secure Access 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 Secure Access categories from the Secure Access Reporting API /categories endpoint. The category object includes the category ID. For more information about the Secure Access Reporting API /categories endpoint, see Get Categories.

Secure Access Reporting API Categories with IDs

Secure Access Reporting API Categories with Legacy IDs

Secure Access Reporting API Categories with Deprecated Legacy IDs

Request Data by Time Range

Many Secure Access 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. Additionally, some Secure Access Reporting API endpoints enable a timerange header.

Time Range Header

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

• minute
• hour (default value)
• day

Secure Access 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 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

Secure Access 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 Secure Access Reporting API from Europe (EU) and the United States (US) are:

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

Note: If an HTTP request does not originate from the same continent as the location of the Secure Access data warehouse, Secure Access 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.sse.cisco.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.

Secure Access 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
• Get Activity ZTNA
• Get Activity Decryption

Top Identities

• Get Top Identities (All)
• Get Top Identities

Identity Distribution

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

Top Resources

• Top Resources (All)
• Top Resources by Types

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
• Get Summaries by Rule for Policy Rule Firewall Hit Count
• Get Summaries by Rule for Policy Rule Hit Count

Remote Access

• Get Remote Access Events

Private Resource

• Get Private Resource Access Statistics in Details Report
• Get Private Resource Access Statistics in Identity Report
• Get Private Resource Access Statistics in Summary Report

Requests Resource Connector

• Get Total Requests by Resource Connector
• Get Total Requests by Resource Connector Group

Requests Summary Resource Connector Groups

• Get Requests Summary for Resource Connector Groups

Resource Connectors

• Get Detailed Resource Connector Group Statistics
• Get Count of Overloaded Groups
• Get Detailed Resource Connector Group Statistics

Rules Activity

• Get the Rules for the Event Activity

Unique Resources

• Get Unique Resources (All)