Enterprise Usage Reports API | IBM Cloud API Docs

Introduction

Last updated: 2022-10-25

The Enterprise Usage Reports API (Beta) provides access to the usage reports for entities that are managed by an IBM Cloud® enterprise. Usage reports are provided for three types of entities: an enterprise, an account group, and an account. You can query for usage reports for an entity or its immediate children in the enterprise hierarchy. This API is a beta release.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

API endpoint

https://enterprise.cloud.ibm.com

Installing the Java SDK

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>enterprise-usage-reports</artifactId>
    <version>{version}</version>
</dependency>
Copy to clipboard

Gradle

compile 'com.ibm.cloud:enterprise-usage-reports:{version}'

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-java-sdk

Installing the Go SDK

Installation

go get -u github.com/IBM/platform-services-go-sdk/enterpriseusagereportsv1

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-go-sdk

Installing the Node SDK

Installation

npm install @ibm-cloud/platform-services

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

Installation

pip install --upgrade "ibm-platform-services"

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-python-sdk

Endpoint URLs

The Enterprise Usage Reports API uses the following global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://enterprise.cloud.ibm.com/v1/resource-usage-reports

If you enabled service endpoints in your account, you can send API requests over the IBM Cloud® private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.

Private endpoint URL for VPC infrastructure: https://private.enterprise.cloud.ibm.com/v1/resource-usage-reports
Private endpoint URLs for classic infrastructure:
- Dallas: https://private.us-south.enterprise.cloud.ibm.com/v1/resource-usage-reports
- Washington DC: https://private.us-east.enterprise.cloud.ibm.com/v1/resource-usage-reports

Base URL

https://enterprise.cloud.ibm.com/v1/resource-usage-reports

Authentication

Access to the Enterprise Usage Reports API is enforced through IBM Cloud Identity and Access Management (IAM) access tokens. The access control is hierarchical. The subject that calls the API must have one of the following roles on the Enterprise service for the entity to retrieve any report under the entity hierarchy.

Administrator
Editor
Usage Reports Viewer

Each method lists the specific IAM action that you need to be assigned a role to access. For more information about these roles, see Assigning enterprise access.

The user or service must pass a valid IAM token in the Authorization header. The token is used to identify the subject.

-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 IAM token. For more information, see Getting an IBM Cloud IAM token by using an API key.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey={api_key}'
Copy to clipboard

Replace <API_KEY> with your service credentials. Then use the full IAM token value, prefixed by the Bearer token type, to authenticate your API requests.

Example that sets options by using environment variables

export ENTERPRISE_USAGE_REPORTS_APIKEY={api_key}

import com.ibm.cloud.platform_services.enterprise_usage_reports.v1.EnterpriseUsageReports;

EnterpriseUsageReports service = EnterpriseUsageReports.newInstance();
Copy to clipboard

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the service variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Example that sets options by using environment variables

export ENTERPRISE_USAGE_REPORTS_APIKEY={api_key}

enterpriseUsageReportsService, err := enterpriseusagereportsv1.NewEnterpriseUsageReportsV1UsingExternalConfig(
        &enterpriseusagereportsv1.EnterpriseUsageReportsV1Options{})
if err != nil {
    panic(err)
}
Copy to clipboard

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the enterpriseUsageReportsService variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Example that sets options by using environment variables

export ENTERPRISE_USAGE_REPORTS_APIKEY={api_key}

from ibm_platform_services.enterprise_usage_reports_v1 import *

enterprise_usage_reports_service =  EnterpriseUsageReportsV1.new_instance()

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the enterprise_usage_reports_service variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Example that sets options by using environment variables

export ENTERPRISE_USAGE_REPORTS_APIKEY={api_key}

const EnterpriseUsageReportsV1 = require('ibm-platform-services/enterprise-usage-reports/v1');

const enterpriseUsageReportsService = EnterpriseUsageReportsV1.newInstance();
Copy to clipboard

Replace {api_key} with your IBM Cloud IAM API key. Invoke service operations by using the enterpriseUsageReportsService variable.

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. When an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.

For more information about how to track enterprise usage report activity, see Auditing events for account management.

Error handling

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

HTTP Code	Description	Recovery
`200`	Success	The request was successful.
`400`	Bad Request	The input parameters in the request are either incomplete or incorrect. Be sure to validate your request.
`401`	Authentication Failed	The token provided in the `Authorization` header is invalid or expired.
`403`	Authorization Failed	The subject does not have access to the reports.
`404`	Not Found	The entity does not exist.
`424`	Dependency Failure	The entity does not have all its dependencies set up correctly. The dependencies needs to be fixed before a report could be generated.
`5xx`	Internal Server Error	The API is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Pagination

Some API requests might return a large number of results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for the following resources use pagination:

/v1/resource-usage-reports

The next and reports fields are included in the collection response. The next field gives the link to the next page of results. The default page size is 30 items, and the maximum size of responses on a page is 100. To use a different page size, use the limit query parameter.

You can use the following related APIs to manage your enterprise:

Enterprise Management API: Create and manage enterprises, account groups, and accounts.
Enterprise Billing Units API: Manage enterprise billing and credit pools.

Usage reports for entities in the IBM Cloud enterprise. These entities can be the enterprise, an account group, or an account.

GET /v1/resource-usage-reports

(enterpriseUsageReports *EnterpriseUsageReportsV1) GetResourceUsageReport(getResourceUsageReportOptions *GetResourceUsageReportOptions) (result *Reports, response *core.DetailedResponse, err error)

(enterpriseUsageReports *EnterpriseUsageReportsV1) GetResourceUsageReportWithContext(ctx context.Context, getResourceUsageReportOptions *GetResourceUsageReportOptions) (result *Reports, response *core.DetailedResponse, err error)

ServiceCall<Reports> getResourceUsageReport(GetResourceUsageReportOptions getResourceUsageReportOptions)
Copy to clipboard

getResourceUsageReport(params)

get_resource_usage_report(self,
        *,
        enterprise_id: str = None,
        account_group_id: str = None,
        account_id: str = None,
        children: bool = None,
        month: str = None,
        billing_unit_id: str = None,
        limit: int = None,
        offset: str = None,
        **kwargs
    ) -> DetailedResponse
Copy to clipboard

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

The actions that are required correspond with the entities that you're retrieving the usage report for.

enterprise.enterprise.retrieve
enterprise.enterprise.retrieve-usage-report
enterprise.account-group.retrieve-usage-report
enterprise.account-group.retrieve
enterprise.account.retrieve-usage-report
enterprise.account.retrieve
billing.billing-unit.read

Auditing

Calling this method generates the following auditing event.

Calling the method generates billing.enterprise-usage-report.read auditing event.

billing.enterprise-usage-report.read

Request

Instantiate the GetResourceUsageReportOptions struct and set the fields to provide parameter values for the GetResourceUsageReport method.

Use the GetResourceUsageReportOptions.Builder to create a GetResourceUsageReportOptions object that contains the parameter values for the getResourceUsageReport method.

Query Parameters

enterprise_id
string
The ID of the enterprise for which the reports are queried. This parameter cannot be used with the account_id or account_group_id query parameters.

Example: abc12340d4bf4e36b0423d209b286f24
account_group_id
string
The ID of the account group for which the reports are queried. This parameter cannot be used with the account_id or enterprise_id query parameters.

Example: def456a237b94b9a9238ef024e204c9f
account_id
string
The ID of the account for which the reports are queried. This parameter cannot be used with the account_group_id or enterprise_id query parameters.

Example: 987abcba31834216b8c726a7dd9eb8d6
children
boolean
Returns the reports for the immediate child entities under the current account group or enterprise. This parameter cannot be used with the account_id query parameter.
month
string
The billing month for which the usage report is requested. The format is in yyyy-mm. Defaults to the month in which the report is queried.

Possible values: Value must match regular expression ^\d{4}\-(0?[1-9]|1[012])$
Example: 2019-06
billing_unit_id
string
The ID of the billing unit by which to filter the reports.
limit
integer
The maximum number of search results to be returned.

Example: 10
offset
string
An opaque value representing the offset of the first item to be returned by a search query. If not specified, then the first page of results is returned. To retrieve the next page of search results, use the 'offset' query parameter value within the 'next.href' URL found within a prior search query response.

parameter

WithContext method only

GetResourceUsageReportOptions

The GetResourceUsageReport options.

GetResourceUsageReportOptions

The getResourceUsageReport options.

parameters

enterpriseId
string
The ID of the enterprise for which the reports are queried. This parameter cannot be used with the account_id or account_group_id query parameters.
Examples:
accountGroupId
string
The ID of the account group for which the reports are queried. This parameter cannot be used with the account_id or enterprise_id query parameters.
Examples:
accountId
string
The ID of the account for which the reports are queried. This parameter cannot be used with the account_group_id or enterprise_id query parameters.
Examples:
children
boolean
Returns the reports for the immediate child entities under the current account group or enterprise. This parameter cannot be used with the account_id query parameter.
month
string
The billing month for which the usage report is requested. The format is in yyyy-mm. Defaults to the month in which the report is queried.

Possible values: Value must match regular expression /^\\d{4}\\-(0?[1-9]|1[012])$/
Examples:
billingUnitId
string
The ID of the billing unit by which to filter the reports.
limit
number
The maximum number of search results to be returned.
Examples:
offset
string
An opaque value representing the offset of the first item to be returned by a search query. If not specified, then the first page of results is returned. To retrieve the next page of search results, use the 'offset' query parameter value within the 'next.href' URL found within a prior search query response.

parameters

enterprise_id
str
The ID of the enterprise for which the reports are queried. This parameter cannot be used with the account_id or account_group_id query parameters.
Examples:
account_group_id
str
The ID of the account group for which the reports are queried. This parameter cannot be used with the account_id or enterprise_id query parameters.
Examples:
account_id
str
The ID of the account for which the reports are queried. This parameter cannot be used with the account_group_id or enterprise_id query parameters.
Examples:
children
bool
Returns the reports for the immediate child entities under the current account group or enterprise. This parameter cannot be used with the account_id query parameter.
month
str
The billing month for which the usage report is requested. The format is in yyyy-mm. Defaults to the month in which the report is queried.

Possible values: Value must match regular expression /^\\d{4}\\-(0?[1-9]|1[012])$/
Examples:
billing_unit_id
str
The ID of the billing unit by which to filter the reports.
limit
int
The maximum number of search results to be returned.
Examples:
offset
str
An opaque value representing the offset of the first item to be returned by a search query. If not specified, then the first page of results is returned. To retrieve the next page of search results, use the 'offset' query parameter value within the 'next.href' URL found within a prior search query response.

Enterprise usage

curl -X GET 'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?enterprise_id=abc12340d4bf4e36b0423d209b286f24&month=2019-07' -H 'Authorization: Bearer <IAM Token>'

Enterprise children usage

Account group usage

Account group children usage with page size

Account usage

Example request

getResourceUsageReportOptions := &enterpriseusagereportsv1.GetResourceUsageReportOptions{
  EnterpriseID: &enterpriseID,
  Month:        &billingMonth,
}

pager, err := enterpriseUsageReportsService.NewGetResourceUsageReportPager(getResourceUsageReportOptions)
if err != nil {
  panic(err)
}

var allResults []enterpriseusagereportsv1.ResourceUsageReport
for pager.HasNext() {
  nextPage, err := pager.GetNext()
  if err != nil {
    panic(err)
  }
  allResults = append(allResults, nextPage...)
}
b, _ := json.MarshalIndent(allResults, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetResourceUsageReportOptions getResourceUsageReportOptions = new GetResourceUsageReportOptions.Builder()
    .enterpriseId(enterpriseId)
    .month(billingMonth)
  .build();

GetResourceUsageReportPager pager = new GetResourceUsageReportPager(service, getResourceUsageReportOptions);
List<ResourceUsageReport> allResults = new ArrayList<>();
while (pager.hasNext()) {
  List<ResourceUsageReport> nextPage = pager.getNext();
  allResults.addAll(nextPage);
}

System.out.println(GsonSingleton.getGson().toJson(allResults));
Copy to clipboard

Example request

const params = {
  enterpriseId: enterpriseId,
  month: billingMonth,
};

const allResults = [];
try {
  const pager = new EnterpriseUsageReportsV1.GetResourceUsageReportPager(enterpriseUsageReportsService, params);
  while (pager.hasNext()) {
    const nextPage = await pager.getNext();
    expect(nextPage).not.toBeNull();
    allResults.push(...nextPage);
  }
  console.log(JSON.stringify(allResults, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

all_results = []
pager = GetResourceUsageReportPager(
  client=enterprise_usage_reports_service,
  enterprise_id=enterprise_id,
  month=billing_month,
)
while pager.has_next():
  next_page = pager.get_next()
  assert next_page is not None
  all_results.extend(next_page)

print(json.dumps(all_results, indent=2))
Copy to clipboard

Response

Response Body

Reports

Resource Usage Reports API response

Reports

Resource Usage Reports API response.

Examples:

Reports

Resource Usage Reports API response.

Examples:

Reports

Resource Usage Reports API response.

Examples:

Reports

Resource Usage Reports API response.

Examples:

Status Code

200
Usage Reports
401
Unauthenticated
403
Unauthorized
500
Unexpected errors

Example responses

Status 200

{
  "limit": 2,
  "first": {
    "href": "/v1/resource-usage-reports?enterprise_id=5ac9eb23c91b429b893e038aa5a2dec8&children=true&month=2019-06&limit=2"
  },
  "next": {
    "href": "/v1/resource-usage-reports?enterprise_id=5ac9eb23c91b429b893e038aa5a2dec8&children=true&month=2019-06&limit=2&offset=Mg%3D%3D"
  },
  "reports": [
    {
      "entity_id": "41848d0e2711434bbc134242452f7fc7",
      "entity_type": "account",
      "entity_crn": "crn:v1:bluemix:public:enterprise::a/3f99f8accbc848ea96f3c61a0ae22c44::account:41848d0e2711434bbc134242452f7fc7",
      "entity_name": "Example Account",
      "month": "2019-06",
      "billing_unit_id": "65719a07280a4022a9efa2f6ff4c3369",
      "billing_unit_crn": "crn:v1:bluemix:public:billing::a/3f99f8accbc848ea96f3c61a0ae22c44::billing-unit:65719a07280a4022a9efa2f6ff4c3369",
      "billing_unit_name": "Example Billing Unit",
      "currency_code": "USD",
      "country_code": "USA",
      "billable_cost": 75,
      "billable_rated_cost": 75,
      "non_billable_cost": 0,
      "non_billable_rated_cost": 0,
      "resources": [
        {
          "resource_id": "cloudant",
          "resource_name": "Cloudant",
          "billable_cost": 75,
          "billable_rated_cost": 75,
          "non_billable_cost": 0,
          "non_billable_rated_cost": 0,
          "plans": [
            {
              "plan_id": "cloudant-standard",
              "plan_name": "Standard",
              "pricing_plan_id": "billable:v4:cloudant-standard::1552694400000:",
              "billable": true,
              "cost": 75,
              "rated_cost": 75,
              "usage": [
                {
                  "metric": "GB_STORAGE_ACCRUED_PER_MONTH",
                  "unit": "GIGABYTE_MONTHS",
                  "quantity": 10,
                  "rateable_quantity": 10,
                  "cost": 10,
                  "rated_cost": 10
                },
                {
                  "metric": "GLOBAL_QUERY_CAPACITY_ACCRUED_PER_MONTH",
                  "unit": "EVENTS",
                  "quantity": 10,
                  "rateable_quantity": 10,
                  "cost": 50,
                  "rated_cost": 50
                },
                {
                  "metric": "READ_CAPACITY_ACCRUED_PER_MONTH",
                  "unit": "EVENTS",
                  "quantity": 20,
                  "rateable_quantity": 20,
                  "cost": 5,
                  "rated_cost": 5
                },
                {
                  "metric": "WRITE_CAPACITY_ACCRUED_PER_MONTH",
                  "unit": "EVENTS",
                  "quantity": 20,
                  "rateable_quantity": 20,
                  "cost": 10,
                  "rated_cost": 10
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "entity_id": "3f99f8accbc848ea96f3c61a0ae22c44",
      "entity_type": "account",
      "entity_crn": "crn:v1:bluemix:public:enterprise::a/3f99f8accbc848ea96f3c61a0ae22c44::account:3f99f8accbc848ea96f3c61a0ae22c44",
      "entity_name": "Other Example Account",
      "month": "2019-06",
      "billing_unit_id": "65719a07280a4022a9efa2f6ff4c3369",
      "billing_unit_crn": "crn:v1:bluemix:public:billing::a/3f99f8accbc848ea96f3c61a0ae22c44::billing-unit:65719a07280a4022a9efa2f6ff4c3369",
      "billing_unit_name": "Other Example Billing Unit",
      "currency_code": "USD",
      "country_code": "USA",
      "billable_cost": 0,
      "billable_rated_cost": 0,
      "non_billable_cost": 0,
      "non_billable_rated_cost": 0,
      "resources": []
    }
  ]
}
Copy to clipboard

Success example

{
  "limit": 2,
  "first": {
    "href": "/v1/resource-usage-reports?enterprise_id=5ac9eb23c91b429b893e038aa5a2dec8&children=true&month=2019-06&limit=2"
  },
  "next": {
    "href": "/v1/resource-usage-reports?enterprise_id=5ac9eb23c91b429b893e038aa5a2dec8&children=true&month=2019-06&limit=2&offset=Mg%3D%3D"
  },
  "reports": [
    {
      "entity_id": "41848d0e2711434bbc134242452f7fc7",
      "entity_type": "account",
      "entity_crn": "crn:v1:bluemix:public:enterprise::a/3f99f8accbc848ea96f3c61a0ae22c44::account:41848d0e2711434bbc134242452f7fc7",
      "entity_name": "Example Account",
      "month": "2019-06",
      "billing_unit_id": "65719a07280a4022a9efa2f6ff4c3369",
      "billing_unit_crn": "crn:v1:bluemix:public:billing::a/3f99f8accbc848ea96f3c61a0ae22c44::billing-unit:65719a07280a4022a9efa2f6ff4c3369",
      "billing_unit_name": "Example Billing Unit",
      "currency_code": "USD",
      "country_code": "USA",
      "billable_cost": 75,
      "billable_rated_cost": 75,
      "non_billable_cost": 0,
      "non_billable_rated_cost": 0,
      "resources": [
        {
          "resource_id": "cloudant",
          "resource_name": "Cloudant",
          "billable_cost": 75,
          "billable_rated_cost": 75,
          "non_billable_cost": 0,
          "non_billable_rated_cost": 0,
          "plans": [
            {
              "plan_id": "cloudant-standard",
              "plan_name": "Standard",
              "pricing_plan_id": "billable:v4:cloudant-standard::1552694400000:",
              "billable": true,
              "cost": 75,
              "rated_cost": 75,
              "usage": [
                {
                  "metric": "GB_STORAGE_ACCRUED_PER_MONTH",
                  "unit": "GIGABYTE_MONTHS",
                  "quantity": 10,
                  "rateable_quantity": 10,
                  "cost": 10,
                  "rated_cost": 10
                },
                {
                  "metric": "GLOBAL_QUERY_CAPACITY_ACCRUED_PER_MONTH",
                  "unit": "EVENTS",
                  "quantity": 10,
                  "rateable_quantity": 10,
                  "cost": 50,
                  "rated_cost": 50
                },
                {
                  "metric": "READ_CAPACITY_ACCRUED_PER_MONTH",
                  "unit": "EVENTS",
                  "quantity": 20,
                  "rateable_quantity": 20,
                  "cost": 5,
                  "rated_cost": 5
                },
                {
                  "metric": "WRITE_CAPACITY_ACCRUED_PER_MONTH",
                  "unit": "EVENTS",
                  "quantity": 20,
                  "rateable_quantity": 20,
                  "cost": 10,
                  "rated_cost": 10
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "entity_id": "3f99f8accbc848ea96f3c61a0ae22c44",
      "entity_type": "account",
      "entity_crn": "crn:v1:bluemix:public:enterprise::a/3f99f8accbc848ea96f3c61a0ae22c44::account:3f99f8accbc848ea96f3c61a0ae22c44",
      "entity_name": "Other Example Account",
      "month": "2019-06",
      "billing_unit_id": "65719a07280a4022a9efa2f6ff4c3369",
      "billing_unit_crn": "crn:v1:bluemix:public:billing::a/3f99f8accbc848ea96f3c61a0ae22c44::billing-unit:65719a07280a4022a9efa2f6ff4c3369",
      "billing_unit_name": "Other Example Billing Unit",
      "currency_code": "USD",
      "country_code": "USA",
      "billable_cost": 0,
      "billable_rated_cost": 0,
      "non_billable_cost": 0,
      "non_billable_rated_cost": 0,
      "resources": []
    }
  ]
}
Copy to clipboard

Introduction

Endpoint URLs

Authentication

Auditing

Error handling

Pagination

Related APIs

Methods

Get usage reports for enterprise entities

Authorization

Auditing

Request

Query Parameters

enterprise_id

account_group_id

account_id

children

month

billing_unit_id

limit

offset

parameter

ctx

GetResourceUsageReportOptions

EnterpriseID

AccountGroupID

AccountID

Children

Month

BillingUnitID

Limit

Offset

GetResourceUsageReportOptions

enterpriseId

accountGroupId

accountId

children

month

billingUnitId

limit

offset

parameters

enterpriseId

accountGroupId

accountId

children

month

billingUnitId

limit

offset

parameters

enterprise_id

account_group_id

account_id

children

month

billing_unit_id

limit

offset

Response

Response Body

limit

first

href

next

href

reports

Reports

Limit

First

Href

Next

Href

Reports

EntityID

EntityType

EntityCRN

EntityName

BillingUnitID

BillingUnitCRN