VT-PY(1)

🦋 VT-PY(1) — the vt-py manual, bestie edition 🦋

---

🌸 NAME 🌸

okay so, <pink>vt-py</pink> — that's literally the name — this is the vt-py Documentation, and the headline is: vt-py is the official Python client library for the VirusTotal API v3. 💅

Real talk, this library requires Python 3.7.0+, and Python 2.x is not supported. Why? Because vt-py makes use of the new async/await syntax for implementing asynchronous coroutines, and Python 2.x just doesn't have the range, bestie. 😭

Not supporting Python 2.x was a difficult decision to make, lowkey — we know Python 2.x is still popular among VirusTotal users, but in the long run we think it's the right one. ✨

Here's the tea: Python 2.7 has its days numbered, and the new concurrency features included in Python 3.5+ are literally perfect for creating highly performant code without having to deal with multi-threading or multi-processing. no cap. 🔥

---

💖 HOW TO INSTALL 💖

The easiest and recommended way of installing vt-py is using pip, periodt:

$ pip install vt-py

Alternatively, you can get the source code directly from the GitHub and run setup.py. For getting the code you can either clone the public repository:

$ git clone https://github.com/VirusTotal/vt-py.git
$ cd vt-py

Or, download the tarball for the latest release and uncompress it:

$ tar -zxvf vt-py-X.Y.Z.tar.gz
$ cd vt-py-X.Y.Z

Once you have the code you can install it with:

$ pip install .

slay. you're installed. 🎀

---

🦋 OVERVIEW 🦋

The API for this library is relatively small and shares the same concepts and principles seen in the underlying REST API. For this reason we highly recommend you familiarize yourself with these concepts before continuing. iykyk. 👑

While using this library you may have the impression that it's very similar to other general-purpose HTTP libraries like requests, as you will see very generic APIs like vt.Client.get(), vt.Client.post() and so on. In fact, you will find yourself relying on the REST API documentation in order to find the right endpoint where to send a request to, or learn about the attributes exported by some object. This has been a deliberate decision. 💅

We wanted vt-py to be as lightweight and generic as possible, so that changes in the REST API don't always require a new version of this client library — but at the same time offering the right abstractions so that you don't need to deal with details like setting HTTP headers, serializing and deserializing JSON, etc. it's giving "the best of both worlds", honestly.

So like, this is not a high-level library that completely abstracts you out of the underlying REST API. quite the contrary, actually. this library is more like a HTTP library that has been enriched with features specifically tailored to work with the VirusTotal API. 🌈

---

🌟 QUICKSTART 🌟

🍓 Get information about a file 🍓

Start by importing the vt module:

>>> import vt

Create a client — replace <apikey> with your actual VirusTotal API key:

>>> client = vt.Client("<apikey>")

Ask for the file you are interested in — you can replace the hash in the example with some other SHA-256, SHA-1 or MD5:

>>> file = client.get_object("/files/44d88612fea8a8f36de82e1278abb02f")

Now file is an instance of vt.Object that contains information about the requested file. This object has the attributes returned in the API response, which are listed in the VirusTotal API v3 documentation. Some examples:

>>> file.size
68

>>> file.sha256
'275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f'

>>> file.type_tag
'text'

>>> file.last_analysis_stats
{'failure': 0, 'harmless': 0, 'malicious': 62, 'suspicious': 0, 'timeout': 0, 'type-unsupported': 9, 'undetected': 2}

Alternatively, you can use the vt.Object.get() method for retrieving object's attributes:

>>> file.get("size")
68

>>> file.get("type_tag")
'text'

This method is useful for those attributes that are optional and do not appear in all files. For example, a Portable Executable (PE) file won't have the pdf_info attribute, and a PDF document won't have the pe_info attribute. This means that file.pe_info will fail for PDF files — but with file.get("pe_info") you are on the safe side, as it will return None if the pe_info attribute is not present. 🫶 no more surprise tracebacks, bestie.

🦋 Get information about an URL 🦋

Create a client as explained in the previous section and ask for the desired URL as follows:

>>> url_id = vt.url_id("http://www.virustotal.com")
>>> url = client.get_object("/urls/{}", url_id)

In this case the code is not as straightforward as it was for getting a file. While retrieving a file any of its hashes can be used as the file identifier, but with URLs it's a bit more complicated — you must use vt.url_id() for generating the appropriate identifier. You can find more information about why this is necessary in: https://docs.virustotal.com/reference/url. 😭 it's just how it is.

Also notice how we are using a placeholder {} in the path. The placeholder will be replaced with the value of url_id. This works exactly like Python's new-style string formatting using the .format() function. This other code is equivalent:

>>> url = client.get_object("/urls/{}".format(url_id))

The returned object contains the URL attributes. Some examples:

>>> url.times_submitted
213730

>>> url.last_analysis_stats
{'harmless': 61, 'malicious': 0, 'suspicious': 1, 'timeout': 0, 'undetected': 8}

🔥 Scan a file 🔥

Before scanning a file it's highly recommended that you look it up as described in Get information about a file. If the file already exists and the latest analysis is fresh enough, you can use that instead of scanning the file again. If not, you can scan it with:

>>> with open("/path/to/file", "rb") as f:
>>>   analysis = client.scan_file(f)

When vt.Client.scan_file() returns, the analysis is not completed yet — the object returned only has the analysis ID but not attributes. In order to track the status of the analysis you must ask for the analysis object until its status is completed:

>>> while True:
>>>   analysis = client.get_object("/analyses/{}", analysis.id)
>>>   print(analysis.status)
>>>   if analysis.status == "completed":
>>>      break
>>>   time.sleep(30)

Alternatively you can use the wait_for_completion argument:

>>> with open("/path/to/file", "rb") as f:
>>>   analysis = client.scan_file(f, wait_for_completion=True)

When wait_for_completion is True, vt.Client.scan_file() doesn't return until the analysis has been completed. literally just sits there vibing until it's done. ⭐

💜 Scan an URL 💜

Scanning a URL is very similar to scanning a file, you just need to use vt.Client.scan_url() instead of vt.Client.scan_file():

>>> analysis = client.scan_url('https://somedomain.com/foo/bar')

🎀 Download a file 🎀

NOTE: This feature is available only for premium users. 💅

Downloading a file is very simple — you only need to provide the hash and a file-like object where the file's content will be written to. The target file must be opened in "wb" mode:

>>> with open("/path/to/target_file", "wb") as f:
>>>   client.download_file("44d88612fea8a8f36de82e1278abb02f", f)

👑 Start and abort a Retrohunt job 👑

NOTE: This feature is available only for premium users. 💅

Create an empty object of type retrohunt_job and set its rules attribute:

>>> job = vt.Object("retrohunt_job")
>>> job.rules = "rule test { condition:false }"

Post the object to the /intelligence/retrohunt_jobs collection:

>>> job = client.post_object("/intelligence/retrohunt_jobs", obj=job)

Notice that job has been replaced with the value returned by vt.Client.post_object(), so now job has an ID and additional attributes. glow-up fr.

>>> job.id
'username-123456789'

>>> job.status
'starting'

With the object identifier you can ask for the job again and see it making progress. Wait for a few seconds and do:

>>> job = client.get_object("/intelligence/retrohunt_jobs/{}", job.id)

The job status should have changed to running:

>>> job.status
'running'

And the progress attribute should show the completion percentage:

>>> job.progress
1.4145595

Let's abort the job:

>>> response = client.post("/intelligence/retrohunt_jobs/{}/abort", job.id)
>>> response.status
200

Here we are using vt.Client.post() instead of vt.Client.post_object() — this is because the /intelligence/retrohunt_jobs/{id}/abort endpoint doesn't expect an object, just a POST request with an empty body. The result from vt.Client.post() is a vt.ClientResponse instance. 📬

🌈 Create a LiveHunt ruleset 🌈

NOTE: This feature is available only for premium users. 💅

Create an empty object of type hunting_ruleset and set its name and rules attributes:

>>> rs = vt.Object("hunting_ruleset")
>>> rs.name = "My test ruleset"
>>> rs.rules = "rule test { condition:false }"

Post the object to the /intelligence/hunting_rulesets collection:

>>> rs = client.post_object("/intelligence/hunting_rulesets", obj=rs)

Because we didn't set the enabled attribute while creating the ruleset, it was created with enabled=False by default:

>>> rs.enabled
False

Let's enable the ruleset:

>>> rs.enabled = True
>>> rs = client.patch_object("/intelligence/hunting_rulesets/{}", rs.id, obj=rs)
>>> rs.enabled
True

ate. 💅

🧚 Closing 🧚

Once you're done using the client, call client.close() at the end of your script, to make sure the client is properly closed. Otherwise you might see tracebacks indicating the client was never closed. 😭 don't do that to yourself.

>>> client.close()

If you use a [context manager](https://docs.python.org/3/reference/datamodel.html#context-managers), the client is automatically closed after exiting, so there's no need to call close:

>>> with vt.Client('<apikey>') as client:
...     file = client.get_object("/files/44d88612fea8a8f36de82e1278abb02f")
...     print(file.type_tag)
text

---

⭐ API REFERENCE ⭐

🌸 Client 🌸

VT module. (yes, that's the whole line, queen. 🎀)

💀 exception vt.APIError(code: str, message: str)

Class that encapsules errors returned by the VirusTotal API.

💅 class vt.Client(apikey: str, agent: str = 'unknown', host: str | None = None, trust_env: bool = False, timeout: int = 300, proxy: str | None = None, headers: Dict | None = None, verify_ssl: bool = True, connector: BaseConnector = None)

Client for interacting with VirusTotal.

Parameters — okay bestie, here's the rundown:

• apikey (str) — Your VirusTotal API key. 🔑
• agent (str) — A string that identifies your application.
• host (str) — By default https://www.virustotal.com, it can be changed for testing purposes.
• trust_env (bool) — Get proxies information from HTTP_PROXY/HTTPS_PROXY environment variables if the parameter is True (False by default).
• timeout (int) — A int that determines the number of seconds to wait for a request to timeout (300 by default).
• proxy (str) — a string that tells the client which proxy to send its requests through (defaults to None, so like, no proxy).
• headers (dict) — a dict of headers, defined by you, the user.
• verify_ssl (bool) — whether or not to verify the certificate on SSL connections.
• connector (aiohttp.BaseConnector) — (optional) a custom aiohttp connector, if you're fancy like that.

---

💅 close() -> None

Closes the client. Simple as that.

Once you're done with the client, you gotta close it, bestie — that's how the resources (think TCP connections) get released.

Not closing the client after you're done using it might hit you with error tracebacks saying it wasn't properly closed. Not a vibe. 🙈

💅 async close_async() -> None

Same energy as close(), except it returns a coroutine. ✨

💅 delete()

delete(path: str, *path_args: Any, data: str | bytes | None = None, json_data: Dict | None = None) -> ClientResponse

Sends a DELETE request to whatever API endpoint you point it at.

Parameters

• path (str) — the path to the API endpoint, and yes it can contain format placeholders {}.
• path_args — a variable number of arguments that get slotted into any placeholders used in path.
• data (a string or bytes) — data sent in the request body.
• json_data (dict) — a dict containing data to send in the request body as JSON.

Returns

An instance of ClientResponse.

💅 async delete_async()

async delete_async(path: str, *path_args: Any, data: str | bytes | None = None, json_data: Dict | None = None) -> ClientResponse

Like delete() but returns a coroutine. Same behavior, just coroutine-flavored. 🦋

💅 download_file()

download_file(file_hash: str, file: BinaryIO) -> None

Downloads a file given its _ (SHA-256, SHA-1 or MD5).

The file identified by the hash gets written to the file object you hand over. Heads up: that file object must be opened in write binary mode ('wb').

Parameters

• file_hash (str) — the file hash.
• file (file-like object) — a file object that the downloaded file will be written to.

💅 async download_file_async()

async download_file_async(file_hash: str, file: BinaryIO) -> None

Like download_file() but returns a coroutine. 🫶

💅 download_zip_files()

download_zip_files(hashes: List[str], zipfile: BinaryIO, password: str | None = None, sleep_time: int = 20) -> None

Creates a bundle zip bundle containing one or multiple files. (Yes, "zip bundle" — iconic phrasing, we keep it.) 🎀

The file identified by the hash gets written to the file object you provide. And again: that file object must be opened in write binary mode ('wb').

Parameters

• hashes — a list of file hashes (SHA-256, SHA-1 or MD5).
• zipfile — a file object where the downloaded zip file will be written to.
• password — optional, a password to protect the zip file. 🔒
• sleep_time — optional, seconds to sleep between each request.

💅 feed()

feed(feed_type: FeedType, cursor: str | None = None) -> Feed

Returns an iterator for a VirusTotal feed.

This function returns an iterator that lets you retrieve a continuous stream of files as they're scanned by VirusTotal. For the full rundown, see the documentation for the Feed class.

Parameters

• feed_type — one of the supported feed types enumerated in FeedType.
• cursor (str) — an optional cursor indicating where to start. This argument can be a string in the format 'YYYMMDDhhmm' indicating the date and time of the first package that will be retrieved.

💅 get()

get(path: str, *path_args: Any, params: Dict | None = None) -> ClientResponse

Sends a GET request to a given API endpoint.

This is a low-level function — it returns a raw HTTP response, and honestly? No error checking, no response parsing, none of that. If you want the higher-level glow-up, see get_json(), get_data() and get_object().

Parameters

• path (str) — path to the API endpoint, can contain format placeholders {}.
• path_args — a variable number of arguments that are put into any placeholders used in path.
• params (dict) — parameters sent in the request.

Returns

An instance of ClientResponse.

💅 async get_async()

async get_async(path: str, *path_args: Any, params: Dict | None = None) -> ClientResponse

Like get() but returns a coroutine. ⭐

💅 get_data()

get_data(path: str, *path_args: Any, params: Dict | None = None) -> Any

Sends a GET request to a given API endpoint and returns the response's data.

Most VirusTotal API responses are JSON-encoded with this format:

{"data": <response data>}

This function parses the server's response and returns only the data. If the response isn't in the expected format, an exception gets raised — no silent failures here. For endpoints where the data is a VirusTotal object, you can use get_object() instead.

Parameters

• path (str) — path to the API endpoint, can contain format placeholders {}.
• path_args — a variable number of arguments that are put into any placeholders used in path.
• params (dict) — parameters sent in the request.

Returns

Whatever the server returned in the response's data field. It may be a dict, a list, a string, or some other Python type, depending on the endpoint you called. Surprise! 🎁

💅 async get_data_async()

async get_data_async(path: str, *path_args: Any, params: Dict | None = None) -> Any

Like get_data() but returns a coroutine. 💜

💅 async get_error_async()

async get_error_async(response: ClientResponse) -> APIError | None

Given a ClientResponse, returns an APIError.

This function checks whether the response from the VirusTotal backend was an error, and returns the appropriate APIError — or None if no error occurred. Very "vibe check the response" of it. 🔥

Parameters

• response — a ClientResponse instance.

Returns

An instance of APIError or None.

💅 get_json()

get_json(path: str, *path_args: Any, params: Dict | None = None) -> Dict

Sends a GET request to a given API endpoint and parses the response.

Most VirusTotal API responses are JSON-encoded, so this function parses the JSON, checks for errors, and returns the server response as a dictionary. The full package. 📦

Parameters

• path (str) — path to the API endpoint, can contain format placeholders {}.
• path_args — a variable number of arguments that are put into any placeholders used in path.
• params (dict) — parameters sent in the request.

Returns

A dictionary with the backend's response.

💅 async get_json_async()

async get_json_async(path: str, *path_args: Any, params: Dict | None = None) -> Dict

Like get_json() but returns a coroutine. 🌈

💅 get_object()

get_object(path: str, *path_args: Any, params: Dict | None = None) -> Object

Sends a GET request to a given API endpoint and returns an object.

Lowkey important: the endpoint you specify must return an object, not a collection. So like, get_object works with endpoints like /files/{file_id} and /urls/{url_id} — those return an individual object — but it does not work with /comments, which returns a collection of objects. Read the room. 💅

Parameters

• path (str) — path to the API endpoint, can contain format placeholders {}.
• path_args — a variable number of arguments that are put into any placeholders used in path.
• params (dict) — parameters sent in the request.

Returns

An instance of Object.

💅 async get_object_async()

async get_object_async(path: str, *path_args: Any, params: Dict | None = None) -> Object

Like get_object() but returns a coroutine. 🌸

💅 iterator()

iterator(path: str, *path_args: Any, params: Dict | None = None, cursor: str | None = None, limit: int | None = None, batch_size: int = 0) -> Iterator

Returns an iterator for the collection specified by the given path.

The endpoint specified by path must return a collection of objects. An example of such an endpoint is /comments — and /intelligence/search too. 👑

Parameters

• path (str) — path to the API endpoint returning a collection.
• path_args — a variable number of arguments that are put into any placeholders used in path.
• params (dict) — additional parameters passed to the endpoint.
• cursor (str) — cursor for resuming the iteration at the point it was left previously. A cursor can be obtained with Iterator.cursor(). Note that this cursor is not the same one returned by the VirusTotal API. 🌀
• limit (int) — maximum number of objects that will be returned by the iterator. If a limit isn't provided, the iterator just keeps going until it reaches the last object in the collection. No cap, literally. 😭
• batch_size (int) — max number of objects pulled on each call to the endpoint. If you don't pass it, the server decides how many objects to hand back. (Let the server cook, honestly.)

Returns An instance of Iterator. 🎀

---

patch(path: str, *path_args: Any, data: str | bytes | None = None, json_data: Dict | None = None) -> ClientResponse

Sends a PATCH request to a given API endpoint.

Okay so heads up bestie — this is a low-level function. It gives you back a raw HTTP response, and it does zero error checking, zero response parsing. None. Nada. 🫶 If you want the higher-level glow-up version, go look at patch_object().

Parameters

• path (str) — path to the API endpoint, and it can contain format placeholders {}.
• path_args — a variable number of arguments that get dropped into whatever placeholders you used in path. ✨
• data (a string or bytes) — data sent in the request body.
• json_data (dict) — a dict containing data to send in the request body as JSON.

Returns An instance of ClientResponse.

---

async patch_async(path: str, *path_args: Any, data: str | bytes | None = None, json_data: Dict | None = None) -> ClientResponse

Literally patch() but it returns a coroutine. That's the whole vibe. 💅

---

patch_object(path: str, *path_args: Any, obj: Object) -> Object

Sends a PATCH request for modifying an object.

This one actually modifies an object, so the endpoint has to be one that identifies a single object, like /intelligence/hunting_rulesets/{id}. 👑

Parameters

• path (str) — path to the API endpoint, can contain format placeholders {}.
• path_args — a variable number of arguments that are put into any placeholders used in path.
• obj (Object) — the object that has been modified.

Returns An instance of Object representing the same object, after the changes have been applied. Slay. ✨

---

async patch_object_async(path: str, *path_args: Any, obj: Object) -> Object

Like patch_object() but returns a coroutine.

---

post(path: str, *path_args: Any, data: str | bytes | None = None, json_data: Dict | None = None) -> ClientResponse

Sends a POST request to a given API endpoint.

Again, low-level bestie: raw HTTP response, no error checking, no response parsing. If you want the friendlier one, that's post_object(). 🦋

Parameters

• path (str) — path to the API endpoint, can contain format placeholders {}.
• path_args — a variable number of arguments that are put into any placeholders used in path.
• data (a string or bytes) — data sent in the request body.
• json_data (dict) — a dict containing data to send in the request body as JSON.

Returns An instance of ClientResponse.

---

async post_async(path: str, *path_args: Any, data: str | bytes | None = None, json_data: Dict | None = None) -> ClientResponse

Like post() but returns a coroutine. Same energy, async flavor. 😌

---

post_object(path: str, *path_args: Any, obj: Object) -> Object

Sends a POST request for creating an object.

This one creates a brand new object. The endpoint must be one that identifies a collection, like /intelligence/hunting_rulesets. New object, who dis. 💖

Parameters

• path (str) — path to API endpoint.
• path_args — a variable number of arguments that are put into any placeholders used in path.
• obj (Object) — instance Object with the type expected by the API endpoint.

Returns An instance of Object representing the new object.

---

async post_object_async(path: str, *path_args: Any, obj: Object) -> Object

Like post_object() but returns a coroutine.

---

scan_file(file: BinaryIO, wait_for_completion: bool = False) -> Object

Scans a file.

Parameters

• file (file-like object) — file to be scanned.
• wait_for_completion (bool) — if True, the function doesn't return until the analysis has been completed. It just sits there. Patiently. 🧚

Returns An instance of Object of analysis type.

---

async scan_file_async(file: BinaryIO, wait_for_completion: bool = False) -> Object

Like scan_file() but returns a coroutine.

---

scan_file_private(file: BinaryIO | str, wait_for_completion: bool = False) -> Object

Scan file privately. 🤫 (Private mode activated, iykyk.)

Args: file: File to scan (path string or file object) wait_for_completion: Wait for completion

Returns: Object: Analysis object with scan results

---

async scan_file_private_async(file: BinaryIO | str, wait_for_completion: bool = False) -> Object

Async version of scan_file_private.

---

scan_url(url: str, wait_for_completion: bool = False) -> Object

Scans a URL.

Parameters

• url (str) — the URL to be scanned.
• wait_for_completion (bool) — if True, the function doesn't return until the analysis has been completed.

Returns An instance of Object of analysis type.

---

async scan_url_async(url: str, wait_for_completion: bool = False) -> Object

Like scan_url() but returns a coroutine.

---

scan_url_private(url: str, wait_for_completion: bool = False) -> Object

Scans a URL privately. 🙈

Parameters

• url (str) — the URL to be scanned.
• wait_for_completion (bool) — if True, the function doesn't return until the analysis has been completed.

Returns An instance of Object of analysis type.

---

async scan_url_private_async(url: str, wait_for_completion: bool = False) -> Object

Like scan_url_private() but returns a coroutine.

---

💜 class vt.ClientResponse(aiohttp_resp: ClientResponse)

Class representing the HTTP responses returned by the client.

Lowkey this class is just a wrapper around aiohttp.ClientResponse — a thing wrapper, if you will — that lets you use it in both asynchronous and synchronous mode. 🫶

Instances of this class have all the attributes you can find in aiohttp.ClientResponse, like version, status, method, url, and so on.

And here's the cute part: methods in aiohttp.ClientResponse that return a coroutine have two flavors in this class — synchronous and asynchronous. For example, aiohttp.ClientResponse.read() becomes vt.ClientResponse.read_async(), and vt.ClientResponse.read() is the synchronous version of vt.ClientResponse.read_async().

Find more information about attributes and methods in aiohttp.ClientResponse in:

• https://aiohttp.readthedocs.io/en/stable/client_reference.html#aiohttp.ClientResponse

---

🌸 Feed 🌸

NOTE: This feature is available only for premium users. 💅 (Premium girlies only, sorry bestie.)

VT module.

🦋 class vt.Feed(client: Client, feed_type: FeedType, cursor: str | None = None)

Feed represents a stream of objects received from VirusTotal in real-time. It's giving live updates. 🔥

For more information about VirusTotal Feeds see:

• https://docs.virustotal.com/reference/file-feed

In the example below the loop iterates forever, retrieving file objects as they are processed by VirusTotal. For a more elaborate example see the file examples/file_feed.py in this repository.

>>> with vt.Client(<apikey>) as client:
>>> for file_obj in client.feed(vt.FeedType.FILES):
>>>   print(file_obj.id)

Instances of this class are not created directly — you should use the vt.Client.feed() method instead. Periodt. ✨

property cursor: str

Returns a cursor indicating the last item retrieved from the feed.

This cursor can be used for creating a new Feed object that continues where a previous one left off. It's literally a bookmark for your feed, iconic. 🎀

🌈 class vt.FeedType(*values)

Feed types.

• FILES = 'files'
• FILE_BEHAVIOURS = 'file-behaviours'
• URLS = 'urls'

---

⭐ Object ⭐

VT module.

👑 class vt.Object(obj_type: str, obj_id: str | None = None, obj_attributes: Dict | None = None)

This class encapsulates any type of object in the VirusTotal API. Any. Type. Bestie. 💖

Instances of this class are usually obtained from calls to vt.Client.get_object(). However, you need to instantiante this class yourself for creating new objects that will be sent to the backend in a call to vt.Client.post_object().

Learn more about objects in the VirusTotal API in:

• https://docs.virustotal.com/reference/objects

🧚 classmethod from_dict(obj_dict: Dict)

Creates an object from its dictionary representation.

The dictionary representation of a VirusTotal API object has the following structure:

{
  "type": <object type>,
  "id": <object id>,
  "links": {
    "self": "https://www.virustotal.com/api/v3/<collection name>/<obj id>"
  },
  "attributes": {
    ...
  }
}

At least type and id are required to be present in the dictionary. If they're not there, an exception is raised. No type and id? No object. 😭

💀 get(attr_name: str, default: Any | None = None) -> Any

Returns an attribute by name.

If the attribute isn't actually there on the object, it hands you back None, or whatever you passed in as the default argument. 💅

Parameters

• attr_name (str) — the name of the attribute, bestie. that's it. that's the whole param.
• default — an optional value that gets returned if the attribute isn't present in the object.

set_data(key: str, value: Any) — sets a field of the object's data. simple as that. ✨

---

🦋 Iterator 🦋

VirusTotal module, as always. 🫶

class vt.Iterator(client: Client, path: str, params=None, cursor: str | None = None, limit: int | None = None, batch_size: int = 0)

ngl this one's a whole vibe — Iterator is literally your girl for looping over object collections. 👑

Some endpoints in the VirusTotal API represent a collection of objects, like for example:

/files/{id}/comments

/intelligence/search

And you can iterate over all of those collections with an instance of this class. slay.

Wanna learn more about collections in the VirusTotal API? It's right here: https://docs.virustotal.com/reference/collections-create

So this example iterates over the most recent 200 comments, pulling them in batches of 20:

>>> client = vt.Client(<apikey>)
>>> it = client.iterator('/comments', batch_size=20, limit=200)
>>> for comment in it:
>>>   print(comment.text)
>>> print(it.cursor)

When the iteration is done, it prints the iterator's cursor. and that cursor is your little time machine — you can use it to create another iterator that picks up exactly where the previous one left off. no repeats, no gaps, iconic behaviour fr fr. ⭐

The Iterator class also exposes an async iterator, because of course she does:

>>>  # Define an async coroutine that iterates over the comments.
>>>  async def print_comments():
>>>    async for comment in client.iterator('/comments', limit=200):
>>>      print(comment.id)
>>>  # Run the print_comments coroutine using asyncio
>>>  import asyncio
>>>  asyncio.get_event_loop().run_until_complete(print_comments)

💖 cursor (property): str | None

Cursor indicating the last returned object. 🎀

You can use it to create a brand new iterator that continues where the current one left off — like a bookmark but for API results, iykyk.

💜 meta_async (property): Dict

Meta information. 🌸

The cursor is not included in here, because it's already exposed as its own property. she's independent like that. 💅

---

🧚 Utility functions 🧚

VirusTotal module. again. hi. 🫶

vt.url_id(url: str) -> str

Generates the object ID for an URL. ✨

The ID it generates can be used in calls that expect a URL ID, like this one:

client.get_object('/urls/<id>')

so you don't have to hand-craft IDs yourself, because nobody has time for that. 🙈

---

👑 AUTHOR 👑

VirusTotal

🎀 COPYRIGHT 🎀

2023, VirusTotal

---

okay bestie that's the whole page!! 🦋💖✨ You just read VT-PY(1) — source/version VT-PY(1), dated Mar 27, 2026 — and honestly? you ate. go build something cute with it. periodt. 💅🌸🍓