How to create usage reports for partner subaccounts

This tutorial shows how to create a usage report for partner subaccounts.

As a partner, you can generate usage report requests for your organizations and subaccounts. If the subaccounts don't pass to the request body, only the partner organization usage report generates. If subaccounts pass to the request body, the usage report includes the subaccounts.

You can add filters using query parameters to query by app ID, project HRN, or billing tag. When you add filters, the response includes elements which match the filter criteria. There is a groupBy feature which controls the grouping of properties in the response. By default, groupBy appId, name, and billingTag are in the response.

Report generation requests support the detail levels of summarized, day, and month, with the default level set to summarized. The maximum number of returned records in the usage report CSV file is 1 million, and the maximum time range for the query is 95 days.

The response includes the current status of the request and a the report ID.

This sample request uses org123456789 as the realmId, 2021-07-01T10:39:51 as the startDate, and 2021-08-30T10:39:51 as the endDate.

POST https://usage.bam.api.here.com/v2/usage/realms/org123456789/startDate=2021-07-01T10:39:51&endDate=2021-08-30T10:39:51/reports

Parameters

The parameters shown here are only those required for this sample request. For a complete list of parameters, see the Cost Management Usage API v2 API Reference.

The usage search results can group into pages. A page is a set of usage records presented in a single view. You can customize he search results view by using offset and limit parameters. The offset determines the current page number on the view, and limit restricts search result counts to a specified number.


realmId required	string [ 5 ... 30 ] characters. Example: org123456789 Your org ID.
startDate required	string "date-time". Example:startDate=yyyy-MM-dd'T'HH:mm:ss The start date for a search.
endDate required	string "date-time". Example:endDate=yyyy-MM-dd'T'HH:mm:ss >End date for search.
featureId	string less than or equal to 256 characters. Example:featureId=hrn:here:service::org123456789:search-geocoding-1 Feature HRN.
appId	string less than or equal to 128 characters. Example:appId=j1dasda012edasfgne Client app ID. This is the app ID which the platform created.
channelId	string Enum: "hot" "cold" Example:channelId=cold When you provide this parameter, the results filter by the ID identifying the channel used for the usage reporting. A cold channel is a new billing data processing pipeline, whereas the hot channel is the old billing data processing pipeline. Use the channelId for testing purposes.
projectHrn	string less than or equal to 256 characters. Example:projectHrn=hrn:here:authorization::myrealm:project/my-project-0000 The HRN which identifies the project.
billingTag	string less than or equal to 500 characters. Example:billingTag=testtag Use billing tags for combining costs from your invoices.
category	string less than or equal to 128 characters. Example:category=Pipelines The category is the name of the billable service you have selected, such as location services or pipelines.
detailLevel	string Enum: "summarized" "hour" "day" "month" Example:detailLevel=hour You can use this query parameter to select one of the levels of detail to view in your usage records. Levels of detail include: summarized, hour, day, or month. The summarized detail level shows you a summary of your usage and is the default. The usageDateTime field value isn't present if summarized is the detailLevel value.
groupBy	string less than or equal to 256 characters. Example:groupBy=appId, billingTag, project, resource The groupBy parameter is a comma separated list of parameters which combine as groups. Supported values are project, billingTag, and appId. The default groupBy parameters are featureId and subscription ID. When you add groupBy parameters in the query, they append to featureId and subscription ID.
usageFields	Array of strings Enum: "realmId" "featureId" "billingSubscriptionId" "billingChargeNumber" "category" "name" "valueDriver" "usageValue" "billableValue" "resource" Example:usageFields=realmId,featureId,category A set of unique/distinct usage field names to filter responses.

Header parameters


X-Request-ID	string User-provided token to trace a request or a group of requests sent to the service.
X-Correlation-ID required	string Auto-generated ID, which uniquely identifies the request, available in the response. When contacting the support team with an inquiry regarding a specific request, provide the value of this header. This helps when troubleshooting the issue.

Request Body

The following shows a sample request body, which is a requirement.


subAccounts required	object The org IDs for each of the subAccounts.

{
    "subAccounts": 
    [
        "org112135",
        "org124566",
        "org134564"
    ]
}

Response HTTP 201 The request returns the following sample response:

{

    "id": "REPORT-1007",
    "status": "inProgress"

}