VirusTotal API Tutorial 2026: Automate IOC & Malware Analysis for SOC Analysts

VirusTotal (VT) is a Google/Chronicle-owned threat-intelligence service. When you submit a file hash, URL, domain or IP, VT returns the combined verdict of 70+ anti-malware engines plus sandbox behaviour, static properties, and a web of relationships — the other domains a file contacted, the files that dropped it, the IPs a domain resolved to. For a SOC analyst, that turns a lone, context-free indicator into an attributed story.

The modern interface is the v3 REST API. Every request is plain HTTPS with a single authentication header, x-apikey, and every response is a JSON object — a file, url, domain, ip_address or analysis. Learn the object model once and every endpoint behaves the same way. The legacy v2 API still answers but is deprecated; write all new tooling against v3.

Every v3 endpoint returns an object with a stable shape: a type, an id, a bag of attributes, and a set of relationships you can expand. Once you can read one object, you can read them all.

The single most useful attribute on a file, domain or ip_address object is last_analysis_stats — the counts of malicious, suspicious, undetected, harmless and timeout engines. That ratio (for example 52/72 malicious) is the number your automation keys off.

Create a free account at virustotal.com, then open your profile menu and choose API key. The key is a 64-character hex string tied to your account. Everything in this guide works on the free (Public) key; the premium tiers remove the rate limits and unlock Intelligence search, Retrohunt and Livehunt.

Store the key in an environment variable so it never lands in your shell history or a committed script. On Linux/macOS:

The free Public API is rate-limited and non-commercial. Design your tooling around the ceiling from day one — it is the single most common thing that breaks a VT script in production.

Pick whichever client matches your workflow. You do not need all three — but seeing the same lookup in CLI, Python and raw REST makes the object model click.

vt-cli is VirusTotal's official Go-based command-line client. It is a single static binary with no runtime dependencies, which makes it ideal for analyst workstations and CI runners alike.

Either run the interactive initialiser — which writes the key to ~/.vt.toml — or rely on the VTCLI_APIKEY environment variable you set earlier. The --apikey flag overrides both for one-off calls.

Full objects are huge. Use --include to pull only the attributes you need and --format json when you intend to pipe into jq. This also conserves nothing on quota (one lookup is one lookup) but it keeps your terminal readable.

vt-py is VirusTotal's official Python client. Always install it into a project virtual environment so its dependency pins never collide with your system Python.

The client reads objects with get_object() using the same path you would hit over REST. Read the key off the environment — never inline it.

On premium quota you will want concurrency. vt.Client doubles as an async context manager, exposing *_async() coroutines you can gather. (On the free tier the 4/min limit dominates, so keep it serial there.)

Any HTTP client works — the only requirement is the x-apikey header. This is what you reach for when debugging, or when integrating from a language without an official SDK.

A small enrichment microservice is the cleanest way to share VT access across a team without handing the key to everyone. Here is a complete Flask + vt-py service with a docker-compose.yml that keeps the key in an env file and caps the container.

The number everyone quotes — "52/72" — is last_analysis_stats.malicious over the total engines. But a serious triage reads more: first/last submission dates tell you whether this is a fresh sample or a years-old commodity, and reputation plus community votes flag known false positives.

For network indicators, the engine verdict matters less than the context: who owns the ASN, when the domain was registered (a day-old domain is a red flag), the current resolutions, and the HTTPS certificate. VT surfaces all of it on the object.

If a URL has never been seen, submit it for analysis. VT returns an analysis ID you poll until it is complete, then read the resulting URL object. vt-py wraps the whole dance in one call.

To analyse a file VT has never seen, upload it. vt-py streams the file and, with wait_for_completion=True, blocks until the multi-engine scan and sandbox run finish. Files over 32 MB need a special upload URL, which vt-py negotiates for you.

When you do not want to block, submit and poll. The analysis object carries a status of queued, in-progress or completed. Respect the rate limit while polling.

Relationships are what make VT an investigation tool rather than a lookup table. From a single dropper you can walk to the domains it contacted, the files it wrote, and the parent that delivered it — building out the campaign without touching the endpoint again.

Intelligence search (premium) lets you query the entire corpus with modifiers — file type, detection count, sandbox behaviour, import hash, submitter geography and dozens more. It is the difference between "tell me about this hash" and "show me every PE in the last week that beacons and is signed by this cert".

Retrohunt runs a YARA rule across VT's historic corpus (a rolling window of recent submissions). Write a rule that captures your threat's unique bytes, launch the job, and collect every matching sample VT has ever seen.

Livehunt keeps a YARA ruleset running against every new submission. When something matches — a new variant of your tracked family, a document abusing your brand — VT notifies you. It is the closest thing to a standing tripwire across the global malware stream.

The real-world task: take a CSV of hashes from quarantine or a hunt, enrich each against VT, and write a verdict column — without blowing the 4/min / 500-day free quota. The pattern is: cache locally, skip anything already known, sleep between calls, and handle the 404 for hashes VT has never seen.

Before you call VT, you need the list of indicators worth spending quota on. These queries pull distinct, recent file hashes from your telemetry so your enrichment job only touches what is new. Run the query, feed the output into enrich_hashes.py, and write the verdict back as a watchlist or lookup.

Wazuh ships a native VirusTotal integration that checks file hashes from its File Integrity Monitoring against VT and raises an alert on a hit. For everything else, a cron-driven enrichment job keeps your indicator store warm.

v3 returns a JSON error body with a machine-readable code alongside the HTTP status. Handle these explicitly — especially the difference between 429 (slow down) and a 404 (VT has never seen this indicator).

The VT API is a force multiplier, but the two mistakes that actually hurt organisations are uploading things they should not and treating a clean result as proof of safety. Internalise these before you point automation at it.

Primary documentation and official tooling used throughout this guide. Always defer to the current VT documentation for endpoint and quota changes.