IBM Cloud Enterprise Usage Reports API (Beta)

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:

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

/v1/resource-usage-reports

Request

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.

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

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

Response

Response Body

Reports

Resource Usage Reports API response

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

Introduction

Endpoint

Authentication

Error handling

Report organization

Example hierarchy

Example queries and responses

Related APIs

Methods

Get usage reports for enterprise entities

Query Parameters

enterprise_id

account_group_id

account_id

children

month

billing_unit_id

Response Body

limit

first

href

next

href

reports

Status Code

200

401

403

500