Edit

Get small cost datasets on demand

  • Article

Use the Cost Details API to get raw, unaggregated cost data that corresponds to your Azure bill. The API is useful when your organization needs a programmatic data retrieval solution. Consider using the API if you want to analyze smaller cost data sets of 2 GB (2 million rows) or less. However, you should use Exports for ongoing data ingestion workloads and for the download of larger datasets.

If you want to get large amounts of exported data regularly, see Retrieve large cost datasets recurringly with exports.

To learn more about the data in cost details (formerly referred to as usage details), see Ingest cost details data.

The Cost Details report is only available for customers with an Enterprise Agreement or Microsoft Customer Agreement. If you're an MSDN, pay-as-you-go or Visual Studio customer, see Get cost details for a pay-as-you-go subscription.

Permissions

To use the Cost Details API, you need read only permissions for supported features and scopes.

Note

The Cost Details API doesn't support management groups for either EA or MCA customers.

For more information, see:

Cost Details API best practices

Microsoft recommends the following best practices as you use the Cost Details API.

Request schedule

If you want to get the latest cost data, we recommend you query at most once per day. Reports are refreshed every four hours. If you call more frequently, you receive identical data. Once you download your cost data for historical invoices, the charges don't change unless you're explicitly notified. We recommend caching your cost data in a queryable store on your side to prevent repeated calls for identical data.

Chunk your requests

Chunk your calls into small date ranges to get more manageable files that you can download over the network. For example, we recommend chunking by day or by week if you have a large Azure cost file month-to-month. If you have scopes with a large amount of cost data (for example a Billing Account), consider placing multiple calls to child scopes so you get more manageable files that you can download. For more information about Cost Management scopes, see Understand and work with scopes. After you download the data, use Excel to analyze data further with filters and pivot tables.

If your dataset is more than 2 GB (or roughly 2 million rows) month-to-month, consider using Exports as a more scalable solution.

Latency and rate limits

On demand calls to the API are rate limited. The time it takes to generate your cost details file is directly correlated with the amount of data in the file. To understand the expected amount of time before your file becomes available for download, you can use the retry-after header in the API response.

Supported dataset time ranges

The Cost Details API supports a maximum data set time range of one month per report. Historical data can be retrieved for up to 13 months before the current date. If you want to seed a 13-month historical dataset, we recommend placing 13 calls in one month datasets for the past 13 months. To retrieve historical data that is older than 13 months, use the Exports REST API.

Example Cost Details API requests

The following example requests are used by Microsoft customers to address common scenarios. The data returned by the request corresponds to the date when the cost got received by the billing system. It might include costs from multiple invoices. It's an asynchronous API. As such, you place an initial call to request your report and receive a polling link in the response header. From there, you can poll the link provided until the report is available for you.

Use the retry-after header in the API response to dictate when to poll the API next. The header provides an estimated minimum time that your report takes to generate.

To learn more about the API contract, see Cost Details API.

Actual cost versus amortized cost

To control whether you would like to see an actual cost or amortized cost report, change the value used for the metric field in the initial request body. The available metric values are ActualCost or AmortizedCost.

Amortized cost breaks down your reservation purchases into daily chunks and spreads them over the duration of the reservation term. For example, instead of seeing a $365 purchase on January 1, you'll see a $1.00 purchase every day from January 1 to December 31. In addition to basic amortization, the costs are also reallocated and associated by using the specific resources that used the reservation. For example, if the $1.00 daily charge was split between two virtual machines, you'd see two $0.50 charges for the day. If part of the reservation isn't utilized for the day, you'd see one $0.50 charge associated with the applicable virtual machine and another $0.50 charge with a charge type of UnusedReservation. Unused reservation costs are seen only when viewing amortized cost.

Because of the change in how costs are represented, it's important to note that actual cost and amortized cost views show different total numbers. In general, the total cost of months over time for a reservation purchase will decrease when viewing amortized costs. The cost of months following a reservation purchase increase. Amortization is available only for reservation purchases and doesn't currently apply to Azure Marketplace purchases.

Initial request to create report

POST https://management.azure.com/{scope}/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2022-05-01

Request body:

Here's an example request for an ActualCost dataset for a specified date range.

{
  "metric": "ActualCost",
  "timePeriod": {
    "start": "2020-03-01",
    "end": "2020-03-15"
  }
}

Available {scope} options to build the proper URI are documented at Identify the resource ID for a scope.

Here are the available fields you can provide in the report request body.

  • metric - The type of report requested. It can be either ActualCost or AmortizedCost. Not required. If the field isn't specified, the API defaults to an ActualCost report.
  • timePeriod - The requested date range for your data. Not required. This parameter can't be used alongside either the invoiceId or billingPeriod parameters. If a timePeriod, invoiceId or billingPeriod parameter isn't provided in the request body the API returns the current month's cost.
  • invoiceId - The requested invoice for your data. This parameter is only used by Microsoft Customer Agreement customers. Additionally, it can only be used at the Billing Profile or Customer scope. This parameter can't be used alongside either the billingPeriod or timePeriod parameters. If a timePeriod, invoiceId or billingPeriod parameter isn't provided in the request body the API returns the current month's cost.
  • billingPeriod - The requested billing period for your data. This parameter is only used by Enterprise Agreement customers. Use the YearMonth format. For example, 202008. This parameter can't be used alongside either the invoiceId or timePeriod parameters. If a timePeriod, invoiceId or billingPeriod parameter isn't provided in the request body the API returns the current month's cost.

API response:

Response Status: 202 – Accepted : Indicates that the request was accepted. Use the Location header to check the status.

Response headers:

Name Type Format Description
Location String The URL to check the result of the asynchronous operation.
Retry-After Integer Int32 The expected time for your report to be generated. Wait for this duration before polling again.

Report polling and download

Poll for the report using the endpoint provided in the location header of the API response after you make a request to create a Cost Details report. Here's an example polling request.

Report polling request:

GET https://management.azure.com/{scope}/providers/Microsoft.CostManagement/costDetailsOperationStatus/{operationId}?api-version=2022-05-01

Response Status 200 – Succeeded: Indicates that the request succeeded.

{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/operationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2022-05-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 160769,
    "compressData": false,
    "requestContext": {
      "requestScope": "subscriptions/00000000-0000-0000-0000-000000000000",
      "requestBody": {
        "metric": "ActualCost",
        "timePeriod": {
          "start": "2020-03-01",
          "end": "2020-03-15"
        }
      }
    },
    "blobs": [
      {
        "blobLink": "{downloadLink}",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}

Here's a summary of the key fields in the API response:

  • manifestVersion - The version of the manifest contract that is used in the response. At this time, the manifest version remains the same for a given API version.
  • dataFormat - CSV is the only supported file format provided by the API at this time.
  • blobCount - Represents the number of individual data blobs present in the report dataset. It's important to note that this API might provide a partitioned dataset of more than one file in the response. Design your data pipelines to be able to handle partitioned files accordingly. Partitioning allows you to be able to ingest larger datasets more quickly moving forward.
  • byteCount - The total byte count of the report dataset across all partitions.
  • compressData - Compression is always set to false for the first release. The API will support compression in the future, however.
  • requestContext - The initial configuration requested for the report.
  • blobs - A list of n blob files that together comprise the full report.
    • blobLink - The download URL of an individual blob partition.
    • byteCount - The byte count of the individual blob partition.
  • validTill - The date when the report is no longer accessible.

Next steps