Skip to main content

Get Usage V2​

Select

SaaS

Usage API Documentation

Overview​

The Usage API provides a way to obtain usage data with various search parameters. All dates in the Usage API refer to the UTC time zone. Usage data on each usage date shows the peak usage up to that usage date in that calendar month.

Usage Retrieval​

Partners can use the API in two ways:

  • Directly call the API with no parameters to get usage data for yesterday (current calendar month peak usage up to yesterday).
  • Specify start date and end date parameters to get historical peak usage data. The duration we support for each API call cannot exceed a calendar month, and end date is exclusive. For example: Valid Params: (startDate: 2025-05-01, endDate: 2025-06-01); Invalid Params: (startDate: 2025-05-15, endDate: 2025-06-05)

Usage Collection Schedule​

Usage collection runs at 4 am UTC every day for yesterday's usage data. It is suggested for partners to call the Usage API for yesterday's data after 6 am UTC.

Database Usage​

Database usage is metered by capacity unless the application is hosted on virtual machines, in which case it is metered as a VM instance.

File & Object Usage​

File & Object usage is metered by capacity unless the application is hosted on Virtual Machines, in which case it is metered as a VM instance.

Metallic Backup for Microsoft 365 Service​

Metallic Backup for Microsoft 365 service will incur storage usage. Each user with Metallic Backup for Microsoft 365 Standard (Not including no storage option) will have 5 GB storage capacity included, and each user with Metallic Backup for Microsoft 365 Enterprise (Not including no storage option) will have 50 GB storage capacity included.

Storage Usage Calculation Examples​

Example 1:​

Customer had 100 Standard users, 100 Enterprise users, and 5000 GB storage reported in usage.

  • Storage included quantity: 100 5 + 100 50 = 5500 GB
  • Since 5000 GB < 5500 GB, no storage usage will be charged.

Example 2:​

Customer had 100 Standard users, 100 Enterprise users, and 6000 GB storage reported in usage.

  • Storage included quantity: 100 5 + 100 50 = 5500 GB
  • Since 6000 GB > 5500 GB, 500 GB storage usage will be charged.

Usage API Response​

In the Usage API response, storage quantity will be shown in TB.

MSP with volume commit​

When MSP has volume commit for services, we don't calculate cost at account level, the usage API will show only consumed quantity in individual accounts. Volume commit usage and cost can be retrieved from Usage Summary API.

Usage API Response Documentation

Response Body​

FieldDescriptionTypeNotes
dataList of usage detailsUsage Objects ArraySee - Usage Object
metadataList usage metadataMetadata ObjectSee - Metadata Object

Usage Object​

FieldDescriptionTypeNotes
usageDateDate of this usage objectDateUsage Data on usageDate means peak usage up to usageDate in the current calendar month.
accountIdAccount metallic idUUID
externalAccountIdAccount id in partner systemString / UUID
fulfillmentIdFulfillment metallic idUUID
externalFulfillmentIdFulfillment id in partner systemString / UUID
skuIdService sku in metallicString
consumedQuantityUsage quantityDoublePeak usage quantity against billingUnit that was consumed up to usageDate in the current calendar month.
entitledQuantityQuantity committed upfrontDoubleFor non-commit service, this field is the included quantity from M365 for Metallic Storage service and 0 for the others. For services with volume commit, this field is not applicable.
overageQuantityAny quantity consumed more than entitled quantityDoubleFor non-commit service, this field is Max(0, consumedQuantity minus entitledQuantity) for Metallic Storage service and 0 for the others. For services with volume commit, this field is not applicable.
billableQuantityQuantity to be charged forDoubleFor non-commit service, this field is the same as overageQuantity for Metallic Storage service and consumedQuantity for the others. For services with volume commit, this field is not applicable.
billingUnitUnit of measure (1 user, 10 vm, etc.)StringAll quantity fields are measured in billingUnit.
unitPricePrice for a single billingUnitDouble
overageUnitPriceOverage price for a single billingUnit when upfront service goes over entitled quantityDouble
totalCostTotal costDoublebillableQuantity * unitPrice. For services with volume commit, this field is not applicable.
currencyBilling currencyString
paymentOptionPayment optionStringCurrently supported values are "pay_as_you_go" and "upfront"
partnerIdMSP's reseller Metallic IDString
externalPartnerIdMSP's reseller reference IDString

Metadata Object​

FieldDescriptionTypeNotes
filterFilter string that contains search parametersString
sortSort string that contains sorting criteriaString
paginationPagination InfoPagination ObjectSee - Pagination Object

Pagination Object​

FieldDescriptionTypeNotes
pageNumberPage numberInteger0 to x
pageSizePage sizeInteger
totalRecordsTotal number of recordsInteger
Query Parameters
  • startDate string

    Optional - The date from which usage is returned. startDate is inclusive UTC time zone Format "YYYY-MM-DD". If not provided, defaults to yesterday. The duration between startDate and endDate cannot exceed a calendar month.

  • endDate string

    Optional - The date to which usage is returned. endDate is exclusive UTC time zone Format "YYYY-MM-DD". If not provided, defaults to today. The duration between startDate and endDate cannot exceed a calendar month.

  • accountId string

    Optional - Metallic account id.

  • fulfillmentId string

    Optional - Metallic fulfillment id.

  • pageNumber int32

    Optional - Page number >= 0. default 0

  • pageSize int32

    Optional - Page size, default 100

Responses

OK

Schema
  • data object[]
  • usageDate string
  • accountId string
  • externalAccountId string
  • fulfillmentId string
  • externalFulfillmentId string
  • skuId string
  • consumedQuantity number
  • entitledQuantity number
  • overageQuantity number
  • billableQuantity number
  • unitPrice number
  • billingUnit string
  • totalCost number
  • currency string
GET /api/v2/partner/usage

Authorization

Request

Click Edit to configure Base URL
https://api.metallic.io
Bearer Token
startDate — query
endDate — query
accountId — query
fulfillmentId — query
pageNumber — query
pageSize — query
lhAccountId — header
curl -L -X GET 'https://api.metallic.io/api/v2/partner/usage' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'