Cisco Umbrella Investigate API
The Umbrella Investigate API provides a complete view of domains in relation to IP and autonomous system number (ASN) information.
OpenAPI Specification
openapi: 3.0.0
info:
title: Cisco Umbrella Investigate API
description: 'The Umbrella Investigate API provides a complete view of domains in relation to IP and autonomous system number
(ASN) information.
You can get the following domain information:
* Domain status, risk score, and geolocation
* Number of domain searches
* Co-occurring domains
* Subdomains of a domain
* Tagged timeline of a domain, IP, or URL
* Security reputation of a domain
* Top accessed domains
* WHOIS information for the domain
* Threat intelligence data for domains, IPs, and URLs
* Threat intelligence samples by file hash'
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: investigate/v2
tags:
- name: Domain Status and Categorization
- name: Domain Volume
- name: Co-occurrences for a Domain
- name: Passive DNS
- name: Tagging Timeline
- name: Subdomains for a Domain
- name: Related Domains for a Domain
- name: Security Information for a Domain
- name: AS Information for a Domain
- name: WHOIS Information for a Domain
- name: Popularity List-Top Million Domains
- name: Search Domain
- name: Cisco Secure Malware Analytics Integration
- name: Umbrella
security:
- oauthFlow: []
paths:
/domains/categorization/{domain}:
get:
summary: Get Domain Status and Categorization
operationId: getDomainsCategorization
tags:
- Domain Status and Categorization
- Umbrella
description: 'Look up the status, and security and content category IDs for the domain.
The domain status is a numerical value determined by the Cisco Security Labs team.
Valid status values are: ''-1'' (malicious), ''1'' (safe), or ''0'' (undetermined status).
'
parameters:
- $ref: '#/components/parameters/domainParam'
- $ref: '#/components/parameters/showLabels'
security:
- oauthFlow:
- investigate.investigate:read
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/DomainCategorization'
example:
amazon.com:
status: 1
security_categories:
- '150'
content_categories:
- '8'
'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'
/domains/categorization:
post:
summary: Check Status and Categorization of Domains
operationId: postDomainsCategorization
tags:
- Domain Status and Categorization
- Umbrella
description: 'Provide a list of domains and look up the status, and security and content category IDs for each domain.
The domain status is a numerical value determined by the Cisco Security Labs team.
Valid status values are: ''-1'' (malicious), ''1'' (safe), or ''0'' (undetermined status).
'
parameters:
- $ref: '#/components/parameters/showLabels'
security:
- oauthFlow:
- investigate.bulk:read
requestBody:
required: true
description: 'In a single request, the payload must not exceed 100KB and contain no more
than 1000 domains.'
content:
application/json:
schema:
type: array
description: The list of domains.
items:
type: string
description: A domain name.
example: yahoo.com
example:
- google.com
- yahoo.com
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DomainCategorization'
example:
- google.com: null
status: 1
security_categories: []
content_categories:
- '23'
- '25'
- '190'
- yahoo.com: null
status: 1
security_categories: []
content_categories:
- '23'
- '167'
'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'
/domains/volume/{domain}:
get:
summary: Get Domain Volume
operationId: getDomainVolume
tags:
- Domain Volume
- Umbrella
description: 'List the query volume for a domain over the last 30 days.
If there is no information about the domain, Investigate returns an empty array.
As the query takes time to generate, the last two hours may be blank.
'
parameters:
- $ref: '#/components/parameters/domainParam'
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/stop'
- name: match
in: query
required: false
description: 'Valid values are: `exact`, `component`, or `all`. The default value is `all`.'
schema:
type: string
default: all
enum:
- exact
- component
- all
example: exact
security:
- oauthFlow:
- investigate.investigate:read
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
type: object
properties:
dates:
type: array
description: The list of dates recorded for the domain.
items:
type: string
description: The dates recorded for this domain expressed in the Unix epoch time.
example:
- '1510873200000'
- '1510959600000'
queries:
type: array
description: The list of the numbers of DNS queries requested for the domain in one hour, listed in ascending
order.
items:
type: string
description: The number of DNS queries requested for the domain in one hour.
example:
- '1378426'
- '1361934'
- '1308188'
example:
dates:
- '1510873200000'
- '1510959600000'
queries:
- '1378426'
- '1361934'
- '1308188'
- '1238823'
- '1245126'
- '1215994'
- '1256917'
- '1200190'
- '1245963'
- '1355719'
- '1332685'
- '1319825'
- '1362464'
- '1457174'
- '1695448'
'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'
/recommendations/name/{domain}.json:
get:
summary: Get Recommendations by Name
operationId: getRecommendationsName
tags:
- Co-occurrences for a Domain
- Umbrella
description: 'List the co-occurences for the specified domain.
A co-occurrence is when two or more domains are accessed by the same users within a small window of time.
Co-occurring domains are not necessarily problematic; legitimate sites co-occur with each other as a part
of normal web activity. However, unusual or suspicious co-occurences can provide additional information regarding
attacks.
To determine co-occurrences for a domain, a small time window of traffic across all of our datacenters is taken.
Investigate checks the sites that end users visited before and after the domain was requested in the API call.'
parameters:
- $ref: '#/components/parameters/domainParam'
security:
- oauthFlow:
- investigate.investigate:read
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
type: object
properties:
pfs2:
type: array
description: The list of the co-occurring domains.
items:
type: string
description: The domain name.
example: query.example.com
example:
- download.example.com
- query.example.com
found:
type: boolean
description: Specify whether the domain is co-occurring.
example: true
example:
pfs2:
- download.example.com
- query.example.com
found: true
'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'
/pdns/name/{domain}:
get:
summary: Get Resource Records for Name
operationId: getPassiveDNSName
tags:
- Passive DNS
- Umbrella
description: The Passive DNS endpoint provides historical data from the Umbrella resolvers for domains, IPs, and other
resource records.
parameters:
- $ref: '#/components/parameters/domainParam'
- $ref: '#/components/parameters/limitRecordsParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/sortorderParam'
- $ref: '#/components/parameters/sortbyParam'
- $ref: '#/components/parameters/recordTypeParam'
- $ref: '#/components/parameters/includeFeaturesParam'
- $ref: '#/components/parameters/minFirstSeenParam'
- $ref: '#/components/parameters/maxFirstSeenParam'
- $ref: '#/components/parameters/minLastSeenParam'
- $ref: '#/components/parameters/maxLastSeenParam'
- $ref: '#/components/parameters/sortCategoriesParam'
- $ref: '#/components/parameters/requiredCategoriesParam'
security:
- oauthFlow:
- investigate.investigate:read
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/Records'
example:
- minTtl: 86400
maxTtl: 86400
firstSeen: 1506630180000
lastSeen: 1557133071000
name: coinhive.com
type: NS
rr: lara.ns.cloudflare.com.
securityCategories:
- '8'
- '150'
contentCategories:
- Software/Technology
- Business Services
firstSeenISO: '2017-09-28T20:23:00Z'
lastSeenISO: 2019-05-06T08:57Z
'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'
/pdns/domain/{domain}:
get:
summary: Get Resource Records for Domain
operationId: getPassiveDNSDomain
tags:
- Passive DNS
- Umbrella
description: Get the Resource Record (RR) data for DNS responses, and categorization data, where the answer (or rdata)
is the domain(s).
parameters:
- $ref: '#/components/parameters/domainParam'
- $ref: '#/components/parameters/limitRecordsParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/sortorderParam'
- $ref: '#/components/parameters/sortbyParam'
- $ref: '#/components/parameters/recordTypeParam'
- $ref: '#/components/parameters/includeFeaturesParam'
- $ref: '#/components/parameters/minFirstSeenParam'
- $ref: '#/components/parameters/maxFirstSeenParam'
- $ref: '#/components/parameters/minLastSeenParam'
- $ref: '#/components/parameters/maxLastSeenParam'
- $ref: '#/components/parameters/sortCategoriesParam'
- $ref: '#/components/parameters/requiredCategoriesParam'
security:
- oauthFlow:
- investigate.investigate:read
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/Records'
example:
- minTtl: 3600
maxTtl: 3600
firstSeen: 1482339360000
lastSeen: 1482339360000
name: coinhive.com
type: CNAME
rr: www.coinhive.com.
securityCategories:
- Potentially Harmful
- Cryptomining
contentCategories: []
firstSeenISO: '2016-12-21T16:56:00Z'
lastSeenISO: 2016-12-21T16:56Z
'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'
/pdns/ip/{ip}:
get:
summary: Get Resource Records for IP
operationId: getPassiveDNSIp
tags:
- Passive DNS
- Umbrella
description: Get the Resource Record (RR) data for DNS responses, and categorization data, where the answer (or rdata)
is the domain(s).
parameters:
- name: ip
in: path
required: true
description: 'An IP address, for example: 2620:119:35::35.'
schema:
type: string
example: 208.67.222.222
- $ref: '#/components/parameters/limitRecordsParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/sortorderParam'
- $ref: '#/components/parameters/sortbyParam'
- $ref: '#/components/parameters/recordTypeParam'
- $ref: '#/components/parameters/includeFeaturesParam'
- $ref: '#/components/parameters/minFirstSeenParam'
- $ref: '#/components/parameters/maxFirstSeenParam'
- $ref: '#/components/parameters/minLastSeenParam'
- $ref: '#/components/parameters/maxLastSeenParam'
- $ref: '#/components/parameters/sortCategoriesParam'
- $ref: '#/components/parameters/requiredCategoriesParam'
security:
- oauthFlow:
- investigate.investigate:read
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/Records'
example:
- minTtl: 3600
maxTtl: 3600
firstSeen: 1544388420000
lastSeen: 1553839713000
name: 146.112.61.104
type: A
rr: hit-block.umbrella.com.
securityCategories:
- Malware
contentCategories:
- Software/Technology
firstSeenISO: '2018-12-09T20:47:00Z'
lastSeenISO: 2019-03-29T06:08Z
'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'
/pdns/raw/{anystring}:
get:
summary: Get Resource Records for Raw Data
operationId: getPassiveDNSRaw
tags:
- Passive DNS
- Umbrella
description: Get the Resource Record (RR) data for DNS responses, and categorization data, where the answer (or rdata)
could be anything.
parameters:
- name: anystring
in: path
required: true
description: 'The text representation of the data. When querying TXT records, add quotes around the text.
For example, to search for the ''abc'', provide the string as a path parameter
in an API request: ''https://api.umbrella.com/investigate/v2/pdns/raw/%22abc%22''.'
schema:
type: string
example: '%22abc%22'
- $ref: '#/components/parameters/limitRecordsParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/sortorderParam'
- $ref: '#/components/parameters/sortbyParam'
- $ref: '#/components/parameters/recordTypeParam'
- $ref: '#/components/parameters/includeFeaturesParam'
- $ref: '#/components/parameters/minFirstSeenParam'
- $ref: '#/components/parameters/maxFirstSeenParam'
- $ref: '#/components/parameters/minLastSeenParam'
- $ref: '#/components/parameters/maxLastSeenParam'
- $ref: '#/components/parameters/sortCategoriesParam'
- $ref: '#/components/parameters/requiredCategoriesParam'
security:
- oauthFlow:
- investigate.investigate:read
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
$ref: '#/components/schemas/Records'
example:
- minTtl: 3600
maxTtl: 3600
firstSeen: 1544386020000
lastSeen: 1555327199000
name: 926723159-3188410
type: TXT
rr: cisco.com
securityCategories:
- Malware
- Cryptomining
contentCategories:
- Software/Technology
- Business Services
firstSeenISO: '2018-12-09T20:07:00Z'
lastSeenISO: 2019-04-15T11:19Z
'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'
/links/name/{domain}:
get:
summary: Get Related Domains for Domain
operationId: getLinksName
tags:
- Related Domains for a Domain
- Umbrella
description: 'List the domain names that are frequently requested around
the same time (up to 60 seconds before or after) as the given domain name,
but that are not frequently associated with other domain names.'
parameters:
- $ref: '#/components/parameters/domainParam'
security:
- oauthFlow:
- investigate.investigate:read
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
type: object
properties:
tb1:
type: array
description: 'The list of domain name and score pairs where score is the number of client IP requests
to the site around the same time that the site is looked up.'
items:
type: object
properties:
domain:
type: string
description: A domain name.
example: www.example1.com
score:
type: number
description: 'The number of client IP requests to the site around the same time
that the site is looked up.'
example: 10
description: 'A [domain name, score] tuple where score is the number of client IP requests
to the site around the same time as the site is looked up.
This is a score that reflects the number of client IPs querying related
sites within 60 seconds of the original request.'
example:
- domain: www.example1.com
score: 10
found:
type: boolean
description: Specifies whether the results are available.
example: true
example:
tb1:
- domain: www.example1.com
score: 10
- domain: info.example2.com
score: 9
- domain: support.example.com
score: 3
found: true
'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'
/security/name/{domain}:
get:
summary: Get Security Score Information for Domain
operationId: getSecurityName
tags:
- Security Information for a Domain
- Umbrella
description: 'List multiple scores or security features for a domain. You can use the scores
or security features to determine relevant data points and build insights on the reputation
or security risk posed by the site. No one security information feature is conclusive.
Instead, consider these features as part of your security research.'
parameters:
- $ref: '#/components/parameters/domainParam'
security:
- oauthFlow:
- investigate.investigate:read
responses:
'200':
description: OK
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Date:
$ref: '#/components/headers/Date'
content:
application/json:
schema:
type: object
properties:
dga_score:
type: number
description: 'A domain generation algorithm (DGA) is used by malware to generate large lists of domain
names.
This score is created based on the likeliness
of the domain name being generated by an algorithm
rather than a human. This algorithm is designed to identify domains which
have been created using an automated randomization
strategy, which is a common evasion technique in malware kits or botnets.
This score ranges from -100 (suspicious) to 0 (benign).'
example: 38.301771886101335
perplexity:
type: number
description: 'A second score on the likeliness of the name to be algorithmically
generated, on a scale from 0 to 100. This score is used in conjunction with DGA.'
example: 0.4540313302593146
entropy:
type: number
description: The number of bits required to encode the domain name as a score. This score is used in conjunction
with DGA and Perplexity.
example: 2.5216406363433186
securerank2:
type: number
description: 'The suspicious rank for a domain that reviews base on the lookup behavior
of client IP for the domain.
Securerank is designed to identify hostnames requested by known infected
clients but never requested by clean clients,
assuming these domains are more likely to be bad.
Scores returned range from -100 (suspicious) to 100 (benign).'
example: -1.3135141095601992
pagerank:
type: number
description: A popularity score according to Google's PageRank algorithm.
example: 0.0262532
asn_score:
type: number
description: The ASN reputation score ranges from -100 to 0 where -100 is very suspicious.
example: -29.75810625887133
prefix_score:
type: number
description: 'The prefix ranks domains given their IP prefixes
(an IP prefix is the first three octets in an IP address)
and the reputation score of these prefixes. The scores range from -100 to 0 where -100 is
very suspicious.'
example: -64.9070502788884
rip_score:
type: number
description: 'The RIP ranks domains given their IP addresses and the reputation score
of these IP addresses. The scores ranges from -100 to 0 where -100 is very suspicious.'
example: -75.64720536038982
popularity:
type: number
description: 'The number of unique client IPs visiting this site, relative to all
requests to all sites. A score of how many different client or unique IPs requested
to this domain compared to others.'
example: 25.335450495507196
geodiversity:
type: array
description: The list of scores that represent the number of queries from clients visiting the domain,
broken down by country.
items:
type: number
description: 'A score that represents the number of queries from clients visiting the domain,
broken down by country. Score is a non-normalized ratio between 0 and 1.'
example: 0.24074075
example:
- 0.24074075
- 0.018518519
geodiversity_normalized:
type: array
description: 'The list of scores that represents the amount of queries for clients visiting the domain,
broken down by country.'
items:
type: number
description: A score that represents the amount of queries for clients visiting the domain, broken down
by country. The score is a normalized ratio between 0 and 1.
example: 0.3761535390278368
example:
- 0.3761535390278368
- 0.0005015965168831449
tld_geodiversity:
type: array
description: 'The list of scores that represent the top-level domain country code geodiversity as a percentage
of clients visiting the domain.'
items:
type: number
description: 'A score that represents the top-level domain country code geodiversity as a percentage
of clients visiting the domain. Occurs most often with domains that have a ccTLD.
The score is the normalized ratio between 0 and 1.'
example:
- 0.0
geoscore:
type: number
description: 'A score that represents how far the different physical locations serving this name
are from each other.'
example: 0
ks_test:
type: number
description: 'A number that represents the Kolmogorov-Smirnov test on geodiversity.
Zero indicates that the client traffic matches what is expected for this top-level domain.'
example: 0
attack:
type: string
description: 'The name of any known attacks associated with this domain.
Returns an empty string if no known threat associated with domain.'
example: ''
threat_type:
type: string
description: 'The type of the known attack, such as botnet or APT. Returns an empty string if no known
threat associated with domain.'
example: Botnet
found:
type: boolean
description: Specifies whether the results are available.
example: false
example:
dga_score: 38.301771886101335
perplexity: 0.4540313302593146
entropy: 2.5216406363433186
securerank2: -1.3135141095601992
pagerank: 0.0262532
asn_score: -29.75810625887133
prefix_score: -64.9070502788884
rip_score: -75.64720536038982
popularity: 25.335450495507196
geodiversity:
- 0.24074075
- 0.018518519
# --- truncated at 32 KB (134 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cisco-umbrella/refs/heads/main/openapi/cisco-umbrella-investigate-investigate-openapi.yml