Generate Cost Details Report - Create Operation

  • Reference
Service:
Cost Management
API Version:
2023-11-01

This API is the replacement for all previously release Usage Details APIs. Request to generate a cost details report for the provided date range, billing period (Only enterprise customers) or Invoice Id asynchronously at a certain scope. The initial call to request a report will return a 202 with a 'Location' and 'Retry-After' header. The 'Location' header will provide the endpoint to poll to get the result of the report generation. The 'Retry-After' provides the duration to wait before polling for the generated report. A call to poll the report operation will provide a 202 response with a 'Location' header if the operation is still in progress. Once the report generation operation completes, the polling endpoint will provide a 200 response along with details on the report blob(s) that are available for download. The details on the file(s) available for download will be available in the polling response body. To Understand cost details (formerly known as usage details) fields found in files ,see https://learn.microsoft.com/en-us/azure/cost-management-billing/automate/understand-usage-details-fields

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

URI Parameters

Name In Required Type Description
scope
 path True

string

The ARM Resource ID for subscription, billing account, or other billing scopes.Currently Resource Group and Management Group are not supported. For details, see https://aka.ms/costmgmt/scopes.
api-version
 query True

string

The API version to use for this operation.

Request Body

Name Type Description
billingPeriod

string

This parameter can be used only by Enterprise Agreement customers. Use the YearMonth(e.g. 202008) format. This parameter cannot be used alongside either the invoiceId or timePeriod parameters. If a timePeriod, invoiceId or billingPeriod parameter is not provided in the request body the API will return the current month's cost.
invoiceId

string

This parameter can only be used by Microsoft Customer Agreement customers. Additionally, it can only be used at the Billing Profile or Customer scope. This parameter cannot be used alongside either the billingPeriod or timePeriod parameters. If a timePeriod, invoiceId or billingPeriod parameter is not provided in the request body the API will return the current month's cost.
metric

CostDetailsMetricType

The type of the detailed report. By default ActualCost is provided
timePeriod

CostDetailsTimePeriod

The specific date range of cost details requested for the report. This parameter cannot be used alongside either the invoiceId or billingPeriod parameters. If a timePeriod, invoiceId or billingPeriod parameter is not provided in the request body the API will return the current month's cost. API only allows data to be pulled for 1 month or less and no older than 13 months. If no timePeriod or billingPeriod or invoiceId is provided the API defaults to the open month time period

Responses

Name Type Description
200 OK

CostDetailsOperationResults

Request processing completed.
202 Accepted

Accepted. Request will be processed. Use the Location header to check the status.

Headers

  • Location: string
  • Retry-After: integer
204 No Content

No Content. The request has succeeded but returned no results.
Other Status Codes

GenerateCostDetailsReportErrorResponse

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

GenerateCostDetailsReportByBillingAccountEnterpriseAgreementCustomerAndBillingPeriod
GenerateCostDetailsReportByBillingProfileAndInvoiceId
GenerateCostDetailsReportByBillingProfileAndInvoiceIdAndCustomerId
GenerateCostDetailsReportByCustomerAndTimePeriod
GenerateCostDetailsReportByDepartmentsAndTimePeriod
GenerateCostDetailsReportByEnrollmentAccountsAndTimePeriod
GenerateCostDetailsReportBySubscriptionAndTimePeriod

GenerateCostDetailsReportByBillingAccountEnterpriseAgreementCustomerAndBillingPeriod

Sample Request

POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2023-11-01

{
  "metric": "ActualCost",
  "billingPeriod": "202205"
}

Sample Response

Status code:
200 
{
  "id": "providers/Microsoft.Billing/billingAccounts/12345/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2023-11-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 32741,
    "compressData": false,
    "requestContext": {
      "requestScope": "providers/Microsoft.Billing/billingAccounts/12345",
      "requestBody": {
        "metric": "ActualCost",
        "billingPeriod": "202205"
      }
    },
    "blobs": [
      {
        "blobLink": "https://ccmreportstorageeastus.blob.core.windows.net/armreports/00000/00000000-0000-0000-0000-000000000000?sv=2020-05-31&sr=b&sig=abcd",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}
Status code:
202 
Location: https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000?api-version=2023-11-01
Retry-After: 60
Status code:
204

GenerateCostDetailsReportByBillingProfileAndInvoiceId

Sample Request

POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/billingProfiles/13579/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2023-11-01

{
  "metric": "ActualCost",
  "invoiceId": "M1234567"
}

Sample Response

Status code:
200 
{
  "id": "providers/Microsoft.Billing/billingAccounts/12345:6789/billingProfiles/13579/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2023-11-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 32741,
    "compressData": false,
    "requestContext": {
      "requestScope": "providers/Microsoft.Billing/billingAccounts/12345:6789/billingProfiles/13579",
      "requestBody": {
        "metric": "ActualCost",
        "billingPeriod": "202205"
      }
    },
    "blobs": [
      {
        "blobLink": "https://ccmreportstorageeastus.blob.core.windows.net/armreports/00000/00000000-0000-0000-0000-000000000000?sv=2020-05-31&sr=b&sig=abcd",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}
Status code:
202 
Location: https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/billingProfiles/13579/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000?api-version=2023-11-01
Retry-After: 60
Status code:
204

GenerateCostDetailsReportByBillingProfileAndInvoiceIdAndCustomerId

Sample Request

POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/customers/13579/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2023-11-01

{
  "metric": "ActualCost",
  "invoiceId": "M1234567"
}

Sample Response

Status code:
200 
{
  "id": "providers/Microsoft.Billing/billingAccounts/12345:6789/customers/13579/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2023-11-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 32741,
    "compressData": false,
    "requestContext": {
      "requestScope": "providers/Microsoft.Billing/billingAccounts/12345:6789/customers/13579",
      "requestBody": {
        "metric": "ActualCost",
        "billingPeriod": "202205"
      }
    },
    "blobs": [
      {
        "blobLink": "https://ccmreportstorageeastus.blob.core.windows.net/armreports/00000/00000000-0000-0000-0000-000000000000?sv=2020-05-31&sr=b&sig=abcd",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}
Status code:
202 
Location: https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/customers/13579/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000?api-version=2023-11-01
Retry-After: 60
Status code:
204

GenerateCostDetailsReportByCustomerAndTimePeriod

Sample Request

POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/customers/13579/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2023-11-01

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

Sample Response

Status code:
200 
{
  "id": "providers/Microsoft.Billing/billingAccounts/12345:6789/customers/13579/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2023-11-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 32741,
    "compressData": false,
    "requestContext": {
      "requestScope": "providers/Microsoft.Billing/billingAccounts/12345:6789/customers/13579",
      "requestBody": {
        "metric": "ActualCost",
        "timePeriod": {
          "start": "2020-03-01",
          "end": "2020-03-15"
        }
      }
    },
    "blobs": [
      {
        "blobLink": "https://ccmreportstorageeastus.blob.core.windows.net/armreports/00000/00000000-0000-0000-0000-000000000000?sv=2020-05-31&sr=b&sig=abcd",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}
Status code:
202 
Location: https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/customers/13579/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000?api-version=2023-11-01
Retry-After: 60
Status code:
204

GenerateCostDetailsReportByDepartmentsAndTimePeriod

Sample Request

POST https://management.azure.com/providers/Microsoft.Billing/departments/12345/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2023-11-01

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

Sample Response

Status code:
200 
{
  "id": "providers/Microsoft.Billing/departments/12345/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2023-11-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 32741,
    "compressData": false,
    "requestContext": {
      "requestScope": "providers/Microsoft.Billing/departments/12345",
      "requestBody": {
        "metric": "ActualCost",
        "timePeriod": {
          "start": "2020-03-01",
          "end": "2020-03-15"
        }
      }
    },
    "blobs": [
      {
        "blobLink": "https://ccmreportstorageeastus.blob.core.windows.net/armreports/00000/00000000-0000-0000-0000-000000000000?sv=2020-05-31&sr=b&sig=abcd",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}
Status code:
202 
Location: https://management.azure.com/providers/Microsoft.Billing/departments/12345/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000?api-version=2023-11-01
Retry-After: 60
Status code:
204

GenerateCostDetailsReportByEnrollmentAccountsAndTimePeriod

Sample Request

POST https://management.azure.com/providers/Microsoft.Billing/enrollmentAccounts/1234/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2023-11-01

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

Sample Response

Status code:
200 
{
  "id": "providers/Microsoft.Billing/enrollmentAccounts/1234/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2023-11-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 32741,
    "compressData": false,
    "requestContext": {
      "requestScope": "providers/Microsoft.Billing/enrollmentAccounts/1234",
      "requestBody": {
        "metric": "ActualCost",
        "timePeriod": {
          "start": "2020-03-01",
          "end": "2020-03-15"
        }
      }
    },
    "blobs": [
      {
        "blobLink": "https://ccmreportstorageeastus.blob.core.windows.net/armreports/00000/00000000-0000-0000-0000-000000000000?sv=2020-05-31&sr=b&sig=abcd",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}
Status code:
202 
Location: https://management.azure.com/providers/Microsoft.Billing/enrollmentAccounts/1234/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000?api-version=2023-11-01
Retry-After: 60
Status code:
204

GenerateCostDetailsReportBySubscriptionAndTimePeriod

Sample Request

POST https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2023-11-01

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

Sample Response

Status code:
200 
{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2023-11-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 32741,
    "compressData": false,
    "requestContext": {
      "requestScope": "subscriptions/00000000-0000-0000-0000-000000000000",
      "requestBody": {
        "metric": "ActualCost",
        "timePeriod": {
          "start": "2020-03-01",
          "end": "2020-03-15"
        }
      }
    },
    "blobs": [
      {
        "blobLink": "https://ccmreportstorageeastus.blob.core.windows.net/armreports/00000/00000000-0000-0000-0000-000000000000?sv=2020-05-31&sr=b&sig=abcd",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}
Status code:
202 
Location: https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/costDetailsOperationResults/00000000-0000-0000-0000-000000000000?api-version=2023-11-01
Retry-After: 60
Status code:
204

Definitions

Name Description
BlobInfo

The blob information generated by this operation.
CostDetailsDataFormat

The data format of the report
CostDetailsMetricType

The type of the detailed report. By default ActualCost is provided
CostDetailsOperationResults

The result of the long running operation for cost details Api.
CostDetailsStatusType

The status of the cost details operation
CostDetailsTimePeriod

The start and end date for pulling data for the cost detailed report. API only allows data to be pulled for 1 month or less and no older than 13 months.
ErrorDetails

The details of the error.
GenerateCostDetailsReportErrorResponse

Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Some Error responses:

  • 400 Bad Request - Invalid Request Payload. Request payload provided is not in a json format or had an invalid member not accepted in the request payload.

  • 400 Bad Request - Invalid request payload: can only have either timePeriod or invoiceId or billingPeriod. API only allows data to be pulled for either timePeriod or invoiceId or billingPeriod. Customer should provide only one of these parameters.

  • 400 Bad Request - Start date must be after . API only allows data to be pulled no older than 13 months from now.

  • 400 Bad Request - The maximum allowed date range is 1 months. API only allows data to be pulled for 1 month or less.

  • 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "retry-after" header.

  • 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.
GenerateCostDetailsReportRequestDefinition

The definition of a cost detailed report.

BlobInfo

The blob information generated by this operation.

Name Type Description
blobLink

string

Link to the blob to download file.
byteCount

integer

Bytes in the blob.

CostDetailsDataFormat

The data format of the report

Name Type Description
Csv

string

Csv data format.

CostDetailsMetricType

The type of the detailed report. By default ActualCost is provided

Name Type Description
ActualCost

string

Actual cost data.
AmortizedCost

string

Amortized cost data.

CostDetailsOperationResults

The result of the long running operation for cost details Api.

Name Type Description
error

ErrorDetails

The details of the error.
id

string

The id of the long running operation.
manifest.blobCount

integer

The total number of blobs.
manifest.blobs

BlobInfo[]

List of blob information generated by this operation.
manifest.byteCount

integer

The total number of bytes in all blobs.
manifest.compressData

boolean

Is the data in compressed format.
manifest.dataFormat

CostDetailsDataFormat

The data format of the report
manifest.manifestVersion

string

The Manifest version.
manifest.requestContext.requestBody

GenerateCostDetailsReportRequestDefinition

The request payload body provided in Cost Details call
manifest.requestContext.requestScope

string

The request scope of the request.
name

string

The name of the long running operation.
status

CostDetailsStatusType

The status of the cost details operation
type

string

The type of the long running operation.
validTill

string

The time at which report URL becomes invalid/expires in UTC e.g. 2020-12-08T05:55:59.4394737Z.

CostDetailsStatusType

The status of the cost details operation

Name Type Description
Completed

string

Operation is Completed.
Failed

string

Operation Failed.
NoDataFound

string

Operation is Completed and no cost data found.

CostDetailsTimePeriod

The start and end date for pulling data for the cost detailed report. API only allows data to be pulled for 1 month or less and no older than 13 months.

Name Type Description
end

string

The end date to pull data to. example format 2020-03-15
start

string

The start date to pull data from. example format 2020-03-15

ErrorDetails

The details of the error.

Name Type Description
code

string

Error code.
message

string

Error message indicating why the operation failed.

GenerateCostDetailsReportErrorResponse

Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Some Error responses:

  • 400 Bad Request - Invalid Request Payload. Request payload provided is not in a json format or had an invalid member not accepted in the request payload.

  • 400 Bad Request - Invalid request payload: can only have either timePeriod or invoiceId or billingPeriod. API only allows data to be pulled for either timePeriod or invoiceId or billingPeriod. Customer should provide only one of these parameters.

  • 400 Bad Request - Start date must be after . API only allows data to be pulled no older than 13 months from now.

  • 400 Bad Request - The maximum allowed date range is 1 months. API only allows data to be pulled for 1 month or less.

  • 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "retry-after" header.

  • 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.

Name Type Description
error

ErrorDetails

The details of the error.

GenerateCostDetailsReportRequestDefinition

The definition of a cost detailed report.

Name Type Description
billingPeriod

string

This parameter can be used only by Enterprise Agreement customers. Use the YearMonth(e.g. 202008) format. This parameter cannot be used alongside either the invoiceId or timePeriod parameters. If a timePeriod, invoiceId or billingPeriod parameter is not provided in the request body the API will return the current month's cost.
invoiceId

string

This parameter can only be used by Microsoft Customer Agreement customers. Additionally, it can only be used at the Billing Profile or Customer scope. This parameter cannot be used alongside either the billingPeriod or timePeriod parameters. If a timePeriod, invoiceId or billingPeriod parameter is not provided in the request body the API will return the current month's cost.
metric

CostDetailsMetricType

The type of the detailed report. By default ActualCost is provided
timePeriod

CostDetailsTimePeriod

The specific date range of cost details requested for the report. This parameter cannot be used alongside either the invoiceId or billingPeriod parameters. If a timePeriod, invoiceId or billingPeriod parameter is not provided in the request body the API will return the current month's cost. API only allows data to be pulled for 1 month or less and no older than 13 months. If no timePeriod or billingPeriod or invoiceId is provided the API defaults to the open month time period