Task Management

DATA_TYPE

string

Always has value "task" to indicate this document type.

task_id

string

Globally unique uuid for this task.

type

string

The type of task - either "TRANSFER" or "DELETE".

status

string

fatal_error

object

For tasks with "FAILED" status, this is an object with code and description strings from the fatal event. Otherwise, this is null. Note: This field is valid only for tasks submitted after July 1, 2017.

label

string

User defined label to make finding tasks simpler.

username

string

[DEPRECATED] Use owner_id instead. The globus username of the user who created the task. For non-globusid.org identities, this will be a meaningless string starting with 'u_', and for globusid.org identities it will be the globusid.org username.

owner_id

string

Identity id of the task owner. If the task was submitted with multiple linked identities, the owner will be the primary identity.

request_time

string

The date and time the task was created, in ISO 8601 format.

completion_time

string

The date and time the task was completed or failed, in ISO 8601 format. If the task is still in progress (status "ACTIVE" or "INACTIVE"), this will be null.

deadline

string

If set when the task is created, cancel the task if it’s not finished when this date and time is reached. By default transfer tasks will not be canceled as long as they are making progress. Delete tasks default to 24 hours after task submission.

source_endpoint^[1]

string

[DEPRECATED] Use source_endpoint_id instead.

source_endpoint_id^[1]

string

id of the source collection.

source_endpoint_display_name^[1]

string

display_name of the source collection at time of submit, or the canonical_name if display_name is not set.

destination_endpoint^[1]

string

[DEPRECATED] Use destination_endpoint_id instead.

destination_endpoint_id^[1]

string

id of the destination collection if any (null for "DELETE" tasks).

destination_endpoint_display_name^[1]

string

Like source_endpoint_display_name but for the destination, or null for "DELETE" tasks.

sync_level

integer

The sync level used for the transfer, or null if not used. Always null for delete tasks.

encrypt_data

boolean

For transfer tasks, this will be true if the data channel is encrypted. This can happen in two ways: if one of the collections or involved in the transfer has force_encryption set to true, or if the transfer request has the encrypt_data option set to true. Always false for delete tasks.

verify_checksum

boolean

The verify_checksum option used for the transfer. Always false for delete tasks.

delete_destination_extra

boolean

The delete_destination_extra option used for the transfer. Always false for delete tasks.

recursive_symlinks

string

The recursive_symlinks option used for transfer tasks. Always null for delete tasks.

preserve_timestamp

boolean

The preserve_timestamp option used for the transfer. Always false for delete tasks.

skip_source_errors

boolean

The skip_source_errors option used for the transfer. Always false for delete tasks.

fail_on_quota_errors

boolean

The fail_on_quota_errors option used for the transfer. Always false for delete tasks.

command

string

If the task was submitted via the CLI, this field will contain the original command line, including options, that created the task. If submitted via the Globus Web App or directly via the Transfer API, this will contain the string "API", followed by the API version, and optionally followed by a short string representing the client that submitted the request. The format of this field is subject to change and should not be relied upon.

history_deleted

boolean

This flag will be set for tasks older than one month, and indicates that details of the task are no longer available. In particular, subtasks and successful transfers will not be available for the task if this is true, so clients should always check this before querying for subtasks and successful transfers.

faults

int

The number of errors this task encountered. Note that certain types of faults are not fatal (for example, network communication errors) and can be successfully retried. A CANCELED or EXPIRED event is not included in this fault count.

files

int

The total number of files in a transfer task. This can grow as the task recursively scans directories.

directories

int

The total number of directories in a transfer task. This can grow as the task recursively scans directories.

symlinks

int

The total number of kept symlinks (not copied or ignored) in a transfer task. This can grow as the task recursively scans directories.

files_skipped

int

The number of files skipped because no changes were detected. This will always be zero for non-sync transfer tasks (with null sync_level) and for all delete tasks.

files_transferred

int

The number of files actually transferred over the network. For a successful transfer, files = files_skipped + files_transferred. Not used for delete tasks.

subtasks_total

int

Total number of subtasks. This includes file transfer or delete subtasks and helper subtasks such as directory expansion, so is not a reliable measure of the number of files being transferred. It can also grow over time as new files and directories are discovered in directory expansions.

subtasks_pending

int

Number of subtasks which are still in progress.

subtasks_retrying

int

This field is deprecated, and may be 0 or removed in a future release.

subtasks_succeeded

int

Number of subtasks which have completed successfully.

subtasks_expired

int

Number of subtasks which expired and were not completed.

subtasks_canceled

int

Number of subtasks which were canceled.

subtasks_failed

int

Number of subtasks which failed for reasons other than expiring or being cancelled.

subtasks_skipped_errors

int

Number of subtasks that were skipped due to skip_source_errors being set on the task. This will equal the total number of discovered files and directories skipped from the source collection. Note that if a directory is skipped then the files and directories under it will not be discovered and not included in this count.

bytes_transferred

int

The total number of bytes transferred summed across all subtasks.

bytes_checksummed

int

If sync level 3 is used, the number of bytes checksummed while determining which files need to be transferred.

effective_bytes_per_second

int

A simplistic calculation of bytes/second based on the start time of the task and its completion time, if applicable, or the current time. Valid for transfer tasks. Always 0 for other task types.

nice_status

string

For tasks with status ACTIVE or INACTIVE, a string indicating a more detailed status of the task. For completed tasks, this will always be empty or null. If it has value OK or Queued, the task is waiting for other tasks to complete or proceeding normally, and no intervention should be required. All other values indicate that some error is being encountered, which may or may not resolve on it’s own. Examples: Creds Expired, PERMISSION_DENIED, ENDPOINT_ERROR, CONNECT_FAILED, PAUSED_BY_ADMIN.

nice_status_details

string

DEPRECATED This field is always null. Use the task event_list instead.

nice_status_short_description

string

3-4 word description of nice_status code

nice_status_expires_in

string

Seconds until any credential required for the task expires (-1=never, 0=expired)

canceled_by_admin

string

canceled_by_admin_message

string

For tasks with canceled_by_admin set to a non-null value, this will contain a message from the activity manager who canceled the task.

is_paused

boolean

"true" if the task is in progress (status "ACTIVE" or "INACTIVE") and has been paused by the activity manager of the source or destination collection, "false" if the task has not been paused or is complete (status "SUCCEEDED" or "FAILED"). Use Get task pause info to get information about why the task is paused.

filter_rules

list

List of filter_rules applied on this task during recursive expansion. Can be null. See task submit for details.

source_local_user

string

The value of the source_local_user option used in Identity Mapping if given at task submission, otherwise this field will be null.

source_local_user_status

string

If source_local_user is provided at task submission, displays a status code indicating if the local user is available for the source collection, or the reason it’s not available. See Advanced Collection Management for details.

destination_local_user

string

Like source_local_user, but for the destination collection. Always null for delete tasks, which don’t have a destination.

destination_local_user_status

string

Like source_local_user_status, but for destination collections.

source_base_path

string

If store_base_path_info was set to true when task was submitted, the parent directory of the source_path (transfer) or path (delete) field for the first item listed in the task. Is null otherwise.

destination_base_path

string

If store_base_path_info was set to true when a transfer task was submitted, the parent directory of the destination_path field for the first item listed in the task. Is null otherwise.

DATA_TYPE

string

Always has value "event" to indicate this document type.

code

string

A code indicating the type of the event.

is_error

boolean

true if event is an error event

description

string

A description of the event.

details

string

Type specific details about the event.

time

string

The date and time the event occurred, in ISO 8601 format (YYYY-MM-DD HH:MM:SS) and UTC.

endpoint_id^[1]

string list

Comma separated list of UUID strings. Return only tasks run against the specified collection ids. Only returns tasks owned by the current user.

task_id

string list

Comma separated list of UUID strings. Return tasks matching the specified task ids. Only returns tasks owned by the current user.

type

string list

Comma separated list of type names (TRANSFER, DELETE). Return only tasks of the specified type(s). The default is all tasks.

status

string list

Comma separated list of status codes (ACTIVE, INACTIVE, FAILED, SUCCEEDED). Return only tasks with one of the specified statuses.

label

pattern list

Comma separated list of patterns to match against the label field. Returns tasks that match any of the patterns. Each pattern is an operator, followed by a string. The operator is one of !, =, ~, or !~. The = operator requires an exact match, and ! matches anything other than the specified string. The ~ operator is a case-insensitive match and allows the use of as a wildcard. The !~ operator matches anything that does not match the pattern. As a shortcut, if no operator is specified, = (exact match) is assumed.

Backslashes are used to escape ambiguous literal characters in the label filter. / is escaped as \/, , is escaped as \,, \ is escaped as \\, and when using either the ~ or !~ operators is escaped as *. For example, filter=label:~\/\** would match tasks with labels beginning with the literal string "/*".

request_time

datetime range

Accepts a time range, specified by a comma separated list of two ISO 8601 date/time strings. If one of the dates is omitted, it forms an open range, so "dt," returns all records with date greater or equal to dt, and ",dt" returns all records with dates less than or equal to dt. If there is no comma, it is treated in the same way as "dt,". If the time is omitted from a date/time, it’s assumed to be 00:00.

completion_time

datetime range

Like the request time filter, but for the completion time.

PermissionDenied

403

Task is not eligible for removal, for example if it does not involve a HA collection.

TaskNotFound

404

Task does not exist, or has already been removed

Conflict

409

Task is still active (paused or running). Canceling the task will resolve this.

is_error

boolean

"1" for true, "0" for false. If true, return only events that are classified as errors. If false, return only events that are classified as non-error (informational). By default, returns all events.

HistoryDeleted

409

After 30 days, the event list for a task is no longer available and this error will be returned.

DATA_TYPE

string

Always has value "successful_transfer" to indicate this document type.

source_path

string

The path to the file on the source.

destination_path

string

The path to the file on the destination.

checksum

string

The file checksum, if one was used to verify the result of the transfer.

checksum_algorithm

string

The checksum algorithm, if one was used to verify the result of the transfer.

size

int

The size (bytes) of the file that was transferred.

DATA_TYPE

string

Always has value "skipped_error" to indicate this document type.

error_code

string

The code of the skipped error. Either PERMISSION_DENIED or FILE_NOT_FOUND.

error_details

string

Additional information from the collection about the skipped error.

source_path

The path on the source collection that hit the error.

destination_path

string

The path on the destination collection the item would have been transferred to.

is_directory

boolean

True if the source_path is for a directory.

is_symlink

boolean

True if the source_path is for a symlink.

is_delete_destination_extra

boolean

True if the delete destination extra stage of a task was skipped for this path. Note that delete destination extra is a separate task stage. This error indicates a problem traversing the source directory path and that the checks required to compare source and destination were incomplete. Partial work including deletions may have occurred. Some transfers may have also occurred for files beneath this path.

external_checksum

string

The external_checksum submitted with the item.

checksum_algorithm

string

The checksum_algorithm submitted with the item.