Advanced Endpoint Management

1. Overview

The advanced endpoint management API is available to Globus subscribers. This API allows site administrators to manage the transfers to and from their endpoints, to aid in proactive debugging of user transfers. All operations listed below require the user to have either the "activity_manager" or "activity_monitor" roles on on an endpoint, and the endpoint must be marked as Managed and associated with a provider subscription. In particular, for TRANSFER tasks the user must have either of the roles on either the source or destination endpoint to view the task and the manager role to cancel or pause the task. Note that the "activity_manager" role includes all privileges of the "activity_monitor" role. See the Endpoint Role API for how to assign "activity_manager" and "activity_monitor" roles to identities or groups.

All resources in this part of the API are prefixed with /endpoint_manager. This prefix is used to denote that the operation will be run with elevated privileges.

If the user does not have any "activity_manager" or "activity_monitor" roles, PermissionDenied will be returned by all resources under /endpoint_manager.

Note:This API is alpha and is likely to change between releases without a change to the API version.

1.1. Shared Endpoints and Manager Privileges

A user can have the "activity_manager" or "activity_monitor" roles on a shared endpoint or a host endpoint. Having one of these two roles on a host endpoint implicitly gives the corresponding role on all hosted shared endpoints.

Note:If the user has multiple roles on an endpoint (including explicit roles and roles inherited from a host endpoint), the highest privilege role will be used.

With few exceptions, a user with the "activity_manager" role on a shared endpoint can not override a configuration change made by user with the "activity_manager" role on the host endpoint. Activity managers on host and shared endpoints have the following rules:

A user with the "activity_manager" role on a host endpoint can create a pause rule on the host endpoint, which also affects all its shared endpoints. The pause rule will not be in the puase rule list of a user with the "activity_manager" role on a shared endpoint.
A user with the "activity_manager" role on a host endpoint can also create a pause rule on a specific shared endpoint. In that case, the rule will be in the pause rule list of users with the "activity_manager" role on the shared endpoint, but they cannot edit or delete the rule.
A user with the "activity_manager" role on a shared endpoint can create a rule on the shared endpoint. A rule that was created by such a user can be updated or deleted by users with the "activity_manager" role on either the shared endpoint or its host.
Users with the "activity_manager" role on a shared endpoint or its host endpoint can pause a task (per-task pause). The pause state is tracked separately depending on whether the user who initiated the pause had the "activity_manager" role on the host endpoint or only on the shared endpoint. A user with the "activity_manager" role on the host endpoint can resume a per-task pause set by either type of user. However, a user with the "activity_manager" role only on the shared endpoint cannot resume a per-task pause set by a user with the "activity_manager" role on the host endpoint.
A task to or from a shared endpoint can be canceled by a user with the "activity_manager" role on either the shared endpoint or the host endpoint.

For more details, see the individual operation documentation below.

2. Document Types

2.1. Task Document

The task document includes all fields from the user facing task resources (see the Task Documentation), with the following additions:

2.1.1. Extra Fields

Also includes descriptions for fields that behave differently from their counterpart in the single user document returned by /task_list, notably source endpoint and destination endpoint fields which have different visibility rules.

Field Name	JSON Type	Description
source_endpoint	string	[DEPRECATED] Use `source_endpdoint_id` instead. Canonical name of the source endpoint. Same visibility rules as `source_endpoint_id`.
source_endpoint_id	string	Id of the source endpoint. Visible if the endpoint is public or if the user has the "administrator" or "activity_monitor" role on the endpoint, otherwise it will be null.
source_endpoint_display_name	string	Display name of the source endpoint, same visibility rules as `source_endpoint_id`.
destination_endpoint	string	[DEPRECATED] Use `destination_endpoint_id` instead. Canonical name of the destination endpoint for tasks of type `TRANSFER`, null for tasks of type `DELETE`. Same visibility rules as `destination_endpoint_id`.
destination_endpoint_id	string	Id of the destination endpoint. Visible if the endpoint is public or if the user has the "administrator" or "activity_monitor" role on the endpoint, otherwise it will be null.
destination_endpoint_display_name	string	Display name of the destination endpoint, same visibility rules as `destination_endpoint_id`.
source_host_endpoint	string	[DEPRECATED] Use `source_host_endpoint_id` instead. Canonical name of the endpoint hosting the source_endpoint if the source endpoint is a shared endpoint. Same visibility rules as `source_host_endpoint_id`.
source_host_endpoint_id	string	Id of the endpoint hosting the source endpoint if the source endpoint is a shared endpoint. Visible if the host endpoint is public, or if the user has the "administrator" or "activity_monitor" effective role on the source host endpoint; otherwise it will be null. Will also be null if the source endpoint is not a shared endpoint.
source_host_endpoint_display_name	string	Display name of the endpoint hosting the source endpoint if the source endpoint is a shared endpoint. Same visibility rules as `source_host_endpoint_id`.
destination_host_endpoint	string	[DEPRECATED] Use `destination_host_endpoint_id` instead. Canonical name of the endpoint hosting the destination endpoint if the destination endpoint is a shared endpoint. Same visibility rules as `destination_host_endpoint_id`.
destination_host_endpoint_id	string	Id of the endpoint hosting the destination endpoint if the destination endpoint is a shared endpoint. Same visibility rules as for `source_host_endpoint_id`, but requires an effective role on the destination endpoint and destination host endpoint instead of source endpoints. Will also be null for delete tasks.
destination_host_endpoint_display_name	string	Display name of the endpoint hosting the destination endpoint if the destination endpoint is a shared endpoint. Same visibility rules as `destination_host_endpoint_id`.
source_host_path	string	If the source endpoint is a shared endpoint, the path the share is located on at the host endpoint. Visible if the user has the "administrator" effective role on the source endpoint, or if the user has the "activity_monitor" effective role on the source host endpoint; otherwise it will be null. Will also be null if the source endpoint is not a shared endpoint.
destination_host_path	string	If the source endpoint is a shared endpoint, the path the share is located on at the host endpoint. Same visibility rules as `source_host_path`, but based on having an appropriate effective role on the destination endpoint or destination host endpoint instead of the source endpoints. Will also be null for delete tasks.
is_ok	boolean	For active tasks, this will be True if `nice_status` is either `OK` or `Queued`. Always null for completed tasks, which do not have `nice_status`.
source_local_user	string	The name of the local user that the activation credential mapped to on the source endpoint at the time the task was started. This will always be "null" for S3 endpoints, and will be "null" initially for all tasks until the information can be acquired. For Globus Connect Personal endpoint, this will be the local user that the application was run as during setup. For shared endpoints, this will be the local user that was used when creating the shared endpoint. This will also be "null" on older jobs, that were started before this feature was added, and if the GridFTP server of the endpoint does not support the `SITE WHOAMI` command. For shared endpoints, this field will be "null" unless the user has the "activity_monitor" effective role on the source host endpoint. For all other endpoint types, this will be "null" unless the user has the "activity_monitor" effective role on the endpoint itself.
source_local_user_status	string	A status code indicating if the local user is available for the source endpoint, or the reason it’s not available. It can have any of the following values, and new values may be added in the future: "OK" The local user is set. "NO_PERMISSION" The user does not have the "activity_manager" or "activity_monitor" role on the endpoint (or for shared endpoints, the user does not have one of the two roles on the host endpoint). "NOT_SCANNED" For active tasks, this indicates that the asynchronous process that fetches the local user has not completed. For complete tasks, this indicates that the task completed before this feature was added or cancelled before the local user could be fetched. "S3_UNSUPPORTED" The endpoint is an S3 endpoint, and does not support the local user feature. "ENDPOINT_ERROR" An error occurred while contacting the endpoint to determine the local user. The most likely cause is an older GridFTP server that does not support the `SITE WHOAMI` command.
destination_local_user	string	Like `source_local_user` but for the destination endpoint. Always "null" for delete tasks, which don’t have a destination.
destination_local_user_status	string	Like `source_local_user_status`, but for the destination endpoint. In addition to the status codes described above, it can have the value "NO_ENDPOINT" for delete tasks.
owner_string	string	The Globus Auth identity username corresponding to the primary task owner (with id `owner_id`). This is provided as a convenience to clients, as something that can be displayed to end users (without having to call the Globus Auth API to get the identity details using `owner_id`).

2.2. Admin cancel document

The admin cancel document is used to request and track cancellation of one or more tasks by id.

Admin cancel document example

{
  "DATA_TYPE": "admin_cancel",
  "id": 985,
  "message": "Disk failure on GridFTP server",
  "task_id_list": ["041751b8-d6e3-4452-82a7-aa98200f4557",
                   "b30c7cb0-946e-4397-aaa4-a541a2c3ee77"],
  "done": false
}

2.2.1. Admin cancel fields

Field Name	JSON Type	Description
DATA_TYPE	string	Always has value "admin_cancel" to indicate this document type.
message	string	Message to users as to why the tasks are being canceled. This will be included in the email notification sent to the owners of each canceled task. This field is required and must be non-empty, with a maximum of 256 characters. Unicode is supported. Not included in create response or later GET responses.
id	string	Unique id of this bulk cancel request. This should not be set in create requests, and will be generated by the system and set in the create response.
done	boolean	"true" when all tasks in the list have been canceled or finished on their own, "false" otherwise. Returned in the create response and the status request, not used on in the create request body.
task_id_list	string list	List of task ids, maximum 1000. Not included in the create response or later GET responses to save bandwidth on large cancel requests. Note that the limit of 1000 is larger than the limit on the `filter_task_id` parameter on `task_list`.

2.3. Admin pause document

The admin pause document is used to request pause for one or more tasks by id. This is tracked separately from pause rules.

Admin pause document example

{
  "DATA_TYPE": "admin_pause",
  "message": "Scratch is getting full",
  "task_id_list": ["041751b8-d6e3-4452-82a7-aa98200f4557",
                   "b30c7cb0-946e-4397-aaa4-a541a2c3ee77"],
}

2.3.1. Admin pause fields

Field Name	JSON Type	Description
DATA_TYPE	string	Always has value "admin_pause" to indicate this document type.
message	string	Message to users as to why the tasks are being canceled. This will be included in the email notification sent to the owners of each canceled task. This field is required and must be non-empty, with a maximum of 256 characters. Unicode is supported.
task_id_list	string list	List of task ids, maximum 1000. Not included in the create response or later GET responses to save bandwidth on large pause requests.

2.4. Admin resume document

The admin resume document is used to request resume of one or more tasks by id.

Admin resume document example

{
  "DATA_TYPE": "admin_resume",
  "task_id_list": ["041751b8-d6e3-4452-82a7-aa98200f4557",
                   "b30c7cb0-946e-4397-aaa4-a541a2c3ee77"],
}

2.4.1. Admin resume fields

Field Name	JSON Type	Description
DATA_TYPE	string	Always has value "admin_resume" to indicate this document type.
task_id_list	string list	List of task ids, maximum 1000. Note that the limit of 1000 is larger than the limit on the `filter_task_id` parameter on `task_list`.

2.5. Pause rule document

The pause rule document represents a rule that causes tasks and certain operation to be paused.

Uniqueness

Pause rule uniqueness is enforced on (endpoint_id, identity_id, created_by_host_manager). For shared endpoints, this means that for each pair of (endpoint_id, identity_id), there can be one pause rule created by a user with the "activity_manager" role on the host endpoint, and one created by a user with the "activity_manager" role on the shared endpoint. For other endpoint types, there can only be one such rule. Rules on the entire endpoint, i.e. with a null identity_id, are treated as a special value of identity_id regarding uniqueness, so there can be only one endpoint wide rule (or two on shared endpoints).

Pause rule document example

{
  "DATA_TYPE": "pause_rule",
  "id": 985,
  "message": "Quota exceeded, please delete data from /scratch",
  "endpoint_id": "339abc22-aab3-4b45-bb56-8d40535bfd80",
  "endpoint_display_name": "Globus Tutorial Endpoint 1",
  "identity_id": "bbe7b12b-d397-41e3-8895-3b56518302ef",
  "start_time": null,
  "modified_by_id": "4c77dd76-aa99-4490-af19-dc81a312c3a1",
  "modified_time": "2015-05-04 16:32:39+00:00"
  "created_by_host_manager": true,
  "editable": true,
  "pause_ls": false,
  "pause_mkdir": true,
  "pause_symlink": true,
  "pause_rename": true,
  "pause_task_delete": true,
  "pause_task_transfer_write": true,
  "pause_task_transfer_read": false,
}

2.5.1. Pause rule fields

Field Name	JSON Type	Description
DATA_TYPE	string	Always has value "pause_rule" to indicate this document type.
id	string	Unique id of this pause rule. This should not be set in create requests, and will be generated by the system and set in the create response.
message	string	Message to users as to why the tasks are being paused. This will be included in the email notification sent to the owners of each canceled task. This field is required and must be non-empty, with a maximum of 256 characters. Unicode is supported.
start_time	ISO 8601 datetime string, null, or "now"	If null (the default value), pause existing tasks and all future tasks. If specified, only pause tasks created at or after the specified time. If the special string "now", exact case, is specified, uses the current time on the server at the time the request is received.
endpoint_id	string	Id of the endpoint to pause new tasks on. Required (for backward compatibility, `endpoint` can be specified instead, but all code should be updated to use `endpoint_id`).
endpoint_display_name	string	Display name of the endpoint. This is an output only field, for convenience when displaying pause rules. Note that it may be null if the display name has not been set for the endpoint. In that case, consider using the endpoint’s canonical name in the `endpoint` field for display.
endpoint	string	[DEPRECATED] Use `endpoint_id` instead. Canonical name of the endpoint to pause new tasks on.
user	string	[DEPRECATED] Use `identity_id` isntead. Username of a user to pause tasks for on the endpoint. If `identity_id` is set to an identity that has never been used in the Transfer service, then this will be null. This will also be null for rules that apply to all users on an endpoint, in which case `identity_id` will also be null.
identity_id	string	Identity id of an identity to pause tasks for on the endpoint, or null to indicate all identities on the endpoint. This will affect tasks with a matching `owner_id` or with a match in the set of linked identities at the time the task was submitted.
modified_time	ISO 8601 datetime string	Time the rule was created or last updated. This is set by the server on create and update and can’t be modified by clients.
modified_by	string	[DEPRECATED] Username of the user who last updated or created the pause rule. Note that this field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations. Use `modified_by_id` instead. If the modified by identity id is not a globus-id.org identity, this will be the same as the `modified_by_id`.
modified_by_id	string	Identity id of the identity that last updated or created the pause rule. If the endpoint in the rule is a shared endpoint, the user has the "activity_monitor" effective role on the shared endpoint and not its host, and the rule has `created_by_host_manager` set to "true" or has been updated by a user with the "activity_manager" effective role on the host endpoint, this field and `modified_by` will be set to "null". Note that this field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations.
created_by_host_manager	boolean	A rule on a shared endpoint, created by a user with the "activity_manager" role on the shared endpoint and not its host endpoint, will have this field set to false; in all other cases it will be true. This field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations.
editable	boolean	True if the current user has permission to update or delete the rule. See the pause rule operation documentation for details about authorization requirements and when this will be set. See pause rule list for details. Note that this field will not be included in the pause_rule_limited documents returned by the get task pause info and get my effective pause rule operations.
pause_ls	boolean	Prevent API ls (directory listing) operations. Default "true".
pause_mkdir	boolean	Prevent API mkdir (create directory) operations. Default "true". Note that this only affects the API mkdir operation - if `pause_transfer_write` is "false", then directories can be created as part of the transfer operation.
pause_symlink	boolean	Prevent API symlink creation operations. Default "true". Note that this only affects the API symlink operation - if `pause_transfer_write` is "false", then symlinks can be created as part of the transfer operation.
pause_rename	boolean	Prevent API file and directory rename operations. Default true.
pause_task_delete	boolean	Whether to pause matching tasks of type "DELETE". Default "true".
pause_task_transfer_write	boolean	Whether to pause matching tasks of type "TRANSFER" with the endpoint as destination.
pause_task_transfer_read	boolean	Whether to pause matching tasks of type "TRANSFER" with the endpoint as source.

3. Common Query Parameters

Name	Description
fields	Comma separated list of fields to include in the response. This can be used to save bandwidth on large list responses when not all fields are needed. For list document types (with `DATA_TYPE` ending in "_list"), this selects the fields of the item documents, not the top level paging and list meta data fields.

4. Common Errors

Code	HTTP Status	Description
EndpointNotFound	404	If <endpoint_xid> not found
TaskNotFound	404	If the task specified by <task_id> is not found
PauseRuleNotFound	404	If the pause rule specified by <pause_rule_id> is not found
PermissionDenied	403	If user does not have the required role on one or more of the specified tasks, endpoints, or pause rules.
ServiceUnavailable	503	If the service is down for maintenance.

5. Path Arguments

The operations below make use of the following arguments in the URL path. In this documentation parameter names are denoted by < and >; these should not be included literally in the request path.

Name	Type	Description
endpoint_xid	string	The `id` field of the endpoint, or for backward compatibility the `canonical_name` of the endpoint. The latter is deprecated, and all clients should be updated to use `id`.
task_id	string	Unique id string of a task.

6. Operations

6.1. Get tasks

Get a list of tasks involving the endpoints the user has the "activity_monitor" role on. All requests will implicitly filter based on the privileges of the user. The results can be sorted and filtered in different ways, and paging is required unless a filter to show only active tasks is used.

To facilitate paging, the result has fields last_key, has_next_page, and limit at the top level. If has_next_page is true, last_key can be passed as a query parameter to fetch the next page. If has_next_page is false, there are no more results at the time of the request. The limit field echoes the client specified limit from the query string, or the default if none was specified.

Note:The name of the source and destination endpoints (fields source_endpoint and destination_endpoint) will be visible if the endpoint is public or if it’s owned by the current user, just like standard visibility in /endpoint_list. As a special case, if the endpoint is private and not owned by the current user (and would normally be hidden), but the current user has the "activity_monitor" role on the host, then the name will be visible. This is the same as the visibility rules for /endpoint_manager/endpoint/<endpoint_xid>. See the extra field descriptions above for visibility of the host endpoint name and path.

URL	/endpoint_manager/task_list
Method	GET
Response Body	List of Task documents. { "DATA_TYPE": "task_list", "limit": 10, "last_key": "123abc", "has_next_page": true, "DATA": [ { "DATA_TYPE": "task", "source_endpoint": "bob#myshare", "source_host_endpoint": "org1#server3", "source_host_path": "/projects/experiment7/", "destination_endpoint": "bob#laptop", "destination_host_endpoint": null, "destination_host_path": null, "username": "jsmith", "task_id": "12345678-9abc-def0-1234-56789abcde03", "type": "TRANSFER", "status": "ACTIVE", "request_time": "2000-01-02 03:45:06+00:00", "completion_time": null, "deadline": "2000-01-03 03:45:06+00:00", "nice_status": "OK", "nice_status_short_description": "OK", "nice_status_details": null, "nice_status_expires_in": -1, "is_ok": true, "bytes_checksummed": 10, "bytes_transferred": 10240, "effective_bytes_per_second": 171, "delete_destination_extra": false, "sync_level": null, "verify_checksum": false "encrypt_data": false, "preserve_timestamp": false, "history_deleted": false, "command": "transfer", "label": null, "faults": 0, "directories": 10, "files": 10, "files_skipped": 3, "subtasks_canceled": 10, "subtasks_expired": 10, "subtasks_failed": 10, "subtasks_pending": 10, "subtasks_retrying": 10, "subtasks_succeeded": 10, "subtasks_total": 10, } ] }

URL

/endpoint_manager/task_list

Method

GET

Response Body

List of Task documents.

{
    "DATA_TYPE": "task_list",
    "limit": 10,
    "last_key": "123abc",
    "has_next_page": true,
    "DATA": [
        {
            "DATA_TYPE": "task",

            "source_endpoint": "bob#myshare",
            "source_host_endpoint": "org1#server3",
            "source_host_path": "/projects/experiment7/",

            "destination_endpoint": "bob#laptop",
            "destination_host_endpoint": null,
            "destination_host_path": null,

            "username": "jsmith",
            "task_id": "12345678-9abc-def0-1234-56789abcde03",
            "type": "TRANSFER",
            "status": "ACTIVE",
            "request_time": "2000-01-02 03:45:06+00:00",
            "completion_time": null,
            "deadline": "2000-01-03 03:45:06+00:00",

            "nice_status": "OK",
            "nice_status_short_description": "OK",
            "nice_status_details": null,
            "nice_status_expires_in": -1,
            "is_ok": true,

            "bytes_checksummed": 10,
            "bytes_transferred": 10240,
            "effective_bytes_per_second": 171,

            "delete_destination_extra": false,
            "sync_level": null,
            "verify_checksum": false
            "encrypt_data": false,
            "preserve_timestamp": false,

            "history_deleted": false,
            "command": "transfer",
            "label": null,

            "faults": 0,
            "directories": 10,
            "files": 10,
            "files_skipped": 3,
            "subtasks_canceled": 10,
            "subtasks_expired": 10,
            "subtasks_failed": 10,
            "subtasks_pending": 10,
            "subtasks_retrying": 10,
            "subtasks_succeeded": 10,
            "subtasks_total": 10,
        }
    ]
}

6.1.1. Query Parameters

Query Parameter	Type	Default	Description
last_key	string	null	Opaque value representing the last element in the previous result set page, used to fetch the following page. This will return all results starting from but not including the last element of the previous page.
limit	int	100	Maximum number of results to return. The maximum allowed limit is 1000. If `filter_status` is a subset of ("ACTIVE", "INACTIVE"), `limit=0` is supported as a shortcut for `limit=1000`. It was originally designed to return all active tasks, but this was a mistake in the original design because the number of active tasks is not bounded. It’s unlikely we will have more than 1000 active tasks any time soon, but it’s not the kind of thing we want to risk. For this reason `limit=0` is deprecated, but for now the UX can safely assume that it will return all active tasks (which it will with very high probability, just not 100%).
filter_*	string	null	See filter documentation below.

6.1.2. Ordering

Tasks that are still in progress are always sorted by request_time descending (newest first). Completed tasks are sorted by completion_time descending. In progress tasks will be sorted before completed tasks.

6.1.3. Filters

Filter Syntax

Filters are passed as separate query parameters, of the form filter_FILTERNAME=FILTERVALUE. Many of the filters are named after a field they apply to, but a few are custom filters with more complex behavior.

If multiple filters are set in the request, only results matching all filters will be returned - there is an implicit logical AND between filters, unless otherwise specified. Within a single filter that accepts multiple values, there is typically an implicit OR. For example, specifying filter_task_id=123,456,678 will return tasks with id 123 OR 456 OR 678.

Filter values, like any other query parameter value, must be percent encoded. The query parameter names will always be safe to pass without further encoding, because they use a subset of characters that do not require encoding.

Task List Filters

All task list filters are subject to the user’s endpoint privileges. For example, filtering on user will only return tasks submitted by that user if they involve an endpoint the requesting user has the "activity_manager" or "activity_monitor" role on. Some requests will result in an error: specifying a task id filter for a task that does not involve an endpoint the user has an appropriate role on will result in a PermissionDenied error.

For any query that doesn’t specify a filter_status that is a subset of ("ACTIVE", "INACTIVE"), at least one of filter_task_id or filter_endpoint is required. This requirement is present because completed tasks are stored separately in a very large table and it is very expensive to query without making use of an index, which can be done only if an appropriate filter is present.

Query Parameter	Filter Type	Description
filter_status	equality list	Comma separated list of task statuses. Return only tasks with any of the specified statuses. Note that in-progress tasks will have status "ACTIVE" or "INACTIVE", and completed tasks will have status "SUCCEEDED" or "FAILED".
filter_task_id	equality list	Comma separated list of task_ids, limit 50. Return only tasks with any of the specified ids. If any of the specified tasks do not involve an endpoint the user has an appropriate role for, a `PermissionDenied` error will be returned. This filter can’t be combined with any other filter. If another filter is passed, a `BadRequest` will be returned.
filter_owner_id	equality	A Globus Auth identity id. Limit results to tasks submitted by the specified identity, or linked to the specified identity, at submit time. Returns `UserNotFound` if the identity does not exist or has never used the Globus Transfer service. If no tasks were submitted by this user to an endpoint the current user has an appropriate role on, an empty result set will be returned. Unless filtering for running tasks (i.e. `filter_status` is a subset of ("ACTIVE", "INACTIVE"), `filter_endpoint` is required when using `filter_owner_id`.
filter_username	equality	[DEPRECATED] Use `filter_owner_id` instead. A Globus username. The username is mapped to the globus identity id, and passed to `filter_owner_id`. Just like `filter_owner_id`, `filter_endpoint` is required unless filtering for running tasks. Returns `UserNotFound` if the user does not exist.
filter_endpoint	equality	Single endpoint id or canonical name. Using canonical name is deprecated. Return only tasks with a matching source or destination endpoint or matching source or destination host endpoint.
filter_is_paused	boolean equality	Return only tasks with the specified `is_paused` value. Requires that `filter_status` is also passed and contains a subset of "ACTIVE" and "INACTIVE". Completed tasks always have `is_paused` equal to "false" and filtering on their paused state is not useful and not supported. Note that pausing is an async operation, and after a pause rule is inserted it will take time before the is_paused flag is set on all affected tasks. Tasks paused by id will have the `is_paused` flag set immediately.
filter_completion_time	datetime range	Start and end date-times separated by a comma. Each datetime should be specified as a string in ISO 8601 format: YYYY-MM-DDTHH:MM:SS, where the "T" separating date and time is literal, with optional +/-HH:MM for timezone. If no timezone is specified, UTC is assumed, or a trailing "Z" can be specified to make UTC explicit. A space can be used between the date and time instead of a space. A blank string may be used for either the start or end (but not both) to indicate no limit on that side. Returns only complete tasks with `completion_time` in the specified range. If the end date is blank, it will also include all active tasks, since they will complete some time in the future.
filter_min_faults	int	Minimum number of cumulative faults, inclusive. Return only tasks with `faults >= N`, where N is the filter value. Use `filter_min_faults=1` to find all tasks with at least one fault. Note that many errors are not fatal and the task may still be successful even if `faults >= 1`. See the faults field documentation for details.
filter_local_user	equality	A valid username for the target system running the endpoint, as a utf8 encoded string. Requires that `filter_endpoint` is also set. Return only tasks that have successfully fetched the local user from the endpoint, and match the values of `filter_endpoint` and `filter_local_user` on the source or on the destination.

6.2. Get task

Get details of a single task by id. The result will include the standard task fields and the extra task fields described above.

Authorization

Requires the "activity_monitor" effective role on a source or destination endpoint of the task. Note that if the user owns the task but does not have an appropriate role on an endpoint this will still return a "PermissionDenied" error.

URL	/endpoint_manager/task/<task_id>
Method	GET
Response Body	Task document.

6.3. Get task events

Get list of events for a single task. Paging is done using the old limit and offset parameters.

See the event document documentation for details.

Authorization

URL	/endpoint_manager/task/<task_id>/event_list
Method	GET
Response Body	List of event documents

6.3.1. Query Parameters

Query Parameter	Type	Default	Description
offset	int	0	Return results starting from this offset within the total result set. Note that for active tasks this results set will be changing, and as the result set changes so will the meaning of the offset. For this reason, paging through events on active tasks may return unexpected results.
limit	int	100	Maximum number of results to return. The maximum allowed limit is 1000.
filter_*	string	null	See filter documentation below.

6.3.2. Ordering

Results are sorted by time descending (newest first).

6.3.3. Filters

Query Parameter	Filter Type	Description
filter_is_error	flag	1 for True. Return only events that are errors. The inverted form (returning only non-errors) is not supported. By default all events are returned.

6.4. Get task pause info as admin

This operation returns the same information as the normal user get task pause info operation, but has different authorization requirements. Note that pause_rule_limited documents are still returned instead of the full pause_rule, since the result can include pause rules for endpoints the current user does not have an "activity_monitor" role on.

Authorization

URL	/endpoint_manager/task/<task_id>/pause_info
Method	GET
Response Body	{ "DATA_TYPE": "pause_info_limited", "pause_rules": [... list of pause_rule_limited documents...], "source_pause_message": null, "destination_pause_message": "Disk problems, pausing all tasks until we resolve", "source_pause_message_share": null, "destination_pause_message_share": null }

URL

/endpoint_manager/task/<task_id>/pause_info

Method

GET

Response Body

{
    "DATA_TYPE": "pause_info_limited",
    "pause_rules": [... list of pause_rule_limited documents...],
    "source_pause_message": null,
    "destination_pause_message": "Disk problems, pausing all tasks until we resolve",
    "source_pause_message_share": null,
    "destination_pause_message_share": null
}

6.5. Get task successful transfers as admin

For a "TRANSFER" type task, get a list of files transferred successfully, after a task is complete (with status "FAILED" or "SUCCEEDED"), as an endpoint admin. See Get task successful transfers (as normal user) for details. If the current user has the "activity_monitor" role on only one of the endpoints, the paths corresponding to the other endpoint will be "null".

Authorization

URL	/endpoint_manager/task/<task_id>/successful_transfers [?marker=MARKER]
Method	GET
Response Body	{ "DATA_TYPE": "successful_transfers" "marker": 0, "next_marker": 93979, "DATA": [ { "destination_path": "/path/to/destination", "source_path": "/path/to/source", "DATA_TYPE": "successful_transfer" } ], }

URL

/endpoint_manager/task/<task_id>/successful_transfers [?marker=MARKER]

Method

GET

Response Body

{
  "DATA_TYPE": "successful_transfers"
  "marker": 0,
  "next_marker": 93979,
  "DATA": [
    {
      "destination_path": "/path/to/destination",
      "source_path": "/path/to/source",
      "DATA_TYPE": "successful_transfer"
    }
  ],
}

6.6. Get endpoint as admin

Get details of an endpoint. This resource is similar to standard get endpoint, and has the same authorization requirements. The one difference is that the in_use field is always set to "null".

See the endpoint document documentation for details.

Authorization

Requires that the endpoint be public, or that the user has the "administrator" or "activity_monitor" effective role on the endpoint.

URL	/endpoint_manager/endpoint/<endpoint_xid>
Method	GET
Response Body	Endpoint document.

6.7. Get hosted endpoint list

Get a list of shared endpoints hosted on a specified endpoint. The response contains full endpoint documents, with the same differences from the standard endpoint document as Get endpoint as admin.

Authorization

Requires the "activity_monitor" effective role on the endpoint.

URL	/endpoint_manager/endpoint/<endpoint_xid>/hosted_endpoint_list
Method	GET
Response Body	{ "DATA_TYPE": "endpoint_list", "DATA": [ { "DATA_TYPE": "endpoint", "owner_id": "8ea74f97-e9e4-433d-a513-ac9920350258", "owner_string": "bob@globusid.org", "display_name": "Project1 Share", ... } ] }

6.7.1. Ordering

Results are ordered by display_name.

6.7.2. Filtering

No filtering options are supported at this time.

6.8. Get endpoint access list as admin

Get a list of ACLs on the specified endpoint. Returns the same access_list document as the standard access list resource, but has different authorization requirements.

Authorization

Requires the "activity_monitor" effective role on the endpoint.

URL	/endpoint_manager/endpoint/<endpoint_xid>/access_list
Method	GET
Response Body	"access_list" document

6.9. Get monitored endpoints

Get a list of the endpoints the current users has explicit monitor or manager role on. Like all endpoint manager resources, a 403 response with a "PermissionDenied" error code body will be returned if the user has no permissions. The standard my_effective_roles field can be used to determine which roles the user has.

Note:If the user has the "activity_manager" or "activity_monitor" role on a host endpoint, they implicitly have the corresponding role on all shared endpoints hosted by that endpoint, but this list will not necessarily include any of the hosted shared endpoints. Shared endpoints will only be in this list if the user has been explicitly granted one of the roles on the shared endpoint itself. If the user has an explicit role on both a shared endpoint and its host endpoint, both will be in the list.

The response contains full endpoint documents, with the same differences from the standard endpoint document as Get endpoint as admin.

URL	/endpoint_manager/monitored_endpoints
Method	GET
Response Body	{ "DATA_TYPE": "monitored_endpoints", "DATA": [ { "DATA_TYPE": "monitored_endpoint", "id": "196b3545-0878-4443-a1e6-57eb833beb06", "my_effective_roles": ["activity_manager"], "display_name": "Great Endpoint", ... }, ... ] }

URL

/endpoint_manager/monitored_endpoints

Method

GET

Response Body

{
    "DATA_TYPE": "monitored_endpoints",
    "DATA": [
        {
            "DATA_TYPE": "monitored_endpoint",
            "id": "196b3545-0878-4443-a1e6-57eb833beb06",
            "my_effective_roles": ["activity_manager"],
            "display_name": "Great Endpoint",
            ...
        },
        ...
    ]
}

6.9.1. Ordering

Results are ordered by display_name.

6.10. Cancel tasks as admin

Cancel one or more tasks by task id as an endpoint administrator. If a task is already complete or canceled at the time of the submission it will not raise an error, which allows clients to re-submit the request if there was a network error.

Task owners will be notified via email that their task(s) were canceled by an administrator. One email will be sent for each task, and they will be sent even if the user has notifications disabled in their profile.

Note:Admin cancel requests still involve processing each task individually, so it’s possible that some tasks will succeed before the cancel request is processed, and others will get canceled by this request or even a concurrent cancel request. The done field indicates when all tasks in the request have status "FAILED" or "SUCCEEDED" and are no longer running.

Authorization

Requires the "activity_manager" effective role on the source or destination endpoint of each task in the request. If this check fails for any of the tasks, the entire request will fail with a "PermissionDenied" error.

URL	/endpoint_manager/admin_cancel
Method	POST
Request Body	Admin cancel document with `task_id_list` and `message` fields.
Response Body	Admin cancel document with `id` and `done` fields.

6.11. Get cancel status by id

Returns an admin_cancel document without the task_id_list; clients can check the done field to determine if the cancel request is complete.

Authorization

Only the user who submitted the original cancel request is guaranteed to be able to get its status.

Note:In the current implementation, all completed request IDs and all request IDs never before seen are returned as "done". Clients should not rely on this behavior, and take care not to corrupt the ID.

URL	/endpoint_manager/admin_cancel/<admin_cancel_id>
Method	GET
Response Body	Admin cancel document with `id` and `done` fields.

6.12. Pause tasks as admin

Pause one or more tasks by task id as an endpoint administrator. If a task is already complete or paused at the time of the submission it will not raise an error, which allows clients to re-submit the request if there was a network error.

Per-task pause is tracked separately for host endpoint admins and shared endpoint admins. A task is paused if either has been set, and will only resume when both are cleared. A host endpoint admin can clear both when resuming, while a shared endpoint admin can only clear a pause set by other shared endpoint admins.

Task owners will be notified via email that their task(s) were paused by an administrator. One email will be sent for each task, and they will be sent even if the user has notifications disabled in their profile.

Note:Admin pause requests are asynchronous, and it’s possible that some tasks will succeed before the pause request is processed.

Authorization

URL	/endpoint_manager/admin_pause
Method	POST
Request Body	admin_pause document
Response Body	result document with code "PauseAccepted"

6.13. Resume tasks as admin

Resuming a task involves removing all per-task pauses on the task, and overriding existing pause rules (host and share, source and destination) that affect the task. This operation removes and overrides pause on whichever endpoints the current user has the "activity_manager" role on.

As an example, suppose a task involving a shared endpoint has been paused by two different users, one with the "activity_manager" role on the host endpoint, and one with the "activity_manager" role on the shared endpoint. A user with the "activity_manager" role on the host endpoint can clear both per-task pause flags and set an override on all pause rules that might affect the task, so the task will resume. A user with the "activity_manager" role on the shared endpoint and not its host endpoint can only clear one of the per-task pause flags; a resume operation submitted by such a user will still be considered successful, but the task won’t actually start running again until a user with the "activity_manager" role on the host endpoint clears the other per-task pause flag.

This applies to source and destination endpoints as well, i.e. if a user has the "activity_manager" role on the source but not the destination, a resume operation will clear per-task pause and override pause rules on the source but not the destination.

To resume all tasks affected by a pause_rule, use Delete pause rule by id.

This API call will not raise an error if the task is already running and no per-task pause exists - it will simply set the pause rule override timestamp for the task to the specified value.

If there are no other pauses on the task, the task will resume. Otherwise it will only resume once an "activity_manager" of the other endpoint removes the remaining pauses. When the task actually begins running again, a resume email will be sent to the user. Just like pause, this is an asynchronous process.

Authorization

URL	/endpoint_manager/admin_resume
Method	POST
Request Body	admin_resume document
Response Body	result document with code "ResumeAccepted"

6.14. Get pause rules

Get a list of pause rules on endpoints that the current user has the "activity_monitor" role on.

Pause rules will be editable (the editable field will be "true") if one of the following conditions are met:

The endpoint is a normal or host endpoint, and the current user has the "activity_manager" effective role on the endpoint
The endpoint is a shared endpoint, the current user has the "activity_manager" effective role on the shared endpoint, and the rule was not created by a user with the "activity_manager" effective role on the host endpoint. Note that rules created by a share manager and later modified by a host manager are NOT protected from further editing by a share manager.
The endpoint is a shared endpoint, and the current user has the "activity_manager" effective role on the host endpoint (host endpoint managers have higher privileges, and can edit and delete rules set by both host managers and share managers).

If the result set contains over 1000 rules, a "LimitExceeded" error will be returned and the client must pass the filter_endpoint query parameter (with the endpoint id) to get the rules one endpoint at a time.

Authorization

Returns rules on endpoints for which the user has the "activity_monitor" effective role. If filter_endpoint or filter_host_endpoint is specified, the user must have the "activity_monitor" effective role on the specified endpoint.

Note:Pause rules are also accessible to normal users via the Get endpoint pause rules API.

URL	/endpoint_manager/pause_rule_list [?filter_endpoint=ENDPOINT_ID]
Method	GET
Response Body	Pause rule list document.

6.14.1. Pause Rule Filtering

Query Parameter	Filter Type	Description
filter_endpoint	string equality	Single endpoint id. Include only pause rules on the specified endpoint.
filter_host_endpoint	string equality	Single endpoint id. Include only pause rules on shared endpoints hosted by the specified endpoint.

6.15. Create pause rule

Create a new pause rule. New tasks matching the rule will be paused immediately. If start_time is not set, any existing tasks that match will be paused asynchronously. If set, only tasks submitted after the specified time will be paused.

If the appropriate flags are set, the rule will also prevent foreground operations for ls, mkdir, and rename. Clients requesting these operation on the specified endpoint and matching the user clause will receive an OperationPaused error containing the pause message (or the most specific pause message if multiple pause messages are in effect).

Authorization

Requires the "activity_manager" effective role on the endpoint in the rule.

URL	/endpoint_manager/pause_rule
Method	POST
Request Body	Pause rule document without `id` field.
Response Body	Pause rule document with server generated `id` field added.

6.16. Get pause rule

Get a pause rule by id.

Authorization

Requires the "activity_monitor" effective role on the endpoint in the rule.

URL	/endpoint_manager/pause_rule/<pause_rule_id>
Method	GET
Response Body	Pause rule document

6.17. Update pause rule

Update a pause rule by id. Only the start_time, message, and pause type fields (with the pause_ prefix) can be updated. It is recommended that clients include only the fields to be updated in the request. If non-updatable fields are included, they will be ignored.

The modified_time and modified_by_id fields will be updated based on the time of the request and the user updating the rule. The response will contain these updated fields. Any manual task resume requests made in the past that overrode this pause rule will no longer be in effect, and such tasks will become paused.

Authorization

The rule must be marked editable in the pause rule list, see link for details.

URL	/endpoint_manager/pause_rule/<pause_rule_id>
Method	PUT
Request Body	Partial pause rule document (containing fields to be updated).
Response Body	Pause rule document

6.18. Delete pause rule

Delete an existing pause rule by id. Any tasks that were paused by this rule and are not affected by any other rule or per-task pause will resume.

Authorization

The rule must be marked editable in the pause rule list, see link for details.

URL	/endpoint_manager/pause_rule
Method	DELETE
Response Body	Result document.

6.19. [DEPRECATED] Get hosted endpoint info list

Deprecated, use Get hosted endpoint list instead. Get a list of shared endpoints hosted on a specified endpoint.

Fields

display_name
owner_id
owner_string
canonical_name [DEPRECATED]
user_rule_count ("identity" rules) [DEPRECATED]
group_rule_count [DEPRECATED]
all_rule_count ("all_authenticated_user" rules) [DEPRECATED]
anonymous_rule_count [DEPRECATED]

Authorization

Requires the "activity_monitor" effective role on the endpoint.

URL	/endpoint_manager/endpoint/<endpoint_xid>/hosted_endpoint_info_list
Method	GET
Response Body	{ "DATA_TYPE": "hosted_endpoint_info_list", "DATA": [ { "DATA_TYPE": "hosted_endpoint_info", "owner_id": "8ea74f97-e9e4-433d-a513-ac9920350258", "owner_string": "bob@globusid.org", "display_name": "Project1 Share", "user_rule_count": 4, "group_rule_count": 1, "all_rule_count": 0 "anonymous_rule_count": 0 } ] }

URL

/endpoint_manager/endpoint/<endpoint_xid>/hosted_endpoint_info_list

Method

GET

Response Body

{
    "DATA_TYPE": "hosted_endpoint_info_list",
    "DATA": [
        {
            "DATA_TYPE": "hosted_endpoint_info",
            "owner_id": "8ea74f97-e9e4-433d-a513-ac9920350258",
            "owner_string": "bob@globusid.org",
            "display_name": "Project1 Share",
            "user_rule_count": 4,
            "group_rule_count": 1,
            "all_rule_count": 0
            "anonymous_rule_count": 0
        }
    ]
}

6.19.1. Ordering

Results are ordered by display_name.

6.19.2. Filtering

No filtering options are supported at this time.

Transfer API Menu

Advanced Endpoint Management

1. Overview

1.1. Shared Endpoints and Manager Privileges

2. Document Types

2.1. Task Document

2.1.1. Extra Fields

2.2. Admin cancel document

2.2.1. Admin cancel fields

2.3. Admin pause document

2.3.1. Admin pause fields

2.4. Admin resume document

2.4.1. Admin resume fields

2.5. Pause rule document

2.5.1. Pause rule fields

3. Common Query Parameters

4. Common Errors

5. Path Arguments

6. Operations

6.1. Get tasks

6.1.1. Query Parameters

6.1.2. Ordering

6.1.3. Filters

Filter Syntax

Task List Filters

6.2. Get task

6.3. Get task events

6.3.1. Query Parameters

6.3.2. Ordering

6.3.3. Filters

6.4. Get task pause info as admin

6.5. Get task successful transfers as admin

6.6. Get endpoint as admin

6.7. Get hosted endpoint list

6.7.1. Ordering

6.7.2. Filtering

6.8. Get endpoint access list as admin

6.9. Get monitored endpoints

6.9.1. Ordering

6.10. Cancel tasks as admin

6.11. Get cancel status by id

6.12. Pause tasks as admin

6.13. Resume tasks as admin

6.14. Get pause rules

6.14.1. Pause Rule Filtering

6.15. Create pause rule

6.16. Get pause rule

6.17. Update pause rule

6.18. Delete pause rule

6.19. [DEPRECATED] Get hosted endpoint info list

6.19.1. Ordering

6.19.2. Filtering