How to retrieve usage by organization

This tutorial shows how to retrieve the usage for your organization. By adding additional filters in your query parameters, you can 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 allows you to group usage data together in the response by selecting a category, such as location services, content, SDKs, pipelines, or data. By default, there is the groupBy appId, name, and billingTag, so the response includes all of these properties.

Billable usage calculates at the hour level. The API supports detail at the levels of summarized, hour, day, and month, with the default level set to summarized. You must be part of the organization requesting usage. The maximum time range you can query is 95 days.

API response records sort alphabetically in ascending order by subscription ID, category, and charge item (differentiates features within the same service and links to the corresponding charge).

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

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

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.


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 The End date for a 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 have 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 `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 to combine 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, content, SDKs, data, or pipelines.
limit	integer [ 1 ... 100 ]. Default: 100 The number of records returned. The default and maximum is 100 records.
offset	integer greater than or equal to zero. Default: 0 The offset determines the current page number on the search results view.
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, appId, featureId, and subscription ID. The default groupBy parameters are featureId and subscription ID. When you add groupBy parameters in the query, they add to featureId and subscription ID.
usageFields	Array of strings Enum: realmId: Organization ID. featureId: Feature HRN. billingSubscriptionId: The subscription ID for your organization. billingChargeNumber: Unique charge identifier that maps to corresponding service usage costs. This number combines with corresponding usage value to compute billable costs. category: The product category, such as pipelines, data, content, SDKs, and location services. name: The name of the organization. valueDriver: The unit of usage value. For example, GB or Transactions. usageValue: Numerical metric to measure customer usage for a particular service. billableValue: The amount of billable usage accrued. resource: All the usage data statistics retrieved and presented to the user. Example:usageFields=realmId,featureId,category A set of unique or distinct usage field names used to filter responses. Example:usageFields=realmId,featureId,category A set of unique or distinct usage field names used to filter responses

Header parameters


X-Request-ID	string User-provided token used 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.

Response: HTTP 200 OK

The request returns the following sample response:

{
    "total": 10,
    "limit": 2,
    "items":[
    {
      "realmId": "org123456789",
      "featureId": "hrn:here:service::org123456789:search-geocoding-1",
      "billingSubscriptionId": "A-S00000021",
      "billingChargeNumber": "C-00011212",
      "category": "service",
      "name": "Geocoder Autosuggest",
      "valueDriver": "Transactions",
      "usageValue": "10",
      "billableValue": "10"
    },
    {
      "realmId": "org123456789",
      "featureId": "hrn:here:service::org123456789:search-geocoding-1",
      "billingSubscriptionId": "A-S00000021",
      "billingChargeNumber": "C-0001124",
      "category": "service",
      "name": "Lane attributes",
      "valueDriver": "GB",
      "usageValue": "10",
      "billableValue": "10"
    }
  ], 
    "nextOffset": 1,
    "lastOffset": 4
}