🚧
Public Preview
Threat Profile module is provided as a public preview and is subject to change. Use with caution.

Use this endpoint to list a Threat Profile’s timeline associations, with following format:

{
    "data": /* <_list of dictionaries_> list of timeline associations. */
    [
        {
            "id": "<_string_> identifier of the timeline association.",
            "type": "timeline_event",
            "attributes": /* <_dictionary_> attributes of the timeline association. */
            {
                "event_type": "<_string_> the type of the timeline association such as Alias, Motivation, Malware, Actor, Toolkit, Report, Campaign, etc. Available values are listed in the Events filter section below.",
                "event_entity": "<_string_> the name or value of the timeline association like another alias of the main threat actor object associated with a threat profile, or the new motivation of the main threat actor object associated with a threat profile.",
                "first_seen": "<_integer_> Unix epoch UTC time (seconds) when the association between the object and the threat profile was made.",
                "last_seen": "<_integer_> Unix epoch UTC time (seconds) of most recent observed relationship between the object and the threat profile.",
                "name": "<_string_> name of the object directly associated with the threat profile.",
                "link": "<_string_> URL of the object directly associated with the threat profile."
            },
            "context_attributes":
            {
                "collection":
                {
                    "id": "<_string_> identifier of the object directly associated with the threat profile.",
                    "name": "<_string_> name of the object directly associated with the threat profile.",
                    "collection_type": "<_string_> type of the object directly associated with the threat profile.",
                    "origin": "Google Threat Intelligence"
                }
            },
            "links":
            {
                "self": "<_string_> URL to the timeline association."
            },
        },
    ]
}

Events filter

Available events for filtering a Threat Profile’s timeline associations:

Direct associations

Actor - Object associated with the Threat Profile
Campaign - Object associated with the Threat Profile
Malware - Object associated with the Threat Profile
Report - Object associated with the Threat Profile
Toolkit - Object associated with the Threat Profile
Vulnerability - Object associated with the Threat Profile

Indirect associations

Merged Actor - Subgroups of the Threat Profile's associated larger Actor groups.
Suspected Group - Subgroups that are suspected to belong to the Threat Profile's associated larger Actor groups.
Alias - Aleases of Actors associated with the Threat Profile
Available Exploit - Available Exploits for Vulnerabilities associated with the Threat Profile
Exploit State - Exploit State of Vulnerabilities associated with the Threat Profile
Vulnerability Score - Vulnerability Score of Vulnerabilities associated with the Threat Profile
Key Event - Key Events of Campaigns associated with the Threat Profile
Motivation - Motivations of threats associated with the Threat Profile
Source Region - Source Regions of threats associated with the Threat Profile
Targeted Region - Targeted Regions by threats associated with the Threat Profile
Targeted Industry - Targeted Industries by threats associated with the Threat Profile
Curated Rule - Curated Rules detecting malicious behaviours of threats associated with the Threat Profile
Hunting Ruleset - Hunting Ruleset detecting malicious behaviours of threats associated with the Threat Profile
TTP - TTPs of objects associated with the Threat Profile
X509 - X509 certificates related with threats associated with the Threat Profile

Several event types can be grouped together, separated only by commas (',').

Examples

Get the list of timeline events associated with Threat Profile 332e02da667746f180a9740e94a3ec98.

import requests

profile_id = "332e02da667746f180a9740e94a3ec98"

url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/timeline/associations"
headers = {
    "accept": "application/json","x-apikey": <api-key>
}
response = requests.get(url, headers=headers)

Get 5 timeline events associated with Threat Profile 332e02da667746f180a9740e94a3ec98 between 2024-01-01 and 2025-01-01 UTC.

import requests

profile_id = "332e02da667746f180a9740e94a3ec98"
limit = 5
later_than = 1704067200
before_than = 1735689600

url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/timeline/associations?limit={limit}&later_than={later_than}&before_than={before_than}"
headers = {
    "accept": "application/json","x-apikey": <api-key>
}
response = requests.get(url, headers=headers)

Get only Actor and Motivation timeline events associated with Threat Profile 332e02da667746f180a9740e94a3ec98.

import requests

profile_id = "332e02da667746f180a9740e94a3ec98"
events = "Actor,Motivation,Merged Actor"

url = f"https://www.virustotal.com/api/v3/threat_profiles/{profile_id}/timeline/associations?events={events}"
headers = {"accept": "application/json","x-apikey": <api-key>}

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