Microsoft Azure UsageDetails API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector UsageDetails API
schemes:
- https
tags:
- name: UsageDetails
paths:
  /{scope}/providers/Microsoft.Consumption/usageDetails:
    get:
      tags:
      - UsageDetails
      operationId: microsoftAzureUsagedetailsList
      description: Lists the usage details for the defined scope. Usage details are available via this API only for May 1, 2014 or later.
      externalDocs:
        url: https://docs.microsoft.com/en-us/rest/api/consumption/
      x-ms-examples:
        UsageDetailsList:
          $ref: ./examples/UsageDetailsList.json
        UsageDetailsListFilterByTag:
          $ref: ./examples/UsageDetailsListFilterByTag.json
        UsageDetailsListForBillingPeriod:
          $ref: ./examples/UsageDetailsListForBillingPeriod.json
        UsageDetailsExpand:
          $ref: ./examples/UsageDetailsExpand.json
        UsageDetailsListByMetricActualCost:
          $ref: ./examples/UsageDetailsListByMetricActualCost.json
        UsageDetailsListByMetricAmortizedCost:
          $ref: ./examples/UsageDetailsListByMetricAmortizedCost.json
        UsageDetailsListByMetricUsage:
          $ref: ./examples/UsageDetailsListByMetricUsage.json
        BillingAccountUsageDetailsList:
          $ref: ./examples/UsageDetailsListByBillingAccount.json
        BillingAccountUsageDetailsListForBillingPeriod:
          $ref: ./examples/UsageDetailsListForBillingPeriodByBillingAccount.json
        DepartmentUsageDetailsList:
          $ref: ./examples/UsageDetailsListByDepartment.json
        DepartmentUsageDetailsListForBillingPeriod:
          $ref: ./examples/UsageDetailsListForBillingPeriodByDepartment.json
        EnrollmentAccountUsageDetailsList:
          $ref: ./examples/UsageDetailsListByEnrollmentAccount.json
        EnrollmentAccountUsageDetailsListForBillingPeriod:
          $ref: ./examples/UsageDetailsListForBillingPeriodByEnrollmentAccount.json
        ManagementGroupUsageDetailsList:
          $ref: ./examples/UsageDetailsListByManagementGroup.json
        ManagementGroupUsageDetailsListForBillingPeriod:
          $ref: ./examples/UsageDetailsListForBillingPeriodByManagementGroup.json
      parameters:
      - $ref: '#/parameters/scopeUsageDetailsParameter'
      - name: $expand
        description: May be used to expand the properties/additionalInfo or properties/meterDetails within a list of usage details. By default, these fields are not included when listing usage details.
        in: query
        required: false
        type: string
      - name: $filter
        description: May be used to filter usageDetails by properties/resourceGroup, properties/resourceName, properties/resourceId, properties/chargeType, properties/reservationId or tags. The filter supports 'eq', 'lt', 'gt', 'le', 'ge', and 'and'. It does not currently support 'ne', 'or', or 'not'. Tag filter is a key value pair string where key and value is separated by a colon (:).
        in: query
        required: false
        type: string
      - name: $skiptoken
        description: Skiptoken is only used if a previous operation returned a partial result. If a previous response contains a nextLink element, the value of the nextLink element will include a skiptoken parameter that specifies a starting point to use for subsequent calls.
        in: query
        required: false
        type: string
      - name: $top
        description: May be used to limit the number of results to the most recent N usageDetails.
        in: query
        required: false
        type: integer
        minimum: 1
        maximum: 1000
      - $ref: '#/parameters/apiVersionParameter'
      - $ref: '#/parameters/metricParameter'
      responses:
        '200':
          description: OK. The request has succeeded.
          schema:
            $ref: '#/definitions/UsageDetailsListResult'
        default:
          description: Error response describing why the operation failed.
          schema:
            $ref: '#/definitions/ErrorResponse'
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Microsoft Azure Get Scope Providers Microsoft Consumption Usagedetails
  /{scope}/providers/Microsoft.Consumption/usageDetails/download:
    post:
      tags:
      - UsageDetails
      x-ms-examples:
        UsageDetailsDownload:
          $ref: ./examples/UsageDetailsDownload.json
        UsageDetailsDownloadByMetricUsage:
          $ref: ./examples/UsageDetailsDownloadByMetricUsage.json
      operationId: microsoftAzureUsagedetailsDownload
      x-ms-long-running-operation: true
      x-ms-long-running-operation-options:
        final-state-via: location
      description: Download usage details data.
      parameters:
      - $ref: '#/parameters/scopeUsageDetailsParameter'
      - $ref: '#/parameters/apiVersionParameter'
      - $ref: '#/parameters/metricParameter'
      responses:
        '200':
          description: OK. The request has succeeded.
          schema:
            $ref: '#/definitions/UsageDetailsDownloadResponse'
        '202':
          description: Accepted.
          headers:
            Location:
              description: GET this URL to retrieve the status of the asynchronous operation.
              type: string
            Retry-After:
              description: The amount of delay to use while the status of the operation is checked. The value is expressed in seconds.
              type: string
            Azure-AsyncOperation:
              description: To get the progress of the operation, call GET operation on the URL in Azure-AsyncOperation header field.
              type: string
        default:
          description: Error response describing why the operation failed.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Post Scope Providers Microsoft Consumption Usagedetails Download
definitions:
  ErrorResponse:
    description: Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.
    type: object
    properties:
      error:
        description: The details of the error.
        $ref: '#/definitions/ErrorDetails'
  UsageDetailsListResult:
    description: Result of listing usage details. It contains a list of available usage details in reverse chronological order by billing period.
    properties:
      value:
        description: The list of usage details.
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/UsageDetail'
      nextLink:
        description: The link (url) to the next page of results.
        type: string
        readOnly: true
  Resource:
    description: The Resource model definition.
    properties:
      id:
        readOnly: true
        type: string
        description: Resource Id.
      name:
        readOnly: true
        type: string
        description: Resource name.
      type:
        readOnly: true
        type: string
        description: Resource type.
      tags:
        readOnly: true
        type: object
        additionalProperties:
          type: string
        description: Resource tags.
    x-ms-azure-resource: true
  UsageDetailsDownloadResponse:
    description: Download response of Usage Details.
    type: object
    allOf:
    - $ref: '#/definitions/Resource'
    properties:
      properties:
        x-ms-client-flatten: true
        $ref: '#/definitions/DownloadUrl'
        title: Download url properties.
  ErrorDetails:
    description: The details of the error.
    properties:
      code:
        description: Error code.
        type: string
        readOnly: true
      message:
        description: Error message indicating why the operation failed.
        type: string
        readOnly: true
  DownloadUrl:
    description: A secure URL that can be used to download a an entity until the URL expires.
    properties:
      downloadUrl:
        description: The URL to the csv file.
        type: string
        readOnly: true
      validTill:
        description: The time in UTC at which this download URL will expire.
        type: string
        readOnly: true
  UsageDetailProperties:
    description: The properties of the usage detail.
    properties:
      billingAccountId:
        description: Billing Account identifier.
        type: string
        readOnly: true
      billingAccountName:
        description: Billing Account Name.
        type: string
        readOnly: true
      billingPeriodStartDate:
        description: The billing period start date.
        type: string
        format: date-time
        readOnly: true
      billingPeriodEndDate:
        description: The billing period end date.
        type: string
        format: date-time
        readOnly: true
      billingProfileId:
        description: Billing Profile identifier.
        type: string
        readOnly: true
      billingProfileName:
        description: Billing Profile Name.
        type: string
        readOnly: true
      accountOwnerId:
        description: Account Owner Id.
        type: string
        readOnly: true
      accountName:
        description: Account Name.
        type: string
        readOnly: true
      subscriptionId:
        description: Subscription guid.
        type: string
        readOnly: true
      subscriptionName:
        description: Subscription name.
        type: string
        readOnly: true
      date:
        description: Date for the usage record.
        type: string
        format: date-time
        readOnly: true
      product:
        description: Product name for the consumed service or purchase. Not available for Marketplace.
        type: string
        readOnly: true
      partNumber:
        description: Part Number of the service used. Can be used to join with the price sheet. Not available for marketplace.
        type: string
        readOnly: true
      meterId:
        description: The meter id (GUID). Not available for marketplace. For reserved instance this represents the primary meter for which the reservation was purchased. For the actual VM Size for which the reservation is purchased see productOrderName.
        type: string
        format: uuid
        readOnly: true
      meterDetails:
        description: The details about the meter. By default this is not populated, unless it's specified in $expand.
        $ref: '#/definitions/MeterDetailsResponse'
        readOnly: true
      quantity:
        description: The usage quantity.
        type: number
        format: decimal
        readOnly: true
      effectivePrice:
        description: Effective Price that’s charged for the usage.
        type: number
        format: decimal
        readOnly: true
      cost:
        description: The amount of cost before tax.
        type: number
        format: decimal
        readOnly: true
      unitPrice:
        description: Unit Price is the price applicable to you. (your EA or other contract price).
        type: number
        format: decimal
        readOnly: true
      billingCurrency:
        description: Billing Currency.
        type: string
        readOnly: true
      resourceLocation:
        description: Resource Location.
        type: string
        readOnly: true
      consumedService:
        description: Consumed service name. Name of the azure resource provider that emits the usage or was purchased. This value is not provided for marketplace usage.
        type: string
        readOnly: true
      resourceId:
        description: Azure resource manager resource identifier.
        type: string
        readOnly: true
      resourceName:
        description: Resource Name.
        type: string
        readOnly: true
      serviceInfo1:
        description: Service Info 1.
        type: string
        readOnly: true
      serviceInfo2:
        description: Service Info 2.
        type: string
        readOnly: true
      additionalInfo:
        description: Additional details of this usage item. By default this is not populated, unless it's specified in $expand. Use this field to get usage line item specific details such as the actual VM Size (ServiceType) or the ratio in which the reservation discount is applied.
        type: string
        readOnly: true
      invoiceSection:
        description: Invoice Section Name.
        type: string
        readOnly: true
      costCenter:
        description: The cost center of this department if it is a department and a cost center is provided.
        type: string
        readOnly: true
      resourceGroup:
        description: Resource Group Name.
        type: string
        readOnly: true
      reservationId:
        description: ARM resource id of the reservation. Only applies to records relevant to reservations.
        type: string
        readOnly: true
      reservationName:
        description: User provided display name of the reservation. Last known name for a particular day is populated in the daily data. Only applies to records relevant to reservations.
        type: string
        readOnly: true
      productOrderId:
        description: Product Order Id. For reservations this is the Reservation Order ID.
        type: string
        readOnly: true
      productOrderName:
        description: Product Order Name. For reservations this is the SKU that was purchased.
        type: string
        readOnly: true
      offerId:
        description: 'Offer Id. Ex: MS-AZR-0017P, MS-AZR-0148P.'
        type: string
        readOnly: true
      isAzureCreditEligible:
        description: Is Azure Credit Eligible.
        type: boolean
        readOnly: true
      term:
        description: Term (in months). 1 month for monthly recurring purchase. 12 months for a 1 year reservation. 36 months for a 3 year reservation.
        type: string
        readOnly: true
      publisherName:
        description: Publisher Name.
        type: string
        readOnly: true
      publisherType:
        description: Publisher Type.
        type: string
        readOnly: true
      planName:
        description: Plan Name.
        type: string
        readOnly: true
      chargeType:
        description: Indicates a charge represents credits, usage, a Marketplace purchase, a reservation fee, or a refund.
        type: string
        readOnly: true
      frequency:
        description: Indicates how frequently this charge will occur. OneTime for purchases which only happen once, Monthly for fees which recur every month, and UsageBased for charges based on how much a service is used.
        type: string
        readOnly: true
  UsageDetail:
    description: An usage detail resource.
    type: object
    allOf:
    - $ref: '#/definitions/Resource'
    properties:
      properties:
        x-ms-client-flatten: true
        $ref: '#/definitions/UsageDetailProperties'
        title: Usage detail properties
  MeterDetailsResponse:
    description: The properties of the meter detail.
    properties:
      meterName:
        description: The name of the meter, within the given meter category
        type: string
        readOnly: true
      meterCategory:
        description: The category of the meter, for example, 'Cloud services', 'Networking', etc..
        type: string
        readOnly: true
      meterSubCategory:
        description: The subcategory of the meter, for example, 'A6 Cloud services', 'ExpressRoute (IXP)', etc..
        type: string
        readOnly: true
      unitOfMeasure:
        description: The unit in which the meter consumption is charged, for example, 'Hours', 'GB', etc.
        type: string
        readOnly: true
      serviceFamily:
        description: The service family.
        type: string
        readOnly: true
parameters:
  metricParameter:
    name: metric
    in: query
    description: Allows to select different type of cost/usage records.
    required: false
    type: string
    x-ms-parameter-location: method
    enum:
    - actualcost
    - amortizedcost
    - usage
    x-ms-enum:
      name: metrictype
      modelAsString: true
      values:
      - value: actualcost
        description: Actual cost data.
        name: ActualCostMetricType
      - value: amortizedcost
        description: Amortized cost data.
        name: AmortizedCostMetricType
      - value: usage
        description: Usage data.
        name: UsageMetricType
  apiVersionParameter:
    name: api-version
    in: query
    required: true
    type: string
    description: Version of the API to be used with the client request. The current version is 2019-04-01-preview.
  scopeUsageDetailsParameter:
    name: scope
    in: path
    required: true
    type: string
    description: The scope associated with usage details operations. This includes '/subscriptions/{subscriptionId}/' for subscription scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for Billing Account scope, '/providers/Microsoft.Billing/departments/{departmentId}' for Department scope, '/providers/Microsoft.Billing/enrollmentAccounts/{enrollmentAccountId}' for EnrollmentAccount scope and '/providers/Microsoft.Management/managementGroups/{managementGroupId}' for Management Group scope. For subscription, billing account, department, enrollment account and management group, you can also add billing period to the scope using '/providers/Microsoft.Billing/billingPeriods/{billingPeriodName}'. For e.g. to specify billing period at department scope use '/providers/Microsoft.Billing/departments/{departmentId}/providers/Microsoft.Billing/billingPeriods/{billingPeriodName}'
    x-ms-parameter-location: method
    x-ms-skip-url-encoding: true
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'