🚧
Special privileges required
Reports & Analysis are only available to users with the Google Threat Intelligence (Google TI) Enterprise or Enterprise Plus licenses.

This endpoint allows us to search and filter Google TI Reports effectively. It returns a list of Report objects only when filtering by the parameter collection_type:report.

Searches observations

if you don't filter by the collection_type this endpoint will return not only Vulnerabilities but other types of objects such as Vulnerabilitie, Threat Actors, Malware families, Software or Toolkits, Campaigns or IoC Collections, matching the rest of the filters.
filers' values are case-insensitive
several filters can be combined together in a more complex and specific search
boolean operators can be used in more complex searches: AND, OR, NOT
quotes are needed for filters' values with spaces: description:"Phishing campaign"
wildcards (*) can be used for partial matches: name:Ransom*
date filters formats: YYYY-MM-DD, YYYY-MM-DDTHH-mm-ss
date relative formats: 60d (for days), 10m (for minutes)
date ranges can be specified with + or -: last_modification_date:7d+, creation_date:2024-01-01-

Allowed filters by object

View the full list of allowed filters here.

🚧
To restrict the results to Report objects only, you must use the collection_type:report search modifier / extra filter.

Allowed orders

order:name+: sorts objects alphabetically by name, ascending + or descending -.
order:creation_date-: sorts objects descending - (default) by most recently created objects first, or ascending + by oldest objects first.
order:last_modification_date-: sorts objects descending - by most recently modified objects first, or ascending + by firstly modified objects first.
order:lookups_trend-: sorts objects ascending + or descending - based on the trend of the daily distinct-user lookups over the IoCs of the object in the last 14 days.
order:submissions_trend-: sorts objects ascending + or descending - based on the trend of the daily distinct-user submissions of IoCs of the object in the last 14 days.
order:relevance+: sorts objects ascending + or descending - based on the relevance of the object.
order:exploitation_state+: sorts objects ascending + or descending - based on the exploitation state of the vulnerability.
order:risk_rating+: sorts objects ascending + or descending - based on the risk rating of the vulnerability.

Examples

Get the list of all crowdsourced Reports created from the beginning of 2024 whose name contains the "phishing" word and sort results descending by creation date (FIFO order).

import requests
import urllib

filters = "collection_type:report name:phishing creation_date:2024-01-01+ origin:Crowdsourced"
order = "creation_date-"
url = f"https://www.virustotal.com/api/v3/collections?filter={urllib.parse.quote(filters)}&order={order}"
headers = {"accept": "application/json","x-apikey": <api-key>}
response = requests.get(url, headers=headers)

200200

400400