Get client IO profile stats for a virtual volume

NAS File Storage REST API Reference

Version

15.6.x

File Size

1291 KB

Audience

anonymous

Part Number

MK-92HNAS100-07

ft:lastEdition

2026-04-07

get /v9/storage/virtual-volumes/{virtualVolumeObjectId}/statistics/io-profile/{remoteAddress}/file-access

Get client IO profile statistics for a virtual volume, covering the recent past (up to an hour), of client access to individual filesystem paths. The results are grouped by client address and filesystem path.

This API call does not work on all platforms and can potentially return a large amount of data. Unlike most other API calls, the response data is pre-sorted before it is returned, from most active to least active.

Note: Accepted parameter values may be restricted based on the virtual server access granted by the API key used for authentication.

Authentication: x_subsystem_user Api Key "X-Subsystem-User"

Authentication: x_subsystem_password Api Key "X-Subsystem-Password"

Authentication: api_key Api Key "X-Api-Key"

Authentication: basicAuth HTTP - basic scheme

Path parameters

remoteAddress String required

Remote address of the connection

Example: 10.2.3.4

virtualVolumeObjectId String required

Object ID of the virtual volume

Example: 313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56

Query parameters

durationInSeconds Integer

Duration of the time window that the statistics are retrieved for. The duration is limited to the maximum history buffer which is one hour

int32

Example: 60

Default: 10

includeUnknownAccess Boolean

Include results where the path being accessed is unknown

Example: true

Default: false

limitToTopEntries Integer

Limit the number of result entries to the specific number of top entries

int32

Example: 20

Default: 50

minimumOperations Integer

Include results where the number of operations is equal to or greater than this value over the specified duration

int32

Example: 20

Default: 50

subsampleFactor Integer

Cuts down the number of historic samples processed to generate the statistics. If there is a lot of traffic on the system and the statistics take a significant time to return, then increase this value

int32

Example: 1

Default: 0

CLIENT REQUEST

          curl -X 'GET'

         -H "X-Subsystem-User: [[apiKey]]"
        
         \
      
         -H "X-Subsystem-Password: [[apiKey]]"
        
         \
      
         -H "X-Api-Key: [[apiKey]]"
        
         \
      
         -H "Authorization: Basic [[basicHash]]"
         \
      
        -H
        'Accept: application/json'
      
      'https://172.27.146.40:8444/v9/storage/virtual-volumes/{virtualVolumeObjectId}/statistics/io-profile/{remoteAddress}/file-access?durationInSeconds=60&includeUnknownAccess=true&limitToTopEntries=20&minimumOperations=20&subsampleFactor=1'

import http.client

conn = http.client.HTTPSConnection("172.27.146.40:8444")

headers = { 'Authorization': "Basic REPLACE_BASIC_AUTH" }

conn.request("GET", "/v9/storage/virtual-volumes/313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56/statistics/io-profile/10.2.3.4/file-access?durationInSeconds=60&includeUnknownAccess=SOME_BOOLEAN_VALUE&limitToTopEntries=20&minimumOperations=20&subsampleFactor=1", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://172.27.146.40:8444/v9/storage/virtual-volumes/313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56/statistics/io-profile/10.2.3.4/file-access?durationInSeconds=60&includeUnknownAccess=SOME_BOOLEAN_VALUE&limitToTopEntries=20&minimumOperations=20&subsampleFactor=1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic REPLACE_BASIC_AUTH'

response = http.request(request)
puts response.read_body

const data = null;

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://172.27.146.40:8444/v9/storage/virtual-volumes/313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56/statistics/io-profile/10.2.3.4/file-access?durationInSeconds=60&includeUnknownAccess=SOME_BOOLEAN_VALUE&limitToTopEntries=20&minimumOperations=20&subsampleFactor=1");
xhr.setRequestHeader("Authorization", "Basic REPLACE_BASIC_AUTH");

xhr.send(data);

HttpResponse<String> response = Unirest.get("https://172.27.146.40:8444/v9/storage/virtual-volumes/313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56/statistics/io-profile/10.2.3.4/file-access?durationInSeconds=60&includeUnknownAccess=SOME_BOOLEAN_VALUE&limitToTopEntries=20&minimumOperations=20&subsampleFactor=1")
  .header("Authorization", "Basic REPLACE_BASIC_AUTH")
  .asString();

import Foundation

let headers = ["Authorization": "Basic REPLACE_BASIC_AUTH"]

let request = NSMutableURLRequest(url: NSURL(string: "https://172.27.146.40:8444/v9/storage/virtual-volumes/313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56/statistics/io-profile/10.2.3.4/file-access?durationInSeconds=60&includeUnknownAccess=SOME_BOOLEAN_VALUE&limitToTopEntries=20&minimumOperations=20&subsampleFactor=1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8444",
  CURLOPT_URL => "https://172.27.146.40:8444/v9/storage/virtual-volumes/313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56/statistics/io-profile/10.2.3.4/file-access?durationInSeconds=60&includeUnknownAccess=SOME_BOOLEAN_VALUE&limitToTopEntries=20&minimumOperations=20&subsampleFactor=1",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic REPLACE_BASIC_AUTH"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://172.27.146.40:8444/v9/storage/virtual-volumes/313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56/statistics/io-profile/10.2.3.4/file-access?durationInSeconds=60&includeUnknownAccess=SOME_BOOLEAN_VALUE&limitToTopEntries=20&minimumOperations=20&subsampleFactor=1");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Basic REPLACE_BASIC_AUTH");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://172.27.146.40:8444/v9/storage/virtual-volumes/313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56/statistics/io-profile/10.2.3.4/file-access?durationInSeconds=60&includeUnknownAccess=SOME_BOOLEAN_VALUE&limitToTopEntries=20&minimumOperations=20&subsampleFactor=1");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic REPLACE_BASIC_AUTH");
IRestResponse response = client.Execute(request);

Responses

Successful operation

Body

application/json

ioProfileClientarray

[

averageLatencyMicroSecintegerint32

Average latency of all operations divided by the duration of the statistics entry, in micro seconds

Example:50

averageReadDataSizeintegerint32

Average data size across all read requests that make up the statistics entry

Example:8192

averageReadThroughputBytesPerSecintegerint32

Average of all read data divided by the duration of the statistics entry

Example:50

averageWriteDataSizeintegerint32

Average data size across all write requests that make up the statistics entry

Example:8192

averageWriteThroughputBytesPerSecintegerint32

Average of all write data divided by the duration of the statistics entry

Example:50

filesystemIdstring

ID of the file system

Example:"7B263DFD1D71E65A0000000000000000"

maxLatencyMicroSecintegerint32

Maximum latency value of all the operations that make up the statistics entry, in micro seconds

Example:50

nodeIdintegerint32

Cluster node ID

Example:1

objectNumberinteger

Object number of the item within the filesystem that is being accessed

operationsinteger

Total number of operations that are summarized in the statistics entry

Example:"5112"

operationsPerSecintegerint32

Total number of operations divided by the duration of the statistics entry

Example:50

pathstring

Full filesystem path that the statistics entry relates to. A blank value means the path has either been deleted, or the statistics entry could relate to metadata operations that are not accessing a specific file or directory

Example:"/dir1/lun1.iscsi"

protocolstring (Enum)

Protocol covered by the statistics entry

Allowed values:"UNKNOWN""NFS2""NFS3""NFS4""NFS4_1""SMB1""SMB2""SMB2_1""SMB3""ISCSI""OTHER"

readSamplesinteger

Number of read operations covered by the statistics entry

Example:"50"

remoteAddressstring

Remote address of the connection

Example:"10.2.3.4"

virtualServerIdintegerint32

ID of the virtual server. 0 = management virtual server 255 = not assigned to virtual server

Example:1

virtualVolumeIdinteger

ID of the virtual volume

Example:"646464"

virtualVolumeNamestring

Name of the virtual volume

Example:"vv1"

virtualVolumeObjectIdstring

Object ID of the virtual volume

Example:"313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56"

writeSamplesinteger

Number of write operations covered by the statistics entry

Example:"50"

]

RESPONSE
{
  "ioProfileClient": [
    {
      "averageLatencyMicroSec": 50,
      "averageReadDataSize": 8192,
      "averageReadThroughputBytesPerSec": 50,
      "averageWriteDataSize": 8192,
      "averageWriteThroughputBytesPerSec": 50,
      "filesystemId": "7B263DFD1D71E65A0000000000000000",
      "maxLatencyMicroSec": 50,
      "nodeId": 1,
      "objectNumber": 0,
      "operations": "5112",
      "operationsPerSec": 50,
      "path": "/dir1/lun1.iscsi",
      "protocol": "UNKNOWN",
      "readSamples": "50",
      "remoteAddress": "10.2.3.4",
      "virtualServerId": 1,
      "virtualVolumeId": "646464",
      "virtualVolumeName": "vv1",
      "virtualVolumeObjectId": "313a3a3a30373545414439464546414234454239303030303030303030303030303030303a3a3a323a3a3a303a3a3a4f49445f24232140255f56",
      "writeSamples": "50"
    }
  ]
}

Bad Request

Body

application/json

errorCodeintegerint32

Generic error code

Example:1081353

errorMsgstring

Main error message

Example:

"Invalid description parameter - the optional parameter must be between 2 and 30 characters long to be valid, if supplied"

RESPONSE
{
  "errorCode": 1081353,
  "errorMsg": "Invalid description parameter - the optional parameter must be between 2 and 30 characters long to be valid, if supplied"
}

Unauthorized - the request was rejected because the credentials or API key were either missing or invalid

Forbidden - the client does not have the required permissions to perform the operation

Body

application/json

errorMsgstring

Main error message

Example:"Forbidden request - the client does not have the required permissions to perform the operation"

RESPONSE
{
  "errorMsg": "Forbidden request - the client does not have the required permissions to perform the operation"
}

Not Found - a resource specified was not found

Body

application/json

errorCodeintegerint32

Generic error code

Example:1081345

errorDetailobject

Detailed error information

detailstring

More details on why the error occurred

faultstring

fileNamestring

Source file where the error occurred

Example:"RestApiFilesystems.cpp"

functionstring

Internal function name where the error occurred

Example:"mountFilesystem"

lineNumberintegerint32

Line number within the source file, where the error occurred

messagestring

Reason why the error(s) occurred

Example:"The file system is currently unassigned"

reasonstring

Reason why the error(s) occurred

Example:"The file system is currently unassigned"

returnedValueintegerint32

Not used

subCodeintegerint32

Specific failure error code

errorMsgstring

Main error message

Example:"Cannot find the object of the operation on the device"

RESPONSE
{
  "errorCode": 1081345,
  "errorDetail": {
    "detail": "",
    "fault": "",
    "fileName": "RestApiFilesystems.cpp",
    "function": "mountFilesystem",
    "lineNumber": 0,
    "message": "The file system is currently unassigned",
    "reason": "The file system is currently unassigned",
    "returnedValue": 0,
    "subCode": 0
  },
  "errorMsg": "Cannot find the object of the operation on the device"
}

Internal Server Error

Body

application/json

errorCodeintegerint32

Generic error code

errorDetailobject

Detailed error information

detailstring

More details on why the error occurred

faultstring

fileNamestring

Source file where the error occurred

Example:"RestApiFilesystems.cpp"

functionstring

Internal function name where the error occurred

Example:"mountFilesystem"

lineNumberintegerint32

Line number within the source file, where the error occurred

messagestring

Reason why the error(s) occurred

Example:"The file system is currently unassigned"

reasonstring

Reason why the error(s) occurred

Example:"The file system is currently unassigned"

returnedValueintegerint32

Not used

subCodeintegerint32

Specific failure error code

errorMsgstring

Main error message

Example:"Failed to mount file system"

RESPONSE
{
  "errorCode": 0,
  "errorDetail": {
    "detail": "",
    "fault": "",
    "fileName": "RestApiFilesystems.cpp",
    "function": "mountFilesystem",
    "lineNumber": 0,
    "message": "The file system is currently unassigned",
    "reason": "The file system is currently unassigned",
    "returnedValue": 0,
    "subCode": 0
  },
  "errorMsg": "Failed to mount file system"
}