You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/cost-management-billing/costs/manage-automation.md
+73-33Lines changed: 73 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,13 @@
1
1
---
2
2
title: Manage Azure costs with automation
3
3
description: This article explains how you can manage Azure costs with automation.
4
-
author: jojohpm
5
-
ms.author: jojoh
6
-
ms.date: 06/26/2025
4
+
author: maddieminn
5
+
ms.author: maminn
6
+
ms.date: 07/03/2025
7
7
ms.topic: conceptual
8
8
ms.service: cost-management-billing
9
9
ms.subservice: cost-management
10
-
ms.reviewer: jojoh
10
+
ms.reviewer: maminn
11
11
---
12
12
13
13
# Manage costs with automation
@@ -34,69 +34,109 @@ If you want to analyze your data daily, we recommend using the [Power BI data co
34
34
35
35
You might not need to analyze the data daily. If so, consider using Cost Management's [Exports](./tutorial-improved-exports.md) feature to schedule data exports to an Azure Storage account. Then you can load the data into Power BI as needed, or analyze it in Excel if the file is small enough. Exports are available in the Azure portal or you can configure exports with the [Exports API](/rest/api/cost-management/exports).
36
36
37
-
**Usage Details API**
37
+
**Cost Details API**
38
38
39
-
Consider using the [Usage Details API](/rest/api/consumption/usageDetails) if you have a small cost data set. Here are recommended best practices:
39
+
Consider using the [Cost Details API](/rest/api/cost-management/costdetails) if you have a small cost data set. Here are recommended best practices:
40
40
41
41
- If you want to get the latest cost data, we recommend that you query at most once per day. Reports are refreshed every four hours. If you call more frequently, you'll receive identical data.
42
-
- Once you download your cost data for historical invoices, the charges won't change unless you're explicitly notified. We recommend caching your cost data in a queryable store on to prevent repeated calls for identical data.
42
+
- Once you download your cost data for historical invoices, the charges won't change unless you're explicitly notified. We recommend caching your cost data in a queryable store to prevent repeated calls for identical data.
43
43
- Chunk your calls into small date ranges to get more manageable files that you can download. For example, we recommend chunking by day or by week if you have large Azure usage files month-to-month.
44
-
- If you have scopes with a large amount of usage data (for example a Billing Account), consider placing multiple calls to child scopes so you get more manageable files that you can download.
44
+
- 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.
45
45
- If your dataset is more than 2 GB month-to-month, consider using [exports](tutorial-improved-exports.md) as a more scalable solution.
46
46
47
-
## Automate retrieval with Usage Details API
47
+
## Automate retrieval with Cost Details API
48
48
49
-
The [Usage Details API](/rest/api/consumption/usageDetails) provides an easy way 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're looking to analyze smaller cost data sets. However, you should use other solutions identified previously if you have larger datasets. The data in Usage Details is provided on a per meter basis, per day. It's used when calculating your monthly bill. The general availability (GA) version of the APIs is `2019-10-01`. Use `2019-04-01-preview` to access the preview version for reservation and Azure Marketplace purchases with the APIs.
49
+
The [Cost Details API](/rest/api/cost-management/costdetails) enables you to programmatically generate and download detailed, unaggregated cost data for your Microsoft Customer Agreement (MCA) billing account. Unlike the legacy Usage Details API, the Cost Details API is asynchronous and report-based: you submit a request to generate a report, poll for its completion, and then download the resulting file from a secure URL.
50
50
51
-
If you want to get large amounts of exported data regularly, see [Retrieve large cost datasets recurringly with exports](ingest-azure-usage-at-scale.md).
51
+
> [!IMPORTANT]
52
+
> The Cost Details API is only supported for Enteroruse Agreement (EA) or Microsoft Customer Agreement (MCA) scopes. For other account types, we suggest using Exports. If you need to download small datasets and you don't want to use Azure Storage, you can also use the Consumption Usage Details API. See instructions on how to do this [here](/automate/get-usage-details-legacy-customer.md)
52
53
53
-
### Usage Details API suggestions
54
+
### How the Cost Details API works
54
55
55
-
**Request schedule**
56
+
1.**Create a report**: Submit a POST request to the Cost Details API specifying the scope, date range, and optional filters (such as meter, resource, or tag).
57
+
2.**Poll for status**: The API returns an operation ID. Poll the operation status endpoint until the report is complete.
58
+
3.**Download the report**: Once complete, the API provides a secure download URL for the CSV file containing your cost data. The download link is valid for a limited time.
56
59
57
-
We recommend that you make _no more than one request_ to the Usage Details API per day. For more information about how often cost data is refreshed and how rounding is handled, see [Understand cost management data](./understand-cost-mgt-data.md).
60
+
For full details, see [Get small usage datasets on demand](https://learn.microsoft.com/azure/cost-management-billing/automate/get-small-usage-datasets-on-demand)and the [Cost Details API reference](https://learn.microsoft.com/rest/api/cost-management/generate-cost-details-report/create-operation).
58
61
59
-
**Target top-level scopes without filtering**
62
+
## Example: Generate and download a Cost Details report
60
63
61
-
Use the API to get all the data you need at the highest-level scope available. Wait until all needed data is ingested before doing any filtering, grouping, or aggregated analysis. The API is optimized specifically to provide large amounts of unaggregated raw cost data. To learn more about scopes available in Cost Management, see [Understand and work with scopes](./understand-work-scopes.md). Once you've downloaded the needed data for a scope, use Excel to analyze data further with filters and pivot tables.
64
+
To retrieve cost details using the Cost Details API, follow these steps:
62
65
63
-
### Notes about pricing
66
+
### Step 1: Create a report
64
67
65
-
If you want to reconcile usage and charges with your price sheet or invoice, see [Pricing behavior in cost details](../automate/automation-ingest-usage-details-overview.md#pricing-behavior-in-cost-and-usage-details).
68
+
Submit a POST request to start report generation. Replace `{scope}` with your billing account or profile scope.
69
+
70
+
```http
71
+
POST https://management.azure.com/{scope}/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2025-03-01
72
+
Content-Type: application/json
73
+
74
+
{
75
+
"startDate": "2024-06-01",
76
+
"endDate": "2024-06-30"
77
+
}
78
+
```
79
+
80
+
The response will include an `operationId`.
81
+
82
+
### Step 2: Poll for status
83
+
84
+
Check the status of the report generation using the operation ID:
85
+
86
+
```http
87
+
GET https://management.azure.com/{scope}/providers/Microsoft.CostManagement/generateCostDetailsReport/{operationId}?api-version=2025-03-01
88
+
```
89
+
90
+
When the report is ready, the response will include a `downloadUrl` property.
91
+
92
+
### Step 3: Download the report
93
+
94
+
Use the `downloadUrl` to download the CSV file containing your cost details.
95
+
96
+
> [!NOTE]
97
+
> The Cost Details API is asynchronous. You cannot retrieve cost details directly with a GET request to `/costDetails`. Always use the report generation workflow described above. For more information, see the [Cost Details API documentation](https://learn.microsoft.com/rest/api/cost-management/generate-cost-details-report/create-operation).
98
+
99
+
### Best practices for using the Cost Details API
100
+
101
+
-**Request frequency**: Generate reports no more than once per day for a given scope and date range. Cost data is refreshed every four hours, but more frequent requests will return the same data and may be throttled.
102
+
-**Date range**: For large datasets, limit the date range (for example, generate daily or weekly reports) to keep file sizes manageable.
103
+
-**Scope**: Use the highest-level scope available (such as billing account or billing profile) to minimize the number of API calls and ensure data completeness.
104
+
-**Data retention**: Download and store reports promptly. The download URL expires after a short period (typically one hour).
105
+
-**Filtering**: Use filters in the report request to limit data to specific resources, meters, or tags if needed.
106
+
107
+
### Notes about pricing and data
108
+
109
+
- The Cost Details API provides actual and amortized cost data, including all usage, purchases, and adjustments for the selected period.
110
+
- The data is unaggregated and suitable for detailed analysis, reconciliation, and integration with other systems.
111
+
- For more information about pricing behavior, see [Pricing behavior in cost details](../automate/automation-ingest-usage-details-overview.md#pricing-behavior-in-cost-and-usage-details).
66
112
67
113
### A single resource might have multiple records for a single day
68
114
69
-
Azure resource providers emit usage and charges to the billing system and populate the `Additional Info` field of the usage records. Occasionally, resource providers might emit usage for a given day and stamp the records with different datacenters in the `Additional Info` field of the usage records. It can cause multiple records for a meter/resource to be present in your usage file for a single day. In that situation, you aren't overcharged. The multiple records represent the full cost of the meter for the resource on that day.
115
+
Azure resource providers may emit usage and charges to the billing system with different attributes (such as datacenter location), resulting in multiple records for a resource on a single day. This is expected and does not indicate overcharging; all records together represent the full cost for that resource and day.
70
116
71
-
## Example Usage Details API requests
117
+
## Example Cost Details API requests
72
118
73
119
The following example requests are used by Microsoft customers to address common scenarios that you might come across.
74
120
75
-
### Get Usage Details for a scope during specific date range
121
+
### Get Cost Details for a scope during specific date range
76
122
77
123
The data that's returned by the request corresponds to the date when the usage was received by the billing system. It might include costs from multiple invoices. The call to use varies by your subscription type.
78
124
79
-
For legacy customers with an Enterprise Agreement (EA) or a pay-as-you-go subscription, use the following call:
80
-
81
-
```http
82
-
GET https://management.azure.com/{scope}/providers/Microsoft.Consumption/usageDetails?$filter=properties%2FusageStart%20ge%20'2020-02-01'%20and%20properties%2FusageEnd%20le%20'2020-02-29'&$top=1000&api-version=2019-10-01
83
-
```
84
-
85
-
For modern customers with a Microsoft Customer Agreement, use the following call:
125
+
For customers with a Microsoft Customer Agreement, use the following call:
86
126
87
127
```http
88
-
GET https://management.azure.com/{scope}/providers/Microsoft.Consumption/usageDetails?startDate=2020-08-01&endDate=2020-08-05&$top=1000&api-version=2019-10-01
128
+
GET https://management.azure.com/{scope}/providers/Microsoft.CostManagement/costDetails?startDate=2024-06-01&endDate=2024-06-30&$top=1000&api-version=2024-05-01
89
129
```
90
130
91
131
> [!NOTE]
92
-
> The `$filter` parameter isn't supported by Microsoft Customer Agreements.
132
+
> The Cost Details API supports only Microsoft Customer Agreement scopes. For legacy Enterprise Agreement (EA) or pay-as-you-go subscriptions, use Exports or the Query API.
93
133
94
134
### Get amortized cost details
95
135
96
-
If you need actual costs to show purchases as they're accrued, change the *metric* to `ActualCost` in the following request. To use amortized and actual costs, you must use the `2019-04-01-preview` version. The current API version works the same as the `2019-10-01` version, except for the new type/metric attribute and changed property names. If you have a Microsoft Customer Agreement, your filters are `startDate` and `endDate` in the following example.
136
+
If you need actual costs to show purchases as they're accrued, change the *metric* to `ActualCost` in the following request. To use amortized and actual costs, use the latest API version. Your filters are `startDate` and `endDate` in the following example.
97
137
98
138
```http
99
-
GET https://management.azure.com/{scope}/providers/Microsoft.Consumption/usageDetails?metric=AmortizedCost&$filter=properties/usageStart+ge+'2019-04-01'+AND+properties/usageEnd+le+'2019-04-30'&api-version=2019-04-01-preview
139
+
GET https://management.azure.com/{scope}/providers/Microsoft.CostManagement/costDetails?metric=AmortizedCost&startDate=2024-06-01&endDate=2024-06-30&api-version=2024-05-01
100
140
```
101
141
102
142
## Automate alerts and actions with budgets
@@ -324,4 +364,4 @@ List of remaining quotas.
324
364
325
365
-[Analyze Azure costs with the Power BI template app](./analyze-cost-data-azure-cost-management-power-bi-template-app.md).
326
366
-[Create and manage exported data](./tutorial-improved-exports.md) with Exports.
327
-
- Learn more about the [Usage Details API](/rest/api/consumption/usageDetails).
367
+
- Learn more about the [Cost Details API](/rest/api/cost-management/generate-cost-details-report).
0 commit comments