IBM Cloud API Docs

Introduction

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>

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}'

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();

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)
}

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();

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:

Methods

Get usage reports for enterprise entities

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

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

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

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

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)
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

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

  • 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

  • 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

  • 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

  • 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.

  • 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

  • The ID of the billing unit by which to filter the reports.

  • The maximum number of search results to be returned.

    Example: 10

  • 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.

WithContext method only

The GetResourceUsageReport options.

The getResourceUsageReport options.

parameters

  • 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:
    value
    _source
    _lines
    _html
  • 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:
    value
    _source
    _lines
    _html
  • 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:
    value
    _source
    _lines
    _html
  • 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.

  • 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:
    value
    _source
    _lines
    _html
  • The ID of the billing unit by which to filter the reports.

  • The maximum number of search results to be returned.

    Examples:
    value
    _source
    _lines
    _html
  • 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

  • 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:
    value
    _source
    _lines
    _html
  • 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:
    value
    _source
    _lines
    _html
  • 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:
    value
    _source
    _lines
    _html
  • 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.

  • 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:
    value
    _source
    _lines
    _html
  • The ID of the billing unit by which to filter the reports.

  • The maximum number of search results to be returned.

    Examples:
    value
    _source
    _lines
    _html
  • 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.

  • curl -X GET 'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?enterprise_id=abc12340d4bf4e36b0423d209b286f24&month=2019-07' -H 'Authorization: Bearer <IAM Token>'
    
  • curl -X GET 'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?enterprise_id=abc12340d4bf4e36b0423d209b286f24&month=2019-07&children=true' -H 'Authorization: Bearer <IAM Token>'
    
  • curl -X GET 'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_group_id=def456a237b94b9a9238ef024e204c9f&month=2019-07' -H 'Authorization: Bearer <IAM Token>'
    
  • curl -X GET 'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_group_id=def456a237b94b9a9238ef024e204c9f&month=2019-07&children=true&limit=2' -H 'Authorization: Bearer <IAM Token>'
    
  • curl -X GET 'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_id=987abcba31834216b8c726a7dd9eb8d6&month=2019-07&children=true' -H 'Authorization: Bearer <IAM Token>'
    
  • 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))
  • 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));
  • 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);
    }
  • 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))

Response

Resource Usage Reports API response

Resource Usage Reports API response.

Examples:
View

Resource Usage Reports API response.

Examples:
View

Resource Usage Reports API response.

Examples:
View

Resource Usage Reports API response.

Examples:
View

Status Code

  • Usage Reports

  • Unauthenticated

  • Unauthorized

  • Unexpected errors

Example responses
  • {
      "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": []
        }
      ]
    }
  • {
      "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": []
        }
      ]
    }