/usage

Retrieve usage data, as bytes transferred in, bytes transferred out, and total, listed by usage ID. The usage ID is a user-defined tag that is configured as part of the transfer request, either in an /ops/transfers request body or on the ascp command line. You can also retrieve usage data for a specific usage ID. Usage information (usage ID and bytes transferred) is not available until the FASP transfer gracefully terminates (completes or errors). If the FASP transfer is stopped abruptly, no usage information is retained. To get transfer rates for a specific transfer as timeseries data, use /ops/transfers/bandwidth.

Requirements
  • Available as of Enterprise Server version 3.7.2.
  • Event activity logging must be enabled on the node (it is enabled by default). If it is not enabled, run the following command:
    $ asconfigurator -x "set_server_data;activity_logging,true"
Access Control
  • HTTP Basic Auth
    Authentication with Node API credentials allows you to retrieve usage for the node user. If an access key is also provided as a query, the response is the same as for access key authentication. Authentication with a master access key ID and secret allows you to retrieve usage associated with the access key, including usage by all usage IDs, aggregate usage for the access key and any sub-access keys, and usage by access key (for sub-access keys). Authentication with a sub-access key allows you to retrieve only usage data associated with the sub-access key (no data by usage IDs or aggregate data).
  • Bearer Token
    Authentication with a bearer token allows you to retrieve usage data for the associated access key only if the bearer token has an admin scope-role. Bearer tokens with user scope-role cannot access /usage.
Headers

All requests to this endpoint use the same headers.

Header Name Required Description Values
Content-Type Optional The format of the request data. application/json
Accept Optional The format of the response data. application/json
X-Aspera-AccessKey Required
(for bearer token authorization)
The access key ID that was used to create the bearer token. Access key ID.
Authorization Required
(for bearer token authorization)
The bearer token. "Bearer token_string"
Status Codes and Errors
Code Description Notes
200 OK Success
400 Bad Request Error Request contains a formatting or syntax error.
404 Error Event logging is not enabled on the server or the usage ID is not valid.

Endpoint Actions

Get All Usage Data

Retrieve usage information, as allowed by the authentication method.

URL
GET https://{domain}:9092/usage

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/usage?access_key=ak123 \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Query Parameters
Parameter Type Description Values
access_key String When authenticating with Node API credentials, retrieve usage data for the specified access key. access key ID
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
 
[
{
"id" : "1234",
"bytes_in" : 50000000,
"bytes_out" : 0,
"bytes_total" : 5000000
},
{
"id" : "3359723",
"bytes_in" : 0,
"bytes_out" : 100000,
"bytes_total" : 100000
},
{
"id" : "32352934",
"bytes_in" : 80000000,
"bytes_out" : 0,
"bytes_total" : 8000000
}
]

Response
Element Type Description
id String The usage ID, as set in the transfer request.
bytes_in Unsigned integer The number of bytes downloaded by the usage ID.
bytes_out Unsigned integer The number of bytes uploaded by the usage ID.
bytes_total Unsigned integer The total number of bytes transferred by the usage ID.

Get Usage Data for a Specific Usage ID

Retrieve usage information for a specific usage ID, as allowed by the authentication method.

URL
GET https://{domain}:9092/usage/{id}

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/usage/{id} \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
 
[
{
"id" : "1234",
"bytes_in" : 50000000,
"bytes_out" : 0,
"bytes_total" : 5000000
}
]

Response
Element Type Description
id String The usage ID, as set in the transfer request.
bytes_in Unsigned integer The number of bytes downloaded by the usage ID.
bytes_out Unsigned integer The number of bytes uploaded by the usage ID.
bytes_total Unsigned integer The total number of bytes transferred by the usage ID.
Video player

Video

×

Reset your Password Password resets are handled on the Support Site

×