Scality Utilization Reporting API

Description

The Scality Utilization Reporting (SUR) API provides access to storage usage metrics at different levels: account, bucket, and location.

The API retrieves the latest metrics for specific resources. The metrics provide information about storage utilization, including the number of objects and total bytes used.

API Access

The SUR API is available under the utilization.<base-domain> endpoint of the workload plane.

For example: https://utilization.zenko.workloadplane.scality.local.

Authorization

The API grants requests for the following identities:

• Account credentials

• Storage manager

• Storage account owners

• Data consumers

• Storage usage reporters

Custom identities must be granted the sur:GetMetrics IAM permission.

Note

To retrieve storage usage across all accounts in a single call, use the Storage Usage Reporting API instead.

A valid AWS Authorization Header is required for all requests. Refer to the example <#example> section for more details.

API Endpoints

Get Latest Metrics

Retrieves the latest metrics for a specific resource.

HTTP Request

POST /metrics/{metricsClass}/{resourceName}/latest

Path Parameters

Name	Description	Type
metricsClass	The class of metrics to retrieve (account, bucket, or location)	string
resourceName	The name of the resource (account name, bucket name, or location name)	string

Response

{
  "objectsTotal": 1234,
  "bytesTotal": 5678901234,
  "metricsClass": "bucket",
  "resourceName": "my-bucket",
  "date": "2025-05-01T12:00:00.000Z"
}

Important

The resourceName field returned in the API responses is for internal use only and may be removed in the future. Applications must not use this field. Instead, applications must maintain their own references to resource names using the values provided in the API requests.

Get Latest Sub-Metrics

Retrieves the latest sub-metrics (e.g., location-specific metrics) for a resource. Currently, only location-specific sub-metrics are supported.

HTTP Request

POST /metrics/{metricsClass}/{resourceName}/{subMetricsClass}/{subResourceName}/latest

Path Parameters

Name	Description	Type
metricsClass	The class of metrics to retrieve (account, bucket, or location)	string
resourceName	The name of the resource (account name, bucket name, or location name)	string
subMetricsClass	The type of sub-metric (e.g., ‘location’)	string
subResourceName	The name of the sub-metric (e.g., ‘us-east-1’)	string

Response

{
  "objectsTotal": 645,
  "bytesTotal": 2345678901,
  "metricsClass": "bucket",
  "resourceName": "my-bucket",
  "date": "2025-05-01T12:00:00.000Z"
}

Response Error Handling

In case of errors, the API may return error objects:

Resource Error

{
  "metricsClass": "bucket",
  "resourceName": "non-existent-bucket",
  "error": {
    "code": 404,
    "description": "Resource not found"
  }
}

Date Error

{
  "date": "2025-01-01",
  "error": {
    "code": 404,
    "description": "Metrics not available for this date"
  }
}

Important

If a bucket is non-existent or owned by a different account, the API will return a 403 Access Denied error.

Example

This example shows how to retrieve the latest metrics for an account using the AWS Authorization Header and an IAM user.

export DOMAIN='your_instance_domain'
export ACCOUNT_NAME='your_account_name'
export ACCESS_KEY_ID='your_access_key_id'
export SECRET_ACCESS_KEY='your_secret_access_key'

curl -X POST "https://utilization.${DOMAIN}/metrics/account/${ACCOUNT_NAME}/latest" \
  --user "${ACCESS_KEY_ID}:${SECRET_ACCESS_KEY}" \
  -H "x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "Content-Type: application/json" \
  --aws-sigv4 "aws:amz:us-east-1:s3"

Important

Requires curl version 7.86.0 or higher.