{ "openapi": "3.0.0", "info": { "description": "## Introduction\n\nThe 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. In addition, you can retrieve enterprise cost and usage data in the FinOps Open Cost and Usage Specification (FOCUS) v1.2 format by using the `/v1/focus-reports` endpoint. This API is a beta release.\n\nSDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the [IBM Cloud SDK Common project](https://github.com/IBM/ibm-cloud-sdk-common) on GitHub.\n\nAPI endpoint\n\n```bash\nhttps://enterprise.cloud.ibm.com\n```\n\nInstalling the Java SDK\n\nMaven\n\n```xml\n\n com.ibm.cloud\n enterprise-usage-reports\n {version}\n\n```\n\nGradle\n\n```java\ncompile 'com.ibm.cloud:enterprise-usage-reports:{version}'\n```\n\nFor more installation options, view this project in GitHub.\nhttps://github.com/IBM/platform-services-java-sdk\n\nInstalling the Go SDK\n\nInstallation\n\n```bash\ngo get -u github.com/IBM/platform-services-go-sdk/enterpriseusagereportsv1\n```\n\nFor more installation options, view this project in GitHub.\nhttps://github.com/IBM/platform-services-go-sdk\n\nInstalling the Node SDK\n\nInstallation\n\n```bash\nnpm install @ibm-cloud/platform-services\n```\n\nFor more installation options, view this project in GitHub.\nhttps://github.com/IBM/platform-services-node-sdk\n\nInstalling the Python SDK\n\nInstallation\n\n```bash\npip install --upgrade \"ibm-platform-services\"\n```\n\nFor more installation options, view this project in GitHub.\nhttps://github.com/IBM/platform-services-python-sdk\n\n## Endpoint URLs\n\nThe Enterprise Usage Reports API uses the following global endpoint URLs. When you call the API, add the path for each method to form the complete API endpoint for your requests.\n\n```\nhttps://enterprise.cloud.ibm.com/v1/resource-usage-reports\n```\n\n```\nhttps://enterprise.cloud.ibm.com/v1/focus-reports\n```\n\nIf you enabled service endpoints in your account, you can send API requests over the IBM Cloud® private network at the following base endpoint URLs. For more information, see [Enabling VRF and service endpoints](https://cloud.ibm.com/docs/account?topic=account-vrf-service-endpoint).\n\nFor usage reports (`/v1/resource-usage-reports`):\n\n* Private endpoint URL for VPC infrastructure: `https://private.enterprise.cloud.ibm.com/v1/resource-usage-reports`\n* Private endpoint URLs for classic infrastructure:\n * Dallas: `https://private.us-south.enterprise.cloud.ibm.com/v1/resource-usage-reports`\n * Washington DC: `https://private.us-east.enterprise.cloud.ibm.com/v1/resource-usage-reports`\n\nFor FOCUS reports (`/v1/focus-reports`):\n\n* Private endpoint URL for VPC infrastructure: `https://private.enterprise.cloud.ibm.com/v1/focus-reports`\n* Private endpoint URLs for classic infrastructure:\n * Dallas: `https://private.us-south.enterprise.cloud.ibm.com/v1/focus-reports`\n * Washington DC: `https://private.us-east.enterprise.cloud.ibm.com/v1/focus-reports`\n\nBase URL\n\n```\nhttps://enterprise.cloud.ibm.com/v1/resource-usage-reports\n```\n\n## Authentication\n\nAccess 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.\n\n* Administrator\n* Editor\n* Usage Reports Viewer\n\n Each method lists the specific IAM action that you need to be assigned a role to access. For more information about these roles, see [Assigning access for enterprise management](https://cloud.ibm.com/docs/enterprise-management?topic=enterprise-management-assign-access-enterprise&interface=ui).\n\nThe user or service must pass a valid IAM token in the Authorization header. The token is used to identify the subject.\n\n```\n-H 'Authorization: Bearer '\n```\n\nYou 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 [Generate an IAM token by using an API key](https://cloud.ibm.com/docs/iam?topic=iam-iamtoken_from_apikey#iamtoken-from-apikey-api).\n\nTo retrieve your access token:\n\n```bash\ncurl -X POST \\\n \"https://iam.cloud.ibm.com/identity/token\" \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --header 'Accept: application/json' \\\n --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \\\n --data-urlencode 'apikey={api_key}'\n```\n\nReplace `` with your service credentials. Then use the full `IAM token` value, prefixed by the _Bearer_ token type, to authenticate your API requests.\n\nExample that sets options by using environment variables\n\n```bash\nexport ENTERPRISE_USAGE_REPORTS_APIKEY={api_key}\n```\n\n```java\nimport com.ibm.cloud.platform_services.enterprise_usage_reports.v1.EnterpriseUsageReports;\n\nEnterpriseUsageReports service = EnterpriseUsageReports.newInstance();\n```\n\nReplace `{api_key}` with your IBM Cloud IAM API key. Invoke service operations by using the `service` variable.\n\nFor more authentication examples, check out the [IBM Cloud SDK Common project on GitHub](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.md#authentication).\n\nExample that sets options by using environment variables\n\n```bash\nexport ENTERPRISE_USAGE_REPORTS_APIKEY={api_key}\n```\n\n```go\nenterpriseUsageReportsService, err := enterpriseusagereportsv1.NewEnterpriseUsageReportsV1UsingExternalConfig(\n &enterpriseusagereportsv1.EnterpriseUsageReportsV1Options{})\nif err != nil {\n panic(err)\n}\n```\n\nReplace `{api_key}` with your IBM Cloud IAM API key. Invoke service operations by using the `enterpriseUsageReportsService` variable.\n\nFor more authentication examples, check out the [IBM Cloud SDK Common project on GitHub](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.md#authentication).\n\nExample that sets options by using environment variables\n\n```bash\nexport ENTERPRISE_USAGE_REPORTS_APIKEY={api_key}\n```\n\n```python\nfrom ibm_platform_services.enterprise_usage_reports_v1 import *\n\nenterprise_usage_reports_service = EnterpriseUsageReportsV1.new_instance()\n```\n\nReplace `{api_key}` with your IBM Cloud IAM API key. Invoke service operations by using the `enterprise_usage_reports_service` variable.\n\nFor more authentication examples, check out the [IBM Cloud SDK Common project on GitHub](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.md#authentication).\n\nExample that sets options by using environment variables\n\n```bash\nexport ENTERPRISE_USAGE_REPORTS_APIKEY={api_key}\n```\n\n```javascript\nconst EnterpriseUsageReportsV1 = require('ibm-platform-services/enterprise-usage-reports/v1');\n\nconst enterpriseUsageReportsService = EnterpriseUsageReportsV1.newInstance();\n```\n\nReplace `{api_key}` with your IBM Cloud IAM API key. Invoke service operations by using the `enterpriseUsageReportsService` variable.\n\nFor more authentication examples, check out the [IBM Cloud SDK Common project on GitHub](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.md#authentication).\n\n## Auditing\n\nYou can monitor API activity within your account by using the IBM Cloud Logs service. Whenever an API method is called, an event is generated that you can then track and audit from within IBM Cloud Logs. The specific event type is listed for each individual method.\n\nFor more information about how to track enterprise usage report activity, see [Activity tracking events for enterprise management](https://cloud.ibm.com/docs/enterprise-management?topic=enterprise-management-at_events_em).\n\n## Error handling\n\nThis 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.\n\n| HTTP Code | Description | Recovery |\n|:----------|:----------------------|:---------------------------------------------------------------------------------------------------------------------------------------|\n| `200` | Success | The request was successful. |\n| `400` | Bad Request | The input parameters in the request are either incomplete or incorrect. Be sure to validate your request. |\n| `401` | Authentication Failed | The token provided in the `Authorization` header is invalid or expired. |\n| `403` | Authorization Failed | The subject does not have access to the reports. |\n| `404` | Not Found | The entity does not exist. |\n| `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. |\n| `5xx` | Internal Server Error | The API is currently unavailable. Your request could not be processed. Wait a few minutes and try again. |\n\n## Pagination\n\nSome API requests might return many results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. `GET` requests for the following resources use pagination:\n\n * `/v1/resource-usage-reports`\n\nThe `next` and `reports` fields are included in the collection response. The `next` field gives the link to the next page of results.\nBy default, each page contains 30 items, and the maximum number of items per page is 100. To specify a different number of items per page, use the `limit` query parameter.\n\n## Related APIs\n\nYou can use the following related APIs to manage your enterprise:\n\n* [Enterprise Management API](https://cloud.ibm.com/docs/apis/enterprise-apis/enterprise): Create and manage enterprises, account groups, and accounts.\n* [Enterprise Billing Units API](https://cloud.ibm.com/docs/apis/enterprise-apis/billing-unit): Manage enterprise billing and credit pools.", "version": "1.0.0-beta.1", "title": "Enterprise Usage Reports API", "x-alternate-name": "Enterprise Usage Reports", "contact": { "email": "rajkiranrbala@us.ibm.com" }, "x-codegen-config": { "java": { "apiPackage": "com.ibm.cloud.platform_services" }, "go": { "apiPackage": "github.com/IBM/platform-services-go-sdk", "improvedNameFormattingV2": true }, "python": { "apiPackage": "ibm_platform_services" } }, "x-sdk-supported-languages": [ "curl", "go", "java", "node", "python" ], "x-github": "https://github.ibm.com/cloud-api-docs/enterprise", "x-github-issues": "https://github.ibm.com/cloud-api-docs/enterprise/issues/new", "x-last-updated": "2026-09-17" }, "servers": [ { "url": "https://enterprise.cloud.ibm.com", "description": "Production" }, { "url": "https://enterprise.test.cloud.ibm.com", "description": "Staging" } ], "security": [ { "IAM": [] } ], "tags": [ { "name": "Usage reports", "description": "Operations to obtain enterprise usage reports." }, { "name": "FOCUS reports", "description": "Operations to obtain enterprise FOCUS (FinOps Open Cost and Usage Specification v1.2) reports." } ], "paths": { "/v1/resource-usage-reports": { "get": { "tags": [ "Usage reports" ], "operationId": "get_resource_usage_report", "summary": "Get usage reports for enterprise entities", "description": "Usage reports for entities in the IBM Cloud enterprise. These entities can be the enterprise, an account group, or an account.", "parameters": [ { "name": "enterprise_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "example": "abc12340d4bf4e36b0423d209b286f24" }, { "name": "account_group_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "example": "def456a237b94b9a9238ef024e204c9f" }, { "name": "account_id", "in": "query", "description": "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.", "schema": { "type": "string" }, "example": "987abcba31834216b8c726a7dd9eb8d6" }, { "name": "children", "in": "query", "description": "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.", "schema": { "type": "boolean" } }, { "name": "month", "in": "query", "description": "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.", "schema": { "type": "string", "pattern": "^\\d{4}\\-(0?[1-9]|1[012])$" }, "example": "2019-06" }, { "name": "billing_unit_id", "in": "query", "description": "The ID of the billing unit by which to filter the reports.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The maximum number of search results to be returned.", "schema": { "type": "integer" }, "example": 10 }, { "name": "offset", "in": "query", "description": "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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage Reports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reports" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-ibm-permissions": { "description": "The actions that are required correspond with the entities that you're retrieving the usage report for.", "actions": [ { "name": "enterprise.enterprise.retrieve" }, { "name": "enterprise.enterprise.retrieve-usage-report" }, { "name": "enterprise.account-group.retrieve-usage-report" }, { "name": "enterprise.account-group.retrieve" }, { "name": "enterprise.account.retrieve-usage-report" }, { "name": "enterprise.account.retrieve" }, { "name": "billing.billing-unit.read" } ] }, "x-ibm-events": { "description": "Calling the method generates ```billing.enterprise-usage-report.read``` auditing event.", "events": [ { "name": "billing.enterprise-usage-report.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Enterprise usage", "example": [ { "type": "code", "source": [ "curl -X GET \\\n'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?enterprise_id=abc12340d4bf4e36b0423d209b286f24&month=2019-07' \\\n-H 'Authorization: Bearer '\n" ] } ] }, { "name": "Enterprise children usage", "example": [ { "type": "code", "source": [ "curl -X GET \\\n'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?enterprise_id=abc12340d4bf4e36b0423d209b286f24&month=2019-07&children=true' \\\n-H 'Authorization: Bearer '\n" ] } ] }, { "name": "Account group usage", "example": [ { "type": "code", "source": [ "curl -X GET \\\n'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_group_id=def456a237b94b9a9238ef024e204c9f&month=2019-07' \\\n-H 'Authorization: Bearer '\n" ] } ] }, { "name": "Account group children usage with page size", "example": [ { "type": "code", "source": [ "curl -X GET \\\n'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_group_id=def456a237b94b9a9238ef024e204c9f&month=2019-07&children=true&limit=2' \\\n-H 'Authorization: Bearer '\n" ] } ] }, { "name": "Account usage", "example": [ { "type": "code", "source": [ "curl -X GET \\\n'https://enterprise.cloud.ibm.com/v1/resource-usage-reports?account_id=987abcba31834216b8c726a7dd9eb8d6&month=2019-07&children=true' \\\n-H 'Authorization: Bearer '\n" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "getResourceUsageReportOptions := &enterpriseusagereportsv1.GetResourceUsageReportOptions{\n", " EnterpriseID: &enterpriseID,\n", " Month: &billingMonth,\n", "}\n", "\n", "pager, err := enterpriseUsageReportsService.NewGetResourceUsageReportPager(getResourceUsageReportOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "\n", "var allResults []enterpriseusagereportsv1.ResourceUsageReport\n", "for pager.HasNext() {\n", " nextPage, err := pager.GetNext()\n", " if err != nil {\n", " panic(err)\n", " }\n", " allResults = append(allResults, nextPage...)\n", "}\n", "b, _ := json.MarshalIndent(allResults, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "GetResourceUsageReportOptions getResourceUsageReportOptions = new GetResourceUsageReportOptions.Builder()\n", " .enterpriseId(enterpriseId)\n", " .month(billingMonth)\n", " .build();\n", "\n", "GetResourceUsageReportPager pager = new GetResourceUsageReportPager(service, getResourceUsageReportOptions);\n", "List allResults = new ArrayList<>();\n", "while (pager.hasNext()) {\n", " List nextPage = pager.getNext();\n", " allResults.addAll(nextPage);\n", "}\n", "\n", "System.out.println(GsonSingleton.getGson().toJson(allResults));" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " enterpriseId: enterpriseId,\n", " month: billingMonth,\n", "};\n", "\n", "const allResults = [];\n", "try {\n", " const pager = new EnterpriseUsageReportsV1.GetResourceUsageReportPager(enterpriseUsageReportsService, params);\n", " while (pager.hasNext()) {\n", " const nextPage = await pager.getNext();\n", " expect(nextPage).not.toBeNull();\n", " allResults.push(...nextPage);\n", " }\n", " console.log(JSON.stringify(allResults, null, 2));\n", "} catch (err) {\n", " console.warn(err);\n", "}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "all_results = []\n", "pager = GetResourceUsageReportPager(\n", " client=enterprise_usage_reports_service,\n", " enterprise_id=enterprise_id,\n", " month=billing_month,\n", ")\n", "while pager.has_next():\n", " next_page = pager.get_next()\n", " assert next_page is not None\n", " all_results.extend(next_page)\n", "\n", "print(json.dumps(all_results, indent=2))" ] } ] } ] } } } }, "/v1/focus-reports": { "get": { "tags": [ "FOCUS reports" ], "operationId": "get_enterprise_focus_report", "summary": "Get a FOCUS report for an enterprise", "description": "Returns the FOCUS (FinOps Open Cost and Usage Specification v1.2) cost and usage report for an enterprise. The following access modes are supported:\n- **Full report** (no `page` parameter): Returns the complete report as a gzip-compressed CSV file (`Content-Type: application/gzip`).\n- **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.", "parameters": [ { "name": "enterprise_id", "in": "query", "required": true, "description": "The ID of the enterprise for which the FOCUS report is requested.", "schema": { "type": "string" }, "example": "abc12340d4bf4e36b0423d209b286f24" }, { "name": "month", "in": "query", "required": true, "description": "The billing month for which the FOCUS report is requested in `YYYY-MM` format. This value cannot be a future month.", "schema": { "type": "string", "pattern": "^\\d{4}\\-(0?[1-9]|1[012])$" }, "example": "2024-06" }, { "name": "page", "in": "query", "required": false, "description": "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.", "schema": { "type": "integer", "minimum": 1 }, "example": 1 } ], "responses": { "200": { "description": "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.", "headers": { "Content-Disposition": { "description": "Attachment filename for the returned file.", "schema": { "type": "string" } }, "X-Report-Type": { "description": "Always `enterprise-focus`.", "schema": { "type": "string" } }, "X-Report-Version": { "description": "FOCUS specification version used to generate the report, for example, `1.2`.", "schema": { "type": "string" } }, "X-Total-Pages": { "description": "Total number of pages available. Present only on paged responses.", "schema": { "type": "integer" } }, "X-Current-Page": { "description": "The page number returned. Present only on paged responses.", "schema": { "type": "integer" } }, "X-Total-Lines": { "description": "Total number of data lines across all pages (excluding headers). Present only on paged responses.", "schema": { "type": "integer" } }, "X-Page-Lines": { "description": "Inclusive line range for this page in the format `start-end`. Present only on paged responses.", "schema": { "type": "string" } } }, "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } }, "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request. One or more query parameters are missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_enterprise_id": { "summary": "Missing enterprise_id", "value": { "errors": [ { "code": "missing_required_parameter", "message": "Missing required parameter: enterprise_id" } ] } }, "invalid_month": { "summary": "Invalid month format", "value": { "errors": [ { "code": "invalid_parameter_value", "message": "Invalid date format. Expected YYYY-MM" } ] } }, "future_month": { "summary": "Future month requested", "value": { "errors": [ { "code": "invalid_parameter_value", "message": "Cannot generate report for a future date" } ] } }, "invalid_page": { "summary": "Invalid page number", "value": { "errors": [ { "code": "invalid_parameter_value", "message": "Invalid page parameter. Must be a positive integer" } ] } } } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. The enterprise was not found, the requested page does not exist, or the report has not yet been generated for this month.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "enterprise_not_found": { "summary": "Enterprise not found", "value": { "errors": [ { "code": "not_found", "message": "Enterprise not found" } ] } }, "report_not_available": { "summary": "Report not yet generated", "value": { "errors": [ { "code": "report_not_available", "message": "Enterprise FOCUS report not available for this month. Reports are generated daily at 03:00 UTC. Try again after the next scheduled generation.", "details": { "enterprise_id": "abc12340d4bf4e36b0423d209b286f24", "month": "2024-06", "next_generation": "Daily at 03:00 UTC" } } ] } }, "page_not_found": { "summary": "Requested page out of range", "value": { "errors": [ { "code": "page_not_found", "message": "Page 5 not found. Total pages available: 3", "details": { "requested_page": 5, "total_pages": 3, "total_lines": 75000 } } ] } } } } } }, "500": { "description": "Unexpected errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-ibm-permissions": { "description": "To retrieve the FOCUS report, you must have the Usage Reports Viewer or Administrator role on the Enterprise service.", "actions": [ { "name": "enterprise.enterprise.retrieve" }, { "name": "enterprise.enterprise.retrieve-usage-report" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Full enterprise FOCUS report (gzip)", "example": [ { "type": "code", "source": [ "curl -X GET \\\n'https://enterprise.cloud.ibm.com/v1/focus-reports?enterprise_id=abc12340d4bf4e36b0423d209b286f24&month=2024-06' \\\n-H 'Authorization: Bearer ' \\\n--output enterprise-focus-2024-06.csv.gz\n" ] } ] }, { "name": "Paged enterprise FOCUS report (CSV, page 1)", "example": [ { "type": "code", "source": [ "curl -X GET \\\n'https://enterprise.cloud.ibm.com/v1/focus-reports?enterprise_id=abc12340d4bf4e36b0423d209b286f24&month=2024-06&page=1' \\\n-H 'Authorization: Bearer '\n" ] } ] } ] } } } } }, "components": { "securitySchemes": { "IAM": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The caller must have the necessary policies set up in IAM to access the usage reports. The APIs must be called by using the bearer token that was generated by using the IAM token service." } }, "schemas": { "Link": { "description": "An object that contains a link to a page of search results.", "type": "object", "properties": { "href": { "description": "A link to a page of search results.", "type": "string" } } }, "Reports": { "type": "object", "description": "Resource Usage Reports API response", "properties": { "limit": { "type": "integer", "description": "The maximum number of reports in the response." }, "first": { "allOf": [ { "$ref": "#/components/schemas/Link" }, { "description": "An object that contains the link to the first page of the search query." } ] }, "next": { "allOf": [ { "$ref": "#/components/schemas/Link" }, { "description": "An object that contains the link to the next page of the search query." } ] }, "reports": { "type": "array", "description": "The list of usage reports.", "items": { "$ref": "#/components/schemas/ResourceUsageReport" } } }, "example": { "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": [] } ] } }, "Reports_CSV_Metadata": { "type": "object", "properties": { "Entity ID": { "type": "string" }, "Entity Type": { "type": "string" }, "Billing Month": { "type": "string" }, "Currency Rate": { "type": "number" }, "Created Time": { "type": "string" } }, "required": [ "Entity ID", "Entity Type", "Billing Month", "Created Time" ] }, "Reports_CSV_Enterprise_Hierarchy": { "type": "object", "properties": { "Entity ID": { "type": "string" }, "Entity Type": { "type": "string" }, "Entity Name": { "type": "string" }, "Parent Entity ID": { "type": "string" }, "Parent Entity Name": { "type": "string" }, "Parent Entity Type": { "type": "string" }, "Entity Created On": { "type": "string" } } }, "Reports_CSV_Billing_Unit": { "type": "object", "properties": { "Billing Unit ID": { "type": "string" }, "Billing Unit Name": { "type": "string" }, "Billing Unit Created On": { "type": "string" } } }, "Reports_CSV_Credit_Pools": { "type": "object", "properties": { "Credit Pool Type": { "type": "string" }, "Currency Code": { "type": "string" }, "Billing Option ID": { "type": "string" }, "Category": { "type": "string" }, "Start Date": { "type": "string" }, "End Date": { "type": "string" }, "Total Credits": { "type": "number" }, "Starting Balance": { "type": "number" }, "Used Credits": { "type": "number" }, "Current Balance": { "type": "number" } } }, "Reports_CSV_Overages": { "type": "object", "properties": { "Credit Pool Type": { "type": "string" }, "Currency Code": { "type": "string" }, "Overage": { "type": "number" } } }, "Reports_CSV_Entity_Usage_Summary": { "type": "object", "properties": { "Entity ID": { "type": "string" }, "Entity Type": { "type": "string" }, "Entity Name": { "type": "string" }, "Billing Unit ID": { "type": "string" }, "Billing Unit Name": { "type": "string" }, "Country Code": { "type": "string" }, "Currency Code": { "type": "string" }, "Billable Cost": { "type": "number" }, "Non Billable Cost": { "type": "number" } }, "required": [ "Entity ID", "Entity Type", "Entity Name", "Billing Unit ID", "Billing Unit Name", "Country Code", "Currency Code", "Billable Cost", "Non Billable Cost" ] }, "Reports_CSV_Aggr_Usage_Details": { "type": "object", "properties": { "Entity ID": { "type": "string" }, "Entity Type": { "type": "string" }, "Parent Entity ID": { "type": "string" }, "Billing Unit ID": { "type": "string" }, "Currency Code": { "type": "string" }, "Service Name": { "type": "string" }, "Service ID": { "type": "string" }, "Billable": { "type": "boolean" }, "Plan Name": { "type": "string" }, "Plan ID": { "type": "string" }, "Pricing Region": { "type": "string" }, "Metric": { "type": "string" }, "Unit": { "type": "string" }, "Quantity": { "type": "number" }, "Cost": { "type": "number" }, "Pending": { "type": "boolean" } }, "required": [ "Entity ID", "Entity Type", "Billing Unit ID", "Currency Code", "Service Name", "Service ID", "Billable", "Plan Name", "Plan ID", "Metric", "Unit", "Quantity", "Cost", "Pending" ] }, "ResourceUsageReport": { "type": "object", "description": "An object that represents a usage report", "required": [ "entity_crn", "entity_id", "entity_type", "entity_name", "billing_unit_id", "billing_unit_crn", "billing_unit_name", "currency_code", "country_code", "month", "billable_cost", "non_billable_cost", "billable_rated_cost", "non_billable_rated_cost", "resources" ], "properties": { "entity_id": { "type": "string", "description": "The ID of the entity.", "example": "de129b787b86403db7d3a14be2ae5f76" }, "entity_type": { "type": "string", "enum": [ "enterprise", "account-group", "account" ], "description": "The entity type.", "example": "enterprise" }, "entity_crn": { "type": "string", "description": "The Cloud Resource Name (CRN) of the entity towards which the resource usages were rolled up.", "example": "crn:v1:bluemix:public:enterprise::a/e9a57260546c4b4aa9ebfa316a82e56e::enterprise:de129b787b86403db7d3a14be2ae5f76" }, "entity_name": { "type": "string", "description": "A user-defined name for the entity, such as the enterprise name or account group name.", "example": "Platform-Services" }, "billing_unit_id": { "type": "string", "description": "The ID of the billing unit.", "example": "65719a07280a4022a9efa2f6ff4c3369" }, "billing_unit_crn": { "type": "string", "description": "The CRN of the billing unit.", "example": "crn:v1:bluemix:public:billing::a/3f99f8accbc848ea96f3c61a0ae22c44::billing-unit:65719a07280a4022a9efa2f6ff4c3369" }, "billing_unit_name": { "type": "string", "description": "The name of the billing unit.", "example": "Operations" }, "country_code": { "type": "string", "description": "The country code of the billing unit.", "example": "USA" }, "currency_code": { "type": "string", "description": "The currency code of the billing unit.", "example": "USD" }, "month": { "type": "string", "description": "Billing month", "pattern": "^\\d{4}\\-(0?[1-9]|1[012])$", "example": "2017-08" }, "billable_cost": { "type": "number", "description": "Billable charges that are aggregated from all entities in the report." }, "non_billable_cost": { "type": "number", "description": "Non-billable charges that are aggregated from all entities in the report." }, "billable_rated_cost": { "type": "number", "description": "Aggregated billable charges before discounts." }, "non_billable_rated_cost": { "type": "number", "description": "Aggregated non-billable charges before discounts." }, "resources": { "type": "array", "description": "Details about all the resources that are included in the aggregated charges.", "items": { "$ref": "#/components/schemas/ResourceUsage" } } } }, "MetricUsage": { "type": "object", "description": "An object that represents a metric", "required": [ "metric", "unit", "quantity", "rateable_quantity", "cost", "rated_cost" ], "properties": { "metric": { "type": "string", "description": "The name of the metric.", "example": "UP-TIME" }, "unit": { "type": "string", "description": "A unit to qualify the quantity.", "example": "HOURS" }, "quantity": { "type": "number", "description": "The aggregated value for the metric.", "example": 711.11 }, "rateable_quantity": { "type": "number", "description": "The quantity that is used for calculating charges.", "example": 700 }, "cost": { "type": "number", "description": "The cost that was incurred by the metric.", "example": 123.45 }, "rated_cost": { "type": "number", "description": "The pre-discounted cost that was incurred by the metric.", "example": 130 }, "price": { "type": "array", "description": "The price with which cost was calculated.", "items": { "type": "object" } } } }, "PlanUsage": { "type": "object", "description": "Aggregated values for the plan.", "required": [ "plan_id", "billable", "cost", "rated_cost", "usage" ], "properties": { "plan_id": { "type": "string", "description": "The ID of the plan." }, "pricing_region": { "type": "string", "description": "The pricing region for the plan." }, "pricing_plan_id": { "type": "string", "description": "The pricing plan with which the usage was rated." }, "billable": { "type": "boolean", "description": "Whether the plan charges are billed to the customer." }, "cost": { "type": "number", "description": "The total cost that was incurred by the plan." }, "rated_cost": { "type": "number", "description": "The total pre-discounted cost that was incurred by the plan." }, "usage": { "type": "array", "description": "All of the metrics in the plan.", "items": { "$ref": "#/components/schemas/MetricUsage" } } } }, "ResourceUsage": { "type": "object", "description": "A container for all the plans in the resource.", "required": [ "resource_id", "billable_cost", "billable_rated_cost", "non_billable_cost", "non_billable_rated_cost", "plans" ], "properties": { "resource_id": { "type": "string", "description": "The ID of the resource." }, "billable_cost": { "type": "number", "description": "The billable charges for the account." }, "billable_rated_cost": { "type": "number", "description": "The pre-discounted billable charges for the account." }, "non_billable_cost": { "type": "number", "description": "The non-billable charges for the account." }, "non_billable_rated_cost": { "type": "number", "description": "The pre-discounted, non-billable charges for the account." }, "plans": { "type": "array", "description": "All of the plans in the resource.", "items": { "$ref": "#/components/schemas/PlanUsage" } } } }, "Error": { "type": "object", "description": "An object that represents an error", "required": [ "errors" ], "properties": { "errors": { "type": "array", "description": "Errors that were encountered when serving the request.", "items": { "required": [ "code" ], "type": "object", "properties": { "code": { "type": "string", "description": "An error code that identifies a problem." }, "message": { "type": "string", "description": "A message that describes the error." } } } } } } } } }