Usage Reports

As referred in the 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

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:

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

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 available to all customers with the Built-In support plan and above.

Endpoint Details

URL: /user/organization/{org-uuid}/usage-report
Method: GET
Authentication: Bearer token or API key required
IAM Service: :organization with :read permissions

Parameters

  • period (optional): Filter reports by specific month in YYYY-MM format (e.g., 2024-02)

Usage Report JSON Structure

The API returns aggregated usage data in the following format:

{
  "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"
    }
  ]
}

CLI Usage 

# Get current month usage report
$ exo x list-usage-report

# Get usage report for specific period
$ exo x list-usage-report --period 2024-02

The JSON report will be available through the API-v2 /usage-report or the exoscale-cli exoscale-cli

!!! note API vs Detailed Reports

- **API Usage Reports** (above): Available to all customers including Built-In plan. Provides aggregated usage data by product type via REST API.
- **Detailed Usage Reports** (below): Available only with paid support plans. Provides granular per-resource usage data in SOS buckets.

You can access API reports either through the [API-v2](https://openapi-v2.exoscale.com/topic/topic-api-request-signature)
or the [exoscale-cli](https://community.exoscale.com/documentation/tools/exoscale-command-line-interface/) 
command line program.

Detailed Usage Reports

In case you are subscribed to one of the advanced support plans, 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:

{
  "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