# VirusTotal API v3 β Objects & Relationships Reference
This reference documents the main API object types, their key attributes, and relationship
mappings. Items marked π require enterprise access.
---
## Table of Contents
1. [Object Structure](#object-structure)
2. [File Object](#file-object)
3. [URL Object](#url-object)
4. [Domain Object](#domain-object)
5. [IP Address Object](#ip-address-object)
6. [Comment Object](#comment-object)
7. [Analysis Object](#analysis-object)
8. [File Behaviour Object](#file-behaviour-object)
9. [Graph Object](#graph-object)
10. [Hunting Objects](#hunting-objects)
11. [Other Objects](#other-objects)
12. [Relationship Access Matrix](#relationship-access-matrix)
---
## Object Structure
Every VT API object follows this pattern:
```json
{
"type": "<object_type>",
"id": "<unique_identifier>",
"links": {
"self": "https://www.virustotal.com/api/v3/<type>/<id>"
},
"attributes": { ... },
"relationships": { ... }
}
```
Relationships are not included by default. Request them explicitly:
```
GET /api/v3/files/{id}?relationships=contacted_domains,dropped_files
```
Or fetch them separately:
```
GET /api/v3/files/{id}/contacted_domains
```
---
## File Object
**Type:** `file`
**ID:** SHA-256 hash
### Key attributes
| Attribute | Description |
|-----------|-------------|
| `sha256`, `sha1`, `md5` | File hashes |
| `size` | File size in bytes |
| `type_description` | Human-readable file type |
| `type_tag` | Short type tag (e.g., `peexe`, `pdf`, `doc`) |
| `meaningful_name` | Most meaningful filename from submissions |
| `names` | All known filenames |
| `tags` | Auto-generated tags |
| `creation_date` | File creation timestamp |
| `first_submission_date` | When first submitted to VT |
| `last_submission_date` | When last submitted |
| `last_analysis_date` | When last analyzed |
| `last_analysis_stats` | Detection summary counts |
| `last_analysis_results` | Per-engine results |
| `reputation` | Community reputation score |
| `total_votes` | Vote counts (harmless/malicious) |
| `popular_threat_classification` | Categorized threat type |
| `sigma_analysis_stats` | Sigma rule match statistics |
| `sigma_analysis_results` | Sigma rule matches |
| `crowdsourced_yara_results` | YARA rule matches |
| `crowdsourced_ids_results` | IDS (Snort/Suricata) results |
| `sandbox_verdicts` | Sandbox detection verdicts |
| `pe_info` | PE header information (for executables) |
| `elf_info` | ELF header information (for Linux binaries) |
| `macho_info` | Mach-O information (for macOS binaries) |
| `pdf_info` | PDF structure information |
| `androguard` | Android APK analysis |
| `signature_info` | Digital signature details |
| `ssdeep`, `tlsh`, `telfhash` | Fuzzy hashes for similarity matching |
| `detectiteasy` | Detect-It-Easy packer/compiler identification |
| `magic` | File magic string |
| π `exiftool` | ExifTool metadata |
| π `malware_config` | Extracted malware configuration |
| π `office_info` | Office document details |
| π `openxml_info` | OpenXML document details |
| π `rtf_info` | RTF document details |
### File relationships
**Free access:**
- `behaviours` β Sandbox behavior reports
- `bundled_files` β Files inside archives/bundles
- `collections` β VT collections containing this file
- `comments` β Community comments
- `contacted_domains` β Domains contacted in sandbox
- `contacted_ips` β IPs contacted in sandbox
- `contacted_urls` β URLs contacted in sandbox
- `dropped_files` β Files dropped during execution
- `execution_parents` β Files that spawned this file
- `graphs` β VT Graph references
- `pe_resource_children` / `pe_resource_parents` β PE resource links
- `sigma_analysis` β Sigma rule analysis
- `memory_pattern_domains` / `memory_pattern_ips` / `memory_pattern_urls` β Memory-extracted IOCs
- `votes` β Community votes
**π Enterprise only:**
- `analyses` β Submission analyses history
- `carbonblack_children` / `carbonblack_parents` β Carbon Black telemetry
- `compressed_parents` β Archives containing this file
- `email_attachments` / `email_parents` β Email relationships
- `embedded_domains` / `embedded_ips` / `embedded_urls` β Statically embedded IOCs
- `itw_domains` / `itw_ips` / `itw_urls` β In-the-wild distribution infrastructure
- `overlay_children` / `overlay_parents` β PE overlay relationships
- `pcap_children` / `pcap_parents` β PCAP relationships
- `related_references` β Threat intelligence references
- `related_threat_actors` β Associated threat actors
- `screenshots` β Sandbox execution screenshots
- `similar_files` β Structurally similar files
- `submissions` β Submission history with metadata
- `urls_for_embedded_js` β URLs hosting embedded JavaScript
---
## URL Object
**Type:** `url`
**ID:** Base64url-encoded URL (no padding)
### Key attributes
| Attribute | Description |
|-----------|-------------|
| `url` | The actual URL string |
| `last_http_response_content_length` | Response size |
| `last_http_response_content_sha256` | SHA-256 of response body |
| `last_http_response_code` | HTTP status code |
| `last_analysis_stats` | Detection summary |
| `last_analysis_results` | Per-engine results |
| `last_analysis_date` | When last analyzed |
| `reputation` | Community reputation score |
| `total_votes` | Vote counts |
| `tags` | Auto-generated tags |
| `categories` | Categorization by various vendors |
| `title` | Page title |
| `html_meta` | HTML meta tags |
| `trackers` | Detected tracking technologies |
| `last_final_url` | URL after redirects |
---
## Domain Object
**Type:** `domain`
**ID:** Domain name string
### Key attributes
| Attribute | Description |
|-----------|-------------|
| `last_analysis_stats` | Detection summary |
| `last_analysis_results` | Per-engine results |
| `registrar` | Domain registrar |
| `creation_date` | Domain registration date |
| `last_dns_records` | Current DNS records |
| `last_https_certificate` | Current SSL certificate |
| `popularity_ranks` | Rankings from various services |
| `categories` | Categorization by vendors |
| `whois` | WHOIS data |
| `reputation` | Community reputation |
| `total_votes` | Vote counts |
| `tags` | Auto-generated tags |
---
## IP Address Object
**Type:** `ip_address`
**ID:** IP address string
### Key attributes
| Attribute | Description |
|-----------|-------------|
| `last_analysis_stats` | Detection summary |
| `last_analysis_results` | Per-engine results |
| `asn` | Autonomous System Number |
| `as_owner` | AS owner name |
| `country` | Country code |
| `continent` | Continent code |
| `network` | CIDR network |
| `regional_internet_registry` | RIR (ARIN, RIPE, etc.) |
| `last_https_certificate` | Current SSL cert |
| `whois` | WHOIS data |
| `reputation` | Community reputation |
| `total_votes` | Vote counts |
| `tags` | Auto-generated tags |
---
## Comment Object
**Type:** `comment`
**ID:** Comment ID string
### Key attributes
- `text` β Comment body (supports VT's hashtag and IoC linking syntax)
- `date` β Creation timestamp
- `votes` β Vote counts on the comment
- `html` β Rendered HTML version
### Relationships
- `author` β User who wrote the comment
---
## Analysis Object
**Type:** `analysis`
**ID:** Analysis ID (returned by scan/rescan endpoints)
### Key attributes
- `status` β `queued`, `in-progress`, or `completed`
- `stats` β Detection count summary (when completed)
- `results` β Per-engine results (when completed)
- `date` β Analysis timestamp
### Relationships
- `item` β The file or URL that was analyzed
---
## File Behaviour Object
**Type:** `file_behaviour`
### Key attributes
- `sandbox_name` β Name of the sandbox that produced the report
- `analysis_date` β When the analysis was performed
- `tags` β Behavior tags
- `verdicts` β Sandbox verdicts
- `dns_lookups` β DNS queries made
- `http_conversations` β HTTP request/response pairs
- `ip_traffic` β Network traffic to IPs
- `processes_tree` β Process execution tree
- `files_dropped` β Files created during execution
- `files_copied` β Files copied
- `files_opened` / `files_written` / `files_deleted` β File system activity
- `registry_keys_opened` / `registry_keys_set` / `registry_keys_deleted` β Registry activity
- `mutexes_created` / `mutexes_opened` β Synchronization primitives
- `command_executions` β Commands executed
- `modules_loaded` β DLLs/modules loaded
- `services_created` / `services_started` β Windows services
- `permissions_checked` β Android permissions
- `sms_sent` β SMS messages (Android)
### Relationships
- `file` β The analyzed file
- `attack_techniques` β MITRE ATT&CK techniques observed
---
## Graph Object
**Type:** `graph`
**ID:** Graph ID string
### Key attributes
- `graph_data` β JSON structure of nodes and links
- `label` β Graph name
- `owner` β Creator user ID
### Relationships
- `comments`, `editors`, `group`, `items`, `owner`, `viewers`
---
## Hunting Objects
### Hunting Ruleset (π)
- `type: "hunting_ruleset"`
- Attributes: `name`, `enabled`, `rules` (YARA source), `limit`, `match_object_type`
- Relationships: `owner`, `editors`, `viewers`, `hunting_notification_files`
### Hunting Notification (π)
- `type: "hunting_notification"`
- Attributes: `date`, `source_key`, `rule_name`, `tags`
### Retrohunt Job (π)
- `type: "retrohunt_job"`
- Attributes: `rules`, `status`, `progress`, `scanned_bytes`, `matching_files`
- Relationships: `matching_files`, `owner`
---
## Other Objects
| Object | Type | Description |
|--------|------|-------------|
| Resolution | `resolution` | DNS resolution record (domain β IP) |
| SSL Certificate | `ssl_certificate` | TLS/SSL certificate details |
| Submission | `submission` | File/URL submission metadata |
| Whois | `whois` | Historical WHOIS records |
| Sigma Rule | `sigma_rule` | Sigma detection rule |
| YARA Rule | `yara_rule` | YARA detection rule |
| YARA Ruleset | `yara_ruleset` | Collection of YARA rules |
| Vote | `vote` | Community vote (malicious/harmless) |
| Operation | `operation` | Async operation status |
| π Private File | `private_file` | Privately scanned file |
| π Private Analysis | `private_analysis` | Private scan result |
| π Activity Log | `activity_log` | Audit log entry |
| π Service Account | `service_account` | Programmatic access account |
---
## Relationship Access Matrix
This matrix shows which relationship types are available at each tier for the four main
object types.
### Legend
- β
Free β available with public API key
- π Enterprise β requires premium API key
- π§βπ» Authenticated β requires any API key with appropriate user context
### File relationships
| Relationship | Access |
|-------------|--------|
| behaviours | β
|
| bundled_files | β
|
| collections | β
|
| comments | β
|
| contacted_domains | β
|
| contacted_ips | β
|
| contacted_urls | β
|
| dropped_files | β
|
| execution_parents | β
|
| graphs | β
|
| pe_resource_children | β
|
| pe_resource_parents | β
|
| sigma_analysis | β
|
| memory_pattern_domains | β
|
| memory_pattern_ips | β
|
| memory_pattern_urls | β
|
| user_votes | π§βπ» |
| votes | β
|
| analyses | π |
| carbonblack_children | π |
| carbonblack_parents | π |
| compressed_parents | π |
| email_attachments | π |
| email_parents | π |
| embedded_domains | π |
| embedded_ips | π |
| embedded_urls | π |
| itw_domains | π |
| itw_ips | π |
| itw_urls | π |
| overlay_children | π |
| overlay_parents | π |
| pcap_children | π |
| pcap_parents | π |
| related_references | π |
| related_threat_actors | π |
| screenshots | π |
| similar_files | π |
| submissions | π |
| urls_for_embedded_js | π |
### Domain relationships
| Relationship | Access |
|-------------|--------|
| collections | β
|
| comments | β
|
| communicating_files | β
|
| graphs | β
|
| historical_ssl_certificates | β
|
| historical_whois | β
|
| immediate_parent | β
|
| parent | β
|
| referrer_files | β
|
| related_comments | β
|
| resolutions | β
|
| siblings | β
|
| subdomains | β
|
| user_votes | π§βπ» |
| votes | β
|
| caa_records | π |
| cname_records | π |
| downloaded_files | π |
| mx_records | π |
| ns_records | π |
| related_references | π |
| related_threat_actors | π |
| soa_records | π |
| urls | π |
### IP Address relationships
| Relationship | Access |
|-------------|--------|
| collections | β
|
| comments | β
|
| communicating_files | β
|
| graphs | β
|
| historical_ssl_certificates | β
|
| historical_whois | β
|
| related_comments | β
|
| referrer_files | β
|
| resolutions | β
|
| user_votes | π§βπ» |
| votes | β
|
| downloaded_files | π |
| related_references | π |
| related_threat_actors | π |
| urls | π |
### URL relationships
| Relationship | Access |
|-------------|--------|
| collections | β
|
| comments | β
|
| graphs | β
|
| last_serving_ip_address | β
|
| network_location | β
|
| related_comments | β
|
| user_votes | π§βπ» |
| votes | β
|
| analyses | π |
| communicating_files | π |
| contacted_domains | π |
| contacted_ips | π |
| downloaded_files | π |
| embedded_js_files | π |
| redirecting_urls | π |
| redirects_to | π |
| referrer_files | π |
| referrer_urls | π |
| related_references | π |
| related_threat_actors | π |
| submissions | π |
| urls_related_by_tracker_id | π |