Metering data If your organization has the Intelligent Cloud Data Management feature, you can download metering usage data using the REST API.
To download the metering data, you send an export job request, check the job status, and then download a ZIP file that contains the data.
You can download the following data:
Summary IPU usage data You can download summary IPU usage data for production organizations, additional production organizations, sub-organizations, and sandbox organizations for a specified date range. The ZIP file includes data for the requesting organization and the organizations under it. For example, if the requesting organization is the production organization, the ZIP file contains data for the production organization and its additional production organizations, sub-organizations, and sandbox organizations. If the requesting organization is an additional production organization that has a sub-organization, the ZIP file contains data for the additional production organization and its sub-organization. You can request usage information for all organizations in one CSV file, or you can receive individual CSV files for each organization. Project-level details You can download metering data by project and folder for a specified date range. By default, the ZIP file includes data only for the requesting organization. You can request to receive data for the requesting organization and its sub-organizations. You can request usage information for all organizations in one CSV file, or you can receive individual CSV files for each organization. Asset-level details You can download metering data by asset for a specified date range. You can specify a meter ID in the request to receive usage information for a specific meter. Job-level details If a service supports job-level detail reports, you can download job-level details for a specified date range. You can request job-level details for a particular meter or for all meters. The ZIP file includes data for the requesting organization. You can specify a meter ID in the request to receive usage information for a specific meter. Note: An organization can have a maximum of 5 active jobs. A job is active when the status is CREATED or PROCESSING.
Requesting summary IPU usage data You can run a job to export summary IPU usage data for the parent organization and its linked organizations such as additional production organizations, sub-organizations, and sandbox organizations for a specified date range.
To request and receive summary IPU usage data, you must have access rights to the parent organization and all of the linked organizations.
After the job starts, you can check the job status. For more information, see
Getting the metering data export job status .
When the job completes successfully, you can send a request to download the data. The data file includes the following columns:
• • • • • • • • • • • • • Note: There are two REST API resources available to request summary IPU usage data. The resources return the same data.
Request summary data with the new REST API resource Use the ExportMeteringData resource for all new export requests.
POST request To send an export job request, use the following URI:
/public/core/v3/license/metering/ExportMeteringData
The following table describes the fields to include in the request:
Field
Type
Required
Description
startDate
String
Yes
Start of the date range in ISO 8601 format. For example, 2022-08-12T00:00:00Z
endDate
String
Yes
End of the date range in ISO 8601 format.
When you request summary data, the range can be a maximum of 180 days.
jobType
String
Yes
Type of metering data to export.
Use SUMMARY.
combinedMeterUsage
String
-
Indicates whether to return usage information for all organizations in one CSV file. Include one of the following values:
- - Default is FALSE.
allLinkedOrgs
String
-
Indicates whether to return usage information from the parent organization and all its linked organizations. Include one of the following values:
- - Default is FALSE.
callbackUrl
String
-
A valid, publicly available URL where the service posts the job status.
POST request example You might use a request similar to the following example:
POST <baseApiUrl>/public/core/v3/license/metering/ExportMeteringData
POST response The following table describes the response fields:
Field
Type
Description
jobID
String
ID of the export job.
status
String
Status of the export job.
orgId
String
Organization ID for the requesting organization.
userId
String
ID of the user who sent the request.
selectedOrgId
String
Organization ID for the requesting organization.
meterId
String
Meter ID.
startDate
String
Start of the date range.
endDate
String
End of the date range.
callbackUrl
String
URL that the service uses to post the job status.
createTime
String
Time the export job was created.
updateTime
String
Time the export job was last updated.
POST response example If successful, you might receive a response similar to the following example:
{
Request summary data with the older REST API resource You can continue to use the ExportMeteringDataAllLinkedOrgsAcrossRegion resource for existing export requests.
POST request To send an export job request, use the following URI:
/public/core/v3/license/metering/ExportMeteringDataAllLinkedOrgsAcrossRegion
The following table describes the fields to include in the request:
Field
Type
Required
Description
startDate
Date/time
Yes
Start of the date range.
endDate
Date/time
Yes
End of the date range.
The range can be a maximum of 180 days.
combinedMeterUsage
Boolean
-
Indicates whether to return usage information for all organizations in one CSV file. Include one of the following values:
- - Default is FALSE.
callbackUrl
String
-
A valid, publicly available URL where the service posts the job status.
POST request example You might use a request similar to the following example:
POST <baseApiUrl>/public/core/v3/license/metering/ExportMeteringDataAllLinkedOrgsAcrossRegion
POST response The following table describes the response fields:
Field
Type
Description
jobID
String
ID of the export job.
status
String
Status of the export job.
errorMessage
String
Error message, if any, that is associated with the job.
orgId
String
Organization ID for the requesting organization.
userId
String
ID of the user who sent the request.
selectedOrgId
String
Organization ID for the requesting organization.
startDate
Date/time
Start of the date range.
endDate
Date/time
End of the date range.
callbackUrl
String
URL that the service uses to post the job status.
createTime
String
Time the export job was created.
updateTime
String
Time the export job was last updated.
combinedMeterUsage
Boolean
Whether usage data for all organizations is returned in one CSV file.
POST response example If successful, you might receive a response similar to the following example:
{
If an error occurs, the response might be similar to the following example:
{
Requesting project-level metering data You can run a job to export IPU consumption data by project and folder.
After the job starts, you can check the job status. For more information, see
Getting the metering data export job status .
When the job completes successfully, you can send a request to download the data. The data file includes the following columns:
• • • • • • POST request To send the export job request, use the following URI:
/public/core/v3/license/metering/ExportMeteringData
The following table describes the fields to include in the request:
Field
Type
Required
Description
startDate
String
Yes
Start of the date range in ISO 8601 format. For example, 2022-08-12T00:00:00Z
endDate
String
Yes
End of the date range in ISO 8601 format.
When you request project-level data, the range can be a maximum of 30 days.
jobType
String
Yes
Type of metering data to export.
Use PROJECT_FOLDER.
combinedMeterUsage
String
-
Indicates whether to return usage information for all organizations in one CSV file. Include one of the following values:
- - Default is FALSE.
allLinkedOrgs
String
-
Indicates whether to return usage information from the parent organization and all its linked organizations. Include one of the following values:
- - Default is FALSE.
callbackUrl
String
-
A valid, publicly available URL where the service posts the job status.
POST request example You might use a request similar to the following example:
{
POST response The following table describes the response fields:
Field
Type
Description
jobID
String
ID of the export job.
status
String
Status of the export job.
orgId
String
Organization ID for the requesting organization.
userId
String
ID of the user who sent the request.
selectedOrgId
String
Organization ID for the requesting organization.
meterId
String
Meter ID.
startDate
String
Start of the date range.
endDate
String
End of the date range.
callbackUrl
String
URL that the service uses to post the job status.
createTime
String
Time the export job was created.
updateTime
String
Time the export job was last updated.
POST response example If successful, you might receive a response similar to the following example:
{
Requesting asset-level data You can run a job to export metering data by asset.
After the job starts, you can check the job status. For more information, see
Getting the metering data export job status .
When the job completes successfully, you can send a request to download the data. The data file includes the following columns:
• • • • • • • • • • • • • • • POST request To send the export job request, use the following URI:
/public/core/v3/license/metering/ExportMeteringData
The following table describes the fields to include in the request:
Field
Type
Required
Description
startDate
String
Yes
Start of the date range in ISO 8601 format. For example, 2022-08-12T00:00:00Z
endDate
String
Yes
End of the date range in ISO 8601 format.
When you request asset-level data, the range can be a maximum of 30 days.
meterId
String
-
Meter ID. When you export asset-level data, you can export data for a single meter. By default, data for all meters is included.
jobType
String
Yes
Type of metering data to export.
Use ASSET.
callbackUrl
String
-
A valid, publicly available URL where the service posts the job status.
POST request example You might use a request similar to the following example:
{
POST response The following table describes the response fields:
Field
Type
Description
jobID
String
ID of the export job.
status
String
Status of the export job.
orgId
String
Organization ID for the requesting organization.
userId
String
ID of the user who sent the request.
selectedOrgId
String
Organization ID for the requesting organization.
meterId
String
Meter ID.
startDate
String
Start of the date range.
endDate
String
End of the date range.
callbackUrl
String
URL that the service uses to post the job status.
createTime
String
Time the export job was created.
updateTime
String
Time the export job was last updated.
POST response example If successful, you might receive a response similar to the following example:
{
Requesting job-level metering data For certain meters, you can run a job to export job-level details for a particular service and meter for a specified date range.
After the job starts, you can check the job status. When the job completes successfully, you can send a request to download the data. For more information, see
Getting the metering data export job status .
POST request To send the export job request, use the following URI:
/public/core/v3/license/metering/ExportServiceJobLevelMeteringData
The following table describes the fields to include in the request:
Field
Type
Required
Description
startDate
Date/time
Yes
Start of the date range.
endDate
Date/time
Yes
End of the date range.
The range can be a maximum of 180 days.
allMeters
Boolean
Required when meterId is blank.
Indicates whether to return usage information for all meters. Include one of the following values:
- - Default is FALSE.
meterId
String
Required when allMeters is FALSE.
callbackUrl
String
-
A valid, publicly available URL where the service posts the job status.
POST request example You might use a request similar to the following example:
POST <baseApiUrl>/public/core/v3/license/metering/ExportServiceJobLevelMeteringData
POST response The following table describes the response fields:
Field
Type
Description
jobID
String
ID of the export job.
status
String
Status of the export job.
errorMessage
String
Error message, if any, that is associated with the job.
orgId
String
Organization ID for the requesting organization.
userId
String
ID of the user who sent the request.
selectedOrgId
String
Organization ID for the requesting organization.
allMeters
Boolean
Whether usage information for all meters is included.
meterId
String
Meter ID.
startDate
Date/time
Start of the date range.
endDate
Date/time
End of the date range.
callbackUrl
String
URL that the service uses to post the job status.
createTime
String
Time the export job was created.
updateTIme
String
Time the export job was last updated.
POST response example If successful, you might receive a response similar to the following example:
{
If an error occurs, the response might be similar to the following example:
Meter IDs for job-level reports When you create a request to export job-level metering data, include the meter ID in the request to specify the meter.
The following table lists meter IDs for the meters that support exporting job-level metering data.
Meter name
Meter ID
Advanced Data Integration
3TaYTMo6BFYeNIABfVmH0n
Advanced Data Integration with Advanced Serverless
8tXWie0ZQLWlG1cyxxLwQM
Advanced Pushdown Optimization
dMN0VeTW4cThHyPovp4GEX
Application Integration
3uIRkIV5Rt9lBbAPzeR5Kj
Application Integration with Advanced Serverless
bN6mes5n4GGciiMkuoDlCz
Data Integration
a2nB20h1o0lc7k3P9xtWS8
Data Integration with Advanced Serverless
35m9fB23Tykj4Fb3rN5q2J
Data Integration - Change Data Capture
0sDTANKFZBSbqjzKaXKlmB
Data Validation
2qJ9COoAhfMrsH7mCyh86M
Integration Hub
fqttkiGnSaHeXW255z4IcD
Mass Ingestion Application
i3H6LcmMIYjhUKa9VCi7CI
Mass Ingestion Application - Change Data Capture
4cPkZ5cZxjzc4SK2RHoqgy
Mass Ingestion Database
24WXkCWzeSHjFlQvLPDegF
Mass Ingestion Database - Change Data Capture
aluxJ8jOKmzdXwD0JuHRS1
Mass Ingestion Files
lCwc4CfL7EEhv9773egFC8
Mass Ingestion Streaming
hr7GsCwFFmyfvfZQFn8v81
Model Serve
27nMlr1rtjAk5tOJ3dLoY7
Getting the metering data export job status Use a GET request to get the status of an export job for metering data.
GET request To get the status of the export job, use the following URI:
/public/core/v3/license/metering/ExportMeteringData/<jobId>
GET response The response includes the following fields:
Field
Type
Description
jobID
String
ID of the export job.
status
String
Status of the export job. One of the following values can be returned:
- - - - - If the status is PARTIAL_SUCCESS, the job completed but data couldn't be collected for all of the linked organizations due to errors.
errorMessage
String
Error message, if any, that is associated with the job.
orgId
String
Organization ID for the requesting organization.
userId
String
ID of the user who sent the request.
selectedOrgId
String
Organization ID for the requesting organization.
meterId
String
Meter ID.
Applicable for jobs requesting job-level details.
startDate
Date/time
Start of the date range.
endDate
Date/time
End of the date range.
callbackUrl
String
The URL that the service uses to post the job status.
createTime
String
Time the export job was created.
updateTIme
String
Time the export job was last updated.
GET response example If successful, you might receive a response similar to the following example:
{
If the job is partially successful, the response might be similar to the following example:
Getting custom IPU alert configurations Use a GET request to get the custom IPU alert thresholds that you configured for organizations or tags.
GET request To get the custom IPU alert configurations for your organization, use the following URl:
/public/core/v3/metering/ipuAlert/org('<organization Id>')
To get the custom IPU alert configurations for your tags, use the following URl:
/public/core/v3/metering/ipuAlert/org('organization Id')/viewTagsPreference
GET response The response includes the following fields for organization configurations:
Field
Type
Description
orgName
String
Name of the organizaiton.
orgId
String
ID of the organization.
parentOrgId
String
ID of the parent organization. This field only applies to sub-organizations. Otherwise, it's NULL.
thresholdValue
Integer
Threshold value configured.
ipuConsumed
BigDecimal
Specifies how many IPUs are consumed. This field's value relates to the ipuThresholdPrefType field and displays either an absolute value or a percentage.
ipuThresholdPrefType
String
Type of threshold. Returns one of the following values:
The response includes the following fields for tag configurations:
Field
Type
Description
orgId
String
ID of the organization.
projectName
String
Name of the project.
folderName
String
Name of the folder. For project based thresholds, the folder name is NULL.
thresholdValue
Integer
Threshold value.
currentConsumption
BigDecimal
Specifies how many IPUs are consumed. This field's value relates to the ipuThresholdPrefType field and displays either an absolute value or a percentage.
ipuThresholdPrefType
String
Type of threshold. Returns one of the following values:
Get response example If succesful, you might receive a response similar to the following for organization configurations:
{
A succesful response for tag configurations would look like the following:
{
Downloading the metering data When the export job completes successfully, use a GET request to download a ZIP file that contains the requested metering data.
The ZIP file is available to download for 3 days after the job completes with a status of SUCCESS or PARTIAL_SUCCESS.
Note: You can download the ZIP file when the status of the job is PARTIAL_SUCCESS. However, the data in the ZIP file might be not be complete.
GET request To download the ZIP file, use the following URI:
public/core/v3/license/metering/ExportMeteringData/<jobId>/download
GET response If successful, you receive the ZIP stream in the response body and the response type will be application/zip. To download the file, save the response to a file as shown in the following image using Postman:
