Get usage reports for enterprise entities
GET /v1/resource-usage-reports
Usage reports for entities in the IBM Cloud enterprise. These entities can be the enterprise, an account group, or an account.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
The actions that are required correspond with the entities that you're retrieving the usage report for.
enterprise.enterprise.retrieveenterprise.enterprise.retrieve-usage-reportenterprise.account-group.retrieve-usage-reportenterprise.account-group.retrieveenterprise.account.retrieve-usage-reportenterprise.account.retrievebilling.billing-unit.read
Auditing
Calling this method generates the following auditing event.
billing.enterprise-usage-report.read
Request
Path Parameters
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.
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.
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.
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.
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.
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.
Response
200 - Usage Reports
limit
integer
The maximum number of reports in the response.
first
object
An object that contains a link to a page of search results.
next
object
An object that contains a link to a page of search results.
reports
array
The list of usage reports.
401 - Unauthenticated
errors
array
Errors that were encountered when serving the request.
403 - Unauthorized
errors
array
Errors that were encountered when serving the request.
500 - Unexpected errors
errors
array
Errors that were encountered when serving the request.
Get a FOCUS report for an enterprise
GET /v1/focus-reports
Returns the FOCUS (FinOps Open Cost and Usage Specification v1.2) cost and usage report for an enterprise. The following access modes are supported:
- Full report (no `page` parameter): Returns the complete report as a gzip-compressed CSV file (`Content-Type: application/gzip`).
- Paged report (`page=N`): Returns the requested page as a decompressed CSV file (`Content-Type: text/csv`). Pagination metadata is returned in `X-Total-Pages`, `X-Current-Page`, `X-Total-Lines`, and `X-Page-Lines` response headers.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
To retrieve the FOCUS report, you must have the Usage Reports Viewer or Administrator role on the Enterprise service.
enterprise.enterprise.retrieveenterprise.enterprise.retrieve-usage-report
Request
Path Parameters
Query Parameters
enterprise_id
Required *
string
The ID of the enterprise for which the FOCUS report is requested.
month
Required *
string
The billing month for which the FOCUS report is requested in `YYYY-MM` format. This value cannot be a future month.
page
integer
The page number to return, starting at 1. When omitted, the full gzip-compressed report is returned. When provided, the specified page is returned as a decompressed CSV with pagination headers.
Response
200 - FOCUS report — either the full gzip-compressed CSV (when `page` is omitted) or a single decompressed CSV page (when `page` is specified). Page 1 of a paged response includes the CSV header row; subsequent pages have the header prepended automatically.
400 - Bad request. One or more query parameters are missing or invalid.
errors
array
Errors that were encountered when serving the request.
401 - Unauthenticated
errors
array
Errors that were encountered when serving the request.
403 - Unauthorized
errors
array
Errors that were encountered when serving the request.
404 - Not found. The enterprise was not found, the requested page does not exist, or the report has not yet been generated for this month.
errors
array
Errors that were encountered when serving the request.
500 - Unexpected errors
errors
array
Errors that were encountered when serving the request.