0
# Transfer Service
1

2
High-performance data movement between Globus endpoints with support for large files, directories, checksums, and advanced transfer options. The Transfer service provides reliable, resumable data transfer capabilities for research computing with comprehensive endpoint management and task monitoring.
3

4
## Capabilities
5

6
### Transfer Client
7

8
Core client for all Transfer service operations including data movement, endpoint management, and task monitoring with built-in support for pagination and filtering.
9

10
```python { .api }
11
class TransferClient(BaseClient):
12
    """
13
    Client for Globus Transfer API operations.
14
    
15
    Provides methods for data transfer, endpoint management, task monitoring,
16
    and collection operations with comprehensive filtering and pagination support.
17
    """
18
    
19
    def __init__(
20
        self,
21
        *,
22
        app: GlobusApp | None = None,
23
        authorizer: GlobusAuthorizer | None = None,
24
        environment: str | None = None,
25
        base_url: str | None = None,
26
        **kwargs
27
    ) -> None: ...
28
    
29
    def add_app_data_access_scope(
30
        self, 
31
        collection_ids: str | UUID | Iterable[str | UUID]
32
    ) -> TransferClient:
33
        """
34
        Add dependent data_access scopes for collections to handle consent.
35
        
36
        Used for resolving ConsentRequired errors when accessing
37
        GCS Mapped Collections that require additional permissions.
38
        
39
        Parameters:
40
        - collection_ids: Collection ID(s) requiring data access scopes
41
        
42
        Returns:
43
        Self for method chaining
44
        """
45
```
46

47
### Data Transfer Operations
48

49
Submit and manage high-performance data transfers between Globus endpoints with comprehensive options for sync, verification, and encryption.
50

51
```python { .api }
52
def submit_transfer(self, data: TransferData) -> GlobusHTTPResponse:
53
    """
54
    Submit a transfer task for data movement between endpoints.
55
    
56
    Parameters:
57
    - data: TransferData object containing transfer specification
58
    
59
    Returns:
60
    GlobusHTTPResponse with task_id and submission details
61
    """
62

63
def submit_delete(self, data: DeleteData) -> GlobusHTTPResponse:
64
    """
65
    Submit a delete task to remove files/directories from an endpoint.
66
    
67
    Parameters:
68
    - data: DeleteData object specifying files to delete
69
    
70
    Returns:
71
    GlobusHTTPResponse with task_id and submission details
72
    """
73

74
class TransferData(PayloadWrapper):
75
    """
76
    Container for transfer request data with file/directory specifications.
77
    
78
    Used to build transfer operations with items, sync options, and
79
    advanced transfer parameters like encryption and checksumming.
80
    """
81
    
82
    def __init__(
83
        self,
84
        transfer_client: TransferClient,
85
        source_endpoint: str | UUID,
86
        destination_endpoint: str | UUID,
87
        *,
88
        label: str | None = None,
89
        submission_id: str | None = None,
90
        sync_level: Literal["exists", "size", "mtime", "checksum"] | int = "size",
91
        verify_checksum: bool = False,
92
        preserve_timestamp: bool = False,
93
        encrypt_data: bool = False,
94
        deadline: str | datetime | None = None,
95
        recursive_symlinks: Literal["ignore", "keep", "copy"] = "ignore",
96
        skip_source_errors: bool = False,
97
        fail_on_quota_errors: bool = False,
98
        **kwargs
99
    ) -> None: ...
100
    
101
    def add_item(
102
        self,
103
        source_path: str,
104
        destination_path: str,
105
        *,
106
        recursive: bool = False,
107
        external_checksum: str | None = None,
108
        checksum_algorithm: str | None = None
109
    ) -> None:
110
        """
111
        Add a file or directory to the transfer.
112
        
113
        Parameters:
114
        - source_path: Path on source endpoint
115
        - destination_path: Path on destination endpoint  
116
        - recursive: Whether to recursively transfer directories
117
        - external_checksum: Pre-computed checksum for verification
118
        - checksum_algorithm: Algorithm used for checksum (md5, sha1, sha256, etc.)
119
        """
120
    
121
    def add_symlink_item(
122
        self,
123
        source_path: str,
124
        destination_path: str
125
    ) -> None:
126
        """Add a symbolic link to the transfer."""
127

128
class DeleteData(PayloadWrapper):
129
    """
130
    Container for delete request data specifying files and directories to remove.
131
    """
132
    
133
    def __init__(
134
        self,
135
        transfer_client: TransferClient,
136
        endpoint: str | UUID,
137
        *,
138
        label: str | None = None,
139
        submission_id: str | None = None,
140
        recursive: bool = False,
141
        deadline: str | datetime | None = None,
142
        skip_source_errors: bool = False,
143
        **kwargs
144
    ) -> None: ...
145
    
146
    def add_item(self, path: str) -> None:
147
        """
148
        Add a file or directory path to delete.
149
        
150
        Parameters:
151
        - path: Path to delete on the endpoint
152
        """
153
```
154

155
### Task Management
156

157
Monitor and control transfer tasks with comprehensive status tracking and task lifecycle management.
158

159
```python { .api }
160
def get_task(
161
    self, 
162
    task_id: str, 
163
    *, 
164
    query_params: dict[str, Any] | None = None
165
) -> GlobusHTTPResponse:
166
    """
167
    Get detailed information about a specific task.
168
    
169
    Parameters:
170
    - task_id: UUID of the task to retrieve
171
    - query_params: Additional query parameters
172
    
173
    Returns:
174
    GlobusHTTPResponse with task details including status and statistics
175
    """
176

177
def task_list(
178
    self,
179
    *,
180
    limit: int | None = None,
181
    offset: int | None = None,
182
    filter: str | dict | list[str | dict] | None = None,
183
    **params
184
) -> IterableTransferResponse:
185
    """
186
    List tasks with filtering and pagination support.
187
    
188
    Parameters:
189
    - limit: Maximum number of results to return
190
    - offset: Offset for pagination
191
    - filter: Task filter criteria (see filter formatting documentation)
192
    - **params: Additional query parameters
193
    
194
    Returns:
195
    IterableTransferResponse with task listing
196
    """
197

198
def cancel_task(
199
    self, 
200
    task_id: str, 
201
    *, 
202
    query_params: dict[str, Any] | None = None
203
) -> GlobusHTTPResponse:
204
    """
205
    Cancel a running or pending task.
206
    
207
    Parameters:
208
    - task_id: UUID of task to cancel
209
    - query_params: Additional parameters
210
    
211
    Returns:
212
    GlobusHTTPResponse confirming cancellation
213
    """
214

215
def task_pause_info(
216
    self, 
217
    task_id: str, 
218
    *, 
219
    query_params: dict[str, Any] | None = None
220
) -> GlobusHTTPResponse:
221
    """Get information about why a task is paused."""
222

223
def task_resume(
224
    self, 
225
    task_id: str, 
226
    *, 
227
    query_params: dict[str, Any] | None = None
228
) -> GlobusHTTPResponse:
229
    """Resume a paused task."""
230

231
def task_wait(
232
    self,
233
    task_id: str,
234
    *,
235
    timeout: int = 10,
236
    polling_interval: int = 10
237
) -> bool:
238
    """
239
    Wait for a task to complete with configurable timeout and polling.
240
    
241
    Parameters:
242
    - task_id: UUID of task to wait for
243
    - timeout: Maximum time to wait in seconds
244
    - polling_interval: Seconds between status checks
245
    
246
    Returns:
247
    True if task completed successfully, False if timeout or failure
248
    """
249

250
def get_submission_id(self) -> GlobusHTTPResponse:
251
    """Get a submission ID for grouping related operations."""
252

253
def task_successful_transfers(
254
    self, 
255
    task_id: str, 
256
    *, 
257
    limit: int | None = None,
258
    **params
259
) -> IterableTransferResponse:
260
    """Get list of successfully transferred files from a task."""
261

262
def task_skipped_errors(
263
    self, 
264
    task_id: str, 
265
    *, 
266
    limit: int | None = None,
267
    **params
268
) -> IterableTransferResponse:
269
    """Get list of skipped errors from a transfer task."""
270
```
271

272
### Endpoint Management
273

274
Discover, retrieve, and manage Globus endpoints with activation support and detailed endpoint information.
275

276
```python { .api }
277
def endpoint_search(
278
    self,
279
    filter_fulltext: str | None = None,
280
    *,
281
    limit: int | None = None,
282
    offset: int | None = None,
283
    filter: str | dict | list[str | dict] | None = None,
284
    **params
285
) -> IterableTransferResponse:
286
    """
287
    Search for endpoints using fulltext search and filters.
288
    
289
    Parameters:
290
    - filter_fulltext: Text search across endpoint names and descriptions
291
    - limit: Maximum results to return
292
    - offset: Pagination offset
293
    - filter: Advanced filter criteria
294
    - **params: Additional query parameters
295
    
296
    Returns:
297
    IterableTransferResponse with endpoint search results
298
    """
299

300
def get_endpoint(
301
    self,
302
    endpoint_id: str | UUID,
303
    *,
304
    query_params: dict[str, Any] | None = None
305
) -> GlobusHTTPResponse:
306
    """
307
    Get detailed information about a specific endpoint.
308
    
309
    Parameters:
310
    - endpoint_id: UUID of endpoint to retrieve
311
    - query_params: Additional query parameters
312
    
313
    Returns:
314
    GlobusHTTPResponse with endpoint details
315
    """
316

317
def update_endpoint(
318
    self,
319
    endpoint_id: str | UUID,
320
    data: dict[str, Any],
321
    *,
322
    query_params: dict[str, Any] | None = None
323
) -> GlobusHTTPResponse:
324
    """
325
    Update endpoint configuration.
326
    
327
    Parameters:
328
    - endpoint_id: UUID of endpoint to update
329
    - data: Partial endpoint document with updates
330
    - query_params: Additional parameters
331
    
332
    Returns:
333
    GlobusHTTPResponse confirming update
334
    """
335

336
def endpoint_activate(
337
    self,
338
    endpoint_id: str | UUID,
339
    *,
340
    requirements_data: dict[str, Any] | None = None,
341
    **params
342
) -> ActivationRequirementsResponse:
343
    """
344
    Activate an endpoint for data operations.
345
    
346
    Handles credential submission and activation workflows
347
    required before endpoints can be used for transfers.
348
    
349
    Parameters:
350
    - endpoint_id: UUID of endpoint to activate
351
    - requirements_data: Activation credentials/requirements
352
    - **params: Additional activation parameters
353
    
354
    Returns:
355
    ActivationRequirementsResponse with activation status
356
    """
357

358
def endpoint_deactivate(
359
    self,
360
    endpoint_id: str | UUID,
361
    *,
362
    query_params: dict[str, Any] | None = None
363
) -> GlobusHTTPResponse:
364
    """Deactivate an endpoint, clearing stored credentials."""
365

366
def endpoint_get_activation_requirements(
367
    self,
368
    endpoint_id: str | UUID,
369
    *,
370
    query_params: dict[str, Any] | None = None
371
) -> ActivationRequirementsResponse:
372
    """
373
    Get activation requirements for an endpoint.
374
    
375
    Returns information about what credentials or steps
376
    are needed to activate the endpoint for use.
377
    """
378

379
def endpoint_autoactivate(
380
    self,
381
    endpoint_id: str | UUID,
382
    *,
383
    query_params: dict[str, Any] | None = None,
384
    **kwargs
385
) -> GlobusHTTPResponse:
386
    """
387
    Attempt automatic activation using stored credentials.
388
    
389
    Returns:
390
    GlobusHTTPResponse indicating success or additional requirements
391
    """
392
```
393

394
### File System Operations
395

396
Perform file system operations on Globus endpoints including directory listing, file operations, and path management.
397

398
```python { .api }
399
def operation_ls(
400
    self,
401
    endpoint_id: str | UUID,
402
    *,
403
    path: str = "/",
404
    show_hidden: bool = True,
405
    limit: int | None = None,
406
    offset: int | None = None,
407
    **params
408
) -> IterableTransferResponse:
409
    """
410
    List directory contents on an endpoint.
411
    
412
    Parameters:
413
    - endpoint_id: UUID of endpoint
414
    - path: Directory path to list (default: "/")
415
    - show_hidden: Include hidden files and directories
416
    - limit: Maximum files to return
417
    - offset: Pagination offset
418
    
419
    Returns:
420
    IterableTransferResponse with directory listing
421
    """
422

423
def operation_mkdir(
424
    self,
425
    endpoint_id: str | UUID,
426
    path: str,
427
    *,
428
    query_params: dict[str, Any] | None = None
429
) -> GlobusHTTPResponse:
430
    """
431
    Create a directory on an endpoint.
432
    
433
    Parameters:
434
    - endpoint_id: UUID of endpoint
435
    - path: Directory path to create
436
    
437
    Returns:
438
    GlobusHTTPResponse confirming directory creation
439
    """
440

441
def operation_rename(
442
    self,
443
    endpoint_id: str | UUID,
444
    oldpath: str,
445
    newpath: str,
446
    *,
447
    query_params: dict[str, Any] | None = None
448
) -> GlobusHTTPResponse:
449
    """
450
    Rename/move a file or directory on an endpoint.
451
    
452
    Parameters:
453
    - endpoint_id: UUID of endpoint
454
    - oldpath: Current path
455
    - newpath: New path
456
    
457
    Returns:
458
    GlobusHTTPResponse confirming rename operation
459
    """
460

461
def operation_stat(
462
    self,
463
    endpoint_id: str | UUID,
464
    *,
465
    path: str = "/",
466
    **params
467
) -> GlobusHTTPResponse:
468
    """
469
    Get file/directory metadata (stat information).
470
    
471
    Parameters:
472
    - endpoint_id: UUID of endpoint
473
    - path: Path to get metadata for
474
    
475
    Returns:
476
    GlobusHTTPResponse with file metadata (size, type, permissions, etc.)
477
    """
478
```
479

480
### Collection Management
481

482
Manage collections on Globus Connect Server endpoints including guest collections and access policies.
483

484
```python { .api }
485
def get_collection(
486
    self,
487
    collection_id: str | UUID,
488
    *,
489
    query_params: dict[str, Any] | None = None
490
) -> GlobusHTTPResponse:
491
    """Get detailed information about a collection."""
492

493
def collection_list(
494
    self,
495
    *,
496
    mapped_collection_id: str | UUID | None = None,
497
    limit: int | None = None,
498
    **params
499
) -> IterableTransferResponse:
500
    """List collections with filtering options."""
501

502
def set_subscription_id(
503
    self,
504
    collection_id: str | UUID,
505
    subscription_id: str | UUID | Literal["DEFAULT"] | None
506
) -> GlobusHTTPResponse:
507
    """
508
    Set subscription ID on a mapped collection.
509
    
510
    Used primarily for Globus Connect Personal subscription management.
511
    """
512
```
513

514
### Response Objects
515

516
Specialized response classes providing enhanced access to Transfer service data with pagination and activation support.
517

518
```python { .api }
519
class IterableTransferResponse(IterableResponse):
520
    """
521
    Response class for Transfer API operations that return paginated data.
522
    
523
    Provides iteration support over result sets like task lists,
524
    endpoint searches, and file listings.
525
    """
526
    
527
    def __iter__(self) -> Iterator[dict[str, Any]]:
528
        """Iterate over response data items."""
529

530
class ActivationRequirementsResponse(GlobusHTTPResponse):
531
    """
532
    Response class for endpoint activation operations.
533
    
534
    Contains activation requirements, credentials needed,
535
    and activation status information.
536
    """
537
    
538
    @property
539
    def active(self) -> bool:
540
        """Whether the endpoint is currently activated."""
541
        
542
    @property  
543
    def auto_activation_supported(self) -> bool:
544
        """Whether the endpoint supports automatic activation."""
545
        
546
    def get_requirement_value(
547
        self, 
548
        requirement_name: str, 
549
        default: Any = None
550
    ) -> Any:
551
        """Get value for a specific activation requirement."""
552
```
553

554
### Error Handling
555

556
Transfer-specific error handling for common transfer scenarios and error conditions.
557

558
```python { .api }
559
class TransferAPIError(GlobusAPIError):
560
    """
561
    Error class for Transfer service API errors.
562
    
563
    Provides enhanced error information for transfer-specific
564
    error conditions like consent required, quota exceeded, etc.
565
    """
566
```
567

568
## Common Usage Patterns
569

570
### Basic File Transfer
571

572
```python
573
from globus_sdk import TransferClient, TransferData
574

575
# Initialize client
576
tc = TransferClient(authorizer=authorizer)
577

578
# Create transfer specification
579
transfer_data = TransferData(
580
    tc,
581
    source_endpoint="source-uuid",
582
    destination_endpoint="dest-uuid",
583
    label="My Transfer",
584
    sync_level="checksum",
585
    verify_checksum=True
586
)
587

588
# Add files/directories
589
transfer_data.add_item("/source/file.txt", "/dest/file.txt")
590
transfer_data.add_item("/source/dir/", "/dest/dir/", recursive=True)
591

592
# Submit and monitor
593
response = tc.submit_transfer(transfer_data)
594
task_id = response["task_id"]
595

596
# Wait for completion
597
tc.task_wait(task_id, timeout=3600)
598
task_info = tc.get_task(task_id)
599
print(f"Transfer status: {task_info['status']}")
600
```
601

602
### Endpoint Discovery and Activation
603

604
```python
605
# Search for endpoints
606
endpoints = tc.endpoint_search("tutorial", limit=10)
607
for ep in endpoints:
608
    print(f"{ep['display_name']}: {ep['id']}")
609

610
# Get endpoint details
611
endpoint = tc.get_endpoint("tutorial-endpoint-1")
612
print(f"Endpoint: {endpoint['display_name']}")
613

614
# Check activation requirements
615
req_response = tc.endpoint_get_activation_requirements("tutorial-endpoint-1")
616
if req_response.active:
617
    print("Endpoint is already activated")
618
else:
619
    # Try auto-activation
620
    auto_response = tc.endpoint_autoactivate("tutorial-endpoint-1")
621
    if auto_response["code"] == "AutoActivationFailed":
622
        print("Manual activation required")
623
    else:
624
        print("Auto-activation successful")
625
```
626

627
### Directory Operations
628

629
```python
630
# List directory contents
631
listing = tc.operation_ls("endpoint-uuid", path="/data", limit=100)
632
for item in listing:
633
    print(f"{item['name']} ({'dir' if item['type'] == 'dir' else 'file'})")
634

635
# Create directory
636
tc.operation_mkdir("endpoint-uuid", "/data/new-directory")
637

638
# Get file metadata
639
file_info = tc.operation_stat("endpoint-uuid", path="/data/file.txt")
640
print(f"File size: {file_info['size']} bytes")
641
```
642

643
### Advanced Transfer Options
644

645
```python
646
# High-assurance transfer with encryption and verification
647
transfer_data = TransferData(
648
    tc,
649
    source_endpoint="secure-endpoint",
650
    destination_endpoint="backup-endpoint",
651
    label="Secure Backup",
652
    encrypt_data=True,
653
    verify_checksum=True,
654
    preserve_timestamp=True,
655
    deadline="2024-12-31T23:59:59Z"
656
)
657

658
# Add files with pre-computed checksums
659
transfer_data.add_item(
660
    "/data/important.dat", 
661
    "/backup/important.dat",
662
    external_checksum="sha256:abc123...",
663
    checksum_algorithm="sha256"
664
)
665

666
# Submit with error handling
667
try:
668
    response = tc.submit_transfer(transfer_data)
669
    print(f"Transfer submitted: {response['task_id']}")
670
except TransferAPIError as e:
671
    if "ConsentRequired" in str(e):
672
        print("Additional consent required for collections")
673
    else:
674
        print(f"Transfer failed: {e}")
675
```