---
name: virustotal-api-v3-ingestion
description: "How to get VirusTotal Public API v3 data into a pandas DataFrame and Parquet: access, the request, the format, limits, quirks and terms."
---

# Load a VirusTotal IP report into pandas and Parquet

Source entry: https://signal-lab-jet.vercel.app/datasets/virustotal-api-v3
Provider: https://docs.virustotal.com/reference/overview
Checked against the provider's documentation: 2026-11-01

## Access
- Create a free VirusTotal Community account and store its API key in VIRUSTOTAL_API_KEY.
- This example requests metadata for a well-known public resolver and does not upload or download any file.

## Request
```bash
curl -H "x-apikey: $VIRUSTOTAL_API_KEY" 'https://www.virustotal.com/api/v3/ip_addresses/1.1.1.1'
```

## Format
JSON:API object with an IP identifier and nested attributes such as analysis statistics, reputation, regional registry, ASN, country, network and analysis timestamps.

## Load into pandas and Parquet
Needs Python 3 with requests, pandas and pyarrow.
```python
"""VirusTotal public IP report -> pandas -> Parquet. Requires VIRUSTOTAL_API_KEY."""
import os
import requests
import pandas as pd

URL = "https://www.virustotal.com/api/v3/ip_addresses/1.1.1.1"
headers = {"x-apikey": os.environ["VIRUSTOTAL_API_KEY"]}
r = requests.get(URL, headers=headers, timeout=30)
r.raise_for_status()
obj = r.json()["data"]
row = {"id": obj["id"], "type": obj["type"], **obj.get("attributes", {})}
df = pd.json_normalize([row], sep=".")
df.to_parquet("virustotal_ip_1_1_1_1.parquet", index=False)
print(len(df), "IP report", df.loc[0, "id"], "columns", len(df.columns))
```
Not run: it needs a free API key.

## Limits
- Public API limit: 4 requests per minute and 500 requests per day.
- Public API use is non-commercial or academic and has no SLA.
- Advanced search, sandbox data and additional context require Premium access.

## Quirks
- Any IOC submitted or queried may be scanned and added to the community dataset; never send confidential, sensitive or personally identifiable indicators.
- Analysis counters aggregate engines that can disagree or update at different times; preserve the last_analysis_date where available.
- This workflow deliberately avoids every file-content and sample-download endpoint.

## Terms and attribution
- The Public API must not be used in commercial products or services.
- The Public API must not be used in business workflows that do not contribute new files.
- Do not register multiple accounts to evade quotas.
- Terms page: https://cloud.google.com/terms/secops

## Sources
- https://docs.virustotal.com/reference/public-vs-premium-api.md: "The Public API is limited to **500 requests per day and a rate of 4 requests per minute**."
- https://docs.virustotal.com/reference/public-vs-premium-api.md: "The Public API **must not** be used in commercial products or services."
- https://docs.virustotal.com/reference/authentication.md: "For authenticating with the API you must include the `x-apikey` header with your personal API key in all your requests."
- https://docs.virustotal.com/reference/ip-info.md: "Any IoC submitted or queried via the API will be scanned and added to the VirusTotal dataset, making it accessible to the community."

## Help improve this skill
Missing a source, or see something to improve? Call the MCP tool suggest_source or feedback (or POST /api/suggest or /api/feedback). Reviewed ideas: https://signal-lab-jet.vercel.app/agent-suggestions

Information for educational purposes only. Free tiers, limits and licenses belong to the providers and may change; check the provider's own terms before using the data.