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.
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 hierarchyGiven this structure, the Cloud-Provider
enterprise has the following effective billing units:
- The
Cloud-Provider
enterprise has three effective billing units:Administration
,Operations
, andSupport
. - The
Platform-Services
account group has one effective billing unit:Operations
. - The
Solutions
,AI-Services
, andData-Services
account groups have two effective billing units:Operations
andSupport
.
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
Related APIs
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.
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
Query Parameters
The ID of the enterprise for which the reports are queried. This parameter cannot be used with the
account_id
oraccount_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
orenterprise_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
orenterprise_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.
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>'
Resource Usage Reports API response
The maximum number of reports in the response.
A link to the first page of the search query.
first
A link to the next page of the search query.
next
The list of usage reports.
Status Code
Usage Reports
Unauthenticated
Unauthorized
Unexpected errors
{ "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": [] } ] }