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

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