Retrieving metering data with the API

Edit online

Use the IBM® Sovereign Core metering APIs to view service usage. The metering system collects usage data for deployed services so service providers can provide transparent, usage-based billing.

Before you begin

You must have the Owner role in the platform account to generate an API key that can be used to fetch metering data. The API key must have the account Owner role because the metering data contains information about instances, accounts, and workspaces across the system. For details on how to access the account, see Setting up the platform account.

Use the generated API key to create a bearer token as follows:

From the platform account home page, select Access management in the navigation menu.
From the API keys tab, click Generate API key, and enter a name for the API key, assign the Owner role, and set an expiration date, if applicable.
Click Generate API key.
Important: For security reasons, the API key is only available to be copied or downloaded at the time of creation. Save the API key for your records.
From the terminal in your workstation, save the platform API key in an environment variable:
```
export PLATFORM_API_KEY=<platform-api-key>
```

Exchange the API key for an Identity and Access Management (IAM) token by using the IBM Sovereign Core API:

curl --request POST \
--url https://account-iam.apps.<OCP-domain>/api/2.0/accounts/platform/apikeys/token \
 --header 'Content-Type: application/json' \
 --data '{"apikey": "${PLATFORM_API_KEY}"}'

Save the platform IAM token returned in the REST API response in an environment variable:

export PLATFORM_TOKEN=<platform-iam-token>

About this task

The IBM Sovereign Core metering API provides endpoints for system owners to query usage records. All API requests require authentication with the platform IAM token. For detailed descriptions of the metering API endpoints, and API request and response schemas, see Metering APIs in the IBM Sovereign Core API reference documentation.

Procedure

Retrieve the metering API endpoint URL in one of the following ways:
- Log in to the management cluster where IBM Sovereign Core is installed and use the route named sovereign-core-metrics-aggregator-route in the sovereign-core-metrics-aggregagor-route.
```
export API_ENDPOINT_URL=$(oc get route sovereign-core-metrics-aggregator-route --namespace=sovereign-core-metrics-aggregator --output=jsonpath='{.spec.host}')
```
- Assemble the URL from the OCP domain.
```
export API_ENDPOINT_URL='https://sovereign-core-metrics-aggregator.<OCP-domain>'
```

Retrieve raw usage data or metering metrics for a service. The following commands use the Cluster service as an example.

Retrieve unaggregated usage data points for a specific service.

The following example shows you can retrieve unaggregated usage data points for a service over a given time range that is filtered on tenant IDs, workspace IDs, and service instance IDs:

curl --request GET \
--url '${API_ENDPOINT_URL}/metering/services/cluster-as-a-service/usage/raw?tenantIds=all&workspaceIds=all&instanceIds=all&usageStart=1769990400000&usagePageSize=2&usageNextPageKey=17' \
--header 'Authorization: Bearer ${PLATFORM_TOKEN}' \
--header 'accept: application/json'

The example REST API response shows two metered data points for the service as follows:

{
    "params": {
        "tenantIds": ["all"],
        "workspaceIds": ["all"],
        "instanceIds": ["<service-instance-id>"],
        "usageStart": 1769990400000,
        "usageEnd": 1769990400000,
        "usagePageSize": 2,
        "usageNextPageKey": 19,
        "serviceId": "cluster-as-a-service"
    },
    "meteredUsage": [
        {
            "instanceId": "<service-instance-id>",
            "tenantId": "",
            "workspaceId": "<workspace-id>",
            "serviceId": "cluster-as-a-service",
            "region": "earth-1",
            "crn": "crn:v1:ibm-sc:private:cluster-as-a-service:earth-1:sub/<service-instance-crn>::",
            "metricId": "cpu_cores",
            "meteringModel": "point-in-time",
            "id": 18,
            "startTimestamp": "2026-04-27T12:11:19.357Z",
            "endTimestamp": "2026-04-27T12:11:19.357Z",
            "usageQuantity": 8,
            "correlationId": "my-cluster-provisioned-2026-04-27T12:11:19Z",
            "transactionId": "cluster-as-a-service-c1d7d497-7969-48b4-bb56-5eba530b05bb-1777291879593"
        },
        {
            "instanceId": "<service-instance-id>",
            "tenantId": "",
            "workspaceId": "<workspace-id>",
            "serviceId": "cluster-as-a-service",
            "region": "earth-1",
            "crn": "crn:v1:ibm-sc:private:cluster-as-a-service:earth-1:sub/<service-instance-crn>::",
            "metricId": "memory_gb",
            "meteringModel": "point-in-time",
            "id": 19,
            "startTimestamp": "2026-04-27T12:11:19.357Z",
            "endTimestamp": "2026-04-27T12:11:19.358Z",
            "usageQuantity": 16,
            "correlationId": "my-cluster-provisioned-2026-04-27T12:11:19Z",
            "transactionId": "cluster-as-a-service-c1d7d497-7969-48b4-bb56-5eba530b05bb-1777291879593"
        }
    ]
}

To retrieve list of available metrics for a specific service, run the following API request:

curl --request GET \
--url '${API_ENDPOINT_URL}/metering/services/cluster-as-a-service/metrics' \
--header 'Authorization: Bearer ${PLATFORM_TOKEN}' \
--header 'accept: application/json'

The example API response with details about each metric is as follows:

{
  "metrics": [
    {
      "metricId": "users",
      "serviceId": "cluster-as-a-service",
      "meteringModel": "total-up-to-date"
    },
    {
      "metricId": "instances",
      "serviceId": "cluster-as-a-service",
      "meteringModel": "total-up-to-date"
    },
    {
      "metricId": "storage",
      "serviceId": "cluster-as-a-service",
      "meteringModel": "total-up-to-date"
    },
    {
      "metricId": "tokens",
      "serviceId": "cluster-as-a-service",
      "meteringModel": "total-up-to-date"
    },
    {
      "metricId": "cpu",
      "serviceId": "cluster-as-a-service",
      "meteringModel": "point-in-time"
    }
  ]
}

What to do next

You use the API to analyze metering data and build billing models to charge tenant account owners for service usage.