VirusTotal Getting Started: Account, API Keys, First Scan (2026)

Getting started overview

Getting started with the VirusTotal API involves a sequence of steps to establish access and make initial requests. The primary mechanism for interacting with the API is through an API key, which authenticates requests and ensures adherence to usage policies. VirusTotal offers a Community API for non-commercial use, which provides access to many of its core functionalities, including file, URL, domain, and IP address analysis VirusTotal API reference overview. Premium services, which offer higher rate limits and advanced features, require custom enterprise agreements VirusTotal premium services.

The workflow for a new user typically includes registering a VirusTotal account, generating an API key, and then executing a first API call to test connectivity and functionality. This initial call often involves submitting a benign file or URL for analysis to understand the response structure and data returned by the service. Understanding HTTP methods like GET and POST is fundamental, as these are used for retrieving analysis reports and submitting items for scanning, respectively MDN HTTP request methods.

VirusTotal provides a comprehensive API reference that details endpoints, parameters, and response formats for various operations VirusTotal API documentation. While the platform does not offer official SDKs, the API is designed to be accessible via standard HTTP clients in any programming language. This flexibility allows developers to integrate VirusTotal's threat intelligence capabilities into diverse applications, ranging from automated security tools to incident response playbooks.

Quick reference table

Create an account and get keys

To use the VirusTotal API, you first need a VirusTotal account. For non-commercial use, a free Community API key is available, which is suitable for getting started and exploring the platform's capabilities VirusTotal account creation. This key is personal and should be kept confidential to prevent unauthorized usage.

1. Register an Account: Navigate to the VirusTotal registration page. Provide the required information, including an email address and a strong password. You may need to verify your email address to complete the registration process.
2. Access Your Profile: Once logged in, click on your username or avatar, typically located in the top-right corner of the VirusTotal web interface, to access your profile settings.
3. Locate API Key: Within your profile settings, there will be a section dedicated to your API key. The key is a hexadecimal string. Copy this key, as it will be required for every API request you make. The exact path to your API key, after logging in, is often directly at https://www.virustotal.com/gui/user/YOUR_USERNAME/apikey, where YOUR_USERNAME is replaced with your actual VirusTotal username VirusTotal API key location guidance.
4. Understand Usage Limits: Be aware of the rate limits associated with your API key. For the Community API, there are typically limits on the number of requests per minute and per day. Exceeding these limits can result in temporary blocks or errors. Premium API keys offer significantly higher rate limits and additional features VirusTotal API pricing tiers.

It is critical to handle your API key securely. Avoid hardcoding it directly into public repositories or client-side code. Instead, use environment variables or a secure configuration management system to store and access the key. This practice helps prevent unauthorized access to your API quota and data MDN environment variable security.

Your first request

After obtaining your API key, you can make your first request to the VirusTotal API. This example demonstrates scanning a URL. The API key is passed in the x-apikey header for authentication.

Example: Scan a URL

This request submits a URL to VirusTotal for analysis. The API responds with a unique id that can be used to retrieve the analysis report later.

curl --request POST \
  --url https://www.virustotal.com/api/v3/urls \
  --header 'x-apikey: YOUR_API_KEY' \
  --data 'url=https://www.example.com'

Replace YOUR_API_KEY with your actual VirusTotal API key. Also, modify https://www.example.com to the URL you wish to scan. Upon successful submission, the API will return a JSON object similar to this:

{
  "data": {
    "type": "analysis",
    "id": "YOUR_ANALYSIS_ID"
  }
}

The id from this response is crucial. It represents the identifier for the initiated analysis and will be used in a subsequent request to fetch the full report.

Example: Retrieve URL Analysis Report

Once the submission is processed, you can retrieve the analysis report using the id obtained from the previous step. It may take some time for the analysis to complete, depending on the URL and VirusTotal's processing queue.

curl --request GET \
  --url https://www.virustotal.com/api/v3/analyses/YOUR_ANALYSIS_ID \
  --header 'x-apikey: YOUR_API_KEY'

Again, replace YOUR_API_KEY and YOUR_ANALYSIS_ID with your respective values. The response will be a detailed JSON object containing scan results from various antivirus engines, detection statistics, and other relevant metadata about the URL VirusTotal analysis report endpoint.

For file submissions, the process is similar but involves using the /api/v3/files endpoint and providing the file content as multipart form data. The API reference provides specific instructions for VirusTotal file scanning.

Common next steps

After successfully making your first API calls, consider these common next steps to expand your use of VirusTotal's capabilities:

1. Explore Other Endpoints: VirusTotal offers endpoints for analyzing domains, IP addresses, and retrieving intelligence about previously observed indicators of compromise (IOCs). Review the VirusTotal API reference to understand the full range of available operations.
2. Implement Error Handling: Integrate robust error handling into your code. The API returns standard HTTP status codes (e.g., 400 Bad Request, 401 Unauthorized, 429 Too Many Requests) to indicate issues VirusTotal error codes. Properly handling these errors ensures your application behaves predictably, especially under rate limit conditions.
3. Manage Rate Limits: The Community API has strict rate limits. For applications requiring higher throughput, investigate VirusTotal Premium Services. Implement client-side rate limiting or exponential backoff strategies to avoid exceeding your quota and minimize 429 errors.
4. Asynchronous Processing: For file scanning or large data submissions, consider an asynchronous processing model. Submit the item, retrieve the id, and then periodically poll the analysis endpoint until the report is ready.
5. Data Parsing and Integration: Develop logic to parse the JSON responses and extract the specific threat intelligence data relevant to your use case. This might involve identifying specific antivirus detections, file metadata, or behavioral analysis results.
6. Automate Workflows: Integrate VirusTotal into automated security workflows, such as incident response playbooks, SIEM (Security Information and Event Management) systems, or threat hunting platforms. This allows for automated analysis of suspicious artifacts and enrichment of security alerts.
7. Stay Updated: The VirusTotal API documentation is regularly updated. Monitor the official VirusTotal documentation for new features, endpoint changes, or best practices.

Troubleshooting the first call

Encountering issues during your initial API calls is common. Here's a guide to troubleshoot some frequent problems:

• 401 Unauthorized: Invalid API Key

  This error typically means your API key is either missing, incorrect, or expired. Double-check that:

  • You have copied the entire API key string accurately.
  • The API key is correctly included in the x-apikey HTTP header of your request.
  • There are no leading or trailing spaces or invisible characters in the key.
  • Your API key is still active. Occasionally, keys might be revoked or expire, though this is less common for new keys. Refer to your VirusTotal API key management page to verify your key.

• 403 Forbidden: Insufficient Privileges or Incorrect Endpoint

  A 403 error can indicate that your API key does not have the necessary permissions for the requested operation, or you are attempting to access an endpoint only available to specific premium tiers. Ensure that:

  • The endpoint you are calling is available to the Community API tier (if using a free key). Some advanced features are restricted to premium users VirusTotal premium features.
  • You are using the correct HTTP method (e.g., POST for submitting, GET for retrieving).
  • The data format for your request (e.g., multipart form data for files, URL-encoded for URLs) matches the API's expectations VirusTotal API reference information.

• 429 Too Many Requests: Rate Limit Exceeded

  This error means you have sent too many requests within a given time frame. For the Community API, rate limits are strict. To resolve this:

  • Reduce the frequency of your API calls.
  • Implement a delay or an exponential backoff strategy in your code to automatically retry requests after a waiting period.
  • Review the VirusTotal getting started guide for specific rate limit details for your API tier.
  • If continuous high volume is required, consider upgrading to a VirusTotal Premium API key.

• 400 Bad Request: Malformed Request

  This indicates an issue with the structure or content of your request. Common causes include:

  • Missing required parameters in the request body or URL.
  • Incorrect data types for parameters (e.g., sending a string when an integer is expected).
  • Improperly formatted JSON or multipart data.
  • Refer to the specific endpoint documentation (e.g., VirusTotal file scan parameters) to ensure all parameters are correctly formatted and included.

• Network Connectivity Issues

  Ensure your environment has a stable internet connection and can reach https://www.virustotal.com. Firewalls or proxy servers might also interfere with your requests. Check your local network configuration if other HTTP requests also fail.