Introduction

The IBM Cloud™ Usage Reports API provides details about the usage quantity and cost of resources in an account. Usage details are reported by the month in which they were incurred. Usage quantities and their corresponding costs are aggregated at the following levels:

  • Individual resource instances
  • Cloud Foundry organization or resource group
  • Entire account (all resources)

Endpoint

You access the Usage Reports API by sending requests to the https://billing.cloud.ibm.com endpoint.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Authentication

Access to the Usage Reporting API is enforced through both IBM Cloud Identity and Access Management (IAM) access tokens and Cloud Foundry access roles. For more information, see Managing access in IBM Cloud.

To work with the API, authenticate your app or service by including your IBM Cloud IAM access token in the API request authentication header:

-H 'Authorization: Bearer <IAM_TOKEN>'

You can retrieve an access token by first creating an API key, and then exchanging your API key for a IBM Cloud IAM token. For more information, see Getting an IBM Cloud IAM token by using an API key.

Methods

Get account billing summary

Returns the billing summary for the account for a given month. Users with the Administrator role on the Billing service can access this report.

GET /v4/accounts/{account_id}/summary/{billingmonth}
Request

Path Parameters

  • Account ID for which the summary is requested

  • Billing month for which the summary is requested in yyyy-mm format.

    Constraints: Value must match regular expression ^\d{4}\-(0?[1-9]|1[012])$

Response

Summary for the account for a given month.

Status Code

  • Account Summary

  • Unauthenticated

  • Unauthorized

  • Unexpected errors

Example responses

Get account usage

Returns aggregated usage for all of the resources and plans in an account in a given month. Users with the Administrator role on the Billing service can access this report.

GET /v4/accounts/{account_id}/usage/{billingmonth}
Request

Path Parameters

  • Account ID for which the usage is requested

  • Month for which the usage is requested

    Constraints: Value must match regular expression ^\d{4}\-(0?[1-9]|1[012])$

Response

Aggregated usage and charges for all the plans in the account

Status Code

  • Status 200

  • Unauthenticated

  • Unauthorized

  • Unexpected errors

Example responses

Get resource group usage

Returns aggregated usage for all of the resources and plans in a resource group in a given month. Users with the Administrator role on the Billing service can access this report.

GET /v4/accounts/{account_id}/resource_groups/{resource_group_id}/usage/{billingmonth}
Request

Path Parameters

  • Account ID containing the resource group

  • Resource group for which the usage is requested

  • Month for which the usage is requested

    Constraints: Value must match regular expression ^\d{4}\-(0?[1-9]|1[012])$

Response

Aggregated usage and charges for all the plans in the resource group

Status Code

  • Status 200

  • Unauthenticated

  • Unauthorized

  • Unexpected errors

Example responses

Get Cloud Foundry org usage

Returns aggregated usage for all the resources and plans in a Cloud Foundry organization in a given month. Users with the Administrator role on the Billing service or the Billing Manager role on the Cloud Foundry org can access this report.

GET /v4/accounts/{account_id}/organizations/{organization_id}/usage/{billingmonth}
Request

Path Parameters

  • ID of the account containing the organization

  • ID of the organization

  • Month for which the usage is requested

    Constraints: Value must match regular expression ^\d{4}\-(0?[1-9]|1[012])$

Response

Aggregated usage and charges for all the plans in the org

Status Code

  • Status 200

  • Unauthenticated

  • Unauthorized

  • Unexpected errors

Example responses

Get resource instance usage in an account

Returns instance-level usage for resources in an account. Filter the results with query parameters. Users with the Administrator role on the Billing service can access this report.

GET /v4/accounts/{account_id}/resource_instances/usage/{billingmonth}
Request

Path Parameters

  • Account ID to which the resource instances belong to

  • Month for which the usage is requested

    Constraints: Value must match regular expression ^\d{4}\-(0?[1-9]|1[012])$

Query Parameters

  • Number of usage records returned. The default value is 10. Maximum value is 20.

    Constraints: 1 ≤ value ≤ 20

    Default: 10

  • The offset from which the records must be fetched. Offset information is included in the response.

  • Filter by resource group

  • Filter by organization_id

  • Filter by resource instance id

  • Filter by resource_id

  • Filter by plan_id

  • Region in which the resource instance is provisioned

Response

List of instnace usage reports

Status Code

  • Status 200

  • Status 400

  • Status 401

  • Status 500

Example responses

Get resource instance usage in a resource group

Returns instance-level usage for resources in a resource group. Filter the results with query parameters. Users with the Administrator role on the Billing service can access this report.

GET /v4/accounts/{account_id}/resource_groups/{resource_group_id}/resource_instances/usage/{billingmonth}
Request

Path Parameters

  • ID of the account in which the resource group is present

  • ID of the resource group

  • Month for which the usage is requested

    Constraints: Value must match regular expression ^\d{4}\-(0?[1-9]|1[012])$

Query Parameters

  • Number of usage records returned. The default value is 10. Maximum value is 20.

    Constraints: 1 ≤ value ≤ 20

    Default: 10

  • The offset from which the records must be fetched. Offset information is included in the response.

  • Filter by resource instance id

  • Filter by resource_id

  • Filter by plan_id

  • Region in which the resource instance is provisioned

Response

List of instnace usage reports

Status Code

  • Status 200

  • Status 400

  • Status 401

  • Status 500

Example responses

Get resource instance usage in a Cloud Foundry org

Returns instance-level usage for resources in a Cloud Foundry organization. Filter the results with query parameters. Users with the Administrator role on the Billing service or the Billing Manager role on the Cloud Foundry org can access this report.

GET /v4/accounts/{account_id}/organizations/{organization_id}/resource_instances/usage/{billingmonth}
Request

Path Parameters

  • ID of the account under which the organization is present

  • ID of the organization

  • Month for which the usage is requested

    Constraints: Value must match regular expression ^\d{4}\-(0?[1-9]|1[012])$

Query Parameters

  • Number of usage records returned. The default value is 10. Maximum value is 20.

    Constraints: 1 ≤ value ≤ 20

    Default: 10

  • The offset from which the records must be fetched. Offset information is included in the response.

  • Filter by resource instance id

  • Filter by resource_id

  • Filter by plan_id

  • Region in which the resource instance is provisioned

Response

List of instnace usage reports

Status Code

  • Status 200

  • Status 400

  • Status 401

  • Status 500

Example responses