---
title: "downloadTask(with:completionHandler:)"
framework: foundation
role: symbol
role_heading: Instance Method
path: "foundation/urlsession/downloadtask(with:completionhandler:)-4a84s"
---

# downloadTask(with:completionHandler:)

Creates a download task that retrieves the contents of a URL based on the specified URL request object, saves the results to a file, and calls a handler upon completion.

## Declaration

```swift
func downloadTask(with request: URLRequest, completionHandler: @escaping @Sendable (URL?, URLResponse?, (any Error)?) -> Void) -> URLSessionDownloadTask
```

## Parameters

- `request`: A URL request object that provides the URL, cache policy, request type, body data or body stream, and so on.
- `completionHandler`: The completion handler to call when the load request is complete. This handler is executed on the delegate queue. If you pass nil, only the session delegate methods are called when the task completes, making this method equivalent to the doc://com.apple.foundation/documentation/Foundation/URLSession/downloadTask(with:)-3fb7s method.

## Return Value

Return Value The new session download task.

## Discussion

Discussion By creating a task based on a request object, you can tune various aspects of the task’s behavior, including the cache policy and timeout interval. By using a completion handler, the task bypasses calls to delegate methods for response and data delivery, and instead provides any resulting NSURL, URLResponse, and NSError objects inside the completion handler. Delegate methods for handling authentication challenges, however, are still called. You should pass a nil completion handler only when creating tasks in sessions whose delegates include a urlSession(_:downloadTask:didFinishDownloadingTo:) method. After you create the task, you must start it by calling its resume() method. If the request completes successfully, the location parameter of the completion handler block contains the location of the temporary file, and the error parameter is nil. If the request fails, the location parameter is nil and the error parameter contain information about the failure. If a response from the server is received, regardless of whether the request completes successfully or fails, the response parameter contains that information.

## See Also

### Adding download tasks to a session

- [downloadTask(with:)](foundation/urlsession/downloadtask(with:)-1onj.md)
- [downloadTask(with:completionHandler:)](foundation/urlsession/downloadtask(with:completionhandler:)-7cuje.md)
- [downloadTask(with:)](foundation/urlsession/downloadtask(with:)-3fb7s.md)
- [downloadTask(withResumeData:)](foundation/urlsession/downloadtask(withresumedata:).md)
- [downloadTask(withResumeData:completionHandler:)](foundation/urlsession/downloadtask(withresumedata:completionhandler:).md)
- [URLSessionDownloadTask](foundation/urlsessiondownloadtask.md)
- [URLSessionDownloadDelegate](foundation/urlsessiondownloaddelegate.md)