A task, such as downloading a specific resource, to be undertaken by a URL session.


The NSURLSessionTask class is the base class for tasks in a URL session. Tasks are always part of a session; you create a task by calling one of the task creation methods on an NSURLSession object. The method you call determines the type of task.

URL sessions provide three types of tasks: data tasks, upload tasks, and download tasks. These tasks are instances of the NSURLSessionDataTask, NSURLSessionUploadTask, NSURLSessionDownloadTask, NSURLSessionStreamTask subclasses of NSURLSessionTask, respectively.

  • Data tasks request a resource, returning the server’s response as one or more NSData objects in memory. They are supported in default, ephemeral, and shared sessions, but are not supported in background sessions.

  • Upload tasks are like data tasks, except that they make it easier to provide a request body so you can upload data before retrieving the server’s response. Additionally, upload tasks are supported in background sessions.

  • Download tasks download a resource directly to a file on disk. Download tasks are supported in any type of session.

  • Stream tasks establish a TCP/IP connection from a host name and port or a net service object.

After you create a task, you start it by calling its resume method. The session then maintains a strong reference to the task until the request finishes or fails; you do not need to maintain a reference to the task unless it is useful to do so for your app’s internal bookkeeping purposes.


Controlling the Task State


Cancels the task.


Resumes the task, if it is suspended.


Temporarily suspends a task.


The current state of the task—active, suspended, in the process of being canceled, or completed.


The relative priority at which you’d like a host to handle the task, specified as a floating point value between 0.0 (lowest priority) and 1.0 (highest priority).

Obtaining Task Progress


A representation of the overall task progress


The number of bytes that the task expects to receive in the response body.


The number of bytes that the task has received from the server in the response body.


The number of bytes that the task expects to send in the request body.


The number of bytes that the task has sent to the server in the request body.

Obtaining General Task Information


The URL request object currently being handled by the task.


The original request object passed when the task was created.


The server’s response to the currently active request.


An app-provided description of the current task.


An identifier uniquely identifies the task within a given session.


An error object that indicates why the task failed.

Scheduling Tasks


A best-guess upper bound on the number of bytes the client expects to receive.


A best-guess upper bound on the number of bytes the client expects to send.


The earliest date at which the network load should begin.



Constants for determining the current state of a task.

URL Session Task Priority

Constants for providing task priority hints to a host, used with the priority property.


Inherits From

See Also

First Steps

Fetching Website Data into Memory

Receive data directly into memory by creating a data task from a URL session.

Uploading Data to a Website

Post data from your app to servers.

Downloading Files in the Background

Create tasks that download files while your app is inactive.


An object that coordinates a group of related network data transfer tasks.


A configuration object that defines behavior and policies for a URL session.