Get account summary
GET /v4/accounts/{account_id}/summary/{billingmonth}
Returns the summary for the account for a given month. Account billing managers are authorized to access this report.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.account-summary.read
Auditing
Calling this method generates the following auditing event.
billing.account-summary.read
Request
Response
200 - Account summary was returned successfully
account_id
string
The ID of the account.
account_resources
array
The list of account resources for the month. For accounts on paid support plans, the support resource `ibmcloud-platform-support` is included here alongside other platform services. The `billable_cost` of that entry reflects the computed support charge and includes the `SUPPORT_CHARGE` metric.
month
string
The month in which usages were incurred. Represented in yyyy-mm format.
billing_country_code
string
Country
billing_currency_code
string
The currency in which the account is billed.
resources
object
Charges related to cloud resources.
offers
array
The list of offers applicable for the account for the month.
support
array
Support-related charges. For accounts on paid support plans, the `cost` field is `0` and support costs are instead included in `account_resources` as the `ibmcloud-platform-support` service entry.
support_resources
array
The list of support resources for the month. For accounts on paid support plans, this array is empty (`[]`); support costs are included in `account_resources` instead.
subscription
SubscriptionSummary
A summary of charges and credits related to a subscription.
400 - Invalid parameters
errors
array
Errors while serving the request.
401 - Unauthenticated
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
404 - Account Not Found
errors
array
Errors while serving the request.
500 - Unexpected errors
errors
array
Errors while serving the request.
Get account usage
GET /v4/accounts/{account_id}/usage/{billingmonth}
Usage for all the resources and plans in an account for a given month. Account billing managers are authorized to access this report.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
View account level usage
billing.usage-report.read
Auditing
Calling this method generates the following auditing event.
billing.usage-report.read
Request
Path Parameters
Query Parameters
_names
boolean
Include the name of every resource, plan, resource instance, organization, and resource group.
Response
200 - Account usage was returned successfully
account_id
string
The ID of the account.
pricing_country
string
The target country pricing that should be used.
currency_code
string
The currency for the cost fields in the resources, plans and metrics
month
string
The month
resources
array
All the resource used in the account.
currency_rate
number
The value of the account's currency in USD.
401 - Unauthenticated
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
500 - Unexpected errors
errors
array
Errors while serving the request.
Get resource group usage
GET /v4/accounts/{account_id}/resource_groups/{resource_group_id}/usage/{billingmonth}
Usage for all the resources and plans in a resource group in a given month. Account billing managers or resource group billing managers are authorized to access this report.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.usage-report.read
Auditing
Calling this method generates the following auditing event.
billing.usage-report.read
Request
Path Parameters
Query Parameters
_names
boolean
Include the name of every resource, plan, resource instance, organization, and resource group.
Response
200 - Resource group usage returned successfully
account_id
string
The ID of the account.
resource_group_id
string
The ID of the resource group.
resource_group_name
string
The name of the resource group.
pricing_country
string
The target country pricing that should be used.
currency_code
string
The currency for the cost fields in the resources, plans and metrics
month
string
The month
resources
array
All the resource used in the account
currency_rate
number
The value of the account's currency in USD.
401 - Unauthenticated
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
500 - Unexpected errors
errors
array
Errors while serving the request.
Get organization usage
GET /v4/accounts/{account_id}/organizations/{organization_id}/usage/{billingmonth}
Usage for all the resources and plans in an organization in a given month. Account billing managers or organization billing managers are authorized to access this report.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
View account level summary usage
billing.usage-report.read
Auditing
Calling this method generates the following auditing event.
billing.usage-report.read
Request
Path Parameters
Query Parameters
_names
boolean
Include the name of every resource, plan, resource instance, organization, and resource group.
Response
200 - Organization usage successfully returned
account_id
string
The ID of the account.
organization_id
string
The ID of the organization.
organization_name
string
The name of the organization.
pricing_country
string
The target country pricing that should be used.
currency_code
string
The currency for the cost fields in the resources, plans and metrics
month
string
The month
resources
array
All the resource used in the account.
currency_rate
number
The value of the account's currency in USD.
401 - Unauthenticated
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
500 - Unexpected errors
errors
array
Errors while serving the request.
Get resource instance usage in FOCUS format
GET /v4/accounts/{account_id}/focus/{month}
Query for resource instance usage in FOCUS (FinOps Open Cost and Usage Specification) format. This endpoint supports two response formats:
- JSON format (format=json or default): Returns paginated JSON response from the metering-reporting API with the FOCUS_Usage schema. Supports pagination with _limit and _start parameters. Resource names and tags are always included in the FOCUS data structure.
- CSV format (format=csv): Returns a CSV file download from the metering-report-downloader service with FOCUS-compliant columns. The CSV response does not support pagination parameters. Account billing administrator is authorized to access this report.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
Required IAM permissions to access this endpoint.
billing.usage-report.read
Auditing
Calling this method generates the following auditing event.
billing.usage-report.read
Request
Path Parameters
Query Parameters
format
string
The format of the response. Use `json` for paginated JSON response from the metering-reporting API, or `csv` to download a CSV file from the metering-report-downloader service. Defaults to `json`.
_limit
integer
Number of usage records returned. The default value is 30. Maximum value is 200.
_start
string
The offset from which the records must be fetched. Offset information is included in the response.
Response
200 - Resource instance usage returned successfully. Response format depends on the `format` parameter:
- format=json (default): Returns paginated JSON with Instances_Usage schema
- format=csv: Returns CSV file with FOCUS-compliant columns and appropriate headers
limit
integer
Maximum number of reports in the response.
count
integer
Number of reports in the response.
first
object
Link to the first page of the search query.
next
object
Link to the next page of the search query.
resources
array
List of FOCUS-compliant usage records.
400 - Bad request. Invalid parameters such as invalid date format, future date, invalid format parameter value, or unsupported FOCUS version.
errors
array
Errors while serving the request.
401 - Unauthorized. Invalid or missing IAM token.
errors
array
Errors while serving the request.
403 - Forbidden. User does not have permission to access this account's billing data.
errors
array
Errors while serving the request.
404 - Not found. Account not found or no data available for the specified month.
errors
array
Errors while serving the request.
429 - Too many requests. Rate limit exceeded.
errors
array
Errors while serving the request.
500 - Internal server error. An unexpected error occurred while processing the request.
errors
array
Errors while serving the request.
Get resource instance usage in an account
GET /v4/accounts/{account_id}/resource_instances/usage/{billingmonth}
Query for resource instance usage in an account. Filter the results with query parameters. Account billing administrator is authorized to access this report.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.usage-report.read
Auditing
Calling this method generates the following auditing event.
billing.usage-report.read
Request
Path Parameters
Query Parameters
_names
boolean
Include the name of every resource, plan, resource instance, organization, and resource group.
_tags
boolean
Include the tags associated with every resource instance. By default it is always `true`.
_limit
integer
Number of usage records returned. The default value is 30. Maximum value is 200.
_start
string
The offset from which the records must be fetched. Offset information is included in the response.
resource_group_id
string
Filter by resource group.
organization_id
string
Filter by organization_id.
resource_instance_id
string
Filter by resource instance_id.
resource_id
string
Filter by resource_id.
plan_id
string
Filter by plan_id.
region
string
Region in which the resource instance is provisioned.
Response
200 - Resource instance usage returned successfully
limit
integer
The max number of reports in the response.
count
integer
The number of reports in the response.
first
object
The link to the first page of the search query.
next
object
The link to the next page of the search query.
resources
array
The list of instance usage reports.
400 - Status 400
errors
array
Errors while serving the request.
401 - Status 401
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
429 - Status 429
errors
array
Errors while serving the request.
500 - Status 500
errors
array
Errors while serving the request.
Get resource instance usage in a resource group
GET /v4/accounts/{account_id}/resource_groups/{resource_group_id}/resource_instances/usage/{billingmonth}
Query for resource instance usage in a resource group. Filter the results with query parameters. Account billing administrator and resource group billing administrators are authorized to access this report.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.usage-report.read
Auditing
Calling this method generates the following auditing event.
billing.usage-report.read
Request
Path Parameters
Query Parameters
_names
boolean
Include the name of every resource, plan, resource instance, organization, and resource group.
_tags
boolean
Include the tags associated with every resource instance. By default it is always `true`.
_limit
integer
Number of usage records returned. The default value is 30. Maximum value is 200.
_start
string
The offset from which the records must be fetched. Offset information is included in the response.
resource_instance_id
string
Filter by resource instance id.
resource_id
string
Filter by resource_id.
plan_id
string
Filter by plan_id.
region
string
Region in which the resource instance is provisioned.
Response
200 - Resource instance usage returned successfully
limit
integer
The max number of reports in the response.
count
integer
The number of reports in the response.
first
object
The link to the first page of the search query.
next
object
The link to the next page of the search query.
resources
array
The list of instance usage reports.
400 - Status 400
errors
array
Errors while serving the request.
401 - Status 401
errors
array
Errors while serving the request.
429 - Status 429
errors
array
Errors while serving the request.
500 - Status 500
errors
array
Errors while serving the request.
Get resource instance usage in an organization
GET /v4/accounts/{account_id}/organizations/{organization_id}/resource_instances/usage/{billingmonth}
Query for resource instance usage in an organization. Filter the results with query parameters. Account billing administrator and organization billing administrators are authorized to access this report.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.usage-report.read
Auditing
Calling this method generates the following auditing event.
billing.usage-report.read
Request
Path Parameters
Query Parameters
_names
boolean
Include the name of every resource, plan, resource instance, organization, and resource group.
_tags
boolean
Include the tags associated with every resource instance. By default it is always `true`.
_limit
integer
Number of usage records returned. The default value is 30. Maximum value is 200.
_start
string
The offset from which the records must be fetched. Offset information is included in the response.
resource_instance_id
string
Filter by resource instance id.
resource_id
string
Filter by resource_id.
plan_id
string
Filter by plan_id.
region
string
Region in which the resource instance is provisioned.
Response
200 - Resource instance usage returned successfully
limit
integer
The max number of reports in the response.
count
integer
The number of reports in the response.
first
object
The link to the first page of the search query.
next
object
The link to the next page of the search query.
resources
array
The list of instance usage reports.
400 - Status 400
errors
array
Errors while serving the request.
401 - Status 401
errors
array
Errors while serving the request.
429 - Status 429
errors
array
Errors while serving the request.
500 - Status 500
errors
array
Errors while serving the request.
Setup the snapshot configuration
POST /v1/billing-reports-snapshot-config
Snapshots of the billing reports would be taken on a periodic interval and stored based on the configuration setup by the customer for the given Account Id.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.billing-reports-snapshot-config.create
Request
Request Body
Snapshot_Config_Create
account_id
Required *
string
Account ID for which billing report snapshot is configured.
interval
Required *
string
Frequency of taking the snapshot of the billing reports.
cos_bucket
Required *
string
The name of the COS bucket to store the snapshot of the billing reports.
cos_location
Required *
string
Region of the COS instance.
cos_reports_folder
string
The billing reports root folder to store the billing reports snapshots. Defaults to "IBMCloud-Billing-Reports"
report_types
array
The type of billing reports to take a snapshot of. Possible values are `account_summary`, `enterprise_summary`, `account_resource_instance_usage`. For `enterprise_summary` reports, `ibmcloud-platform-support` appears only in the enterprise-level roll-up report and not in individual child account reports.
versioning
string
A new version of report is created or the existing report version is overwritten with every update. Defaults to "new"
Response
201 - Indicates that the billing reports snapshot for the respective account is successfully created with the submitted payload.
account_id
string
Account ID for which billing report snapshot is configured.
state
string
Status of the billing snapshot configuration. Possible values are [enabled, disabled].
account_type
string
Type of account. Possible values are [enterprise, account].
interval
string
Frequency of taking the snapshot of the billing reports.
versioning
string
A new version of report is created or the existing report version is overwritten with every update.
report_types
array
The type of billing reports to take a snapshot of. Possible values are `account_summary`, `enterprise_summary`, `account_resource_instance_usage`. For `enterprise_summary` reports, `ibmcloud-platform-support` appears only in the enterprise-level roll-up report and not in individual child account reports.
compression
string
Compression format of the snapshot report.
content_type
string
Type of content stored in snapshot report.
cos_reports_folder
string
The billing reports root folder to store the billing reports snapshots. Defaults to "IBMCloud-Billing-Reports"
cos_bucket
string
The name of the COS bucket to store the snapshot of the billing reports.
cos_location
string
Region of the COS instance.
cos_endpoint
string
The endpoint of the COS instance.
created_at
integer
Timestamp in milliseconds when the snapshot configuration was created.
last_updated_at
integer
Timestamp in milliseconds when the snapshot configuration was last updated.
history
array
List of previous versions of the snapshot configurations.
400 - Bad request
errors
array
Errors while serving the request.
401 - Unauthenticated
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
404 - Not found
errors
array
Errors while serving the request.
409 - Conflict
errors
array
Errors while serving the request.
424 - Dependency failure
errors
array
Errors while serving the request.
500 - Internal Server Error
errors
array
Errors while serving the request.
503 - Service Unavailable
errors
array
Errors while serving the request.
Fetch the snapshot configuration
GET /v1/billing-reports-snapshot-config
Returns the configuration of snapshot of the billing reports setup by the customer for the given Account Id.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.billing-reports-snapshot-config.read
Request
Path Parameters
Query Parameters
account_id
Required *
string
Account ID for which the billing report snapshot is configured.
Response
200 - Snapshot configuration was returned successfully.
account_id
string
Account ID for which billing report snapshot is configured.
state
string
Status of the billing snapshot configuration. Possible values are [enabled, disabled].
account_type
string
Type of account. Possible values are [enterprise, account].
interval
string
Frequency of taking the snapshot of the billing reports.
versioning
string
A new version of report is created or the existing report version is overwritten with every update.
report_types
array
The type of billing reports to take a snapshot of. Possible values are `account_summary`, `enterprise_summary`, `account_resource_instance_usage`. For `enterprise_summary` reports, `ibmcloud-platform-support` appears only in the enterprise-level roll-up report and not in individual child account reports.
compression
string
Compression format of the snapshot report.
content_type
string
Type of content stored in snapshot report.
cos_reports_folder
string
The billing reports root folder to store the billing reports snapshots. Defaults to "IBMCloud-Billing-Reports"
cos_bucket
string
The name of the COS bucket to store the snapshot of the billing reports.
cos_location
string
Region of the COS instance.
cos_endpoint
string
The endpoint of the COS instance.
created_at
integer
Timestamp in milliseconds when the snapshot configuration was created.
last_updated_at
integer
Timestamp in milliseconds when the snapshot configuration was last updated.
history
array
List of previous versions of the snapshot configurations.
400 - Bad request
errors
array
Errors while serving the request.
401 - Unauthenticated
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
404 - Not found
errors
array
Errors while serving the request.
500 - Internal Server Error
errors
array
Errors while serving the request.
503 - Service Unavailable
errors
array
Errors while serving the request.
Update the snapshot configuration
PATCH /v1/billing-reports-snapshot-config
Updates the configuration of snapshot of the billing reports setup by the customer for the given Account Id.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.billing-reports-snapshot-config.update
Request
Request Body
Snapshot_Config_Update
account_id
Required *
string
Account ID for which billing report snapshot is configured.
interval
string
Frequency of taking the snapshot of the billing reports.
cos_bucket
string
The name of the COS bucket to store the snapshot of the billing reports.
cos_location
string
Region of the COS instance.
cos_reports_folder
string
The billing reports root folder to store the billing reports snapshots.
report_types
array
The type of billing reports to take a snapshot of. Possible values are `account_summary`, `enterprise_summary`, `account_resource_instance_usage`. For `enterprise_summary` reports, `ibmcloud-platform-support` appears only in the enterprise-level roll-up report and not in individual child account reports.
versioning
string
A new version of report is created or the existing report version is overwritten with every update.
Response
200 - Indicates that the billing reports snapshot for the respective account is successfully updated with the submitted payload.
account_id
string
Account ID for which billing report snapshot is configured.
state
string
Status of the billing snapshot configuration. Possible values are [enabled, disabled].
account_type
string
Type of account. Possible values are [enterprise, account].
interval
string
Frequency of taking the snapshot of the billing reports.
versioning
string
A new version of report is created or the existing report version is overwritten with every update.
report_types
array
The type of billing reports to take a snapshot of. Possible values are `account_summary`, `enterprise_summary`, `account_resource_instance_usage`. For `enterprise_summary` reports, `ibmcloud-platform-support` appears only in the enterprise-level roll-up report and not in individual child account reports.
compression
string
Compression format of the snapshot report.
content_type
string
Type of content stored in snapshot report.
cos_reports_folder
string
The billing reports root folder to store the billing reports snapshots. Defaults to "IBMCloud-Billing-Reports"
cos_bucket
string
The name of the COS bucket to store the snapshot of the billing reports.
cos_location
string
Region of the COS instance.
cos_endpoint
string
The endpoint of the COS instance.
created_at
integer
Timestamp in milliseconds when the snapshot configuration was created.
last_updated_at
integer
Timestamp in milliseconds when the snapshot configuration was last updated.
history
array
List of previous versions of the snapshot configurations.
400 - Bad request
errors
array
Errors while serving the request.
401 - Unauthenticated
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
404 - Not found
errors
array
Errors while serving the request.
409 - Conflict
errors
array
Errors while serving the request.
424 - Dependency failure
errors
array
Errors while serving the request.
500 - Internal Server Error
errors
array
Errors while serving the request.
503 - Service Unavailable
errors
array
Errors while serving the request.
Delete the snapshot configuration
DELETE /v1/billing-reports-snapshot-config
Delete the configuration of snapshot of the billing reports setup by the customer for the given Account Id.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.billing-reports-snapshot-config.delete
Request
Path Parameters
Query Parameters
account_id
Required *
string
Account ID for which the billing report snapshot is configured.
Response
204 - Snapshot configuration was deleted successfully.
400 - Bad request
errors
array
Errors while serving the request.
401 - Unauthenticated
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
404 - Not found
errors
array
Errors while serving the request.
500 - Internal Server Error
errors
array
Errors while serving the request.
503 - Service Unavailable
errors
array
Errors while serving the request.
Verify billing to COS authorization
POST /v1/billing-reports-snapshot-config/validate
Verify billing service to COS bucket authorization for the given account_id. If COS bucket information is not provided, COS bucket information is retrieved from the configuration file.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.billing-reports-snapshot-config.create
Request
Request Body
Snapshot_Config_Validate
account_id
Required *
string
Account ID for which billing report snapshot is configured.
interval
string
Frequency of taking the snapshot of the billing reports.
cos_bucket
string
The name of the COS bucket to store the snapshot of the billing reports.
cos_location
string
Region of the COS instance.
cos_reports_folder
string
The billing reports root folder to store the billing reports snapshots. Defaults to "IBMCloud-Billing-Reports"
report_types
array
The type of billing reports to take a snapshot of. Possible values are `account_summary`, `enterprise_summary`, `account_resource_instance_usage`. For `enterprise_summary` reports, `ibmcloud-platform-support` appears only in the enterprise-level roll-up report and not in individual child account reports.
versioning
string
A new version of report is created or the existing report version is overwritten with every update. Defaults to "new"
Response
200 - Indicates that authorization exists between the billing service and the COS service for the given configuration.
account_id
string
Account ID for which billing report snapshot is configured.
cos_bucket
string
The name of the COS bucket to store the snapshot of the billing reports.
cos_location
string
Region of the COS instance.
400 - Bad request
errors
array
Errors while serving the request.
401 - Unauthenticated
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
404 - Not found
errors
array
Errors while serving the request.
424 - Dependency failure
errors
array
Errors while serving the request.
500 - Internal Server Error
errors
array
Errors while serving the request.
503 - Service Unavailable
errors
array
Errors while serving the request.
Fetch the current or past snapshots
GET /v1/billing-reports-snapshots
Returns the billing reports snapshots captured for the given Account Id in the specific time period.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
billing.billing-reports-snapshot.read
Request
Path Parameters
Query Parameters
account_id
Required *
string
Account ID for which the billing report snapshot is requested.
month
Required *
string
The month for which billing report snapshot is requested. Format is yyyy-mm.
date_from
integer
Timestamp in milliseconds for which billing report snapshot is requested.
date_to
integer
Timestamp in milliseconds for which billing report snapshot is requested.
_limit
integer
Number of usage records returned. The default value is 30. Maximum value is 200.
_start
string
The offset from which the records must be fetched. Offset information is included in the response.
Response
200 - List of snapshots were returned successfully.
count
integer
Number of total snapshots.
first
object
Reference to the first page of the search query.
next
object
Reference to the next page of the search query if any.
snapshots
array
400 - Bad request
errors
array
Errors while serving the request.
401 - Unauthenticated
errors
array
Errors while serving the request.
403 - Unauthorized
errors
array
Errors while serving the request.
500 - Internal Server Error
errors
array
Errors while serving the request.
503 - Service Unavailable
errors
array
Errors while serving the request.