Retrieves historical size statistics over time for a directory. The response includes only the information pertaining to the queried provider; in order to collect globally-complete statistics, all providers supporting the space must be queried. There may be discrepancies in statistics such as logical size of data, which stem from synchronization delays between providers.

Size statistics over time are available only for directories. They are collected hierarchically i.e. for a certain directory, its statistics are a sum of statistics for the directory (regarding its direct children), and the statistics from all its subdirectories. Additionally, size statistics for the space directory encompass relevant information from archives.

This endpoint requires the size statistics to be enabled for the containing space on the queried provider. Otherwise, an adequate error will be returned.

Two request modes are supported:

• layout - returns information about the structure of stats collection, i.e. the names of the available time series and metrics within them
• slice - returns a slice of statistics as a collection of slices of requested time series and metrics

The following time series are available for each directory:

• logical_size - total size of file data contained in the directory, i.e. the sum of logical sizes of all regular files in its subtree. If a file has multiple hardlinks in the subtree, each hardlink is counted separately.
• virtual_size - consolidated logical size, where hardlinks of the same file in the subtree are counted only once. Represents the storage space required for a complete replica of the directory.
• physical_size_$STORAGE_ID - actual amount of storage consumed on a given storage backend by all regular files in the directory’s subtree. May be smaller than the virtual size if some file replicas are incomplete. Only the storage backends owned by the queried providers are returned.
• reg_file_and_link_count - the count of regular files, hard links, and symbolic links contained in the directory.
• dir_count - the count of directories contained in the directory.
• file_error_count - the count of error occurrences when the statistics mechanisms were not able to gather size information about a certain file.
• dir_error_count - like above, for directories.

If the values of file_errors_count or dir_errors_count are not zero, the statistics may not be accurate.

The following metrics are available for each time series: day, hour, minute, month.

Example cURL requests

Get the layout of directory size statistics

curl -H "X-Auth-Token: $TOKEN" \
-X GET "https://$PROVIDER_HOST/api/v3/oneprovider/data/$DIR_ID/dir_size_stats" \
-H "Content-Type: application/json" -d '{
    "mode": "layout"  
}'

{
    "layout": {
        "total_size": [
            "day",
            "hour",
            "minute",
            "month"
        ],
        "storage_use_7ab46e96fdb27a2694493c2c5bd7491dch8f55": [...],
        "reg_file_and_link_count": [...],
        "file_errors_count": [...],
        "dir_errors_count": [...],
        "dir_count": [...]
    }
}

Get a slice of directory size statistics

curl -H "X-Auth-Token: $TOKEN" \
-X GET "https://$PROVIDER_HOST/api/v3/oneprovider/data/$DIR_ID/dir_size_stats" \
-H "Content-Type: application/json" -d '{
    "mode": "slice",
    "extendedInfo": true,
    "layout": {
        "total_size": [
            "minute"
        ],
        "storage_use_7ab46e96fdb27a2694493c2c5bd7491dch8f55": [
            "minute"
        ]
    },
    "startTimestamp": 1687513285,
    "stopTimestamp": 1687499802,
    "windowLimit": 31
}'

{
    "slice": {
        "total_size": {
            "minute": [
                {
                    "value": 883365,
                    "timestamp": 1687513260,
                    "lastMeasurementTimestamp": 1687513287,
                    "firstMeasurementTimestamp": 1687513287
                },
                ...
            ]
        },
        "storage_use_7ab46e96fdb27a2694493c2c5bd7491dch8f55": {
            "minute": [
                {
                    "value": 56280,
                    "timestamp": 1687513260,
                    "lastMeasurementTimestamp": 1687513287,
                    "firstMeasurementTimestamp": 1687513287
                },
                ...
            ]
        }
    }
}'