Cisco Umbrella Reporting API
The Reporting API provides the data to generate the Umbrella reports.
OpenAPI Specification
openapi: 3.0.1
info:
title: Cisco Umbrella Reporting API
description: The Reporting API provides the data to generate the Umbrella reports.
version: 2.0.0
contact:
name: Cloud Security Developer Community
x-provenance:
method: harvested
authored_by: Cisco Umbrella
harvested_by: API Evangelist
harvested_on: '2026-08-19'
first_party: true
provider_published: true
source_host: pubhub.devnetcloud.com
note: 26 first-party OpenAPI 3.0 documents (256 operations) listed by Cisco's own docs-nav config and fetched anonymously.
Byte-identity reconfirmed 2026-08-19 by SHA-256 against the live source.
x-evidence:
- type: source
url: https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/umbrella-config.json
- type: source
url: https://developer.cisco.com/docs/cloud-security/
servers:
- url: https://api.umbrella.com/{basePath}
variables:
basePath:
default: reports/v2
tags:
- name: Activity
- name: Top Identities
- name: Identity Distribution
- name: Top Destinations
- name: Top Categories
- name: Top Event Types
- name: Top DNS Query Types
- name: Organization Requests by Hour
- name: Organization Requests by Timerange
- name: Organization Requests by Hour and Category
- name: Organization Requests by Timerange and Category
- name: Deployment Status
- name: Provider Deployment Status
- name: Provider Requests by Hour
- name: Provider Requests by Timerange
- name: Provider Requests by Organization
- name: Provider Requests by Category
- name: Provider Requests by Destination
- name: Provider Category Requests by Organization
- name: Bandwidth by Hour
- name: Bandwidth by Timerange
- name: Top Files
- name: Total Requests
- name: Top Threats
- name: Top Threat Types
- name: Utility
- name: Top IPs
- name: Summary
- name: Summaries by Category
- name: Summaries by Destination
- name: Summaries by Rule (Intrusion)
- name: Umbrella
security:
- oauthFlow: []
paths:
/activity:
get:
tags:
- Activity
- Umbrella
summary: Get Activities (All)
description: 'List all activities (dns/proxy/firewall/intrusion) within the timeframe.
**Note:** The IP activity report is not available.
**Access Scope:** Reports > Granular Events > Read-Only'
operationId: getActivities
security:
- oauthFlow:
- reports.granularEvents:read
parameters:
- $ref: '#/components/parameters/fromParam'
- $ref: '#/components/parameters/toParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/domainsParam'
- $ref: '#/components/parameters/urlsParam'
- $ref: '#/components/parameters/categoriesParam'
- $ref: '#/components/parameters/policyCategoriesParam'
- $ref: '#/components/parameters/ipParam'
- $ref: '#/components/parameters/portsParam'
- $ref: '#/components/parameters/identityIdsParam'
- $ref: '#/components/parameters/identityTypesParam'
- $ref: '#/components/parameters/applicationIdParam'
- $ref: '#/components/parameters/verdictParam'
- $ref: '#/components/parameters/ruleIdParam'
- $ref: '#/components/parameters/filenameParam'
- $ref: '#/components/parameters/securityOverriddenParam'
- $ref: '#/components/parameters/bundleIdParam'
- $ref: '#/components/parameters/threatsParam'
- $ref: '#/components/parameters/threatTypesParam'
- $ref: '#/components/parameters/ampDispositionParam'
- $ref: '#/components/parameters/antivirusThreatsParam'
- $ref: '#/components/parameters/xTrafficTypeParam'
- $ref: '#/components/parameters/isolatedStateParam'
- $ref: '#/components/parameters/isolatedFileActionParam'
- $ref: '#/components/parameters/dataLossPreventionStateParam'
- $ref: '#/components/parameters/filterNoisyDomainsParam'
- $ref: '#/components/parameters/httpErrorsParam'
- $ref: '#/components/parameters/existsParam'
- $ref: '#/components/parameters/timezoneParam'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
anyOf:
- $ref: '#/components/schemas/ActivityDns'
- $ref: '#/components/schemas/ActivityFirewall'
- $ref: '#/components/schemas/ActivityIntrusion'
- $ref: '#/components/schemas/ActivityProxy'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
example:
meta: {}
data:
- externalip: 52.8.160.247
internalip: 52.8.160.247
policycategories:
- id: 66
label: Malware
type: security
integration: true
categories:
- id: 66
label: Malware
type: security
integration: true
verdict: allowed
domain: google.com
timestamp: 1731002169000
time: 06:31:46
date: '2019-01-24'
identities:
- id: 1
label: Catch Rate Testing System
type:
id: 21
label: Sites
type: site
deleted: true
threats:
- label: Wannacry
type: Ransomware
allapplications:
- id: 1
label: label
type: NBAR
category:
id: 1
label: category
allowedapplications:
- id: 1
label: label
type: NBAR
category:
id: 1
label: category
querytype: MX
returncode: 2
blockedapplications: []
type: dns
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/activity/dns:
get:
tags:
- Activity
- Umbrella
summary: Get Activity DNS
description: 'List all DNS entries within the timeframe.
**Access Scope:** Reports > Granular Events > Read-Only'
operationId: getActivityDns
security:
- oauthFlow:
- reports.granularEvents:read
parameters:
- $ref: '#/components/parameters/fromParam'
- $ref: '#/components/parameters/toParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/orderParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/domainsParam'
- $ref: '#/components/parameters/categoriesParam'
- $ref: '#/components/parameters/policyCategoriesParam'
- $ref: '#/components/parameters/ipParam'
- $ref: '#/components/parameters/identityIdsParam'
- $ref: '#/components/parameters/identityTypesParam'
- $ref: '#/components/parameters/applicationIdParam'
- $ref: '#/components/parameters/verdictParam'
- $ref: '#/components/parameters/threatsParam'
- $ref: '#/components/parameters/threatTypesParam'
- $ref: '#/components/parameters/filterNoisyDomainsParam'
- $ref: '#/components/parameters/timezoneParam'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ActivityDns'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
example:
data:
- externalip: 52.8.160.247
internalip: 52.8.160.247
policycategories:
- id: 66
label: Malware
type: security
integration: true
categories:
- id: 66
label: Malware
type: security
integration: true
verdict: allowed
domain: google.com
timestamp: 1731002169000
time: 06:31:46
date: '2019-01-24'
identities:
- id: 1
label: Catch Rate Testing System
type:
id: 21
label: Sites
type: site
deleted: true
threats:
- label: Wannacry
type: Ransomware
allapplications:
- id: 1
label: label
type: NBAR
category:
id: 1
label: category
allowedapplications:
- id: 1
label: label
type: NBAR
category:
id: 1
label: category
querytype: MX
returncode: 2
blockedapplications: []
type: dns
meta: {}
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/activity/proxy:
get:
tags:
- Activity
- Umbrella
summary: Get Activity Proxy
description: 'List all proxy entries within the timeframe.
**Access Scope:** Reports > Granular Events > Read-Only'
operationId: getActivityProxy
security:
- oauthFlow:
- reports.granularEvents:read
parameters:
- $ref: '#/components/parameters/fromParam'
- $ref: '#/components/parameters/toParam'
- $ref: '#/components/parameters/orderParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/domainsParam'
- $ref: '#/components/parameters/urlsParam'
- $ref: '#/components/parameters/categoriesParam'
- $ref: '#/components/parameters/policyCategoriesParam'
- $ref: '#/components/parameters/ipParam'
- $ref: '#/components/parameters/portsParam'
- $ref: '#/components/parameters/identityIdsParam'
- $ref: '#/components/parameters/identityTypesParam'
- $ref: '#/components/parameters/applicationIdParam'
- $ref: '#/components/parameters/verdictParam'
- $ref: '#/components/parameters/ruleIdParam'
- $ref: '#/components/parameters/filenameParam'
- $ref: '#/components/parameters/securityOverriddenParam'
- $ref: '#/components/parameters/bundleIdParam'
- $ref: '#/components/parameters/threatsParam'
- $ref: '#/components/parameters/threatTypesParam'
- $ref: '#/components/parameters/ampDispositionParam'
- $ref: '#/components/parameters/antivirusThreatsParam'
- $ref: '#/components/parameters/tenantControlsParam'
- $ref: '#/components/parameters/isolatedStateParam'
- $ref: '#/components/parameters/isolatedFileActionParam'
- $ref: '#/components/parameters/dataLossPreventionStateParam'
- $ref: '#/components/parameters/httpErrorsParam'
- $ref: '#/components/parameters/timezoneParam'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ActivityProxy'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
example:
data:
- destinationip: ''
externalip: 32.4.91.7
responsesize: 3329530
allapplications:
- id: 1313
label: Netflix
category:
id: 47
label: Media
date: '2022-02-18'
datalossprevention:
state: ''
antivirusthreats:
puas: []
viruses: []
others: []
internalip: 192.168.1.43
referer: ''
contenttype: ''
tenantcontrols: false
securityoverridden: false
useragent: ''
time: '23:29:42'
amp:
disposition: ''
score: 0
malware: ''
policycategories: []
type: proxy
requestsize: 1996
port: 443
policy:
ruleid: 0
rulesetid: 0
destinationlistids: []
timebasedrule: false
forwardingmethod: ''
categories:
- id: 17
type: content
label: Movies
integration: false
deprecated: true
isolated:
state: not-isolated
fileaction: ''
statuscode: 200
egress:
ip: 155.190.3.8
type: shared
blockedfiletype: ''
url: https://ipv4-lax2-ix.1.oca.anothervideo.net
verdict: allowed
responsefilename: ''
warnstatus: ''
sha256: ''
timestamp: 1645226982000
blockedapplications: []
allowedapplications: []
identities:
- id: 1
type:
id: 34
type: anyconnect
label: Anyconnect Roaming Client
label: Vincent's Macbook
deleted: false
datacenter:
label: Los Angeles, US
id: LAX
threats: []
httperrors: []
bundleid: 3
meta: {}
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/activity/firewall:
get:
tags:
- Activity
- Umbrella
summary: Get Activity Firewall
description: 'List all firewall activity within the timeframe.
**Access Scope:** Reports > Granular Events > Read-Only'
operationId: getActivityFirewall
security:
- oauthFlow:
- reports.granularEvents:read
parameters:
- $ref: '#/components/parameters/fromParam'
- $ref: '#/components/parameters/toParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/identityIdsParam'
- $ref: '#/components/parameters/ruleIdParam'
- $ref: '#/components/parameters/verdictParam'
- $ref: '#/components/parameters/ipParam'
- $ref: '#/components/parameters/portsParam'
- $ref: '#/components/parameters/timezoneParam'
- $ref: '#/components/parameters/categoriesParam'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ActivityFirewall'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
example:
data:
- date: '2019'
destinationip: 52.8.160.247
sourceip: 192.168.0.1
sourceport: 0
destinationport: 0
categories:
- id: 66
label: Malware
type: security
integration: true
verdict: allowed
time: '12:34'
timestamp: 1731002169000
identities:
- id: 1
label: Catch Rate Testing System
type:
id: 21
label: Sites
type: site
deleted: false
protocol:
id: 17
label: UDP
rule:
id: 1
label: Default Rule
type: firewall
allapplications:
- id: 72
label: dns IT Service Management
app: ''
applicationprotocols:
- id: 72
label: dns IT Service Management
app: ''
packetsize: 32
direction: towards
meta: {}
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/activity/intrusion:
get:
tags:
- Activity
- Umbrella
summary: Get Activity Intrusion
description: 'List all Intrusion Prevention System (IPS) activity within the timeframe.
**Access Scope:** Reports > Granular Events > Read-Only'
operationId: getActivityIntrusion
security:
- oauthFlow:
- reports.granularEvents:read
parameters:
- $ref: '#/components/parameters/fromParam'
- $ref: '#/components/parameters/toParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/identityIdsParam'
- $ref: '#/components/parameters/signaturesParam'
- $ref: '#/components/parameters/signatureListIdsParam'
- $ref: '#/components/parameters/intrusionActionParam'
- $ref: '#/components/parameters/ipParam'
- $ref: '#/components/parameters/portsParam'
- $ref: '#/components/parameters/filterNoisyDomainsParam'
- $ref: '#/components/parameters/timezoneParam'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ActivityIntrusion'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
example:
data:
- type: intrusion
date: 12-02-22
destinationip: 10.10.10.10
protocol:
id: 17
label: UDP
sourceip: 10.10.10.10
signaturelist:
id: 1111
classification: malicious
rule:
- id: 391327
label: UNKNOWN
ipsProfile: PROFILE
sourceport: 22
sessionid: 190898098
verdict: detected
destinationport: 33
timestamp: 1594557262000
time: 09:30
identities:
- id: 211034846
type:
id: 34
type: anyconnect
label: Anyconnect Roaming Client
label: omerta
deleted: false
severity: HIGH
signature:
generatorid: 1
id: 47829
label: SERVER-OTHER JBoss Richfaces expression language injection attempt
cves:
- cve-2015-0279
- cve-2018-12532
meta: {}
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/activity/ip:
get:
tags:
- Activity
- Umbrella
summary: Get Activity IP
description: '(Deprecated) List all IP activity within the timeframe.
**Access Scope:** Reports > Granular Events > Read-Only'
operationId: getActivityIP
security:
- oauthFlow:
- reports.granularEvents:read
parameters:
- $ref: '#/components/parameters/fromParam'
- $ref: '#/components/parameters/toParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/identityIdsParam'
- $ref: '#/components/parameters/identityTypesParam'
- $ref: '#/components/parameters/categoriesParam'
- $ref: '#/components/parameters/verdictParam'
- $ref: '#/components/parameters/ipParam'
- $ref: '#/components/parameters/portsParam'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items: {}
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
example:
data: []
meta: {}
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/activity/amp-retrospective:
get:
tags:
- Activity
- Umbrella
summary: Get Activity AMP Retrospective
description: 'List all AMP retrospective activity within the timeframe.
**Access Scope:** Reports > Granular Events > Read-Only'
operationId: getActivityAmpRetrospective
security:
- oauthFlow:
- reports.granularEvents:read
parameters:
- $ref: '#/components/parameters/fromParam'
- $ref: '#/components/parameters/toParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/ampDispositionParam'
- $ref: '#/components/parameters/sha256Param'
- $ref: '#/components/parameters/timezoneParam'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ActivityAMPRetro'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
example:
data:
- timestamp: 1548311506
firstseenat: 1548311506
disposition: clean
score: 10
hostname: google.com
malwarename: malware
sha256: 9495b6c155044053953efe30ebaf804780c114e7b721b14f6a5b0a782769696e
meta: {}
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/top-identities:
get:
tags:
- Top Identities
- Umbrella
summary: Get Top Identities (All)
description: 'List the identities by the number of requests made, sorted in descending order.
**Access Scope:** Reports > Aggregations > Read-Only'
operationId: getTopIdentities
security:
- oauthFlow:
- reports.aggregations:read
parameters:
- $ref: '#/components/parameters/fromParam'
- $ref: '#/components/parameters/toParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/domainsParam'
- $ref: '#/components/parameters/urlsParam'
- $ref: '#/components/parameters/categoriesParam'
- $ref: '#/components/parameters/policyCategoriesParam'
- $ref: '#/components/parameters/ipParam'
- $ref: '#/components/parameters/portsParam'
- $ref: '#/components/parameters/identityIdsParam'
- $ref: '#/components/parameters/identityTypesParam'
- $ref: '#/components/parameters/applicationIdParam'
- $ref: '#/components/parameters/verdictParam'
- $ref: '#/components/parameters/sha256Param'
- $ref: '#/components/parameters/securityOverriddenParam'
- $ref: '#/components/parameters/bundleIdParam'
- $ref: '#/components/parameters/threatsParam'
- $ref: '#/components/parameters/threatTypesParam'
- $ref: '#/components/parameters/ampDispositionParam'
- $ref: '#/components/parameters/antivirusThreatsParam'
- $ref: '#/components/parameters/dataLossPreventionStateParam'
- $ref: '#/components/parameters/filterNoisyDomainsParam'
- $ref: '#/components/parameters/timezoneParam'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TopIdentity'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
example:
data:
- requests: 3827
bandwidth: 7051943359
identity:
id: 1
label: Catch Rate Testing System
type:
id: 21
label: Sites
type: site
deleted: false
counts:
requests: 123
allowedrequests: 60
blockedrequests: 63
rank: 3
meta: {}
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/top-identities/{type}:
get:
tags:
- Top Identities
- Umbrella
summary: Get Top Identities
description: 'List the identities for the specific traffic type by the number of requests.
Sort the results in descending order.
**Access Scope:** Reports > Aggregations > Read-Only'
operationId: getTopIdentitiesType
security:
- oauthFlow:
- reports.aggregations:read
parameters:
- $ref: '#/components/parameters/typeDnsWebIpFirewallParam'
- $ref: '#/components/parameters/fromParam'
- $ref: '#/components/parameters/toParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/domainsParam'
- $ref: '#/components/parameters/urlsParam'
- $ref: '#/components/parameters/categoriesParam'
- $ref: '#/components/parameters/policyCategoriesParam'
- $ref: '#/components/parameters/ipParam'
- $ref: '#/components/parameters/portsParam'
- $ref: '#/components/parameters/identityIdsParam'
- $ref: '#/components/parameters/identityTypesParam'
- $ref: '#/components/parameters/applicationIdParam'
- $ref: '#/components/parameters/verdictParam'
- $ref: '#/components/parameters/sha256Param'
- $ref: '#/components/parameters/securityOverriddenParam'
- $ref: '#/components/parameters/bundleIdParam'
- $ref: '#/components/parameters/threatsParam'
- $ref: '#/components/parameters/threatTypesParam'
- $ref: '#/components/parameters/ampDispositionParam'
- $ref: '#/components/parameters/antivirusThreatsParam'
- $ref: '#/components/parameters/dataLossPreventionStateParam'
- $ref: '#/components/parameters/filterNoisyDomainsParam'
- $ref: '#/components/parameters/timezoneParam'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TopIdentity'
meta:
$ref: '#/components/schemas/Meta'
required:
- data
- meta
example:
data:
- requests: 3827
bandwidth: 7051943359
identity:
id: 1
label: Catch Rate Testing System
type:
id: 21
label: Sites
type: site
deleted: false
counts:
requests: 123
allowedrequests: 60
blockedrequests: 63
rank: 3
meta: {}
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
/identity-distribution:
get:
tags:
- Identity Distribution
- Umbrella
summary: Get Identity Distribution (All)
description: 'List the number of requests by identity types.
**Access Scope:** Reports > Aggregations > Read-Only'
operationId: getIdentityDistribution
security:
- oauthFlow:
- reports.aggregations:read
parameters:
- $ref: '#/components/paramete
# --- truncated at 32 KB (228 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cisco-umbrella/refs/heads/main/openapi/cisco-umbrella-reports-reporting-openapi.yml