Cost Analysis Overview

Cost Analysis is an easy-to-use visualization tool to help you track and optimize your Oracle Cloud Infrastructure spending, allows you to generate charts, and download accurate, reliable tabular reports of aggregated cost data on your Oracle Cloud Infrastructure consumption. Use the tool for spot checks of spending trends and for generating reports. Common scenarios you might be interested in include:

  • Show monthly costs for compartment X and its children, grouped by service or by tag.
  • Show daily costs for tag key A and tag key B, values X, Y and Z, grouped by service and product description (SKU).
  • Show hourly costs for service = compute or database, grouped by compartment name.

You can choose from one of the predefined, default reports from the Reports menu, and you can choose the dates you’re interested in. By default, the Costs by Service report is shown when the Cost Analysis page first opens. Filter to the specific tags, compartments, services, or filter you want, and pick how you want it grouped. As a result, a chart and corresponding data table are generated, and can also be downloaded as a data table. You can also save a custom set of dates, filters, and grouping dimensions into a saved report. Up to ten custom reports can be saved. See Cost Analysis Query Fields and Viewing and Working with the Chart Data for more information on the related Cost Analysis query settings. You can also estimate future usage and consumption information, based on past usage data.

If you want to re-create the breakdown provided by the former Classic Version of the Cost Analysis tool, apply the SKU (Part Number) grouping dimension in the current version of Cost Analysis. To explore your costs in new ways, we recommended viewing your costs based on Service, or Service and Product Description. If you are doing cost tracking, we recommended grouping by Compartment or Tag.

Note

All tags, not only cost tracking tags, are supported.
Note

Costs for tags are based on the date at which the tag was associated with a resource. It does not work retroactively for resources on which these tags are applied.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

If you're new to policies, see Getting Started with Policies and Common Policies.

To use Cost Analysis, the following policy statement is required:

Allow group <group_name> to read usage-report in tenancy

Authentication and Authorization

Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and authorization, for all interfaces (the Console, SDK or CLI, and REST API).

An administrator in your organization needs to set up groups , compartments , and policies  that control which users can access which services, which resources, and the type of access. For example, the policies control who can create new users, create and manage the cloud network, launch instances, create buckets, download objects, etc. For more information, see Getting Started with Policies. For specific details about writing policies for each of the different services, see Policy Reference.

If you’re a regular user (not an administrator) who needs to use the Oracle Cloud Infrastructure resources that your company owns, contact your administrator to set up a user ID for you. The administrator can confirm which compartment or compartments you should be using.

Cost Analysis Query Fields

The following table describes the Cost Analysis query fields.

Field Description
Reports Select from one of the Default Reports:
  • Costs by Service (shown by default when the Cost Analysis page first opens)
  • Costs by Service and Description
  • Costs by Service and Sku (Part Number)
  • Costs by Service and Tag
  • Compute Costs by Compartment
  • Monthly Costs

After you have created some saved reports, they are listed in this menu under Saved Reports.

Start/End Date (UTC)

Select the start and end date according to the UTC time zone.

After clicking either of the calendar icons, you can also query and select predefined time ranges for data available in the usage store:
  • 7D
  • 10D
  • MTD
  • 2M
  • 3M
  • All Data
  • 6M
  • YTD

These preset time ranges are crucial for saved reports, because they will automatically change the time range every time a saved report is launched. For example, if the current date was March 18, and you created a saved report with 7D as the time period, the report shows data from March 11 to March 18. When you launch the same report the next day (March 19), the date range switches to March 12 to March 19. Lastly, when setting the time period, it is also indicated above the chart in Time Period.

Note

Historical data is currently being back-filled for tenancies and may not appear immediately. As the process completes, up to twelve months of past consumption data will become available.
Granularity

Granularity (hourly, daily, monthly) is based on the requested date range size. The logic is the following:

  • Hourly: 48 hours or less (only shown when you select a Start Date and End Date with the same day)
  • Daily: > 48 hours, <= 2 months
  • Monthly: > 2 months
Show

Allows you to view the report in terms of Cost (the default) or Usage.

Show Forecast Allows estimating future usage and consumption information, based on past usage data. See Forecasting Costs for prerequisites and usage information. When Show Forecast is selected, the End Date (UTC) field changes to End Forecast Date (UTC).
Note

When viewing forecast data, you can choose dates from End Date (UTC) after the current day, but you can not do this when Show Forecast is not selected.
Cumulative Select this option to modify the values so that they’re cumulative for the selected time period selected. For example, consider if you were looking at 10 days of data, cumulatively, and the values for each day are $5. In such a case, selecting Cumulative displays values of 5, 10, 15, 20, 25, 30, 35, 40, 45, and 50 across the 10 days, respectively. In a non-cumulative chart, the values display as 5, 5, 5, 5, 5, 5, 5, 5, 5, 5.
Filters

Allows filtering on the following:

  • Availability Domain
  • Compartment
    Note

    Filtering by compartment displays usage and costs attributed to all resources in the selected compartments, and their child compartments.
    • By name
    • By OCID
    • By Path (for example, root/compartmentname/compartmentname)
  • Platform (Gen-1 are services which are not OCI native. Gen-2 includes all OCI native services)
  • Tag
    • By Tag Namespace
    • By TagKey + Value
  • Region
  • Service
  • Resource OCID
  • Product description: The human-readable corresponding name)
  • SKU - Part Number: For example, B91444.
  • Tenant
  • Unit

See Filters for more information on adding, editing, and removing filters, and filter logic.

Grouping Dimensions

Allows visualizing the data in terms of the particular grouping. A grouping dimension by Service is displayed by default. You can view only one grouping dimension at a time.

  • Availability Domain
  • Compartment. When you choose to group by compartment, you can pick the display name value, and a compartment depth. The compartment depth corresponds to the lowest level you want the compartments to be grouped by. All levels above that grouping level return just what is directly in those compartments. The grouping level returns values for all resources in those compartments, plus all resources in compartments below it.
    • Display As
      • Compartment Name
      • Compartment OCID
      • Compartment Path
      Note

      If Compartment OCID is chosen, you cannot view Compartment Level.
    • Compartment Level
      • All (the default): Every compartment is displayed. Values would display usage/spend associated only with the resources in that specific compartment.
      • Level 1 (root only): Only 1 column is returned (root), and values for resources contained in root and every child compartment are displayed.
      • Level 2 (root/<value>): Displays root, with values for root equaling only those resources in root. All compartments that are direct children of root are also returned. The values for each of those compartments is the sum of all resources therein, or within any children of those compartments.
      • Level 3 (root/<value>/<value>): Returns root, with values for root equaling only those resources in root. All Level 2 compartments are also returned, but with values only equal to the resources contained in each of those specific compartments. The first child level of the level 2 compartments are also returned. The values for the third level of compartment (root/child1/child2 <<) would be equal to the resources in those compartments, plus all the resources in all the children of those compartments.
      • Level 4 (root/<value>/<value>/<value>)
      • Level 5 (root/<value>/<value>/<value>/<value>)
  • Platform (Gen-1 are services which are not Oracle Cloud Infrastructurenative, while Gen-2 includes all native Oracle Cloud Infrastructure services)
  • Region
  • Resource OCID
  • Service
  • Service and Product Description
  • Service and SKU (Part Number)
  • SKU (Part Number)
  • SKU (Product Description)
  • Tag
  • Tenant ID
  • Tenant Name

See Grouping Dimensions for more information on viewing and changing grouping dimensions.

Viewing and Working with the Chart Data

When the Cost Analysis page first opens, the default view is to show the Costs by Service report, grouped by Service and with Daily granularity. The default date range is from the first day of the month to the current day. The Cost Analysis chart is organized in terms of time (UTC) on the X-axis, and the cost amount on the Y-axis. When viewing a chart, you can hover the mouse over a data point in the chart to see more information about it. The tooltip shows the cost value summary for the particular Y-axis item at a particular time, whether you are viewing the chart as either a Bars (the default), Lines, or Stacked Lines chart.

You can start by viewing the chart data in terms of the predefined reports, by selecting one from the Reports menu, and then adjust the date range, granularity, and then add or remove filters and grouping dimensions (or both, that is, view the cost data according to one or more filters, or in terms of both filters and a single grouping dimension).

You can also save your adjustments as a saved report that you can view later, alongside the predefined reports. See Saving Reports for more information on saving reports.

To the right of the chart, the Legend box shows all the data by default, and each item is color-coded. You can click the eye icon next to any of the Legend items to toggle the chart data on or off. For example, when viewing a chart with various services and their costs, the Legend box includes all the impacted services related to the query. Toggling one or more of the services shows or hides them dynamically from the chart output. Toggling the Legend data, however, does not change the data shown in the table view, or what is downloaded.

A tabular view of the chart is also provided under the chart, which is updated as you apply different time period, filtering, and grouping dimension options. When viewing the table data, you can click the column header to sort in ascending or descending order.

To help determine what is driving costs, see the following topics:

Note

Data can take up to 48 hours to appear in Cost Analysis.

Filters

See the following for instructions on how to add, edit, and remove filters, as well filter logic.

To add filters
  1. Open the navigation menu and click Governance and Administration. Under Cost Management, click Cost Analysis.
  2. From Start/End Date (UTC), select a time period.
  3. From Show, select whether you want to view Cost or Usage.
  4. Choose from three chart types, whether Bars (the default), Lines, or Stacked Lines.
  5. From Filters, select a filter. A dialog specific to the chosen filter is displayed. For example, if you chose Service, select a service from the drop-down menu. You can add multiple services if preferred, or click the X icon to remove service filters. Click Select when you are finished selecting filtering criteria.
  6. Click Apply to apply the changes and reload the chart and table with the selected filters.
To edit a filter
  1. To edit the filter after it has already been applied to the chart, click the filter. The filter's dialog box is displayed.
  2. From the filter dialog drop-down menu, select one or more filters, and click Select.
  3. Click Apply to apply the changes and reload the chart and table with the selected filters.
To remove a filter
  1. To remove the filter after it has been applied to the chart, click Clear All Filters, or click the filter's X icon under Filters.
  2. Click Apply to apply the changes and reload the chart and table without the selected filters.

Filter Logic

Filters are ORed within each specific filter, and ANDed between filters. For example, a filter for Service = Compute, Block Storage, Object Storage, Database, and Tag = Tag Key "MyKey" displays data that is for (Compute OR Block Storage OR Object Storage OR Database) AND Tag Key "MyKey".

The Tag filter, however, is a unique case. You can add multiple Tag filters, which function as a joined OR.

Note

Only ten Tag Key values are retrieved and shown in the drop-down when you attempt to select a possible Tag Key value. Alternatively, you can manually type in the Tag Key value you want to filter on.

Using Multiple Filters to View Costs

You can start by filtering the Cost Analysis chart data based on a single filter, and then add additional filters. For example:

  1. Set your Grouping Dimensions to Service, to view your costs by service.
  2. From Filters, add a filter by Tag.
  3. Select a Tag Namespace (this example uses "Financial" as the selected namespace).
  4. Select a Tag Key (this example uses "Owner" as the selected key).
  5. Specify whether to Match any value (AND condition), or Match any of the following (OR condition).

    For example, assuming the value "alpha" is the value, and if Match any of the following is chosen, it means show all services that have "alpha" as the owner. Conversely, assuming multiple values "alpha" and "beta" are chosen, and if Match any of the following is selected, this corresponds to an OR condition (meaning, filter to show the costs from all the services from the "Financial" namespace, with the Tag Key "Owner", that matches either the "alpha" or "beta" values).

  6. Click Select, then Apply to reload the Cost Analysis chart with the filtered information.

You can also add another filter by tag, to break the data down further. For example:

  1. From Filters, add a filter by Tag.
  2. Select a Tag Namespace (for example, the "Cost Center" namespace).
  3. Select Match any of the following, and for example, filter for any "Cost Center" values of "1234" or "5678".

    After clicking Select, then Apply, this filter shows the costs from all the services with the previous tag filter, plus this second tag filter ("Financial" namespace, Tag Key "Owner", "alpha" or "beta" values + "Cost Center" namespace with the values of "1234" or "5678"). The two tag filters together amount to an AND with the previous filter (the two filters are shown adjacent to the Add Filter drop-down list).

    Alternatively, instead of this second tag filter ("Cost Center" namespace with the values of "1234" or "5678"), you could add a service filter (NETWORK), and that would show the costs from all the services from the "Financial" namespace, with the Tag Key "Owner", that matches both the "alpha" or "beta" values, and is filtered by the NETWORK service type.

Grouping Dimensions

See the following for instructions on how to view and change grouping dimensions. Grouping dimensions change the way data is aggregated, but does not change the sum. If a resource does not have a value for a particular field, a "no value" column is displayed, which reflects the sum of those resources. Specifically, products which are Gen-1 often do not have an availability domain, compartment, or resource ID.

To view grouping dimensions
  1. Open the navigation menu and click Governance and Administration. Under Cost Management, click Cost Analysis.
  2. From Start/End Date (UTC), select a time period.
  3. From Show, select whether you want to view Cost or Usage.
  4. Choose from three chart types, whether Bars (the default), Lines, or Stacked Lines.
  5. From Grouping Dimensions, select the preferred grouping dimension. If Compartment or Tag is chosen, additional compartment or tag selection fields appear.
  6. Click Apply to apply the changes and reload the chart and table with the selected grouping dimension.
To change a grouping dimension
  1. To change the grouping dimension, select it from Grouping Dimensions.
  2. Click Apply to apply the changes and reload the chart and table with the new grouping dimension.

Identifying a Resource that is Consuming Costs

If you have noticed a large amount of, for example, Database service usage that has appeared in a chart, and you wanted to identify which resource was responsible, you can group by Resource OCID from the Grouping Dimensions drop-down list. Next, from Filters, add a filter for the service type (Database in this example), and click Apply to reload the chart.

The chart reloads to show which resource OCIDs were driving the Database cost, both when hovering over the data point in the chart, and in the Legend box. These resource OCIDs are also displayed in the data table below the chart. If desired, you can save this information by clicking Download, and then selecting Download Table as CSV.

Tip

The Legend box is set to a default size when the charts first loads, but you can click and drag the box to more easily read lengthy items within it (such as OCIDs).

To find more information about the resource, copy the OCID and enter it in the Console's Search box, to pinpoint which resource is driving costs.

Grouping by Service and SKU, or Service and Product Description to Identify Costs

In some instances you may see multiple SKU numbers for a service. When grouping by Service and SKU (Part Number), multiple SKU numbers for the same service appear in the Legend box. For example, if you had multiple Compute entries in the Legend box but they have different SKUs, it means there is one resource using multiple underlying infrastructure components. This case is actually most common for Block Storage (where multiple Block Storage entries appear with different SKUs). Specifically, for the Block Storage case, you are charged for storage itself, but you are also charged for any data transfers out of Block Storage. As a result, you will see multiple "Block Storage" items listed with different SKU numbers in the Legend box. For example:

Block Storage / <SKU number 1>
Block Storage / <SKU number 2>
Block Storage / <SKU number 3>
Block Storage / <SKU number 4>

Another way of looking at this same type of data is to use the Service and Product Description grouping dimension. The Legend box is sorted in the same manner, but presents the data differently. That is, according to the actual product descriptions, versus the SKUs that these are associated with. For example:

Block Storage / Block Volume - Backup
Block Storage / Block Volume - Free
Block Storage / Block Volume - Performance Units
Block Storage / Block Volume - Storage
Tip

By default, these longer descriptions may not be visible, and so you should resize the Legend box to view them.

The Database service is also a useful example. There could be different instances of a database and you could also be charged for Block Storage within the Database service. For example, this entry could appear in the Legend for such a case:

Database / DBaaS - Attached Block Storage Volume - Standard Performance

You could also be charged in the Database service for network transfer. For example:

Database / Oracle Autonomous Data Warehouse - Exadata Storage

Charges for licensing of the application version can also occur:

Database / Database Cloud Service - Enterprise Edition High Performance

Cost and Usage reports are a good way to further slice such information you have noticed in the Cost Analysis charts. For example, in a cost report you might notice a SKU number that's associated with Compute, and also see the same SKU number that's associated with Block Storage. As a result, you may wonder if you were double-billed (though this is actually not the case). To investigate the actual cost, you can first filter the cost CSV spreadsheet by the SKU. Once you have applied a filter to the CSV using a particular SKU, you can see which services are consuming from the product/Description column. For example, a SKU could be using a lot of "Block Volume - Performance Units", but you also notice that "DBaaS - Attached Block Storage Volume" appears in this column.

A way to further segment the data would be to copy the resource ID from the product/resourceid column, of say the "DBaaS - Attached Block Storage Volume" entry you noticed amongst all the "Block Volume - Performance Units", and remove the SKU filter you applied previously. Next, filter the spreadsheet based on the resource ID instead. This then shows all the components (indicated in the product/Description column) that the particular resource ID is consuming.
Note

When viewing a cost report, the cost/productSku and product/description columns map to one another, and are adjacent columns in the CSV. For more information on these fields and other fields that appear in the reports, see Cost and Usage Reports Overview.
Similarly, you can use Cost Analysis to do a Resource OCID grouping dimension, with a Product description filter, to show all the resources that are using a particular product. For example, if you choose Block Volume - Performance Units as the filter, the Cost Analysis chart shows which resources are using "Block Volume - Performance Units". See Identifying a Resource that is Consuming Costs for more information on identifying the particular resource(s).

Download Your Data

Click the Download button to download a CSV file of the data, or a PNG file of the chart. Downloading generates a file that corresponds to the chart or table on the Cost Analysis page, inclusive of applied filters, sorting, and grouping dimensions.

Saving Reports

Use the Report Actions menu to create a saved report. You can later access the report after leaving the Console and returning to Cost Analysis, without having to re-specify your set of dates, filters, granularity, or grouping dimensions. After a report has been saved, it can later be renamed, updated, or deleted. A maximum of ten reports can be saved.

You can create a saved report by modifying one of the predefined Cost Analysis reports, and then save your custom settings as a new report. Your new report(s) can have your own set of filters, grouping dimensions, granularity, and date range settings.

To save a Cost Analysis report:
  1. Open the navigation menu and click Governance and Administration. Under Cost Management, click Cost Analysis.
  2. From Reports, select one of the predefined reports, or use the default Costs by Service report.
  3. Make your preferred query adjustments. See Viewing and Working with the Chart Data, Filters, and Grouping Dimensions for more information on query settings. Also see Cost Analysis Query Fields for an explanation of the Cost Analysis query interface and its fields and possible values.
  4. After you have made changes, the currently selected predefined report name from the Reports menu changes to (edited), to indicate that you have made changes.
  5. If your are done making changes and want to save them as a new report, from Report Actions, select Save as new report. The Save as new report box is displayed.
  6. In Name, enter a saved report name, and click Save. A notification is displayed that your report has been saved, and it is also selected in the Reports menu.

The new saved report is now available for future selection from the Reports menu under Saved Reports.

Note

When the ten-report limit has been exceeded, you must select a pre-existing report from the Overwrite existing report box that you want to be overwritten with the new one.

After a report has been saved, you can rename, reset in-progress changes, update, or delete it.

To rename a report
  1. Select the report from the Reports menu.
  2. From Report Actions, select Rename. The Edit report name box is displayed.
  3. In Name, enter the new report name, and click Save. Notifications are displayed that the report has been updated and renamed.
To reset report changes
  1. Select the report from the Reports menu.
  2. After making changes that you want to revert, from Report Actions, select Reset. The (edited) text next to the report name disappears, to indicate that you have reset the report back to its original state.
To update a report
  1. Select the report from the Reports menu.
  2. Make the preferred changes to dates, filters, granularity, or grouping dimensions.
  3. From Report Actions, select Update. A notification is displayed that the report has been successfully updated.
To delete a report
  1. Select the report from the Reports menu.
  2. From Report Actions, select Delete. A delete confirmation is displayed.
  3. Click Delete to delete the report. A notification is displayed that the report has been deleted.

Forecasting Costs

You can use Cost Analysis to estimate future usage and consumption information, based on past usage data.

Note

Forecasted values are just estimates based on past usage trends, and likely to differ from actual usage.

See Cost Analysis Query Fields for a description of the Cost Analysis search settings, and Viewing and Working with the Chart Data for more information on performing searches.

Forecasting in Cost Analysis has the following characteristics:

  • Exponential smoothing is used for forecasting.
  • You need at least ten days of historical data to be able to do forecasting with Daily granularity. The date range fields (Start/End Date (UTC)) adjust accordingly to this.
  • You need at least three months of historical data to do forecasting with Monthly granularity. As with Daily granularity, the date range fields (Start/End Date (UTC)) adjust accordingly.
  • You can only forecast to the extent you have actual usage. For example, if you only have 15 days of historical data, you can only forecast for 15 days. If you have only four months of data, you can forecast only for four months in the future.
  • The maximum limit for forecasting with Daily granularity is 93 days. The Monthly forecasting maximum limit is 12 months.
  • Since there is a built-in 48-hour delay, the most recent 48 hours are always forecast. Similarly, in monthly forecasting mode, the current month is always forecast, irrespective of how far the current month has progressed.
  • You can only do forecasting from continuous dates with actual usage. Namely, if today is March 26, your date range must start with at least March 24.

To view forecast costs:

  1. Open the navigation menu and click Governance and Administration. Under Cost Management, click Cost Analysis.
  2. Choose your set of search parameters, and then select Show Forecast. You can also select Show Forecast first, and then select search settings. In either case, you can view forecast data.
  3. Click Apply.

The chart reloads with the forecast data. For all chart types (whether Bars, Lines, or Stacked Lines), a Forecast section is displayed (in a grayed out portion) in the right-most end of the chart. In addition, a Total (includes forecast) cost total field is added to the top of the chart, after the Time Period and Cost To Date fields. Lastly, the forecast data is also displayed in the tabular view of the chart (the forecast columns are appended as the grayed out final columns).

You can choose to save your settings, including the forecast data, as a saved report. You can also download a CSV file of the data, or a PNG file of the chart, which includes the forecast data.

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following operations to manage usage:

Use the following operations to manage saved reports:

The Usage API allows retrieval of usage and cost data. You can:
  • Query based on different granularity, for example, MONTHLY or DAILY.
  • Specify queryType, for example, COST, USAGE.
  • Filter and group by different dimension/tags, functioning like an SQL query.
  • Use up to four groupBy parameters.

The following is a sample Usage endpoint URI that conforms to the schema:

  • https://usageapi.<region>.oci.oraclecloud.com/20200107/usage

For more information about the API and to view the full list of endpoints, see the Usage API.

Using granularity

The Usage API supports: MONTLY, DAILY, and HOURLY granularity. All startTime are inclusive, and endTime are exclusive, the same as a Java substring.

  • For HOURLY, only a maximum 36-hour time period is supported, with no more precision than an hour. This means no minutes or seconds in the input time.
  • For MONTHLY, only the first date of the month to another first date of the month is supported. For example, 2020-06-01T00:00:00Z, a maximum 12-month period.

  • For DAILY, no more precision than a day is supported, with a maximum 90-day period. You must enter this as 00:00:00. For example, 2020-06-01T00:00:00Z.

Using groupBy

In an API response, dimension is only shown in terms of groupBy. For example, if "service" isn't in groupBy, the "service" field in the response will be empty.

Note

Only four groupBy parameters can be used at a time.
In addition:
  • If a groupBy list is empty, "currency" will be added into groupBy.
  • If the queryType is "Usage", "unit" will be add into groupBy.
  • If the queryType is "COST" or "empty", "currency" will be add into groupBy.
  • computedAmount works as expected only when "currency" is in groupBy.
  • computedQuantity works as expected only when "unit" is in groupBy.
Using queryType

The API can query USAGE or COST. computedQuantity represents usage and computedAmount represents cost. For getting the expected usage, you need to set queryType to USAGE or add "unit" in groupByKey. This is due to the fact that usage is aggregated/grouped correctly when grouping by unit.

Using filtering

Nested filtering in API requests is supported. The list of filters are evaluated by the operator. In each filter, all dimensions and tags are evaluated by the operator. Simultaneous evaluation of the filter list and dimension/tags is not supported, which means dimensions or tags and the filter list can't be non-empty at the same time.

Supported operators are AND, OR. These two filters below are equal:

"filter": {
  "operator": "AND",
  "dimensions": [
    {
      "key": "service",
      "value": "compute"
    },
    {
      "key": "compartmentPath",
      "value": "abc/cde"
    }
  ],
  "tags": [
    {
      "namespace": "compute",
      "key": "created",
      "value": "string"
    }
  ],
  "filters": null
}
  
or 
 
"filter": {
    "operator": "AND",
    "dimensions": [],
    "tags": [],
    "filters": [{
            "operator": "AND",
            "dimensions": [{
                "key": "service",
                "value": "compute"
            }],
            "tags": null,
            "filters": null
        }, {
            "operator": "AND",
            "dimensions": [{
                "key": "compartmentPath",
                "value": "abc/cde"
            }],
            "tags": null,
            "filters": null
        },
        {
            "operator": "AND",
            "dimensions": null,
            "tags": [{
                "namespace": "compute",
                "key": "created",
                "value": "string"
            }],
            "filters": null
        }
    ]
}
Invalid example because dimensions and filters are non-empty at the same time:
"filter": {
    "operator": "AND",
    "dimensions": [{
                "key": "compartmentPath",
                "value": "abc/cde"
            }],
    "tags": [],
    "filters": [{
            "operator": "AND",
            "dimensions": [{
                "key": "service",
                "value": "compute"
            }],
            "tags": null,
            "filters": null
        },
        {
            "operator": "AND",
            "dimensions": null,
            "tags": [{
                "namespace": "compute",
                "key": "created",
                "value": "string"
            }],
            "filters": null
        }
    ]
}
Querying with tags

As mentioned previously, we only show the field in groupBy. So you need to add tag related fields in groupBy. For example:

"tagNamespace", "tagKey", "tagValue"

If you add tagKey, all items in the response will have a tagKey. tagKey also can be empty even if you add a tagKey. This is because some of your resources don't have a tagKey. We suggested adding all three of these in groupBy, so you can see a complete tag in the response:

"tagNamespace", "tagKey", "tagValue" 

If you want to filter by tag, you need to add the tag in the filter object. This can be filtered by any tagKey/Namespace/value combination of any tagKey/Namespace/value.

Valid groupBy example
"tagNamespace", "tagKey", "tagValue", "service", "skuName", "skuPartNumber", "unit",
"compartmentName", "compartmentPath", "compartmentId", "platform", "region", "logicalAd",
"resourceId", "tenantId", "tenantName"
Note

Only up to four groupBy parameters can be used in an API call.

"tenantId" and "tenantName" are not currently supported.

Valid filter dimension example
"service", "skuName", "skuPartNumber", "unit", "compartmentName", "compartmentPath", "compartmentId", 
"platform", "region", "logicalAd", "resourceId", "tenantId", "tenantName"
This is case-sensitive. "tenantId" and "tenantName" are not currently supported.
How to groupBy compartment?

groupBy compartment-related keys ("compartmentName", "compartmentPath", "compartmentId") are different than the other groupBy keys.

To get an expected result, you must request with compartmentDepth. compartmentDepth is >=1 and <=6.

groupBy compartment means all compartments usage or costs with a higher depth will be aggregated to the compartment with the given depth. For example:

           Root             1

        B          C        2

    D    E                  3

 F                          4

If the depth is 1, it means all usage or costs are grouped to the root compartment.

If the depth is 2, it means all compartments with depth 2 will contain the usage or costs with all its children. In the response, the root will contain its own usage, B will aggregate (B, D, E, F), and C will contain C.

Why are some fields in a response empty?

The fields will show up only when the fields are in groupBy. Not all fields in the response are currently available. Only the fields mentioned in Valid groupBy example are supported.

What is nextPageToken?

This can be set as null. Currently not supported.

Example request body

The best way to understand how the API works is checking how the Console uses the API. You can find the request body in the web browser's debug mode.

{
  "tenantId": "ocid1.tenancy.oc1..<unique_ID>",
  "timeUsageStarted": "2020-04-01T00:00:00.000Z",
  "timeUsageEnded": "2020-07-01T00:00:00.000Z",
  "granularity": "MONTHLY",
  "queryType": "COST",
  "groupBy": [
    "tagNamespace",
    "tagKey",
    "tagValue",
    "service",
    "compartmentPath"
  ],
  "compartmentDepth": 2,
  "filter": null
}

After you make a request without any filter, you can see what the dimension/tags' value can be. Subequently, you can make a request with a filter and a correct dimension value.

{
  "tenantId": "ocid1.tenancy.oc1..<unique_ID>",
  "timeUsageStarted": "2020-04-01T00:00:00.000Z",
  "timeUsageEnded": "2020-07-01T00:00:00.000Z",
  "granularity": "MONTHLY",
  "groupBy": ["tagNamespace","tagKey","tagValue", "service", "compartmentPath"],
  "compartmentDepth": 2,
  "filter": {
    "operator": "AND",
    "dimensions": [],
    "tags": [],
    "filters": [{
      "operator": "AND",
      "dimensions": [{
        "key": "service",
        "value": "compute"
      }],
      "tags": null,
      "filters": null
    }, {
      "operator": "AND",
      "dimensions": [{
        "key": "compartmentPath",
        "value": "abc/cde"
      }],
      "tags": null,
      "filters": null
    },
      {
        "operator": "AND",
        "dimensions": null,
        "tags": [{
          "namespace": "compute",
          "key": "created",
          "value": "string"
        }],
        "filters": null
      }
    ]
  }
}
Using customized scripts, CLI, and SDK

If you write a customized script, Oracle does not support or assist with debugging your script. Only the CLI, SDK, and Terraform are supported. See Command Line Interface (CLI) for more information. For example:

oci raw-request --http-method POST --target-uri https://usageapi.us-ashburn-1.oci.oraclecloud.com/20200107/usage 
--request-body file:///<system_path>SimpleRequestSummarizedUsagesDetails.json 
--config-file ~/Downloads/clitest.conf
SimpleRequestSummarizedUsagesDetails.json:
{
  "tenantId": "ocid1.tenancy.oc1..<unique_ID>",
  "timeUsageStarted": "2020-03-19T17:00:00.000000-07:00",
  "timeUsageEnded": "2020-03-21T00:00:00Z",
  "granularity": "DAILY",
  "groupBy": [],
  "compartmentDepth": null,
  "filter": null,
  "nextPageToken": "string"
}
clitest.conf:
[DEFAULT]
user=ocid1.user.oc1..<unique_ID>
fingerprint=<MAC_ID>
key_file=<system_path>/oci_api_key.pem
#tenancy=ocid1.tenancy.oc1..<unique_ID>
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-ashburn-1
Also see the Oracle Cloud Infrastructure SDK at https://github.com/oracle/oci-java-sdk , https://github.com/oracle/oci-python-sdk.