Usage Report
The Flywheel Usage Report provides a way for Site Admin users to inspect the utilization of the Flywheel Site and per project, over a given time range. The report data is intended to help customers understand how each project's utilization is contributing to consumption driven costs.
Not Billing Data
All Usage Report results reflect only the project data under management, and not storage consumption billing data. Storage data does not represent storage used by backups, snapshots, etc. Similarly, files from Smart Copy or ref-in-place style imports are included in the usage data, despite that storage not contributing to additional physical storage consumption.
Usage Report (Web UI)
The Usage Report page in the Flywheel Web UI displays site utilization data per project over a selected date range.
Changed in version 21.5.0
The Usage Report web UI was updated to use a more efficient API. The "Disk Usage" column was renamed to "Storage", and new columns for group, Gears Run, and Gear Time were added. A CSV download option is now available.
Changed in version 21.6.0
The Web UI now defaults to the current month when opened and provides a set of predefined date ranges in place of the previous custom date range picker. The CSV download now includes detailed file count columns and conditionally includes the year and month columns only when the report is grouped by month.
Generating a Usage Report
To generate a Usage Report, navigate to the Usage Report page under the Admin section of the Flywheel sidebar. A report for the current month runs automatically when the page opens.
The web UI table displays the change in each metric over the selected date range:
| Column | Description |
|---|---|
| Group | The parent group of the project |
| Project | The project name |
| Sessions | The change in session count over the date range |
| Storage | The change in managed data over the date range. Managed data includes all file versions, Smart Copy files, and ref-in-place imported files. It does not include soft-deleted files, backups, or snapshots. |
| Gears Run | The total number of gear jobs run during the date range |
| Gear Time | The total gear compute time during the date range |
Customizing the Report
You can customize the report by selecting from the following predefined date ranges:
- Current month
- Prior month
- Prior 3 months
- Prior 6 months
- Prior 12 months
You can also group the report data by project or by month.
Note
Users who require a custom date range can use the Daily/Monthly SDK APIs or the Legacy API instead of the Web UI.
Downloading Report Data as CSV
You can download the usage report data as a CSV file by clicking the Download CSV button on the Usage Report page.
The CSV differs from the web UI table in two important ways:
- Actual values instead of change: The CSV provides the actual values at the start and end of each period, rather than the change over the date range shown in the web UI. This allows you to compute your own deltas or compare absolute values across periods.
- Includes deleted projects: The CSV includes data for deleted projects, which are hidden in the web UI table.
The CSV contains the following columns:
| Column | Description |
|---|---|
error | Error message, if any, encountered when gathering data for the row |
project_label | The project name |
project_id | The unique project identifier |
group_id | The unique group identifier |
group_label | The group name |
project_deleted | Whether the project has been deleted (True or False) |
year | The year of the reporting period. Only included when grouped by month. |
month | The month of the reporting period. Only included when grouped by month. |
period_start | The start date of the reporting period |
period_end | The end date of the reporting period |
session_count_start | The number of sessions at the start of the period |
session_count_end | The number of sessions at the end of the period |
managed_data_bytes_start | The total managed data in bytes at the start of the period. Managed data includes all file versions, Smart Copy files, and ref-in-place imported files. It does not include soft-deleted files, backups, or snapshots. |
managed_data_bytes_end | The total managed data in bytes at the end of the period |
job_count_sum | The total number of gear jobs run during the period |
compute_ms_sum | The total gear compute time in milliseconds during the period |
File count columns:
Warning
The file count columns included in the CSV download, their names, and their order are subject to change in future releases. Any automated processing of the CSV should identify columns by their heading, not by position.
The CSV includes file count columns with _start and _end values representing the counts at the beginning and end of each period.
Column (with _start / _end suffix) | Description |
|---|---|
files_total_managed_count | Total number of managed files. Includes all file versions, Smart Copy files, and ref-in-place imported files. Does not include soft-deleted files. |
files_source_original_count | Files with their own storage (excludes Smart Copy and ref-in-place files) |
files_source_by_ref_count | Files that reference another file's storage (Smart Copy and ref-in-place imports). This plus files_source_original_count equals files_total_managed_count. |
files_deleted_soft_count | Files deleted by a user or API call but still retained on storage, allowing recovery. For example, a DICOM series deleted from a session in the UI. |
files_deleted_hard_count | Files permanently removed from storage and cannot be recovered. Files are hard-deleted when purged after the site's configured retention period for soft-deleted data. |
files_origin_user_count | Files created by direct user action, including uploads through the UI, CLI, or SDK, as well as files written by API-enabled gears that a user launched. |
files_origin_job_count | Files uploaded by the compute engine on behalf of a gear job. Most gear output files fall into this category regardless of how the job was triggered. |
files_origin_device_count | Files received from an external device connector. For example, DICOM images sent from a scanner or PACS. |
files_origin_user_workspace_count | Files saved from a user workspace session. For example, a Jupyter notebook saved from JupyterHub. |
files_origin_system_count | Files created by internal Flywheel platform operations. These counts are typically zero. |
files_origin_gear_rule_count | Files written directly by an API-enabled gear that was triggered by a gear rule. |
files_origin_task_count | Files created by Flywheel background tasks that support core platform services. These counts are typically zero. |
files_origin_unknown_count | Files whose origin was not recorded. Typically older files that predate origin tracking. |
When grouped by project, the CSV contains one row per project for the entire date range. When grouped by month, the CSV contains one row per project per month.
Usage Report (Daily/Monthly APIs)
A set of usage reporting APIs are available via the Flywheel Python SDK. These APIs support querying usage data by month or day, as well as by group or project. This report reflects the total project data for each day, rather than only reflecting "net new" data. Every night an automated background process collects and preserves usage data to support the largest Flywheel sites and more use cases.
For example: If 1 TB of data was added to Project A, then on different days moved to Project B, then deleted, that rise and fall of 1 TB of data in both projects would be possible to see in this report.
This also makes possible the viewing of historical usage data for deleted projects.
Soft-Deleted Stats
The 19.4.0 release of Flywheel added soft-deleted data stats to this usage report.
- Soft-deleted files are files that have been deleted by a user or device and are no longer available via Flywheel user interfaces and APIs, but whose contents still exist on storage, making recovery possible.
- You can use the soft-deleted stats to understand how much deleted data may still be consuming infrastructure storage capacity.
- Flywheel SDK 19.4.0 or later is required to access the soft-deleted stats.
- It may take up to a week after your Flywheel site is upgraded to 19.4.0 for the system to complete the collection of historical stats.
SDK Documentation
Flywheel Python SDK documentation is available for both the daily and monthly versions of this report.
Legacy Usage Report API
The Legacy Usage Report API was previously used by the Flywheel Web UI. As of version 21.5.0, the Web UI uses a newer, more efficient API and no longer relies on the Legacy Usage Report API.
The Legacy API is still accessible via the Python SDK get_legacy_usage_report method.
Deprecated
The Legacy Usage Report API is deprecated and is scheduled to be removed in the Flywheel 23.0.0 release (October 2026). See the deprecation notice for migration guidance.
Comparing Capabilities
| Report Capability | Web UI | CSV Download | Daily/Monthly SDK | Legacy API |
|---|---|---|---|---|
| Net new sessions and storage over time range? | yes | yes (via start/end values) | yes | yes |
| Data available for usage from the current day? | no | no | no | yes |
| Data available for usage from yesterday and prior days? | yes | yes | yes | yes |
| Specifies the project's parent group? | yes | yes | yes | no |
| Total sessions per project for a given day? | no | yes | yes | no |
| Includes deleted projects? | no | yes | yes | no |
| Counts Smart Copy files? | yes | yes | yes | yes |
| Counts ref-in-place imported files? | yes | yes | yes | yes |
| File counts by storage type (source), origin, and deletion status? | no | yes | no | no |
| Counts soft-deleted data? | no | no | yes | no |
| Separation of usage by Center vs. Lab for Multi Provider customers? | no | no | yes | no |
| Supports sites with millions of files and thousands of projects? | yes | yes | yes | no |
| Gear job count and compute time? | yes | yes | yes | no |