Microsoft Azure UsageDetails API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Usage Details API
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: '#/components/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
        schema:
          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
        schema:
          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
        schema:
          type: string
      - name: $top
        description: May be used to limit the number of results to the most recent N usageDetails.
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
      - $ref: '#/components/parameters/apiVersionParameter'
      - $ref: '#/components/parameters/metricParameter'
      responses:
        '200':
          description: OK. The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageDetailsListResult'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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: '#/components/parameters/scopeUsageDetailsParameter'
      - $ref: '#/components/parameters/apiVersionParameter'
      - $ref: '#/components/parameters/metricParameter'
      responses:
        '200':
          description: OK. The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageDetailsDownloadResponse'
        '202':
          description: Accepted.
          headers:
            Location:
              description: GET this URL to retrieve the status of the asynchronous operation.
              schema:
                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.
              schema:
                type: string
            Azure-AsyncOperation:
              description: To get the progress of the operation, call GET operation on the URL in Azure-AsyncOperation header field.
              schema:
                type: string
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Microsoft Azure Post Scope Providers Microsoft Consumption Usagedetails Download
components:
  schemas:
    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: '#/components/schemas/ErrorDetails'
    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
    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: '#/components/schemas/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
    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
    UsageDetail:
      description: An usage detail resource.
      type: object
      allOf:
      - $ref: '#/components/schemas/Resource'
      properties:
        properties:
          x-ms-client-flatten: true
          $ref: '#/components/schemas/UsageDetailProperties'
          title: Usage detail properties
    UsageDetailsDownloadResponse:
      description: Download response of Usage Details.
      type: object
      allOf:
      - $ref: '#/components/schemas/Resource'
      properties:
        properties:
          x-ms-client-flatten: true
          $ref: '#/components/schemas/DownloadUrl'
          title: Download url properties.
    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: '#/components/schemas/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
    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
  parameters:
    apiVersionParameter:
      name: api-version
      in: query
      required: true
      description: Version of the API to be used with the client request. The current version is 2019-04-01-preview.
      schema:
        type: string
    scopeUsageDetailsParameter:
      name: scope
      in: path
      required: true
      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
      schema:
        type: string
    metricParameter:
      name: metric
      in: query
      description: Allows to select different type of cost/usage records.
      required: false
      x-ms-parameter-location: method
      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
      schema:
        type: string
        enum:
        - actualcost
        - amortizedcost
        - usage
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'