API Reference

Get an hourly Threat List

get https://www.virustotal.com/api/v3/threat_lists//

🚧

Special privileges required

Specific Threat Lists are only available to users with the Google Threat Intelligence (Google TI) Enterprise Plus or Enterprise and Enterprise Plus licenses.

This endpoint provides Indicators of Compromise (IoCs) such as files, URLs domains and IP addresses, categorized by our security engine partners and/or Google TI experts as follos:

Category nameThreat List IDEntities supported (threat_list_id)LicenseDescription
RansomwareransomwarefilesAllIoCs categorized as Ransomware by our security engine partners or Google TI experts.
Malicious Network Infrastructuremalicious-network-infrastructureURLs, domains, IP addressesAllNetwork related IoCs which have been related with Malware Infrastructure by our Google TI experts.
Malwaremalwarefiles, URLs, domains, IP addressesEnterprise and Enterprise PlusIoCs that have been identified and classified as malware by our Google TI specialists.
Threat Actorthreat-actorfiles, URLs, domains, IP addressesEnterprise and Enterprise PlusIoCs that our Google TI experts have linked to specific Threat Actors.
Daily Top Trendingtrendingfiles, URLs, domains, IP addressesEnterprise and Enterprise PlusTop Trending IoCs based on daily lookups and relevance.
MobilemobilefilesEnterprise PlusIOS and Android files that have been identified as malware by our security engine partners.
OS XosxfilesEnterprise PlusOS X files that have been identified as malware by our security engine partners.
LinuxlinuxfilesEnterprise PlusLinux files that have been identified as malware by our security engine partners.
Internet of ThingsiotfilesEnterprise PlusIoT files that have been identified as malware by our security engine partners.
Cryptominerscryptominerfiles, URLs, domains, IP addressesEnterprise PlusIoCs which our security engine partners have classified as Miners.
PhishingphishingURLs, domains, IP addressesEnterprise PlusNetwork related IoCs which our security engine partners have classified as Phishing.
First Stage Delivery Vectorsfirst-stage-delivery-vectorsfilesEnterprise PlusEmails attachments and files served by URLs, that have been identified as malware by our security engine partners.
Vulnerability Weaponizationvulnerability-weaponizationfiles, URLs, domains, IP addressesEnterprise PlusIoCs which have been related with Vulnerabilities exploitation by our security engine partners or Google TI experts.
InfostealersinfostealerfilesEnterprise PlusFiles that have been categorized as Infostealers by our security engine partners or Google TI experts.

Threat Lists are hourly generated as IoCs packages, with 2 hours difference from the current time. This means that if the current time in UTC is T you can get T-2h Threat List but any more recent than that.
Threat Lists can be retrieved for up to 7 days through the time argument, which must be in YYYYMMDDhh format. For example, time 2025022011 returns the batches correspoding to February 20th 2025 11:00 - 11:59 UTC.

Filtering

IoCs can be filtered by IoC type with the type parameter (type=file, type=url, type=ip_address, type=domain). Additionally, multiple types can be included in a single request. Ex: type=file,url or type=domain,url,ip_address.

Alternatively, the query parameter can combine (with or without the and boolean operator) the following search modifiers for extra filtering:

  • gti_score: filter IoCs by the Google TI score. Ex: query=gti_score:60+, query=gti_score:60-, query=gti_score:1
  • positives: filter IoCs by the number of AV detections. Ex: query=positives:2+, query=positives:5-, query=positives:1
  • has:malware_families: retrieve only IoCs that have at least one associated Malware Family. Ex: query=has:malware_families and positives:10+ and gti_score:30+
  • has:campaigns: retrieve only IoCs that have at least one associated Campaign. Ex: query=has:campaigns positives:15+ gti_score:60+
  • has:reports: retrieve only IoCs that have at least one associated Report. Ex: query=has:reports positives:2- gti_score:2-
  • has:threat_actors: retrieve only IoCs that have at least one associated Threat Actor. It is not needed for retrieving Threat Actor Threat Lists. Ex: query=has:threat_actors positives:2- gti_score:30+

Note that only one modifier of each type can be used simultaneously.

  • Use this: gti_score:0+ positives:0+ and has:malware_families has:campaigns has:reports has:threat_actors.
  • Avoid this: gti_score:30+ gti_score:50-, or positives:1+ positives:3-.

Formats

Threat Lists can be exported in several formats by specifying it with the format parameter. These are the available formats:

  • json (by default format).
  • csv - Ex. format=csv
  • stix - Ex. format=csv
  • stix-sentinel - Ex. format=csv
  • misp - Ex. format=csv

Response

{
    "iocs": <_list of dictionaries_> list of IoCs.
    [
        {
            "data": <_dictionary_> data of an IoC.
            {
                "type": "file",
                "id": \<_string_> sha256 hash identifier of the IoC. This identifier can be used to retrieve the complete IoC report.
                "attributes": \<_dictionaries_> attributes of the IoC.
                {
                    "gti_assessment": \<_dictionary_> shows the Google TI calculated Threat Assessment of the IoC, split by numerical threat score, associated severity and the global verdict.  
                    {
                        "verdict": \<_dictionary_> determines the likelihood that the IoC is malicious. Possible verdicts include.
                        {
                            "value": \<_string_> 
                            **VERDICT_BENIGN** means that the IoC is considered harmless
                            **VERDICT_UNDETECTED** means that there are no immediate evidence of malicious intent
                            **VERDICT_SUSPICIOUS** represents potentially malicious activity **VERDICT_MALICIOUS** represents high confidence that the IoC poses a threat
                            **VERDICT_UNKNOWN** means that we were not able to generate a verdict for this IoC.
                        },
                        "threat_score": \<_dictionary_> numerical value representing the harmfulness of the threat behind the IoC if any.
                        {
                            "value": \<_integer_> numerical value between 0 (harmless) and 100 (harmful).
                        },
                        "severity": \<_dictionary_> severity or impact of the threat behind the IoC if any.
                        {
                            "value": \<_string_> 
                            **SEVERITY_NONE** means that the IoC hasnn't a malicious verdict 
                            **SEVERITY_LOW** means that the IoC likely has a minor impact but should still be monitored 
                            **SEVERITY_MEDIUM** indicates a potential threat that warrants attention
                            **SEVERITY_HIGH** requires immediate action because the threat behind the IoC could have a critical impact 
                            **SEVERITY_UNKNOWN**: not enough data to assess a severity.
                        }
                    },
                    "creation_date": \<_integer_> extracted when possible from the file's metadata. Indicates when it was built or compiled. It can also be faked by malware creators. UTC timestamp.
                    "last_analysis_date": \<_integer_> timestamp of the last time the threat severity was calculated.
                    "last_analysis_stats":\ <_dictionary_> a summary of the latest scan results.
                    {
                        "malicious": \<_integer_> the number of AV engines detecting the IoC as malicious.
                        "suspicious": \<_integer_> the number of AV engines detecting the IoC as suspicious.
                        "harmless": \<_integer_> the number of AV engines detecting the IoC as harmless.
                        "undetected": \<_integer_> the number of AV engines returning undetected verdict.
                    },
                    "last_modification_date": \<_integer_> date when any of the file's information was last updated. UTC timestamp.
                    "last_submission_date": \<_integer_> most recent date the file was posted to Google TI. UTC timestamp.
                    "first_submission_date": \<_integer_> date when the file was first seen in Google TI. UTC timestamp.
                    "md5": \<_strings_> file's MD5 hash.
                    "meaningful_name": \<_strings_> the most interesting name out of all file's names.
                    "names": \<_list of strings_> list of names with which the file was submitted to Google TI.
                    "positives": \<_integer_> number of AV detections.
                    "tags": \<_list of strings_> list of tags associated with the IoC.
                    "times_submitted": \<_integer_> number of times the IoC was submitted to Google TI.
                    "type_tags": \<_list of strings_> list of type-related tags associated with the IoC.
                    "vhash": \<_strings_> in-house similarity clustering algorithm value, based on a simple structural feature hash, allows you to find similar files.
                },
                "relationships": \<_dictionary_> other objects with which the IoC is related - associations with other objects.
                {
                    "malware_families": 
                    {
                        "data": <_list of dictionaries_> list of malware families associated with the IoC.
                        [
                            {
                                "id": \<_strings_> identifier of the associated malmare family. This identifier can be used to retrieve the complete malware family data.
                                "type": "collection",
                                "attributes": \<_dictionary_> attributes of the associated malware family.
                                {
                                    "name": \<_strings_> name of the malware family.
                                    "collection_type": "malware-family"
                                }
                            }
                        ]
                    },
                    "reports":
                    {
                        "data": <_list of dictionaries_> list of reports associated with the IoC.
                        [
                            {
                                "id": \<_strings_> identifier of the associated report. This identifier can be used to retrieve the complete report data.
                                "type": "collection",
                                "attributes": \<_dictionary_> attributes of the associated report.
                                {
                                    "name": \<_strings_> name of the report.
                                    "collection_type": "report"
                                }
                            }
                        ]
                    },
                    "threat_actors":
                    {
                        "data": <_list of dictionaries_> list of threat actors associated with the IoC.
                        [
                            {
                                "id": \<_strings_> identifier of the associated threat actor. This identifier can be used to retrieve the complete threat actor data.
                                "type": "collection",
                                "attributes": \<_dictionary_> attributes of the associated threat actor.
                                {
                                    "name": \<_strings_> name of the threat actor.
                                    "collection_type": "threat-actor"
                                }
                            }
                        ]
                    },
                    "campaigns":
                    {
                        "data": <_list of dictionaries_> list of campaigns associated with the IoC.
                        [
                            {
                                "id": \<_strings_> identifier of the associated campaign. This identifier can be used to retrieve the complete campaign data.
                                "type": "collection",
                                "attributes": \<_dictionary_> attributes of the associated campaign.
                                {
                                    "name": \<_strings_> name of the campaign.
                                    "collection_type": "campaign"
                                }
                            }
                        ]
                    }
                }
            }
        },
        {
            "data":
            {
                "type": "ip_address",
                "id": \<_string_> IP address. This identifier can be used to retrieve the complete IoC report.
                "attributes":
                {
                    "gti_assessment": \<_dictionary_> _(as above)_ shows the Google TI calculated Threat Assessment of the IoC, split by numerical threat score, associated severity and the global verdict.
                    "asn": \<_integer_> autonomous System Number to which the IP belongs.
                    "as_owner": \<_string_> owner of the Autonomous System to which the IP belongs.
                    "continent": \<_string_> continent where the IP is placed (ISO-3166 continent code).
                    "country": \<_string_> country where the IP is placed (ISO-3166 country code).
                    "last_analysis_stats": \<_dictionary_> _(as above)_ a summary of the latest scan results.
                    "last_modification_date": \<_integer_> date when any of the IP's information was last updated. UTC timestamp.
                    "jarm": \<_string_> IP address' JARM hash.
                    "network": \<_string_> IPv4 network range to which the IP belongs.
                    "positives": \<_integer_> number of AV detections.
                    "regional_internet_registry": \<_string_> RIR (one of the current RIRs: AFRINIC, ARIN, APNIC, LACNIC or RIPE NCC).
                    "tags": \<_list of strings_> list of tags associated with the IoC.
                },
                "relationships": \<_dictionary_> _(as above)_ other objects with which the IoC is related - associations with other objects.
            }
        },
        {
            "data":
            {
                "type": "url",
                "id": \<_string_> URL hash identifier. This identifier can be used to retrieve the complete IoC report.
                "attributes":
                {
                    "gti_assessment": \<_dictionary_> _(as above)_ shows the Google TI calculated Threat Assessment of the IoC, split by numerical threat score, associated severity and the global verdict.
                    "categories": \<_list of strings_> list of URL categories from security partners.
                    "first_submission_date": \<_integer_> date when the URL was first seen in Google TI. UTC timestamp.
                    "last_analysis_date": \<_integer_> timestamp of the last time the threat severity was calculated.
                    "last_analysis_stats": \<_dictionary_> _(as above)_ a summary of the latest scan results.
                    "last_final_url": \<_string_> if the original URL redirects, where does it end.
                    "last_http_response_code": \<_integer_> HTTP response code of the last response.
                    "last_modification_date": \<_integer_> date when any of the URL's information was last updated. UTC timestamp.
                    "last_submission_date": \<_integer_> most recent date the URL was posted to Google TI. UTC timestamp.
                    "outgoing_links": \<_list of strings_> list of links to different domains.
                    "positives": \<_integer_> number of AV detections.
                    "tags": \<_list of strings_> list of tags associated with the IoC.
                    "title": \<_string_> webpage title.
                    "times_submitted": \<_integer_> number of times the IoC was submitted to Google TI.
                    "tld": \<_string_> URL's top-level domain.
                    "url": \<_string_> original URL to be scanned.
                },
                "relationships": \<_dictionary_> _(as above)_ other objects with which the IoC is related - associations with other objects.
            }
        },
        {
            "data":
            {
                "type": "domain",
                "id": \<_string_> domain name. This identifier can be used to retrieve the complete IoC report.
                "attributes":
                {
                    "gti_assessment": \<_dictionary_> _(as above)_ shows the Google TI calculated Threat Assessment of the IoC, split by numerical threat score, associated severity and the global verdict.
                    "categories": \<_list of strings_> list of domain categories from security partners.
                    "creation_date": \<_integer_> creation date extracted from the Domain's whois (UTC timestamp).
                    "jarm": \<_string_> domain's JARM hash.
                    "last_analysis_stats": \<_dictionary_> _(as above)_ a summary of the latest scan results.
                    "last_modification_date": \<_integer_> date when any of the domain's information was last updated. UTC timestamp.
                    "positives": \<_integer_> number of AV detections.
                    "tags": \<_list of strings_> list of tags associated with the IoC.
                    "tld": \<_string_> domain's top-level domain.
                },
                "relationships": \<_dictionary_> _(as above)_ other objects with which the IoC is related - associations with other objects.
            }
        },
    ]
}

Example response

{
    "iocs":
    [
        {
            "data":
            {
                "type": "file",
                "id": "92293befae5fa3cc80d1beab93993b254742072879b296f89e9039bdb7a4edf4",
                "attributes":
                {
                    "gti_assessment":
                    {
                        "verdict":
                        {
                            "value": "VERDICT_MALICIOUS"
                        },
                        "threat_score":
                        {
                            "value": 30
                        },
                        "severity":
                        {
                            "value": "SEVERITY_LOW"
                        }
                    },
                    "creation_date": 1675657023,
                    "last_analysis_date": 1739966526,
                    "last_analysis_stats":
                    {
                        "malicious": 62,
                        "undetected": 11,
                        "typeUnsupported": 4
                    },
                    "last_modification_date": 1739973772,
                    "last_submission_date": 1691346962,
                    "md5": "7e51245673d182bcf760ca81e3b848e6",
                    "meaningful_name": "sqhost.exe",
                    "names":
                    [
                        "92293befae5fa3cc80d1beab93993b254742072879b296f89e9039bdb7a4edf4exe.exe",
                        "7e51245673d182bcf760ca81e3b848e6.virus",
                        "sqhost.exe"
                    ],
                    "positives": 62,
                    "tags":
                    [
                        "upx",
                        "peexe",
                        "overlay",
                        "spreader"
                    ],
                    "times_submitted": 3,
                    "type_tags":
                    [
                        "win32",
                        "executable",
                        "windows",
                        "pe",
                        "peexe"
                    ],
                    "vhash": "02503e0f7d1013z13z47z101013z13z15z17z"
                },
                "relationships":
                {
                    "malware_families":
                    {
                        "data":
                        [
                            {
                                "id": "malpedia_win_prometei",
                                "type": "collection",
                                "attributes":
                                {
                                    "name": "prometei",
                                    "collection_type": "malware-family"
                                }
                            }
                        ]
                    }
                }
            }
        }
    ]
}

In CSV format, elements belonging to a list such as threat_actors.ids, names, malware_families.names, threat_actors.names, type_tags, tags, malware_families.ids are plit by ;.

gti_severity,creation_date,positives,type,last_analysis_date,first_submission_date,gti_threat_score,threat_actors.ids,names,malware_families.names,meaningful_name,vhash,threat_actors.names,last_submission_date,type_tags,gti_verdict,md5,tags,id,last_modification_date,times_submitted,malware_families.ids

last_http_response_code,last_submission_date,malware_families.ids,url,threat_actors.ids,malware_families.names,times_submitted,tld,gti_verdict,type,last_analysis_date,gti_threat_score,first_submission_date,last_modification_date,id,threat_actors.names,positives,gti_severity,categories
```csv

```csv-domain
gti_verdict,creation_date,type,gti_threat_score,gti_severity,positives,tld,id,jarm,threat_actors.names,last_modification_date,reports.names,reports.ids,malware_families.ids,malware_families.names,threat_actors.ids

continent,country,positives,threat_actors.names,malware_families.names,gti_verdict,network,last_modification_date,malware_families.ids,gti_threat_score,gti_severity,threat_actors.ids,regional_internet_registry,type,id

In MISP format we provide the list of IoCs identifiers without additional information.

{
  "type": "bundle",
  "id": "bundle--0b7af7f4-d710-5fa2-a7da-a1663508c42c",
  "objects": [
    [...]
  ]
}

{
  "sourcesystem": "Google Threat Intelligence",
  "indicators": [
    [...]
  ]
}

Examples

From the Cryptominers Threat List dated February 19, 2025 at 13:00 hours, get 5 files that are associated with a malware family, have 5 or more AV detections and have a Google TI Score of 2 or higher.

import requests
import urllib

threat_list_id = "cryptominer"
time = "2025021913"
limit = 5
ioc_type = "file"
query = 'has:malware_families positives:5+ gti_score:2+'

url = f'https://www.virustotal.com/api/v3/threat_lists/{threat_list_id}/{time}?type={ioc_type}&limit={limit}&query={urllib.parse.quote(query)}'
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)
print(response.text)

From the Malware Threat List dated February 19, 2025 at 13:00 hours, get the entire list of files that have associated malware families, campaigns and threat actors, and export them in CSV format.

import requests
import urllib

threat_list_id = "malware"
time = "2025021913"
ioc_type = "file"
format = "csv"
query = 'has:malware_families has:campaigns has:threat_actors'

url = f'https://www.virustotal.com/api/v3/threat_lists/{threat_list_id}/{time}?type={ioc_type}&format={format}&query={urllib.parse.quote(query)}'
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)
print(response.text)

From the Threat Actor Threat List dated February 20, 2025 at 08:00 hours, get all URLs in STIX format.

import requests

threat_list_id = "threat-actor"
time = "2025022008"
ioc_type = "url"
format = "stix"

url = f'https://www.virustotal.com/api/v3/threat_lists/{threat_list_id}/{time}?type={ioc_type}&format={format}'
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)
print(response.text)

From the Daily TopTrending Threat List dated February 20, 2025 at 08:00 hours, get all domains in MISP format.

import requests

threat_list_id = "trending"
time = "2025022008"
ioc_type = "domain"
format = "misp"

url = f'https://www.virustotal.com/api/v3/threat_lists/{threat_list_id}/{time}?type={ioc_type}&format={format}'
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)
print(response.text)

From the Phishing Threat List dated February 20, 2025 at 08:00 hours, get all IP addresses in JSON format.

import requests

threat_list_id = "phishing"
time = "2025022008"
ioc_type = "ip_address"

url = f'https://www.virustotal.com/api/v3/threat_lists/{threat_list_id}/{time}?type={ioc_type}'
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)
print(response.text)

From the Cryptominers Threat List dated February 20, 2025 at 08:00 hours, get latest network related IoCs in STIX Sentinel format.

import requests

threat_list_id = "cryptominer"
time = "2025022008"
ioc_type = "ip_address,url,domain"
format = "stix-sentinel"

url = f'https://www.virustotal.com/api/v3/threat_lists/{threat_list_id}/{time}?type={ioc_type}&format={format}'
headers = {"accept": "application/json","x-apikey": <api-key>}

response = requests.get(url, headers=headers)
print(response.text)
Language
Click Try It! to start a request and see the response here!