# Usage Reports As referred in the [Billing](https://community.exoscale.com/platform/billing/) section, every resource, unless noted otherwise, is metered for usage consumption and billed on a monthly basis. You can always see your *current consumption*. For past billing periods, you have access to *invoices* and *usage reports* as detailed below. ## Types of Reports - Live Usage Report - Invoices & Usage Reports - Detailed Usage Reports ### Live Usage Report Information about the current consumption (and price estimation) is available through the portal: Organization > Billing > Usage Details ![](usage-reports-usage-details.png "Live Usage Reports") At the top, you can see the **Usage Overview** which does an aggregation by product and below it, on the **Usage Detail**, you will find detailed consumption by product type. There's no live details for individual resources. These figures are updated every hour. ### Invoices & Usage Reports *Invoices* and *usage reports* terms refer to similar objects, mainly with information about the usage (priced). The main difference is that *invoices* aim to be paid and *usage reports* are for information purpose only. If you have the Pre-Paid Billing mode, you get: * Invoices as receipts for top-up payments * *Usage reports* on a monthly basis, providing a summary of all your consumption during a given billing cycle. In case you have the Post-Paid Billing mode, you are billed on a monthly basis. The *invoice* contains the summary of your consumption during the relevant billing cycle. Usage-based invoices and usage reports display the total amount for the period and the resources consumption, grouped by product and aggregated by product type as in the example below: ![](usage-report-pdf-example.png "Live Usage Reports") Once issued, the *invoices* and *usage reports* are available in two formats: PDF and JSON. The PDF is immediately sent via email and available through the portal: Organization > Invoices/Usage Reports ![](usage-reports-invoices-list.png "List Invoices And Usage Reports") You can find the `DOWNLOAD PDF` button in the *invoice*/*usage report* detail page . ## API Access to Usage Reports For programmatic access to usage reports, Exoscale provides an [API endpoint](https://community.exoscale.com/reference/api/general/organization/#get-usage-report) available to all customers. ### Parameters - `period` (optional): Filter reports by specific month in `YYYY-MM` format (e.g., `2024-02`). If not provided, defaults to the current month. ### Usage Report JSON Structure The API returns aggregated usage data in the following format: ```json { "usage": [ { "from": "2024-01-01T03:00:00Z", "to": "2024-01-31T20:00:00Z", "product": "compute", "variable": "medium_running", "description": "Running medium VM", "quantity": "789.10", "unit": "h" }, { "from": "2024-01-01T03:00:00Z", "to": "2024-01-31T20:00:00Z", "product": "storage", "variable": "sos_storage_volume_128k", "description": "SOS Storage Volume", "quantity": "1024.50", "unit": "GiB.h" }, { "from": "2024-01-01T03:00:00Z", "to": "2024-01-31T20:00:00Z", "product": "network", "variable": "output_traffic", "description": "Output network traffic", "quantity": "130.62", "unit": "GB" } ] } ``` ### Error Responses The API returns appropriate HTTP status codes and error messages for invalid requests: **400 Bad Request** - Invalid period format: ```json { "error": "Invalid period format: 2024-13. Expected format: YYYY-MM" } ``` **404 Not Found** - Organization not found or no access permissions ### CLI Usage ```bash # Get current month usage report $ exo x get-usage-report # Get usage report for specific period $ exo x get-usage-report --period 2025-06 ``` ### Detailed Usage Reports In case you are subscribed to one of the [advanced support plans](https://www.exoscale.com/support/), you'll also have detailed usage reports following each billing cycle. These reports are stored in a SOS bucket we create for you, named in the form `usage-reports-UUID` with the following structure: ``` usage-reports[uuid]/2023/10.json usage-reports[uuid]/2023/10.xls usage-reports[uuid]/2023/11.json usage-reports[uuid]/2023/11.xls usage-reports[uuid]/2023/12.json usage-reports[uuid]/2023/12.xls ``` We bundle the information into two formats: JSON and XLS. Inside those files you will find the usage details for every resource and service used on Exoscale during the given period. Json example: ```json { "id": "c06a253f-bc9e-270f-af2d-deacda58c158", "created": "2023-06-24T14:51:43.695Z", "modified": "2023-07-24T15:31:21.882Z", "summary": {...}, "products": { "storage": [ { "entity_id": "511b6af9-34d3-2d75-116a-7f9811d04016", "created": "2023-06-24T15:18:49.166Z", "modified": "2023-07-24T15:13:57.378Z", "meters": { "sos:storage_volume_128k": { "start": 1687615200000, "end": 1690207200000, "value": 464.31794916, "unit": "GiB.h", "meta": { ... "bucket": "BUCKET NAME", } } } }, { "entity_id": "687d36c0-1b4e-4fc3-a8b4-142f8f42a7ab", ... "meters": { "sos:storage_volume_128k": { "start": 1687615200000, "end": 1690207200000, "value": 20725.46139412, "unit": "GiB.h", "meta": { ... "bucket": "ANOTHER BUCKET", } } } } ], "instance": [ { "entity_id": "2fdf658d-fa42-4320-8c25-292c8f70119b", "created": "2023-06-24T16:02:33.541Z", "modified": "2023-07-24T15:07:09.894Z", "meters": { "opencompute:running_extra_large": { "start": 1687617011936, "end": 1690209136494, "value": 720.03459944, "unit": "h", "meta": { ... "name": "INSTANCE-NAME", } } } } ], ... } } ``` Excel example: ![](usage-report-excel-example.png "Usage Report Excel Example")