File transfers to and from an Aspera Node are always executed in the context of the session.  A session can contain one or multiple file transfers.  This section will go over information like lifecycle, states, filters, iterations and other attributes of this Web Service.

Session & File Transfer Lifecycle

Events associated with a session usually include:

  • Session Start - A transfer session starts.
  • File Transfer Start - A file transfer starts transferring within the session.
  • File Transfer Stop - A file transfer stops, either completing successfully or failing.
  • Session Stop - A transfer session completes successfully or fails.

Multiple file transfer events can occur during the lifecycle of a session.  Each event will be recorded in Central's data cache and can be queried through the API.  Progress information is also logged and can be retrieved through the various API calls available.


A session can have the following states, these states are returned with any query and you can also filter via the state.

  • Running - The session is in progress.
  • Paused - The session was paused (e.g. by setting the target bandwidth to 0).
  • Completed - The session has completed successfully.
  • Cancelled - The session was aborted.
  • Error - The session stopped due to an error.
  • Willretry - The session has failed and will retry automatically after its retry period has elapsed (see Retries below).
  • Orphaned - The session has terminated at a time when Aspera Central was not running, and therefore so no exact final session information is available.

A transfer can have the following states

  • Running - The file transfer is in progress.
  • Completed - The file transfer has completed successfully.
  • Error - The file transfer stopped due to an error.


Filters allow you to select the desired information and restrict the number of results that will be returned.  When using filters, the following rules apply:

  • Empty (not set) filter criteria mean "ALL"
  • If a filter criterion is defined as an array of values, the individual values are combined in a logical OR expression.  For example, SessionFilter(Ids={1,5,6}) accepts sessions with ID 1 or 5 or 6.
  • If multiple filter criteria are defined, they are combined in a logical AND expression. For example, SessionFilter(Status={completed}, Initiators={}, MaxResults=20) accepts only completed sessions that were initiated by the computer with IP address "" and returns the first 20 sessions. See also Paged Queries below.
  • Combinations of array-based criteria are evaluated as follows: (criteria1.value1 OR criteria1.value2) AND (criteria2.value1 OR ...) AND ... For example, SessionFilter(Status={completed, failed}, Initiators={}) is evaluated as: (Status is completed OR Status is failed) AND (Initiator is

Query Results Order

The results of an API query are always ordered by last modification date with the newest first.  The API queries can return information on both ongoing and completed sessions or transfers.  Completed items are returned first in the list of results followed by ongoing sessions ordered by their ID number.


Aspera Central stores all events in the order they occur. The web-services interface provides an "event" (or "change") iterator. An application can query for a session or file transfer events, and each response will return an iteration token that can be thought of as the maximum "last modification date" of the items in the result set. Since results are always ordered by increasing last modification date, querying again using the same filters and the iteration token from the previous query, will return the next set of results with a larger modification date. The iterator ensures that an application can reliable get all events regardless of how many it reads at runtime or how many events are being generated by the ongoing transfers. The iteration token is a fixed-size String of 48 alphanumeric characters.

Paged Queries

Query results are always ordered by last modification date.  Since the ordering is done before applying the filters you will want to apply a MaxResults filter that can be used in conjunction with the iteration token to find the results you are looking for. For example:

  • GetSessions(MaxResults=100)
    • returns session 1-100 and an IterationToken1.
  • GetSessions(MaxResults=100, IterationToken1)
    • returns sessions 101-200, IterationToken2
  • GetSessions(MaxResults=100, IterationToken2)
    • returns sessions 201-235, IterationToken3 (assuming that there are no more than 235 sessions)
  • GetSessions(MaxResults=100, IterationToken3)
    • returns an empty list, IterationToken3 (same as in previous call)

Change Queries

Another situation where the iteration token is useful is when an application wants to query Aspera Central periodically in order to retrieve "all changes" since the last API call. This mechanism can easily be combined with paging to quickly retrieve the last X number of changes since the last call.

Paged queries cannot be used to retrieve a large number of ongoing sessions or transfers in a batch since ongoing sessions or transfers are associated with the same last modification date and therefore subsequent queries will return the same result, unless the item has completed.


The special iteration token "CURRENT_POSITION" can be used to retrieve information that has the last modification date of "NOW", this allows you to view only changes that are new and ignore the existing history.  The "CURRENT_POSITION" token will never return a completed session or transfer, only ongoing items.


Transfers submitted can contain a retry policy that will allow Central to retry the failed transfer based on the conditions (count, BaseInerval and MaximumInterval).  If an item is a retry, than it will contain additional fields relating to the retry status in any queries. When a job is submitted and fails, it will retry and receive the state "willretry". It will attempt to retry the job until the policy states otherwise (for example it reaches the max number of retries).  Since Aspera Server version 3.3 after it fails to complete it will receive the status "error", prior to version 3.3 the status would remain "willretry" and the developer would need to use sessionInfo to compare the values JobRetryCount and JobMaxRetries.

Video player