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.
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 last 6 months 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 |
Tip
To generate a report that represents all data currently in the project, select the "All Time" date range.
Customizing the Report
You can customize the report by specifying different time ranges and by grouping the report data by project or by month.
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 |
month | The month of the reporting period |
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 |
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 |
| 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 |