<!--
{
  "availability" : [
    "iOS: 7.0.0 -",
    "iPadOS: 7.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.9.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/URLSessionConfiguration",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSURLSessionConfiguration"
  },
  "title" : "URLSessionConfiguration"
}
-->

# URLSessionConfiguration

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

```
class URLSessionConfiguration
```

## Overview

An [`URLSessionConfiguration`](/documentation/Foundation/URLSessionConfiguration) object defines the behavior and policies to use when uploading and downloading data using an [`URLSession`](/documentation/Foundation/URLSession) object. When uploading or downloading data, creating a configuration object is always the first step you must take. You use this object to configure the timeout values, caching policies, connection requirements, and other types of information that you intend to use with your [`URLSession`](/documentation/Foundation/URLSession) object.

It is important to configure your [`URLSessionConfiguration`](/documentation/Foundation/URLSessionConfiguration) object appropriately before using it to initialize a session object. Session objects make a copy of the configuration settings you provide and use those settings to configure the session. Once configured, the session object ignores any changes you make to the [`URLSessionConfiguration`](/documentation/Foundation/URLSessionConfiguration) object. If you need to modify your transfer policies, you must update the session configuration object and use it to create a new [`URLSession`](/documentation/Foundation/URLSession) object.

> Note:
> In some cases, the policies defined in this configuration may be overridden by policies specified by an ``doc://com.apple.foundation/documentation/Foundation/NSURLRequest`` object provided for a task. Any policy specified on the request object is respected unless the session’s policy is more restrictive. For example, if the session configuration specifies that cellular networking should not be allowed, the ``doc://com.apple.foundation/documentation/Foundation/NSURLRequest`` object cannot request cellular networking.

For more information about using configuration objects to create sessions, see [`URLSession`](/documentation/Foundation/URLSession).

### Types of session configurations

The behavior and capabilities of a URL session are largely determined by the kind of configuration used to create the session.

The singleton shared session (which has no configuration object) is for basic requests. It’s not as customizable as sessions that you create, but it serves as a good starting point if you have very limited requirements. You access this session by calling the shared class method. See that method’s discussion for more information about its limitations.

Default sessions behave much like the shared session (unless you customize them further), but let you obtain data incrementally using a delegate. You can create a default session configuration by calling the default method on the URLSessionConfiguration class.

Ephemeral sessions are similar to default sessions, but they don’t write caches, cookies, or credentials to disk. You can create an ephemeral session configuration by calling the ephemeral method on the URLSessionConfiguration class.

Background sessions let you perform uploads and downloads of content in the background while your app isn’t running. You can create a background session configuration by calling the backgroundSessionConfiguration(_:) method on the URLSessionConfiguration class.

## Topics

### Creating a session configuration object

[`defaultSessionConfiguration`](/documentation/Foundation/URLSessionConfiguration/default)

A default session configuration object.

[`ephemeralSessionConfiguration`](/documentation/Foundation/URLSessionConfiguration/ephemeral)

A session configuration that uses no persistent storage for caches, cookies, or credentials.

[`+  backgroundSessionConfigurationWithIdentifier:`](/documentation/Foundation/URLSessionConfiguration/background(withIdentifier:))

Creates a session configuration object that allows HTTP and HTTPS uploads or downloads to be performed in the background.

[`-  init`](/documentation/Foundation/URLSessionConfiguration/init())

Creates an empty session configuration.

[`+  new`](/documentation/Foundation/URLSessionConfiguration/new())

Creates an empty session configuration.

### Setting general properties

[`identifier`](/documentation/Foundation/URLSessionConfiguration/identifier)

The background session identifier of the configuration object.

[`HTTPAdditionalHeaders`](/documentation/Foundation/URLSessionConfiguration/httpAdditionalHeaders)

A dictionary of additional headers to send with requests.

[`networkServiceType`](/documentation/Foundation/URLSessionConfiguration/networkServiceType)

The type of network service for all tasks within network sessions to enable Cellular Network Slicing.

[`allowsCellularAccess`](/documentation/Foundation/URLSessionConfiguration/allowsCellularAccess)

A Boolean value that determines whether connections should be made over a cellular network.

[`timeoutIntervalForRequest`](/documentation/Foundation/URLSessionConfiguration/timeoutIntervalForRequest)

The timeout interval to use when waiting for additional data.

[`timeoutIntervalForResource`](/documentation/Foundation/URLSessionConfiguration/timeoutIntervalForResource)

The maximum amount of time that a resource request should be allowed to take.

[`sharedContainerIdentifier`](/documentation/Foundation/URLSessionConfiguration/sharedContainerIdentifier)

The identifier for the shared container into which files in background URL sessions should be downloaded.

[`waitsForConnectivity`](/documentation/Foundation/URLSessionConfiguration/waitsForConnectivity)

A Boolean value that indicates whether the session should wait for connectivity to become available, or fail immediately.

[`usesClassicLoadingMode`](/documentation/Foundation/URLSessionConfiguration/usesClassicLoadingMode)

### Setting cookie policies

[`HTTPCookieAcceptPolicy`](/documentation/Foundation/URLSessionConfiguration/httpCookieAcceptPolicy)

A policy constant that determines when cookies should be accepted.

[`HTTPShouldSetCookies`](/documentation/Foundation/URLSessionConfiguration/httpShouldSetCookies)

A Boolean value that determines whether requests should contain cookies from the cookie store.

[`HTTPCookieStorage`](/documentation/Foundation/URLSessionConfiguration/httpCookieStorage)

The cookie store for storing cookies within this session.

[`HTTPCookie`](/documentation/Foundation/HTTPCookie)

A representation of an HTTP cookie.

### Setting security policies

[`TLSMinimumSupportedProtocolVersion`](/documentation/Foundation/URLSessionConfiguration/tlsMinimumSupportedProtocolVersion)

The minimum TLS protocol version that the client should accept when making connections in this session.

[`TLSMaximumSupportedProtocolVersion`](/documentation/Foundation/URLSessionConfiguration/tlsMaximumSupportedProtocolVersion)

The maximum TLS protocol version that the client should request when making connections in this session.

[`URLCredentialStorage`](/documentation/Foundation/URLSessionConfiguration/urlCredentialStorage)

A credential store that provides credentials for authentication.

[`TLSMinimumSupportedProtocol`](/documentation/Foundation/URLSessionConfiguration/tlsMinimumSupportedProtocol)

The minimum TLS protocol to accept during protocol negotiation.

[`TLSMaximumSupportedProtocol`](/documentation/Foundation/URLSessionConfiguration/tlsMaximumSupportedProtocol)

The maximum TLS protocol version that the client should request when making connections in this session.

[`requiresDNSSECValidation`](/documentation/Foundation/URLSessionConfiguration/requiresDNSSECValidation)

### Setting caching policies

[`URLCache`](/documentation/Foundation/URLSessionConfiguration/urlCache)

The URL cache for providing cached responses to requests within the session.

[`requestCachePolicy`](/documentation/Foundation/URLSessionConfiguration/requestCachePolicy)

A predefined constant that determines when to return a response from the cache.

### Supporting background transfers

[`sessionSendsLaunchEvents`](/documentation/Foundation/URLSessionConfiguration/sessionSendsLaunchEvents)

A Boolean value that indicates whether the app should be resumed or launched in the background when transfers finish.

[`discretionary`](/documentation/Foundation/URLSessionConfiguration/isDiscretionary)

A Boolean value that determines whether background tasks can be scheduled at the discretion of the system for optimal performance.

[`shouldUseExtendedBackgroundIdleMode`](/documentation/Foundation/URLSessionConfiguration/shouldUseExtendedBackgroundIdleMode)

A Boolean value that indicates whether TCP connections should be kept open when the app moves to the background.

### Supporting custom protocols

[`protocolClasses`](/documentation/Foundation/URLSessionConfiguration/protocolClasses)

An array of extra protocol subclasses that handle requests in a session.

[`URLProtocol`](/documentation/Foundation/URLProtocol)

An abstract class that handles the loading of protocol-specific URL data.

### Supporting Multipath TCP

[Improving network reliability using Multipath TCP](/documentation/Foundation/improving-network-reliability-using-multipath-tcp)

Use the available radios in iOS devices to improve your app’s network reliability and performance.

[`multipathServiceType`](/documentation/Foundation/URLSessionConfiguration/multipathServiceType-swift.property)

A service type that specifies the Multipath TCP connection policy for transmitting data over Wi-Fi and cellular interfaces.

[`MultipathServiceType`](/documentation/Foundation/URLSessionConfiguration/MultipathServiceType-swift.enum)

Constants that specify the type of service that Multipath TCP uses.

  <doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.networking.multipath>

### Setting HTTP policy and proxy properties

[`HTTPMaximumConnectionsPerHost`](/documentation/Foundation/URLSessionConfiguration/httpMaximumConnectionsPerHost)

The maximum number of simultaneous HTTP/1.1 connections to make to a given host.

[`HTTPShouldUsePipelining`](/documentation/Foundation/URLSessionConfiguration/httpShouldUsePipelining)

A Boolean value that determines whether the session should use HTTP pipelining.

[`proxyConfigurations`](/documentation/Foundation/URLSessionConfiguration/proxyConfigurations)

An array of proxy configuration objects containing information about the proxies to use within this session.

[`proxyConfigurations`](/documentation/Foundation/NSURLSessionConfiguration/proxyConfigurations)

An array of proxy configuration objects containing information about the proxies to use within this session.

[`connectionProxyDictionary`](/documentation/Foundation/URLSessionConfiguration/connectionProxyDictionary)

A dictionary containing information about the proxy to use within this session.

### Supporting connectivity changes

[`waitsForConnectivity`](/documentation/Foundation/URLSessionConfiguration/waitsForConnectivity)

A Boolean value that indicates whether the session should wait for connectivity to become available, or fail immediately.

### Supporting limited modes

[`allowsConstrainedNetworkAccess`](/documentation/Foundation/URLSessionConfiguration/allowsConstrainedNetworkAccess)

A Boolean value that indicates whether connections may use the network when the user has specified Low Data Mode.

[`allowsExpensiveNetworkAccess`](/documentation/Foundation/URLSessionConfiguration/allowsExpensiveNetworkAccess)

A Boolean value that indicates whether connections may use a network interface that the system considers expensive.

### Deprecated methods

[`+  backgroundSessionConfiguration:`](/documentation/Foundation/URLSessionConfiguration/backgroundSessionConfiguration(_:))

Returns a session configuration object that allows HTTP and HTTPS uploads or downloads to be performed in the background.

## Relationships

### Conforms To

[`Equatable`](/documentation/Swift/Equatable)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Hashable`](/documentation/Swift/Hashable)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`CVarArg`](/documentation/Swift/CVarArg)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`NSCopying`](/documentation/Foundation/NSCopying)

[`Sendable`](/documentation/Swift/Sendable)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)