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.

Endpoint

The Enterprise Usage Reports API is accessible at the following endpoint:

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

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.

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.

Report organization

An account's usage charges come from the use of the resource instances that are created in the account. The resource instances belong to different plans, and the usage for those instances are aggregated towards their respective plans. The charges for all of the plans in an account are calculated every month and are billed to the billing unit of the account.

Reports for any entity in the hierarchy that is not an account (the enterprise or an account group) has the usage of all the accounts under that entity rolled up to the billing unit.

Example hierarchy

The following diagram depicts an example hierarchy of an enterprise called Cloud-Provider. The Cloud-Provider enterprise contains an Administration account and the Platform-Services and Solutions account groups. Each account is assigned to one of the following billing units: Administration, Operations, or Support.

Only a single billing unit per enterprise is currently supported.

(E)Cloud-Provider {ID: enterprise-cloud-provider}
├── (A)Administration {ID: account-administration, BU: Administration}
├── (AG)Platform-Services {ID: group-platform-services}
│   └── (A)Platform-Services-Operations {ID: platform-services-operations, BU: Operations}
└── (AG)Solutions {ID: group-solutions}
    ├── (AG)AI-Services {ID: group-ai-services}
    │   ├── (A)AI-Services-Operations {ID: account-ai-services-operations, BU: Operations}
    │   └── (A)AI-Services-Support {ID: account-ai-services-support, BU: Support}
    └── (AG)Data-Services  {ID: group-data-services}
        ├── (A)Data-Services-Operations {ID: account-data-services-operations, BU: Operations}
        └── (A)Data-Services-Support {ID: account-data-services-support, BU: Support}

ID -> Unique identifier of the entity
E  -> Enterprise entity
AG -> Account group entity
A  -> Account entity
BU -> Billing unit
Cloud Provider enterprise hierarchy

Given this structure, the Cloud-Provider enterprise has the following effective billing units:

  • The Cloud-Provider enterprise has three effective billing units: Administration, Operations, and Support.
  • The Platform-Services account group has one effective billing unit: Operations.
  • The Solutions, AI-Services, and Data-Services account groups have two effective billing units: Operations and Support.

Example queries and responses

Enterprise Cloud-Provider reports

Query: https://enterprise.cloud.ibm.com/v1/resource-usage-reports?enterprise_id=enterprise-cloud-provider&month=2019-06

This query returns three reports:

  • Usage aggregated towards (E)Cloud-Provider:(BU)Administration
  • Usage aggregated towards (E)Cloud-Provider:(BU)Operations
  • Usage aggregated towards (E)Cloud-Provider:(BU)Support

Enterprise Cloud-Provider children reports

Query: https://enterprise.cloud.ibm.com/v1/resource-usage-reports?enterprise_id=enterprise-cloud-provider&month=2019-06&children=true

This query returns four reports:

  • Usage aggregated towards (A)Administration:(BU)Administration
  • Usage aggregated towards (AG)Platform-Services:(BU)Operations
  • Usage aggregated towards (AG)Solutions:(BU)Operations
  • Usage aggregated towards (AG)Solutions:(BU)Support

Account group Solutions reports

Query: https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_group_id=group-solutions&month=2019-06

This query returns two reports:

  • Usage aggregated towards (AG)Solutions:(BU)Operations
  • Usage aggregated towards (AG)Solutions:(BU)Support

Account group Solutions children reports

Query: https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_group_id=group-solutions&month=2019-06&children=true

This query returns four reports:

  • Usage aggregated towards (AG)AI-Services:(BU)Operations
  • Usage aggregated towards (AG)AI-Services:(BU)Support
  • Usage aggregated towards (AG)Data-Services:(BU)Operations
  • Usage aggregated towards (AG)Data-Services:(BU)Support

Account group Data-Services reports

Query: https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_group_id=group-data-services&month=2019-06

This query returns two reports:

  • Usage aggregated towards (AG)Data-Services:(BU)Operations
  • Usage aggregated towards (AG)Data-Services:(BU)Support

Account group Data-Services children reports

Query: https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_group_id=group-data-services&month=2019-06&children=true

This query returns two reports:

  • Usage aggregated towards (A)Data-Services-Operations:(BU)Operations
  • Usage aggregated towards (A)Data-Services-Support:(BU)Support

Account Data-Services-Operations report

Query: https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_id=account-data-services-operations&month=2019-06

This query returns one report: Usage aggregated towards (A)Data-Services-Operations:(BU)Operations

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.

GET /v1/resource-usage-reports
Request

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.

    Constraints: 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.

Response

Resource Usage Reports API response

Status Code

  • Usage Reports

  • Unauthenticated

  • Unauthorized

  • Unexpected errors

Example responses