openapi: 3.2.0 info: version: 2.2.0 title: Cost Management API v2 Usage API description: Provides API reference details for Usage API v2 which you can use to retrieve billable usage information. Usage billing rates are dependent on your licensing terms. termsOfService: https://developer.here.com/terms-conditions license: name: HERE Documentation License url: https://legal.here.com/en-gb/terms/documentation-license servers: - url: https://usage.bam.api.here.com/v2 description: Production server. tags: - name: Usage description: Usage paths: /usage/realms/{realmId}: get: tags: - Usage summary: Retrieve usage by organization description: 'This API retrieves the billable usage for your organization (realm). The realm ID is your organization ID. * Sort API response records alphabetically in ascending order by subscription ID, category, and charge item (name in the response), respectively. * The API supports usage by app ID.' operationId: Cost Management Usage API v2 getUsageByRealm parameters: - $ref: '#/components/parameters/Realm' - $ref: '#/components/parameters/StartDate' - $ref: '#/components/parameters/EndDate' - $ref: '#/components/parameters/FeatureId' - $ref: '#/components/parameters/AppIdQueryParam' - $ref: '#/components/parameters/ChannelIdQueryParam' - $ref: '#/components/parameters/ChargeTypeQueryParam' - $ref: '#/components/parameters/ProjectIdQueryParam' - $ref: '#/components/parameters/billingTagQueryParam' - $ref: '#/components/parameters/categoryQueryParam' - $ref: '#/components/parameters/billingSubscriptionIdQueryParam' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/Detail' - $ref: '#/components/parameters/GroupBy' - $ref: '#/components/parameters/UsageFieldSet' - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xCorrelationId' responses: '200': description: Successful response. content: application/json: schema: $ref: '#/components/schemas/UsagePaginationResponse' examples: UsagePaginationResponseNoGroupBySummarizedDetail: value: total: 10 limit: 2 items: - realmId: olp-here featureId: hrn:here:service::olp-here:search-geocoding-1 billingSubscriptionId: A-S00000021 billingChargeNumber: C-00011212 category: service name: Geocoder Autosuggest valueDriver: Transactions usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT - realmId: olp-here featureId: hrn:here:service::olp-here:search-geocoding-1 billingSubscriptionId: A-S00000021 billingChargeNumber: C-0001124 category: service name: Lane attributes valueDriver: GB usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT nextOffset: 1 lastOffset: 4 UsagePaginationResponseWithGroupByProjectAppBillingTagDayLevelDetail: value: total: 10 limit: 2 items: - realmId: olp-here projectHrn: hrn:here:authorization::myrealm:project/my-project-0000 appId: ew023asexaas14a1ps billingTag: testtag featureId: hrn:here:service::olp-here:search-geocoding-1 usageDateTime: 2020-01-01'T'00:00:00 billingSubscriptionId: A-S00000021 billingChargeNumber: C-00011212 category: service name: Geocoder Autosuggest valueDriver: Transactions usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT - projectHrn: hrn:here:authorization::myrealm:project/my-project-0000 realmId: olp-here appId: ew023asexaas14a1ps billingTag: testtag usageDateTime: 2020-01-01'T'00:00:00 featureId: featureHrn billingSubscriptionId: A-S00000021 billingChargeNumber: C-0001124 category: service name: Lane attributes valueDriver: GB usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT nextOffset: 1 lastOffset: 4 UsagePaginationResponseWithGroupByProjectAppBillingTagSummarizedDetail: value: total: 10 limit: 2 items: - appId: ew023asexaas14a1ps realmId: olp-here featureId: hrn:here:service::olp-here:search-geocoding-1 billingSubscriptionId: A-S00000021 billingChargeNumber: C-00011212 category: service name: Geocoder Autosuggest valueDriver: Transactions projectHrn: hrn:here:authorization::myrealm:project/my-project-0000 billingTag: testtag usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT - appId: ew023asexaas14a1ps realmId: olp-here featureId: featureHrn billingSubscriptionId: A-S00000021 billingChargeNumber: C-0001124 category: service name: Lane attributes valueDriver: GB projectHrn: hrn:here:authorization::myrealm:project/my-project-0000 billingTag: testtag1 usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT nextOffset: 1 lastOffset: 4 UsagePaginationResponseWithGroupByProjectSummarizedDetail: value: total: 10 limit: 2 items: - realmId: olp-here featureId: hrn:here:service::olp-here:search-geocoding-1 billingSubscriptionId: A-S00000021 billingChargeNumber: C-00011212 category: service name: Geocoder Autosuggest valueDriver: Transactions projectHrn: hrn:here:authorization::myrealm:project/my-project-0000 usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT - realmId: olp-here featureId: featureHrn billingSubscriptionId: A-S00000021 billingChargeNumber: C-00011212 category: service name: Lane attributes valueDriver: GB projectHrn: hrn:here:authorization::myrealm:project/my-project-0000 usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT nextOffset: 1 lastOffset: 4 UsagePaginationResponseWithGroupByAppSummarizedDetail: value: total: 10 limit: 2 items: - appId: ew023asexaas14a1ps realmId: olp-here featureId: hrn:here:service::olp-here:search-geocoding-1 billingSubscriptionId: A-S00000021 billingChargeNumber: C-00011212 category: service name: Geocoder Autosuggest valueDriver: Transactions usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT - appId: ew023asexaas14a1ps realmId: olp-here featureId: featureHrn billingSubscriptionId: A-S00000021 billingChargeNumber: C-0001124 category: service name: Lane attributes valueDriver: GB usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT nextOffset: 1 lastOffset: 4 UsagePaginationResponseWithGroupByBillingTagSummarizedDetail: value: total: 10 limit: 2 items: - realmId: olp-here featureId: hrn:here:service::olp-here:search-geocoding-1 billingSubscriptionId: A-S00000021 billingChargeNumber: C-00011212 category: service name: Geocoder Autosuggest valueDriver: Transactiosn billingTag: testtag usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT - realmId: olp-here featureId: featureHrn billingSubscriptionId: A-S00000021 billingChargeNumber: C-0001124 category: service billingTag: testtag1 name: Lane attributes valueDriver: GB usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT nextOffset: 1 lastOffset: 4 UsagePaginationResponseWithGroupByResourceSummarizedDetail: value: total: 10 limit: 2 items: - realmId: olp-here featureId: hrn:here:service::olp-here:search-geocoding-1 billingSubscriptionId: A-S00000021 billingChargeNumber: C-00011212 category: service name: Geocoder Autosuggest valueDriver: Transactions usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT - realmId: olp-here featureId: featureHrn billingSubscriptionId: A-S00000021 billingChargeNumber: C-0001124 category: service name: Lane attributes valueDriver: GB usageValue: '10' billableValue: '10' appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT nextOffset: 1 lastOffset: 4 UsagePaginationResponseWithGroupByUsageTypeCodeSummarizedDetail: value: total: 10 limit: 3 items: - realmId: olp-here featureId: hrn:here:service::olp-here:search-geocoding-1 billingSubscriptionId: A-S00000021 billingChargeNumber: C-00011212 category: service name: Geocoder valueDriver: Transactions usageValue: '10' billableValue: '10' appId: YQijV3hAPdxySAVtE6ZT appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT - realmId: olp-here featureId: hrn:here:service::olp-here:search-geocoding-1 billingSubscriptionId: A-S00000021 billingChargeNumber: C-00011212 category: service name: Geocoder valueDriver: Transactions usageValue: '10' billableValue: '10' appId: YQijV3hAPdxySAVtE6ZT appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT - realmId: olp-here featureId: featureHrn billingSubscriptionId: A-S00000021 billingChargeNumber: C-0001124 category: service name: Lane attributes valueDriver: GB usageValue: '10' billableValue: '10' appId: YQijV3hAPdxySAVtE6ZT appName: HERE Platform appHrn: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT nextOffset: 1 lastOffset: 4 headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/X-Request-ID' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - token: [] /usage/realms/{realmId}/csv: get: tags: - Usage summary: Retrieve usage CSV by organization description: 'This API retrieves the billable usage for your organization in CSV format. * Sort API response records alphabetically in ascending order by subscription ID, category, and the charge item (name in the response) respectively. * The API supports usage by app ID.' operationId: Cost Management Usage API v2 getUsageCsvByRealm parameters: - $ref: '#/components/parameters/Realm' - $ref: '#/components/parameters/StartDate' - $ref: '#/components/parameters/EndDate' - $ref: '#/components/parameters/FeatureId' - $ref: '#/components/parameters/AppIdQueryParam' - $ref: '#/components/parameters/ChannelIdQueryParam' - $ref: '#/components/parameters/ChargeTypeQueryParam' - $ref: '#/components/parameters/ProjectIdQueryParam' - $ref: '#/components/parameters/billingTagQueryParam' - $ref: '#/components/parameters/categoryQueryParam' - $ref: '#/components/parameters/billingSubscriptionIdQueryParam' - $ref: '#/components/parameters/Detail' - $ref: '#/components/parameters/GroupBy' - $ref: '#/components/parameters/UsageFieldSet' - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xCorrelationId' responses: '200': description: Successful response. content: text/csv: schema: type: string example: Date and time (usageDateTime), Org ID (realmId), Category (category), App ID (appId), App Name (appName), App Hrn (appHrn), Item (featureId), Subscription ID (billingSubscriptionId), Item description (name), Unit (valueDriver), Project ID (projectHrn), Billing tag (billingTag), Usage Amount (billableValue) headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/X-Request-ID' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: - token: [] /usage/realms/{realmId}/reports: post: summary: Create usage reports for partner subaccounts description: 'This is an Async API which generates usage reports for partner organizations or subaccounts. If the subaccounts aren''t passed, then it only generates the partner organization usage report. If subaccounts pass to the request body, then the usage report consists of data for the subaccounts. * API response has the current status of the request and also a header containing the URL for the "get report status" request. * The API supports usage by app ID.' operationId: Cost Management Usage API v2 createUsageReport tags: - Usage parameters: - $ref: '#/components/parameters/Realm' - $ref: '#/components/parameters/StartDate' - $ref: '#/components/parameters/EndDate' - $ref: '#/components/parameters/FeatureId' - $ref: '#/components/parameters/AppIdQueryParam' - $ref: '#/components/parameters/ChannelIdQueryParam' - $ref: '#/components/parameters/ChargeTypeQueryParam' - $ref: '#/components/parameters/ProjectIdQueryParam' - $ref: '#/components/parameters/billingTagQueryParam' - $ref: '#/components/parameters/categoryQueryParam' - $ref: '#/components/parameters/billingSubscriptionIdQueryParam' - $ref: '#/components/parameters/Detail' - $ref: '#/components/parameters/GroupBy' - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xCorrelationId' - $ref: '#/components/parameters/UsageFieldSet' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/UsageReportRequest' security: - token: [] responses: '201': description: Generate usage report status request. headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/X-Request-ID' Location: $ref: '#/components/headers/Location' content: application/json: schema: $ref: '#/components/schemas/PostUsageReportStatusResponse' examples: PostUsageReportStatusResponse: value: id: REPORT-1007 status: inProgress '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' get: summary: Retrieve status for all usage report requests description: 'The Async API retrieves the status of all usage report requests. The response contains the status of the usage report and the download URL. * Sort API response records based on the created date in ascending or descending order, as the sort parameter in the API request. * The API supports usage by app ID.' operationId: Cost Management Usage API v2 getAllUsageReportRequestsStatus tags: - Usage parameters: - $ref: '#/components/parameters/Realm' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Sort' - $ref: '#/components/parameters/Offset' - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xCorrelationId' security: - token: [] responses: '200': description: Retrieve the status for all usage report requests. headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/UsageReportStatusResponseList' examples: SuccessUsageReportStatusResponseList: value: total: 18 limit: 5 count: 2 nextOffset: 0 lastOffset: 3 items: - id: REPORT-100 status: inProgress created: 2022-03-01'T'00:00:00 parameters: realm: org1879256 startDate: 2022-03-01'T'00:00:00 endDate: 2022-07-01'T'00:00:00 chargeType: all emailId: test_requester@here.com - id: REPORT-145 status: completed resultHref: https://usage/realms/org236848/report/REPORT-1475/output created: 2022-04-01'T'00:00:00 parameters: realm: org1879256 startDate: 2022-03-01'T'00:00:00 endDate: 2022-07-01'T'00:00:00 chargeType: billable emailId: test_requester@here.com - id: REPORT-167 status: failed created: 2022-08-01'T'00:00:00 parameters: realm: org1879586 startDate: 2022-03-01'T'00:00:00 endDate: 2022-07-01'T'00:00:00 chargeType: nonBillable emailId: test_requester2@here.com '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /usage/realms/{realmId}/reports/{reportId}: get: summary: Retrieve status for a usage report request by ID description: 'This API retrieves the status of a usage report request. The report creation Async API starts the report generation request and status, retrieving through this API. In the response of this API , You can identify the status of the usage report creation process and can download it when it has completed. The response contains the usage report download URL. * API response has a single record having the status of the report request. * The API supports usage by app ID.' operationId: Cost Management Usage API v2 getUsageReportRequestStatus tags: - Usage parameters: - $ref: '#/components/parameters/Realm' - $ref: '#/components/parameters/ReportId' - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xCorrelationId' security: - token: [] responses: '200': description: Retrieve the usage report request status. headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/UsageReportStatusResponse' examples: InProgressUsageReportStatusResponse: value: id: REPORT-1001 status: inProgress created: 2022-03-01'T'00:00:00 parameters: realm: org1879256 startDate: '2022-03-01' endDate: '2022-07-01' emailId: test_requester@here.com CompletedUsageReportStatusResponse: value: id: REPORT-1475 status: completed resultHref: https://usage/realms/org236848/reports/REPORT-1475/output created: 2022-04-01'T'00:00:00 parameters: realm: org1879256 startDate: '2022-03-01' endDate: '2022-07-01' chargeType: all emailId: test_requester@here.com FailedUsageReportStatusResponse: value: id: REPORT-1562 status: failed created: 2022-04-01'T'00:00:00 parameters: realm: org1879656 startDate: '2022-06-01' endDate: '2022-07-01' emailId: test_requester3@here.com '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /usage/realms/{realmId}/reports/{reportId}/output: get: summary: Download a usage report description: 'This API downloads the created usage report. * The API responds with the usage report encoded in gzip format. * The API supports usage by app ID.' operationId: Cost Management Usage API v2 fetchCreatedReport tags: - Usage parameters: - $ref: '#/components/parameters/Realm' - $ref: '#/components/parameters/ReportId' - $ref: '#/components/parameters/xRequestId' - $ref: '#/components/parameters/xCorrelationId' security: - token: [] responses: '200': description: Successful response. headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/x-gzip: schema: type: string format: binary description: The usage report output is in gzip file format. example: REPORT-1583.csv.gz '400': $ref: '#/components/responses/BadRequest' '404': description: Get usage report. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: headers: Location: required: false schema: type: string description: The URL which polls the status for a request receiving a 202 response, such as ta/get/{clientId}?xCorrelationId=4199533b-6290-41db-8d79-edf4f4019a74. XCorrelationId: schema: type: string required: false description: 'Correlates HTTP requests between a client and server. Sentry generates the X-Correlation-ID UUID and passes it to downstream services. It generates if it''s not present in the incoming request. ' X-Request-ID: description: 'User provided token used to trace a request or a group of requests sent to the service. ' schema: type: string schemas: UsageResponse: type: object properties: appId: type: string description: Client ID. example: ew023asexaas14a1ps appName: type: string description: Name of app Id in IAM. example: HERE Platform appHrn: type: string description: app in appHrn format. example: hrn:here:account::HERE:app/YQijV3hAPdxySAVtE6ZT realmId: type: string description: Organization HRN. example: realm Hrn billingSubscriptionId: type: string example: A-0001213231 description: Subscription ID. billingChargeNumber: type: string example: C-0121211 description: Billing charge number. featureId: type: string description: Features are identified by feature HERE Resource Names (HRNs). Using API requests, feature HRNs are necessary to acquire your usage. example: hrn category: type: string description: The category is the name of the billable service you have selected, such as location services or pipelines. example: DataServices name: type: string description: Name of this usage. example: Geocoder Autosuggest valueDriver: type: string description: The units specifying how to measure usage. Examples include Transaction, GB, and GB-months. example: Transaction projectHrn: type: string description: Project HRN. example: hrn:here:authorization::myrealm:project/my-project-0000 billingTag: type: string description: Use billing tags to combine expenses from your invoices. example: testtag usageDateTime: type: string format: date-time example: 2020-08-12'T'00:00:00 description: Usage date/time by hour granularity. usageValue: type: number description: Raw usage units. For example, for location services, it's the number of API calls made for an API. example: '10' billableValue: type: number description: Billable usage units. For example, the number of transactions for a given API. A transaction is the billable Unit which is calculated based on the amount of usage units. example: '1' usageValueHot: type: number description: Raw Usage Units computed by hot channel. As an example, for location services, it's the number of API calls made for an API example: '10' billableValueHot: type: number description: Billable Usage Units calculated by a hot channel. As an example, it's the number of transactions for a given API. A transaction is the billable Unit which is calculated based on UsageUnits example: '1' usageValueCold: type: number description: Raw Usage Units calculated by a cold channel. As an example, location services, it's the number of API calls made for an API example: '10' billableValueCold: type: number description: Billable Usage Units calculated by a cold channel. As an example, it's the number of transactions for a given API. A transaction is the billable Unit which is calculated based on UsageUnits example: '1' PostUsageReportStatusResponse: type: object required: - id - status properties: id: type: string description: Usage report to request the status ID. example: REPORT-100 status: type: string description: Usage report request status enum: - pending - inProgress - completed - failed - archived example: inProgress example: id: REPORT-1006 status: inProgress UsageReportRequest: type: object description: The input object which contains a list of subaccounts. required: - subAccounts properties: subAccounts: type: object items: type: string example: - org112135 - org124566 - org134564 ErrorDetail: type: object properties: code: type: string description: Error Code. example: ASYNC_API_DISABLED_FOR_USER title: type: string description: Error message. example: Invalid size value source: type: string description: Reference to a JSON path. example: $.taFeatures.size message: type: string description: Detailed error message. example: Size must be between 1 and 3 messageTemplate: type: string description: Optional error template. example: validation.constraint.between messagePlaceholders: type: object additionalProperties: {} example: field: size min: 1 max: 3 ErrorResponse: type: object required: - title - status - code - cause - action - errorId - correlationId properties: title: type: string description: Error title. example: Input data failed validation errorId: type: string description: Unique ID for the error. This is searchable in the TA logs. example: ERROR-9d862c5a-4cfd-4780-8be4-2728b42849e1 status: type: integer description: HTTP status code. example: 400 code: type: string description: Resource specific error code. example: E706XX cause: type: string description: The cause of the error. example: The input data in question does not meet validation rules. action: type: string description: Actionable instructions for the API requester. example: Correct input data and retry the request. correlationId: type: string description: Correlation ID. example: 4199533b-6290-41db-8d79-edf4f4019a74 details: type: array description: Collection of error details. items: $ref: '#/components/schemas/ErrorDetail' AuthErrorResponse: properties: error: type: string description: Human-readable error. error_description: type: string description: Human-readable error description. UsageReportStatusResponse: type: object required: - id - status properties: id: type: string description: Usage report request ID. example: REPORT-100 status: type: string description: Usage report request status enum: - pending - inProgress - completed - failed - archived example: inProgress resultHref: type: string example: https://usage/realms/org236848/report/REPORT-1475/output created: type: string format: date-time example: 2022-02-04'T'00:00:00 parameters: type: object description: The input object containing a list of filter parameters. required: - startDate - endDate - emailId - username properties: realm: type: string description: Organization ID. example: olp-here startDate: type: string format: date-time description: Start date for search. example: 2022-04-03'T'02:30:40 endDate: type: string format: date-time description: End date for search. example: 2022-07-03'T'05:30:40 emailId: type: string format: email description: Email ID of the usage report requester. example: testaccount@here.com username: type: string description: Username of the requested user. example: Username featureId: type: string description: You identity features using feature HERE Resource Names (HRNs). Use feature HRNs to acquire your usage through API requests. maxLength: 256 example: hrn:here:service::olp-here:search-geocoding-1 appId: type: string maxLength: 128 description: ' App ID of a user.' example: cGjjdhkagthrksvhj channelId: type: string enum: - hot - cold - ds description: When this parameter is provided, the ID identifying the channel used for the usage reporting filters the results. 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. example: cold chargeType: type: string enum: - all - billable - nonBillable description: ChargeType provides an option to filter for usage which is going to be invoiced. projectId: type: string maxLength: 256 description: HRN identifying the project. example: hrn:here:authorization::myrealm:project/my-project-0000 billingTag: type: string maxLength: 500 description: Use billing tags for combining expenses from your invoices. example: testtag category: type: string maxLength: 128 description: The category is the name of the billable service you have selected, such as location services or pipelines. example: Pipelines detail: type: string enum: - summarized - hour - day - month description: 'You can use this query parameter to select one of the levels of detail you want to see in your usage records. Levels of detail include: summarized, hour, day, or month. The summarized detail level shows you a description of your usage and is the default.' example: hour groupBy: type: string maxLength: 256 description: "A comma seperated list of values which can use groupBy to combine like items in your billing. Supported values are project, billingTag, appId, and the default groupBy values which are featureId and subscription ID.\n Additional groupBy values are in query parameters, and added to featureId and subscription ID." example: appId, billingTag, project usageFields: type: array items: type: string uniqueItems: true description: A set of unique and distinct usage field names which filter response object properties. example: realmId,featureId,category subAccounts: type: object items: type: string example: - org112135 - org124566 - org134564 example: realm: org1879256 startDate: '2022-03-01' EndDate: '2022-07-01' emailId: example@here.com UsagePaginationResponse: type: object properties: total: type: integer description: Total number of items. example: 10 limit: type: integer description: Maximum number of items specified in a request. example: 2 items: type: array items: $ref: '#/components/schemas/UsageResponse' nextOffset: type: integer description: Next offset. lastOffset: type: integer description: Last offset. UsageReportStatusResponseList: type: object description: The input object which has a list of subaccounts. required: - total - limit - count - nextOffset - lastOffset properties: total: type: integer description: The total number of items. example: 100 limit: type: integer description: The maximum number of items specified in your request. example: 10 count: type: integer description: The number of records returned in this query. example: 10 nextOffset: type: integer description: Next offset lastOffset: type: integer description: Last offset items: type: array items: $ref: '#/components/schemas/UsageReportStatusResponse' example: - org112135 - org124566 - org134564 examples: InvalidLimit: value: title: Input data failed validation errorId: ERROR-22862c5a-4cfd-4780-8be4-2728b42de3j status: 400 code: E706002 cause: Invalid Limit action: Correct input data and retry request correlationId: 4199533b-6290-41db-8d79-edf4f4019a74 details: title: Invalid Limit. message: Limit value should not be greater than 100. InvalidGroupBy: value: title: Input data failed validation errorId: ERROR-22862c5a-4cfd-4780-8be4-2728b42de3j status: 400 code: E706004 cause: Invalid group by field. Supported are appId, billingTag, and project action: Correct input data and retry request correlationId: 4199533b-6290-41db-8d79-edf4f4019a74 details: title: Invalid group by field. message: Invalid group by field. Supported values are appId, billingTag, and project. InvalidDateRange: value: title: Input data failed validation errorId: ERROR-22862c5a-4cfd-4780-8be4-2728b42de3j status: 400 code: E706003 cause: start or end Date validation failed action: Correct input data and retry request correlationId: 4199533b-6290-41db-8d79-edf4f4019a74 details: title: Invalid Start or end date. message: Invalid Start or end date. UnauthorizedErrorResponse: value: error: Unauthorized error_description: No credentials found. ForbiddenErrorResponse: value: error: Forbidden error_description: These credentials do not provide authorized access. InvalidRealm: value: title: Input data failed validation errorId: ERROR-9d862c5a-4cfd-4780-8be4-2728b42849e1 status: 400 code: E706001 cause: Invalid Realm action: Correct input data and retry request correlationId: 4199533b-6290-41db-8d79-edf4f4019a74 details: title: Invalid Realm {realm} message: Realm {realm} has invalid characters. parameters: UsageFieldSet: name: usageFields in: query required: false example: realmId,featureId,category description: A set of unique and distinct usage field names which filter responses. schema: type: array items: type: string enum: - realmId - featureId - billingSubscriptionId - billingChargeNumber - category - name - valueDriver - usageValue - billableValue - resource uniqueItems: true billingSubscriptionIdQueryParam: name: billingSubscriptionId in: query required: false explode: false description: A comma-separated list of billing subscription IDs, with a minimum of 1 item and a maximum of 20. example: A-S0000231,A-S0000233,A-S0000254 schema: type: array items: type: string minItems: 1 maxItems: 20 Limit: in: query name: limit required: false schema: type: integer minimum: 1 maximum: 100 default: 100 description: Returns the maximum number of records. The default and maximum is 100 records. ChargeTypeQueryParam: name: chargeType in: query required: false description: When this parameter is provided, the results are filtered by usages of a specific charge type. example: all schema: type: string default: all enum: - all - billable - nonBillable EndDate: in: query name: endDate required: true schema: type: string format: date-time example: yyyy-MM-dd'T'HH:mm:ss description: End date for search. GroupBy: name: groupBy in: query required: false example: appId, billingTag, project description: 'The groupBy parameter is a comma seperated list of parameters which you combine to form groups. Supported values are project, billingTag, appId, featureId, and subscription ID. The default groupBy parameters are featureId and subscription ID. When Add groupBy parameters in the query, so that they add to featureId and subscription ID.' schema: type: string maxLength: 256 Sort: in: query name: sort schema: type: string enum: - asc - desc default: desc description: Returns sage report status in ascending or descending order of the creation date of the report. ReportId: name: reportId in: path description: Report ID. required: true example: REPORT-1346 schema: type: string minLength: 11 maxLength: 30 Realm: name: realmId in: path description: Organization ID. required: true example: olp-here schema: type: string minLength: 5 maxLength: 30 ProjectIdQueryParam: name: projectHrn in: query required: false description: HRN identifying the project. example: hrn:here:authorization::myrealm:project/my-project-0000 schema: type: string maxLength: 256 AppIdQueryParam: name: appId in: query required: false description: Client app ID. This is the app ID created in the platform. example: j1dasda012edasfgne schema: type: string maxLength: 128 pattern: ^[a-zA-Z0-9-_]*$ StartDate: in: query name: startDate required: true schema: type: string format: date-time example: yyyy-MM-dd'T'HH:mm:ss description: Start date for search. categoryQueryParam: name: category in: query required: false description: The category is the name of the billable service you select, such as location services or pipelines. example: Pipelines schema: type: string maxLength: 128 xRequestId: name: X-Request-ID in: header description: User-provided token used to trace a request or a group of requests sent to the service. schema: type: string xCorrelationId: name: X-Correlation-ID in: header required: true description: 'Auto-generated ID, which uniquely identifies the request and is in the response. When contacting the support team with an inquiry regarding a specific request, provide the value of this header to assist with troubleshooting. ' schema: type: string ChannelIdQueryParam: name: channelId in: query required: false description: When you provide this parameter, the results are filtered 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. example: cold schema: type: string enum: - hot - cold - ds FeatureId: name: featureId in: query required: false example: hrn:here:service::olp-here:search-geocoding-1 description: Identify features by feature HERE Resource Names (HRNs). Feature HRNs are necessary to acquire your usage using API requests. schema: type: string maxLength: 256 Detail: in: query name: detailLevel required: false schema: type: string example: hour enum: - summarized - hour - day - month description: "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. \nThe summarized detail level is the default and shows you a summary of your usage." billingTagQueryParam: name: billingTag in: query required: false description: Use billing tags for combining expenses from your invoices. example: testtag schema: type: string maxLength: 500 Offset: in: query name: offset required: false schema: type: integer minimum: 0 default: 0 description: The offset page number determines the current page number in the search results view. The default value is zero. responses: NotFound: content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The requested resource was not found, see the error response for details. headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/X-Request-ID' Forbidden: description: You do not have permission to perform this action. headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' examples: errorResponseExample: $ref: '#/components/examples/ForbiddenErrorResponse' Unauthorized: description: Access is denied due to invalid credentials. headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' examples: errorResponseExample: $ref: '#/components/examples/UnauthorizedErrorResponse' BadRequest: content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: InvalidRealm: $ref: '#/components/examples/InvalidRealm' InvalidLimit: $ref: '#/components/examples/InvalidLimit' InvalidDateRange: $ref: '#/components/examples/InvalidDateRange' InvalidGroupBy: $ref: '#/components/examples/InvalidGroupBy' description: Invalid input provided, see error response for details. headers: X-Correlation-ID: $ref: '#/components/headers/XCorrelationId' X-Request-ID: $ref: '#/components/headers/X-Request-ID' securitySchemes: token: type: http scheme: bearer bearerFormat: JWT description: 'A client access token must be obtained from a separate endpoint using the client credentials and an OAuth 1.0a HMAC-SHA256 signed request. For more information, see https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html. ' externalDocs: description: The developer guide and release notes are available here. url: https://www.here.com/docs/category/cost-management