Documentation deprecated: This documentation is no longer being updated as of 3.8.0. For up-to-date information, see the guide information in the IBM Developer Community and the endpoint reference in IBM API Explorer.

/ops/transfers

Start and manage node-to-node transfers, and retrieve information about transfers.

Requirements
  • Available as of Enterprise Server version 3.6.0.
  • To query transfers with this endpoint, enable activity logging on the node by running the following command:
    asconfigurator -x "set_server_data;activity_logging,true"
    Restart the asperanoded service to activate your change. On Linux, run the following command:
    # service asperanoded restart
Access Control
  • HTTP Basic Auth
    Provide a node username and password or access key ID and secret. With HTTP basic authentication, you can start a transfer of any content in the tenant space (as allowed by the node user's file restriction or docroot, and by the storage path in the access key). You can get information about, modify, and cancel any transfers in the same tenant space. Note: Node users in versions 3.6.0 through 3.6.5 have full access to start, list, and stop all transfers.
  • Bearer token
    Actions are restricted to the tenant space defined by the bearer token and the permissions set on the content.
    • Start transfers (POST) - you can start a transfer to and from any file_id for which you have edit and view permissions.
    • List transfer information (GET) - you can see any transfer corresponding to root_id with at least view permissions
    • Modify transfers (PUT) - can modify any local transfer started by the same user_id
    • Stop transfers (CANCEL) -- can stop any local transfer started by the same user_id
As of version 3.8.0, the access key that is used to authorize POST requests (either directly or as a component of the bearer token) can restrict some values that are allowed in the transfer configuration, including encryption cipher, rate policy, target rate, and content protection.

Endpoint Actions

Start a New Transfer

Start a transfer between the local node (the node receiving the Node API request) and a remote node that uses the transfer specifications that are contained in the request body.

URL
POST https://{domain}:9092/ops/transfers

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"

Sample Request
curl -i -X POST https://{domain}:9092/ops/transfers \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "X-Aspera-AccessKey: access_key_id" \
     -H "Authorization: Bearer token_string" \
     -d @request_body.json

Where request_body.json contains the following:
{
    "direction": "send",                               
    "remote_host": "domain",                          
    "remote_user" : "transfer_user",
    "remote_password" : "password",
    "ssh_private_key" : "key_string",
    "ssh_private_key_passphrase" : "passphrase",                 
    "remote_access_key": "remote_access_key_id",      
    "token" : "Bearer|Basic remote_token_string",   
    "source_root_id" : "1",                           
    "destination_root_id" : "1",                        
    "paths": [
        {
            "source" : "file_name",
            "destination" : "destination_file_name"
        },
        {
            "source" : "source_folder",
            "destination" : "destination_folder_name"
        }
    ],
    "ssh_port" : port,
    "fasp_port" : port,
    "http_fallback" : true|false,
    "http_fallback_port" : port,
    "https_fallback_port" : port,
    "cipher" : "cipher",
    "content_protection" : "encrypt|decrypt",
    "content_protection_password" : "password",
    "cookie" : "string",
    "rate_policy_allowed" : "policy",
    "rate_policy" : "policy",
    "symlink_policy" : "policy",
    "tags" : {
        "aspera" : {
        "xfer_retry":number,
        "usage_id" : "transfer_usage_id"
        }
    },
    "target_rate_kbps" : rate,
    "target_rate_cap_kbps" : rate,
    "title" : "transfer_name",
    "overwrite" : "policy",
    "resume_policy" : "policy",
    "retry_duration": "seconds",
    "create_dir" : true|false,
    "precalculate_job_size": true|false,
    "remove_after_transfer": true|false,
    "remove_empty_directories": true|false,
    "use_ascp4" : true|false,
    "delete_source": true|false,
    "multi_session" : 1,
    "multi_session_threshold" : bytes,
    "preserve_access_time" : true|false,
    "preserve_modification_time" : true|false,
    "preserve_creation_time" : true|false,
    "use_ascp4" : true|false
}

Request Body
Parameter Required Type Description
direction Required String Specify the direction of the transfer: send or receive.
remote_host Required String IP or fully qualified domain name of the remote server.
remote_user Optional String The transfer user on the remote node for SSH authentication. Default: xfer.
remote_password Required if using Basic token and no SSH key provided String The password for the remote transfer user. Available as of 3.6.1. Aspera recommends using SSH private keys instead of passwords.
ssh_private_key Required if using Basic token and no SSH password provided String The contents of the transfer user's SSH private key. Available as of 3.7.2.
ssh_private_key_passphrase Required if SSH key is password protected String The passphrase associated with the transfer user's SSH private key. Available as of 3.7.2.
remote_access_key Required if using Bearer token String The access key ID of the access key that was used to construct the bearer token that is used to authenticate to the remote node.
token Required String The token that authorizes access to the storage on the remote node. The token can be a basic token, bearer token, or transfer token. For basic tokens, enter "Basic token_string". For bearer tokens, enter "Bearer token_string". For transfer tokens, enter "token_string".
source_root_id Required if using Bearer token auth for the source node String The file ID of the source root directory. Retrieve the value by using a GET request to /files.
destination_root_id Required if using Bearer token auth for the destination node String The file ID of the destination root directory. Retrieve the value by using a GET request to /files.
paths Required JSON object Array of JSON objects containing source, and optionally, destination paths. For example:
"paths": [
  {
	"source": "fancy.mpg",
	"destination": "sept_fancy.mpg"
  },
  {
	"source": "movie folder"
  }
]
source Required String Source path for the file or directory being transferred, relative to the source root.
destination Optional String Destination path for the file or directory being transferred, relative to the destination root. If no destination is specified, the content is transferred to the destination root.
ssh_port Optional Unsigned integer The TCP port on the remote node for SSH connections. Default: 33001
fasp_port Optional Unsigned integer The UDP port on the remote node for FASP® transfer. Default: 33001. The default value is satisfactory for most situations; however, it can be changed to satisfy firewall requirements.
http_fallback Optional Boolean If set to true, HTTP fallback attempts to perform an HTTP or HTTPS transfer when a FASP transfer cannot be performed. Default: false.
http_fallback_port Optional Unsigned integer The port that is used for HTTP fallback transfers. Default: 443 if a cipher is enabled, 80 otherwise.
https_fallback_port Optional Unsigned integer The port that is used for HTTPS fallback transfers. Default: 443 if a cipher is enabled, 80 otherwise.
cipher Optional String The algorithm used to encrypt data during transfer. Stronger algorithms increase CPU utilization. Allowed values: none, aes-128, aes-192 (available as of 3.8.0), or aes-256 (available as of 3.8.0). Default: aes-128. Note: If an invalid cipher is set (for example, aes, the transfer uses no encryption (none).
content_protection Optional String Enable client-side content protection (encryption-at-rest). For uploads, set to encrypt to transfer encrypted files and store them on the server with the extension ".aspera-env". To download and decrypt encrypted files, set to decrypt. If content_protection_password is not specified, Connect prompts for the passphrase. Default: decrypt.
content_protection_password Optional String Optional password to apply or remove encryption for client-side content protection. Must be provided when content_protection is used.
cookie Optional String Data to associate with the transfer. The cookie is reported to both client- and server-side applications that are monitoring FASP transfers. Cookies are often used by applications to identify associated transfers.
rate_policy Optional String The rate policy to use when sharing bandwidth. Allowed values:
  • high: When sharing bandwidth, transfer at twice the rate of a transfer using a "fair policy.
  • fair (default value): Share bandwidth equally with other traffic.
  • low: Use only unused bandwidth.
  • fixed: Transfer at the target rate, regardless of the actual network capacity. Do not share bandwidth. Aspera recommends that you do not use this setting.
symlink_policy Optional String Handle symbolic links using the specified method, as allowed by the server. Available as of version 3.7.4.

Allowed values:

  • follow: (Default) Follow a symbolic link and transfer the contents of the linked file or directory as long as the link target is in the user's docroot.
  • copy: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link does not replace the file. If the server symbolic link handling configuration in aspera.conf does not include create, then symbolic links are skipped (the default server configuration is create,follow).
  • copy+force: Copy only the symbolic link. If a file with the same name exists at the destination, the symbolic link replaces the file. If the file of the same name at the destination is a symbolic link to a directory, it is not replaced. If the server symbolic link handling configuration in aspera.conf does not include create, then symbolic links are skipped (the default server configuration is create,follow).
  • skip: Skip symbolic links. Neither the link nor the file to which it points are transferred. This is the only option allowed if the transfer destination is a Windows server.
tags Optional JSON Array of information for Aspera applications. Can be used to filter GET requests.
aspera Optional JSON Container for Aspera-related tags. Required when setting xfer_retry or usage_id.
xfer_retry Optional Integer The number of times to retry the transfer before failing. Default: 15.
usage_id Optional String Assign a usage ID to the transfer in order to query transfer usage (bytes transferred) with the /usage endpoint.
target_rate_kbps Optional Unsigned integer The desired speed of the transfer, in Kbps. If there is competing network traffic, FASP may share this bandwidth, depending on the rate_policy value you set. Default: Server-side target rate default value in the configuration file (aspera.conf). Respects both local- and server-side target rate caps, if set. Must be provided when you set a value for target_rate_cap_kbps.
target_rate_cap_kbps Optional Unsigned integer Upper limit of target rate, in Kbps. Default: no limit.
title Optional String Name for the transfer.
overwrite Optional String Condition for overwriting a file. Allowed values: none, diff, older, prompt
resume_policy Optional String Policy to use when resuming partially transferred (incomplete) files.
  • none: Transfers the entire file again.
  • attrs: Resumes transfer if the files' attributes match.
  • sparse_csum (default value): Resumes transfer if the files' attributes and sparse (fast) checksums match.
  • full_csum: Resumes transfer if the files' attributes and full checksums match.
    Note: Computing full checksums of large files takes time, and heavily utilizes the CPU.
retry_duration Optional Integer Duration of transfer retry, in seconds.
create_dir Optional Boolean If set to true, create the destination directory if it does not already exist. When enabling this option, the destination path is assumed to be a directory path.
precalculate_job_size Optional Boolean Compute the size of the requested transfer. If you are transferring a large number of files this can take a long time. Precalculating job size gives better feedback regarding the percent of the transfer that has completed. Default: false.
use_ascp4 Optional Boolean Set to true to use ascp4 for the transfer. Default: false (use ascp). Available as of 3.8.0.

Usage notes:

  • ascp4 does not prepend the docroot to the source file. For source paths, specify the full path to the source file.
  • ascp4 does not support values for destination. To specify a destination directory, use destination_root_id.
  • ascp4 does not support all of the same transfer options as ascp. For a complete comparison, see the Enterprise Server Admin Guide.
delete_source Optional Boolean Remove all source files, empty directories and the source argument itself. Default: false.
delete_before_transfer Optional Boolean Before transfer, delete any files that exist at the destination but not at the source. Default: false. Available as of 3.8.0.
move_after_transfer Optional String Move source files and copy source directories to the specified archive directory after they are successfully transferred. The original source directory tree remains in place. Available as of 3.8.0.
remove_after_transfer Optional Boolean Remove the file from the source after transfer. This is useful for some workflows, where once a file has been transferred, it is no longer needed at the source. Default: false.
remove_empty_directories Optional Boolean Remove empty directories at the destination. Default: false.
preserve_times Optional Boolean Preserve file timestamps. Default: false. Available as of 3.8.0.
preserve_access_time Optional Boolean Preserve file access time from the source to the destination. Default: false. Available as of 3.8.0.
preserve_modification_time Optional Boolean Preserve file modification time from the source to the destination. Default: false. Available as of 3.8.0.
preserve_creation_time Optional Boolean Preserve file creation time from the source to the destination. Only Windows systems retain information about creation time. If the destination is not a Windows computer, this option is ignored. Default: false. Available as of 3.8.0.
exclude_older_than Optional Unsigned integer Exclude files, but not directories, from the transfer if they are older than the specified time. Time is specified as number of seconds after the source computer's epoch. Available as of 3.8.0.
exclude_newer_than Optional Unsigned integer Exclude files, but not directories, from the transfer if they are newer than the specified time. Time is specified as number of seconds after the source computer's epoch. Available as of 3.8.0.
multi_session Optional Unsigned integer The number of simultaneous transfer sessions. Default: 1.
multi_session_threshold Optional Unsigned integer The maximum size, in bytes, of a file that is transferred by one session. If multi_session is greater than 1, files larger than the threshold are split across transfer sessions.
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
    "id" : "73c70c2e-315b-4676-8e96-ce8b82a2ed81",
    "title" : "test transfer",
    "tags" : {
        "aspera": {
            "xfer_id":"73c70c2e-315b-4676-8e96-ce8b82a2ed81",
            "xfer_retry":15
        }
    },
    "token" : "Basic YWsxMjM6YXNwZXJh",
    "cookie" : null,
    "direction" : "send",
    "remote_host" : "10.0.0.2",
    "remote_user" : "xfer",
    "remote_access_key" : null,
    "source_root" : "/",
    "destination_root" : "/tmp/send",
    "fasp_port" : 33001,
    "ssh_port" : 33001,
    "rate_policy" : "fair",
    "target_rate_kbps" : -1,
    "cipher" : "aes-128",
    "content_protection" : null,
    "content_protection_password" : null,
    "overwrite" : "diff",
    "retry_duration" : "",
    "create_dir" : false,
    "precalculate_job_size" : false,
    "delete_source" : false,
    "remove_after_transfer" : false,
    "remove_empty_directories" : false,
    "multi_session" : 1,
    "multi_session_threshold" : null,
    "preserve_access_time" : false,
    "preserve_modification_time" : false,
    "preserve_creation_time" : false,
    "use_ascp4" : false
}

Status Codes and Errors
Code Description Notes
200 OK Success
400 Bad Request Error Request has a formatting or syntax error.
500 Internal Server Error Error The server configuration is invalid.
503 Service Unavailable Error The access key is locked for backup.

Response
Element Type Description
id String Unique transfer ID.
title String Name of the transfer, if any.
tags JSON Application-generated tags to describe the transfer. Can be used to filter GET requests.
xfer_id String Transfer ID (same as id).
xfer_retry Unsigned integer The number of retry attempts.
token String The transfer authorization token.
cookie String The cookie generated by the application or provided in the POST request.
direction String The direction of the transfer.
remote_host String IP or fully qualified domain name of the remote server.
remote_user String Transfer user name.
remote_access_key String Remote access key for the transfer.
source_root String The file ID of the source root directory.
destination_root String The file ID of the destination root directory.
fasp_port Unsigned integer The port that is used for data transfer.
ssh_port Unsigned integer The port that is used for the SSH connection.
rate_policy String The transfer's rate policy.
target_rate_kbps Unsigned integer The target rate for the transfer, in Kbps.
cipher String The encryption algorithm that is used to encrypt data in transit.
content_protection String The client-side encryption-at-rest action: encrypt or decrypt.
content_protection_password String The passphrase for the client-side encryption-at-rest action, if any.
overwrite String The overwrite policy.
resume_policy String The resume policy
retry_duration Unsigned integer The duration of retry attempts.
create_dir Boolean If directories are created on the destination. Default: false.
precalculate_job_size Boolean If the job size is calculated before transfer. Default: false.
delete_source Boolean If all source files, empty directories and the source argument itself are removed after they are successfully transferred. Default: false.
remove_after_transfer Boolean If the source files are removed after they are successfully transferred. Default: false
remove_empty_directories Boolean If empty directories on the source are deleted after the files within them are successfully transferred. Default: false.
multi_session Unsigned integer The number of simultaneous transfer sessions allowed.
multi_session_threshold Unsigned integer The file size above which files are split across sessions.
delete_before_transfer Boolean If any files that exist at the destination but not at the source are deleted before transfer.
preserve_access_time Boolean If file access time is preserved from the source to the destination.
preserve_modification_time Boolean If file modification time is preserved from the source to the destination.
preserve_creation_time Boolean If file creation time is preserved from the source to the destination. Only Windows systems retain information about creation time.
use_ascp4 Boolean If ascp4 is used for the transfer, instead of ascp.

Get Information About Transfers (All or Filtered)

Retrieve information about transfers to which the user has access, that were started by using the Node API, and that can be filtered and sorted as specified. To retrieve information about transfers that were started with Faspex or the Connect Server web UI, use the Reliable Query API. To retrieve bandwidth data, use /ops/transfers/bandwidth.

URL
GET https://{domain}:9092/ops/transfers

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/ops/transfers?after_time=2010-04-24T11:00:00&count=100 \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

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
Bearer Required
(for bearer token authorization)
The bearer token. Bearer token string.

Query Parameters
Parameter Type Description Value
after_time String Get transfers for which at least one event happened (sessions in progress or terminated) after the specified time. Time in ISO format.
iteration_token String Get transfers after the specified iteration token. The iteration token defines a specific time in the log; it is generated by a previous request and returned in the LINK header. The same iteration token is reported to different applications as long as they are querying the same server. Token string
count Unsigned integer Get no more than the specified number of transfers. If the number of transfers exceeds count, then the oldest count of transfer events are returned. Querying /ops/transfers/ again with the returned HTTP link header returns the next oldest set. Unsigned integer
active_only Boolean If set to true, get only running transfers. If set to false, get only transfers that are not running (waiting, completed, failed or canceled). Boolean
direction String Get only transfers that are going in the specified direction. send or receive
tag JSON Filter transfers by tag. The tags variable can be in two formats: KEY[,KEYS...] or KEY[,KEYS...]%3DVALUE, where the equals sign "=" is encoded as %3D. For example:
  • If a transfer has tags set to {"aspera": { "xfer_retry": 10 } } it can be queried with
    ?tag=aspera.xfer_retry%3D10 which returns all transfers that have a retry_timeout value of 10.
  • If a transfer has tags set to {"aspera": { "node": { "access_key": "my_access_key" } } it can be queried with
    ?tag=aspera.node.access_key which returns all transfers run with any access key. Querying with
    ?tag=aspera.node.access_key%3Dmy_access_key only returns transfers that ran with access_key=my_access_key
String
view String Apply the specified view to the transfer information returned by the request.
  • id - Show only the transfer IDs.
  • short_summary - Show an abbreviated summary and session information, but do not report file data.
  • summary - Show the full summary and session information, but do not report file data.
id, short_summary, or summary
access_key String Get transfers that are authorized by the specified access key. This option is only allowed with node user authentication. Access key string
Sample Response
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
Link: <https://localhost:9092/ops/transfers?iteration_token=2>; rel="next"
 
[
  {
    "id" : "69327c2c-b58c-4679-852d-e0d35018b434",
    "status" : "completed",
    "start_spec" : {
      "source_paths" : [
        "aaa.txt"
      ],
      "destination_path" : "/aaa.txt.ascp",
      "tags" : null,
      "cookie" : null,
      "client_token_user_id" : null,
      "server_token_user_id" : "ASPERA_NODE_ADMIN",
      "client_access_key" : null,
      "server_access_key" : "ak123",
      "client_cluster_id" : "7886f7f7-f37c-490f-8a77-58e5933d6baf",
      "server_cluster_id" : "36246c8f-f9b0-4dbd-9f3f-e868760304a1",
      "direction" : "receive",
      "endpoint" : "server",
      "remote_host" : "example.com",
      "remote_user" : "root",
      "fasp_port" : 33001,
      "ssh_port" : 22,
      "dgram_size" : 0,
      "rate_policy" : "adaptive",
      "target_rate_kbps" : 10000,
      "min_rate_kbps" : 0,
      "vlink_id" : 0,
      "cipher" : "aes-128",
      "keepalive" : false,
      "http_fallback" : false,
      "http_fallback_port" : 0,
      "proxy" : "",
      "create_dir" : false,
      "overwrite_policy" : "diff",
      "resume_policy" : "none",
      "lock_target_rate" : false,
      "lock_min_rate" : false,
      "lock_rate_policy" : false,
      "target_rate_percentage" : 0,
      "precalc_enabled" : true,
      "source_root_id" : null,
      "destination_root_id" : null,
      "filters" : [
 
      ]
    },
    "sessions" : [
      {
        "id" : "69327c2c-b58c-4679-852d-e0d35018b434",
        "client_node_id" : "1866b42d-f0a7-495a-b6de-d1b72dd5915f",
        "server_node_id" : "c4a111c2-c813-4ab7-a453-3da9168c66d4",
        "client_ip_address" : "10.0.0.2",
        "server_ip_address" : "53.112.32.53",
        "status" : "completed",
        "retry_timeout" : 0,
        "retry_count" : 0,
        "start_time_usec" : 1470689098000000,
        "end_time_usec" : 1470689233876381,
        "elapsed_usec" : 135876381,
        "bytes_transferred" : 13985536,
        "bytes_written" : 13985536,
        "bytes_lost" : 1408,
        "files_completed" : 1,
        "directories_completed" : 0,
        "target_rate_kbps" : 10000,
        "min_rate_kbps" : 0,
        "calc_rate_kbps" : 1600,
        "network_delay_usec" : 222000,
        "avg_rate_kbps" : 823.43,
        "error_code" : 0,
        "error_desc" : "",
        "precalc" : {
          "status" : "ready",
          "bytes_expected" : 20480000,
          "directories_expected" : 1,
          "files_expected" : 100,
          "files_excluded" : 0,
          "files_special" : 0,
          "files_failed" : 0 
        }
      }
    ],
    "bytes_transferred" : 13985536,
    "bytes_written" : 13985536,
    "bytes_lost" : 1408,
    "avg_rate_kbps" : 823.43,
    "files_completed" : 1,
    "directories_completed" : 0,
    "start_time_usec" : 1470689098000000,
    "end_time_usec" : 1470689233876381,
    "elapsed_usec" : 135876381,
    "error_code" : 0,
    "error_desc" : "",
    "files" : [
      {
        "id" : "2",
        "path" : "/aaa.txt.ascp",
        "start_time_usec" : 1501264303000000,
        "elapsed_usec" : 430,
        "end_time_usec" : 1501264303000430,
        "status" : "completed",
        "error_code" : 0,
        "error_desc" : "No error",
        "size" : 13985536,
        "type" : "file",
        "checksum_type" : "none",
        "checksum" : "",
        "start_byte" : 0,
        "bytes_written" : 13985536,
        "session_id" : "69327c2c-b58c-4679-852d-e0d35018b434"
      }
    ]
  }
]

Status Codes and Errors
Code Description Notes
200 OK Success
400 Bad Request Error Request has a formatting or syntax error.
404 Not Found Error Request contains an invalid transfer ID.
500 Internal Server Error Error The server configuration is invalid.

Response
Element Type Description
id String Unique id for the transfer.
status String Status of the transfer: waiting, running, completed, partially_completed, failed, canceled, or orphaned.
start_spec JSON Array containing the details of the transfer, including the transfer object.
source_paths String List of source files and directories.
destination_path String The target path.
tags JSON The tags that were specified in the transfer request or added by the application.
cookie String The cookie that was specified by the transfer request.
client_token_user_id String If the client provides a token, the username associated with the token.
server_token_user_id String If the server provides a token, the username associated with the token.
client_access_key String The access key ID of the access key that is provided by the client, if any.
server_access_key String The access key ID of the access key that is provided by the server, if any.
direction String The direction of the transfer, either send of receive.
endpoint String If the transfer direction is send, endpoint is client. If the transfer direction is receive, endpoint is server.
remote_host String IP or fully qualified domain name of the remote server.
remote_user String The transfer user on the remote node for SSH authentication.
fasp_port Unsigned integer The port that is used for data transfer.
ssh_port Unsigned integer The port that is used for the SSH connection.
dgram_size Integer The datagram size that is used for the transfer, as configured in aspera.conf on the server.
rate_policy String The transfer's rate policy.
target_rate_kbps Unsigned integer The target rate for the transfer, in Kbps.
min_rate_kbps Unsigned integer The minimum transfer rate.
vlink_id String The ID of the virtual link (bandwidth control) that is applied to the transfer.
cipher String The encryption algorithm that is used to encrypt data in transit.
keepalive Boolean If the transfer is run in persistent mode.
http_fallback Boolean If HTTP fallback is enabled on the server.
http_fallback_port Unsigned integer The HTTP fallback port.
proxy String The URL of the proxy server.
create_dir Boolean If directories are created on the destination. Default: false.
overwrite_policy String The overwrite policy.
resume_policy String The resume policy
lock_target_rate Boolean If the target transfer rate is locked by the server.
lock_min_rate Boolean If the minimum transfer rate is locked by the server.
lock_rate_policy Boolean If the rate policy is locked by the server.
target_rate_percentage Integer The target rate percentage that is set on the server.
precalc_enabled Boolean If the job size is calculated before transfer.
source_root_id String The file ID of the source root directory.
destination_root_id String The file ID of the destination root directory.
filters String List of filters that are applied to the source paths.
sessions JSON Array containing the details of the transfer session or sessions that are used to carry out the transfer.
id String The transfer id (same as the first id).
client_node_id String Client node ID.
server_node_id String Server node ID.
client_ip_address String IP address of the client.
server_ip_address String IP address of the server.
status String The status of the session: waiting, running, completed, partially_completed, failed, canceled, or orphaned. If the transfer uses one session, the session status should match the transfer status.
retry_timeout Unsigned integer The retry timeout set on the server.
retry_count Unsigned integer The number of retries for the session.
start_time_usec Unsigned integer Transfer session start time in microseconds since the server's epoch time.
end_time_usec Unsigned integer Transfer session end time in microseconds since the server's epoch time.
elapsed_usec Unsigned integer The duration of the transfer session, in microseconds.
bytes_transferred Unsigned integer The number of bytes transferred in the session.
bytes_written Unsigned integer The number of bytes written in the session.
bytes_lost Unsigned integer The number of bytes lost in the session.
files_completed Unsigned integer The number of files transferred in the session.
directories_completed Unsigned integer The number of directories transferred in the session.
target_rate_kbps Float The target transfer rate for the session.
min_rate_kbps Float The minimum transfer rate for the session.
calc_rate_kbps Float The calculated transfer rate for the session.
network_delay_usec Unsigned integer The network delay in microseconds.
avg_rate_kbps Float The average transfer rate for the session.
error_code Unsigned integer The error code for the session, if any.
error_desc String A description of the session error, if any.
precalc String JSON array that reports the details of precalculating the session, if precalculating job size is enabled.
status String The status of the precalculation job.
bytes_expected Unsigned integer The number of bytes that will be transferred by the session.
directories_expected Unsigned integer The number of directories that will be transferred by the session.
files_expected Unsigned integer The number of files that will be transferred by the session.
files_excluded Unsigned integer The number of files that will be filtered from the source paths.
files_special Unsigned integer The number of files that are not ordinary files, such as symbolic links.
files_failed Unsigned integer The number of files that could not be pre-calculated.
bytes_transferred Unsigned integer The total number of bytes transferred across all sessions.
bytes_written Unsigned integer The total number of bytes written across all sessions.
bytes_lost Unsigned integer The total number of bytes lost across all sessions.
avg_rate_kbps Float The average transfer rate across all sessions.
files_completed Unsigned integer The number of files that are transferred across all sessions.
directories_completed Unsigned integer The number of directories that are transferred across all sessions.
start_time_usec Unsigned integer The start time of the transfer sessions, relative to the server's epoch.
end_time_usec Unsigned integer The time when all transfer sessions complete, relative to the server's epoch.
elapsed_usec Unsigned integer The total microseconds for all transfer sessions to complete.
error_code String The error code for any transfer session.
error_description String The error description for any transfer session.
files JSON Array of information about each file in the transfer.
id String The file ID.
path String The pathname of the file.
start_time_usec Unsigned integer The time the file began transferring, in microseconds since the server's epoch.
elapsed_usec Unsigned integer The transfer time for the file, in microseconds.
status String The transfer status for the file.
error_code Integer The error code for the file transfer.
error_description String A description of the file transfer error. If no error, "No error".
size Unsigned integer The size of the file, in bytes.
type String The type of file, either file or link (for symbolic links).
checksum_type String The type of checksum that is calculated for the file by the sender.
checksum String The checksum that is calculated for the file by the sender.
start_byte Unsigned integer The first byte of the file that is transferred.
bytes_written Unsigned integer The number of bytes written for the file.
session_id String The ID of the session in which the file was transferred.

Get Information About a Specific Transfer

Retrieve information about a specific transfer to which the user has access and that was started by using the Node API.

GET https://{domain}:9092/ops/transfers/{id}

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/ops/transfers/69327c2c-b58c-4679-852d-e0d35018b434 \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

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
Bearer Required
(for bearer token authorization)
The bearer token. Bearer token string.

Response

The response body and error codes are the same as for getting information about all files, except that only information for the specific transfer is returned.

Monitoring Transfer Status and Retry Progress with GET

The Aspera Node daemon reports the state of transfers, which can be used for monitoring transfer progress and retry attempts.

Transfer states:

  • waiting
  • running
  • completed
  • partially_completed
  • failed
  • canceled
  • orphaned

Retry policy:

If a transfer fails for any reason other than authentication failure, asperanoded—the Aspera node daemon—restarts it based on the retry policy. In the case of multi-session transfers, in which one transfer runs multiple ascp sessions, if any individual session fails, asperanoded restarts it based on the retry policy.

If no progress is made for the retry duration, asperanoded reports the transfer as "failed". This can occur, for example, if the client cannot connect to the server, or the server is unable to write to storage. The back-off intervals between retry attempts are internal to the implementation, such that the last retry might come shortly after the specified retry duration, depending on the current queued transfers.

By default, the server is configured with a retry duration of 20 minutes (set as the value for transfers_retry_duration in aspera.conf) and to retry only those failures that are recoverable, such as failures due to network connectivity. To enable retrying all failures, set transfers_retry_all_failures to true in aspera.conf.

Transfers started or modified with /ops/transfers can specify a 'retry_duration' that overrides the server configuration.

Monitoring Retries:

Use the following process to monitor transfer status and retry progress:

  1. A pending transfer reports a status of "waiting". Send GET requests to /ops/transfers on a loop until the status changes from "waiting" to another status, such as "failed"or "running". A "failed" transfer can still be active if it is within the retry timeout.
  2. Once the transfer is no longer "waiting", send a GET request to /ops/transfers?active_only=true. This returns transfers that are transferring or that are being retried. For more information about retriable transfer errors, see Aspera error codes.

    You can use the query parameter "active_only=true" to your preliminary requests (in step 1) if that is more convenient; however, this returns an empty result until the transfer starts.

    When all retry attempts complete, the "active_only=true" request returns zero (empty) results, indicating that the transfer is no longer active.

  3. To determine the final state of the transfer ("completed", "canceled", or "failed" with a non-retriable error), send a final GET request to /ops/transfers without the "active_only=true" parameter. If you do not omit the parameter, you will get another empty result, since the transfer is no longer active.

Get Bandwidth Usage (Transfer Rate) Data for All Transfers

Retrieve time series data on transfer rates for all transfers to which the user has access.

URL
GET https://{domain}:9092/ops/transfers/bandwidth

Sample Request
curl -i -u user:secret -X GET https://{domain}:9092/endpoint?query1=value&query2=value \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Query Parameters
Parameter Type Description Value
duration Integer Get bandwidth data for the specified number of seconds at the start of each transfer. Number of seconds. Default: 600. Maximum: 3600.
start_time String Get bandwidth data for transfers after the specified time. Time in ISO format.
Sample Response
{
      "current_time":"2015-11-27T15:54:20Z",
      "start_time":"2015-11-27T15:44:20Z",
      "end_time":"2015-11-27T15:54:20Z",
      "send":{
         "transfers":[
            {
            "id": "2359f4ij-23lr23r894-23ronfel",
            "data":[
               {"time":1.00, "rate":1.23},
               ...
               {"time":600.00, "rate":3.49}
            ],
            "last_time":"2015-11-27T15:54:20Z",
            "max_rate":3.49
            },
            "id": "94tmglirs4-23490thjgfi-238nfsefi",
            "data":[
               {"time":1.00, "rate":1.23},
               ...
               {"time":600.00, "rate":3.49}
            ],
            "last_time":"2015-11-27T15:54:20Z",
            "max_rate":3.02
            }
         ],
         "max_left":1.00,
         "min_right":600.00
      },
      "receive":{
         "transfers":[
         ]
         "max_left":0.00
         "min_right":0.00
      }
}

Response
Element Type Description
current_time String Current time in ISO format.
start_time String The time that bandwidth data starts, in ISO format.
end_time String The time that bandwidth data ends, in ISO format.
send JSON An array containing bandwidth data for any "send" transfers.
transfers JSON An array containing the transfers and their bandwidth data.
id String The transfer ID.
data JSON An array of bandwidth time series data.
time Double The number of seconds since the start time.
rate Double The transfer rate, in Kbps.
last_time String The actual time for the last bandwidth data point, in ISO format.
max_rate Double The maximum transfer rate during the reported duration, in Kbps.
max_left Double The first value that is reported for time for the specific transfer session.
min_right Double The last value that is reported for time for the specific transfer session.
receive JSON An array containing bandwidth data for any "receive" transfers. Contents are the same as for the send array.

Modify a Transfer

Modify the transfer specification of an active transfer, specified by transfer ID, by submitting a partial or complete request body that contains the values.

URL
PUT https://{domain}:9092/ops/transfers/{id}

Sample Request
curl -i -u user:secret -X PUT https://{domain}:9092/endpoint/{id} \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"status":"paused","target_rate_kbps":0,"min_rate_kbps":0,"rate_policy":"fair"}'

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
Bearer Required
(for bearer token authorization)
The bearer token. Bearer token string.

Request Body
Element Required Type Description
status Optional String The new value for the status. To cancel a transfer, set to "canceled", "cancelled", or "stopped". To pause a transfer, set to "paused". To resume a paused transfer, set to "running" or "resume".
target_rate_kbps Optional Unsigned integer The new target transfer rate, in Kbps.
min_rate_kbps Optional Unsigned integer The new minimum transfer rate, in Kbps.
rate_policy Optional String The new rate policy to apply to the transfer. Allowed values: "fixed", "fair", or "low".
Sample Response

The response is the same as for a POST request and returns the updated values.


Status Codes and Errors
Code Description Notes
200 OK Success
400 Bad Request Error Request has a formatting or syntax error.
404 Not Found Error Request contains an invalid transfer ID.
500 Internal Server Error Error The server configuration is invalid.
503 Service Unavailable Error The access key is locked for backup.

Cancel a Transfer

Cancel a transfer. The user must have access to the transfer and the transfer must be started by a Node API request. This is a shortcut to a PUT /ops/transfers/{id} request that has { "status" : "canceled" } as the request payload.

URL
CANCEL https://{domain}:9092/ops/transfers/{id}

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

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
Bearer Required
(for bearer token authorization)
The bearer token. Bearer token string.

Sample Responses

Success:

HTTP/1.1 204 No Content
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
Content-Length: 0

Error:

{
   "error":{
      "code":404,
      "reason":"Not Found",
      "user_message":"Transfer not found")
   }
}

Status Codes and Errors
Code Description Notes
204 No Content Success Transfer successfully canceled.
400 Bad Request Error Request has a formatting or syntax error.
404 Not Found Error Request contains an invalid transfer ID.
500 Internal Server Error Error The server configuration is invalid.
503 Service Unavailable Error The access key is locked for backup.

Response
The response body contains no content if the request is successful.
Element Type Description
error JSON object Error response.
code Double HTTP error code.
reason String HTTP error message.
user_message String Error description.
Video player

Video

×