The Visual Agents data download tool saves an account's data to your computer: results and their media, dashboard counts, datasets, and evaluations. It also includes a viewer for browsing everything it downloaded, with no internet connection needed.
The tool was created using the open Visual Agents API, which can also be used to build your own scripts and integrations.
1. Download the tool
- Download the data download tool (.zip).
- Unzip it. The folder contains
download_data.py,viewer.htmlandrequirements.txt. Keep these files together in the same folder.
2. Set up your environment
The tool needs Python 3.9 or newer. To check which version you have, open a terminal (Command Prompt on Windows) and run python3 --version (on Windows, python --version). If Python is missing or older, install it from python.org.
In the terminal, go to the unzipped folder, create a virtual environment and install the tool's packages:
macOS and Linux
cd path/to/unzipped/folder python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt
Windows (Command Prompt)
cd path\to\unzipped\folder python -m venv .venv .venv\Scripts\activate pip install -r requirements.txt
You only need to do this once. Next time, go to the same folder and run just the activate line.
Get an API key: sign in to Visual Agents, open the Keys page from the navigation bar and select Create API Key. Copy the key right away, because it's only shown once. Keys don't expire, so keep yours as private as a password.
3. Run the script
⚠️ Warning: media can take up a lot of disk space. Downloading media for a long time range can add up to multiple terabytes. The time range doesn't apply to datasets, so when media is included, every dataset's media is downloaded. Before a large download:
- try a short time range first, such as one day, to see how much space it uses
- check that the drive you're saving to has enough free space
- leave media out with
--no-media, or download only one kind with--original-media, if you don't need both
With the virtual environment active, run the script with your API key and the data you want. This example downloads one week of results and their original media:
python download_data.py --key YOUR_API_KEY --results --original-media --start-date 2026-10-01 --end-date 2026-10-07
This one downloads everything from the last 30 days:
python download_data.py --key YOUR_API_KEY --all
The script shows what it's about to download and asks you to confirm before it starts. While it runs, it shows progress for each type of data. When it finishes, it prints the folder it saved to and where to find the viewer.
If anything fails, the script lists the errors at the end. Run the same command again with --output-dir set to the same folder to retry. Media that already downloaded is skipped.
Command line arguments
Required:
-
An API key:
--key YOUR_API_KEY(or-k). You can instead set theVISUAL_AGENTS_API_KEYenvironment variable, which keeps the key out of your command history. - At least one type of data, from this list:
| Argument | Downloads |
|---|---|
--all |
Everything below, including both kinds of media |
--results |
Results |
--dashboard |
Dashboard counts by date, hour, camera, policy and compliance |
--datasets |
Datasets, their items and each item's result |
--evaluations |
Evaluations, their item outcomes and results |
--media |
Both kinds of media below |
--original-media |
Original media for each downloaded result |
--processed-media |
Processed media (what was assessed) for each downloaded result |
Media is only downloaded for results that are also downloaded, so the media options need --results, --datasets or --evaluations too. To leave one type out of --all, add its --no- form, such as --all --no-media.
Optional:
| Argument | What it does |
|---|---|
--start-date, --end-date
|
The time range, each as a date (YYYY-MM-DD, in UTC) or an ISO 8601 time such as 2026-10-01T08:00:00-05:00 (in UTC if it has no offset). An end date includes that whole day. The default is the last 30 days. It applies to results, dashboard counts and evaluations, but not datasets. |
--user EMAIL |
Download another account you have access to, such as a group account, using your own API key |
--output-dir FOLDER |
Where to save the download (default: a new visual_agents_export_<date and time> folder) |
--camera-name, --policy-id, --compliance
|
Only results from one camera, for one policy, or that are compliant or noncompliant
|
--dataset-id ID |
Only this dataset and its evaluations. Repeat it for more than one. |
--timezone |
Timezone for the dashboard's dates and hours, such as America/Chicago (default: UTC) |
--csv |
Also save spreadsheet-friendly CSV files |
--zip |
Also zip the finished download |
--yes |
Start without asking to confirm, such as when the script is scheduled |
See every option
To list every argument with a short description, run:
python download_data.py --help
4. View your data
Open viewer.html in the download folder in a web browser. From the viewer you can browse results, dashboard counts, datasets and evaluations, and play their media. The viewer reads files from the download folder, so keep the folder together if you move or share it.
The data is also saved as JSON files, plus CSV files if you used --csv, for use in other tools.
Comments