Storage Usage Reporting API¶

The Storage Usage Reporting API provides a single endpoint to retrieve aggregated storage usage across all accounts and locations. It returns per-account, per-location breakdowns of bytes stored and object counts.

Results are paginated using marker-based pagination, consistent with AWS-style listing APIs.

API Access¶

The reporting API is available through two access points:

Workload plane: https://management.<base-domain>/api/v1/instance/{uuid}/reporting/usage
Control plane: <control-plane-ingress>/zenko/api/v1/instance/{uuid}/reporting/usage

To retrieve the control plane ingress endpoint, refer to Access ARTESCA UI.

Authorization¶

The API requires a valid Keycloak JWT passed via the X-Authentication-Token header.

Access is granted to users with one of the following ARTESCA roles:

StorageManager
StorageUsageReporter

Users with other roles (e.g., DataConsumer, StorageAccountOwner) will receive a 403 Forbidden response.

Note

Newly provisioned users have a temporary password. The user must log in to the management UI at least once and set a permanent password before a token can be retrieved programmatically. See Retrieve Access Tokens for the full procedure.

API Endpoint¶

Get Storage Usage Report¶

Retrieves aggregated storage usage across all accounts, broken down by location.

HTTP Request

GET /api/v1/instance/{uuid}/reporting/usage

Parameters

Name	Location	Required	Description
uuid	path	yes	Zenko Instance ID (retrieved via kubectl as shown in Retrieve Access Tokens).
marker	query	no	Pagination token returned by a previous truncated response.
maxItems	query	no	Maximum number of accounts to return per page. Default: 1000, maximum: 1000.

Response (200 OK)

{
    "isTruncated": false,
    "marker": "",
    "accounts": {
        "my-account": {
            "us-east-1": {
                "bytesTotal": 1099511627776,
                "objectsTotal": 50000
            },
            "eu-west-1": {
                "bytesTotal": 549755813888,
                "objectsTotal": 25000
            }
        },
        "other-account": {
            "us-east-1": {
                "bytesTotal": 274877906944,
                "objectsTotal": 12000
            }
        },
        "empty-account": {}
    }
}

Response Fields

Field	Type	Description
isTruncated	boolean	Whether there are more accounts beyond this page.
marker	string	When `isTruncated` is `true`, contains a pagination token. Pass this value as the `marker` query parameter to fetch the next page.
accounts	object	Per-account storage usage, keyed by account name. Each account maps location names to usage objects containing `bytesTotal` (integer) and `objectsTotal` (integer). Accounts with no data in any location appear as empty objects.

Error Responses

Status	Description
401	No valid authentication token provided.
403	The caller does not have the StorageManager or StorageUsageReporter role.
500	Internal server error (e.g., SCUBA or Vault unavailable).

Example¶

This example shows how to retrieve the storage usage report using curl.

Retrieve URL, TOKEN, and INSTANCE_ID as described in Retrieve Access Tokens.

Note

The INSTANCE_ID only needs to be retrieved once and can be reused across requests.

Retrieve the storage usage report.

[artesca-os@bootstrap ~]$

curl -s -k -X GET \
    -H "X-Authentication-Token: ${TOKEN}" \
    "${URL}/zenko/api/v1/instance/${INSTANCE_ID}/reporting/usage" | \
    jq '.'

Pagination¶

When the response contains "isTruncated": true, use the returned marker value in the next request to retrieve the following page of accounts:

GET /api/v1/instance/{uuid}/reporting/usage?marker={marker}

Continue until isTruncated is false.

Note

There may be a delay between an object operation and its reflection in the reported usage data. Metrics are based on the latest SCUBA checkpoints, which are calculated periodically.