--- updatedAt: 2026-06-17T15:03:35.000Z agentTools: projectIndex: https://gtidocs.readme.io/llms.txt --- # Get recommendations of a Threat Profile This endpoint returns the list of objects associated to a certain [Threat Profile](https://gtidocs.readme.io/reference/threat-profile-object). Each of these objects has one of the following types types: [Threat Actors](https://gtidocs.readme.io/reference/threat-actor-object), [Malware Families](https://gtidocs.readme.io/reference/malware-family-object), [Software or Toolkits](https://gtidocs.readme.io/reference/software-toolkit-object), [Campaigns](https://gtidocs.readme.io/reference/campaign-object), [IoC Collections](https://gtidocs.readme.io/reference/ioc-collection-object), [Reports](https://gtidocs.readme.io/reference/report-object) and [Vulnerabilities](https://gtidocs.readme.io/reference/vulnerability-object). We can distinguish between two other types of objects based on how they were associated with the Threat Profile: * **Recommended** objects are **automatically suggested** or assigned to a Threat Profile based on its configured [**interests**](https://gtidocs.readme.io/reference/create-threat-profile) such as the targeted industries, target regions, source regions, malware roles and actor motivations to recommend the most relevant threats. These objects are identified by the presence of `"source": "SOURCE_RECOMMENDATION"` within the `"context_attributes"` JSON response parameter below. * **Observed** objects are automatically added to a Threat Profile once a connector is setup by your Admin. Observed denotes a threat that has been associated with a malicious observable within your environment. These objects are identified by `"source": "SOURCE_OBSERVED_THREAT"` and your environment, ex: `“observed_threat_sources”: [“OBSERVED_THREAT_SOURCE_SPLUNK”]`. JSON response parameter below. * **Added** objects are assigned or [**added by users**](https://gtidocs.readme.io/reference/add-threat-profile-recommendations) to a Threat Profile, when users find other relevant threats not automatically recommended by our system. These objects are identified by the presence of `"source": "SOURCE_DIRECT_FOLLOW"` within the `"context_attributes"` JSON response parameter below. Example of parameters that will appear next to each threat object (or object descriptor) to inform on how they were associated to the Threat Profile: ```json Automatically recommended by the system "context_attributes": { "source": "SOURCE_RECOMMENDATION", "reason": { "interests": "<_list of dictionaries_> list of the reasons or interests that have been matched to produced the recommendation." [ { "type": "<_string_> type of the interest that produced a match. Existing options: INTEREST_TYPE_TARGETED_INDUSTRY - referes to the Threat Profile's configured targeted industry INTEREST_TYPE_TARGETED_REGION - referes to the Threat Profile's configured targeted region INTEREST_TYPE_SOURCE_REGION - referes to the Threat Profile's configured source region INTEREST_TYPE_MALWARE_ROLE - referes to the Threat Profile's configured malware role INTEREST_TYPE_ACTOR_MOTIVATION - referes to the Threat Profile's configured Threat Actor motivation.", "value": "<_string_> value of the interest that produced a match." } ] }, "recommendation_relevance": "<_integer_> represents the relevance of the recommendation. The highest relevance goes to 1." } ``` ```json From third-party integrations "context_attributes": { "source": "SOURCE_OBSERVED_THREAT", "reason": { "interests": [ { "type": "INTEREST_TYPE_ACTOR_MOTIVATION", "value": "Financial Gain" }, { "type": "INTEREST_TYPE_TARGETED_INDUSTRY", "value": "Financial Services" } ] }, "recommendation_relevance": 0.5331387730792139, "observed_threat_sources": [ "OBSERVED_THREAT_SOURCE_SPLUNK" ], "shared_with_me": false, "role": "viewer" } ``` ```json Added by user "context_attributes": { "source": "SOURCE_DIRECT_FOLLOW" } ``` ## Filters Available filters for objects associated to a certain Threat Profile: * `recommendation_source`: to get only recommendations automatically generated by our ML (`SOURCE_RECOMMENDATION`), only those specifically added by a user (`SOURCE_DIRECT_FOLLOW`), or only those specifically observed from your environment/connector (`SOURCE_OBSERVED_THREAT`). Ex: `recommendation_source:SOURCE_DIRECT_FOLLOW` * `collection_type`: to get only objects of a certain type (`threat-actor`, `malware-family`, `software-toolkit`, `campaign`, `collection` - for IoC Collections, `report`, `vulnerability`). Ex: `collection_type:threat-actor`, `collection_type:collection`, `collection_type:report`. * `targeted_region`: to filter objects by the region targeted by a threat or malicious activity. The region in ISO 3166 code format. Ex: `targeted_region:RU`, `targeted_region:US`, `targeted_region:ES`. * `source_region`: to filter objects by the region from which the threats are known to originate. The region in ISO 3166 code format. Ex: `source_region:RU`, `source_region:US`, `source_region:ES`. * `targeted_industry`: to filter objects by the targeted industry. Ex: `targeted_industry:'Online marketplace'`, `targeted_industry:'Oil and Gas'`, `targeted_industry:Arts` * `targeted_industry_group`: to filter objects by the targeted industry group (`Aerospace & Defense`, `Agriculture`, `Automotive`, `Chemicals & Materials`, `Civil Society & Non-Profits`, `Construction & Engineering`, `Education`, `Energy & Utilities`, `Financial Services`, `Government`, `Healthcare`, `Hospitality`, `Insurance`, `Legal & Professional Services`, `Manufacturing`, `Media & Entertainment`, `Multi-sector`, `Oil & Gas`, `Other`, `Pharmaceuticals`, `Retail`, `Technology`, `Telecommunications`, `Transportation`, `Unknown`). Ex: `targeted_industry_group:Manufacturing`, `targeted_industry_group:'Media & Entertainment'`. * `origin`: to filter objects by the origin or who has created them (`partner`, `crowdsourced`, `'Google Threat Intelligence'`), and list only those curated by our team or our parteners, or to list crowdsourced objects only. Ex: `origin:'Google Threat Intelligence'`, `origin:crowdsourced`. * `creation_date`: to filter objects by their creation date (`YYYY-MM-DD+` - from date until now, `YYYY-MM-DD-` - previous to date, `YYYY-MM-DD` - exact day). Ex: `creation_date:2025-01-15+`, `creation_date:2025-03-01-`, `creation_date:2025-04-04`. * `last_modification_date`: to filter objects by their last modification date (`YYYY-MM-DD+` - from date until now, `YYYY-MM-DD-` - previous to date, `YYYY-MM-DD` - exact day). Ex: `last_modification_date:2025-01-15+`, `last_modification_date:2025-03-01-`, `last_modification_date:2025-04-04`. * `description`: to filter objects by relevant strings within their descriptions. If you use multiple strings in a sentence, enclose them in quotes. Ex: `description:reCAPTCHAs`, `description:"SHADOWLADDER.IDAT and DEERSTEALER"`. * `motivation`: to filter threat actors objects by their motivations (`Attack / Destruction`, `Espionage`, `Financial Gain`, `Hacktivism`, `Influence`, `Notoriety`, `Nuisance`, `Penetration Testing`, `Surveillance`, `Opportunistic`). Ex: `motivation:'Attack / Destruction'`, `motivation:Hacktivism`. * `capability`: to filter malware families objects by their capabilities. Ex: `capability:'Constructs mutex'`, `capability:'Delete files'`, `capability:'Hides windows'`, `capability:'Reads memory'`. * `operating_system`: to filter malware families and software or toolkits by their targeted opetrating systems (`linux`, `windows`, `mac`, `android`, `ios`, etc). Ex: `operating_system:ios`, `operating_system:android`, `operating_system:mac`. * `malware_role`: to filter malware families and software or toolkits by their roles (`Archiver`, `ATM Malware`, `Backdoor - Botnet`, `Backdoor - Webshell`, `Backdoor`, `Bootkit`, `Builder`, `Controller`, `Credential Stealer`, `Cryptocurrency Miner`, `Data Miner`, `Decoder`, `Disruption Tool`, `Downloader`, `Dropper - Memory Only`, `Dropper`, `Exploit Builder`, `Exploit`, `File Infector`, `Framework`, `Installer`, `Keylogger`, `Lateral Movement Tool`, `Launcher`, `Lightweight Backdoor`, `Module`, `Point-of-Sale Malware`, `Privilege Escalation Tool`, `Ransomware`, `Reconnaissance Tool`, `Remote Control and Administration Tool`, `Remote Exploitation Tool`, `Rootkit`, `Screen Capture Tool`, `Sniffer`, `Spambot`, `Tunneler`, `Uploader`, `Utility`). Ex: `malware_role:'Reconnaissance Tool'`, `malware_role:Ransomware`. * `merged_actor`: to filter large threat actor groups by confirmed threat actors as part of the larger one. Ex: `merged_actor:UNC1024`. ## Examples Get 10 objects associated to the Threat Profile 332e02da667746f180a9740e94a3ec98. ```python import requests profile_id = "332e02da667746f180a9740e94a3ec98" url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?limit=10" headers = {"accept": "application/json","x-apikey": } response = requests.get(url, headers=headers) ``` Get only automatically generated recommendations of the Threat Profile 332e02da667746f180a9740e94a3ec98. ```python import requests profile_id = "332e02da667746f180a9740e94a3ec98" filter = "recommendation_source:SOURCE_RECOMMENDATION" url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?filter={filter}" headers = {"accept": "application/json","x-apikey": } response = requests.get(url, headers=headers) ``` Get only objects added by users to the Threat Profile 332e02da667746f180a9740e94a3ec98. ```python import requests profile_id = "332e02da667746f180a9740e94a3ec98" filter = "recommendation_source:SOURCE_DIRECT_FOLLOW" url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?filter={filter}" headers = {"accept": "application/json","x-apikey": } response = requests.get(url, headers=headers) ``` Get only malware fammilies associated to the Threat Profile 332e02da667746f180a9740e94a3ec98. ```python import requests profile_id = "332e02da667746f180a9740e94a3ec98" filter = "collection_type:malware-family" url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?filter={filter}" headers = {"accept": "application/json","x-apikey": } response = requests.get(url, headers=headers) ``` Get only automatically generated recommendations of threat actors of the Threat Profile 332e02da667746f180a9740e94a3ec98. ```python import requests profile_id = "332e02da667746f180a9740e94a3ec98" filter = "recommendation_source:SOURCE_RECOMMENDATION AND collection_type:threat-actor" url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?filter={filter}" headers = {"accept": "application/json","x-apikey": } response = requests.get(url, headers=headers) ``` Get only vulnerabilities and campaingn associated to the Threat Profile 332e02da667746f180a9740e94a3ec98. ```python import requests profile_id = "332e02da667746f180a9740e94a3ec98" filter = "collection_type:report OR collection_type:vulnerability" url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/recommendations?filter={filter}" headers = {"accept": "application/json","x-apikey": } response = requests.get(url, headers=headers) ```
# OpenAPI definition ```json { "info": { "title": "Threat Landscape", "version": "3.0" }, "openapi": "3.1.0", "tags": [ { "name": "Threat Profiles" } ], "paths": { "/threat_profiles/{profile_id}/recommendations": { "get": { "tags": [ "Threat Profiles" ], "description": "", "operationId": "get-threat-profile-recommendations", "parameters": [ { "description": "Your API key", "in": "header", "name": "x-apikey", "required": true, "schema": { "type": "string" } }, { "description": "Threat Prfile's ID", "in": "path", "name": "profile_id", "required": true, "schema": { "type": "string" } }, { "description": "Maximum number of objects to retrieve (max 40)", "in": "query", "name": "limit", "schema": { "default": 10, "format": "int32", "type": "integer", "maximum": 40, "minimum": 0 } }, { "description": "Filter threats / objects by different properties", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "Continuation cursor", "in": "query", "name": "cursor", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Result": { "value": "{}" } }, "schema": { "properties": {}, "type": "object" } } }, "description": "200" }, "400": { "content": { "application/json": { "examples": { "Result": { "value": "{}" } }, "schema": { "properties": {}, "type": "object" } } }, "description": "400" } }, "security": [], "summary": "Get recommendations of a Threat Profile" } } }, "security": [], "servers": [ { "url": "https://www.virustotal.com/api/v3" } ], "x-readme": { "explorer-enabled": true, "headers": [], "proxy-enabled": false, "samples-enabled": true } } ```