---
name: "up.request"
area: "API"
kind: "JavaScript function"
parent: "up.network module"
url: "https://unpoly.com/api/up.request"
---
# up.request([url], [options])
Makes a request to the given URL.
Returns an [`up.Request`](https://unpoly.com/api/up.Request.md) object which contains information about the request. This request object is also a promise for an [`up.Response`](https://unpoly.com/api/up.Response.md) that contains the response text, headers, etc.
## Example {#example}
```js
let request = up.request('/search', { params: { query: 'sunshine' } })
console.log('We made a request to', request.url)
let response = await request
console.log('The response text is', response.text)
```
## Error handling {#error-handling}
The returned promise will fulfill with an [`up.Response`](https://unpoly.com/api/up.Response.md) when the server responds with an HTTP status of 2xx (like `200`).
When the server responds with an HTTP error code (like `422` or `500`), the promise will _reject_ with [`up.Response`](https://unpoly.com/api/up.Response.md).
When the request fails from a fatal error (like a timeout or loss of connectivity), the promise will reject with an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object.
Here is an example for a complete control flow that handles both HTTP error codes and fatal errors:
```js
try {
let response = await up.request('/search', { params: { query: 'sunshine' } })
console.log('Successful response with text:', response.text)
} catch (e) {
if (e instanceof up.Response) {
console.log('Server responded with HTTP status %s and text %s', e.status, e.text)
} else {
console.log('Fatal error during request:', e.message)
}
}
```
## Caching {#caching}
You may [cache](https://unpoly.com/learn/caching.md) responses by passing a `{ cache }` option. Responses for a cached request will resolve instantly.
See [Caching](https://unpoly.com/learn/caching.md) for more details and examples.
---
## Parameters {#parameters}
### Request {#parameters-request}
#### [url] {#url}
(optional)
The requested URL.
Instead of passing the URL as a string argument, you can also pass it as an `{ url }` option.
Type: string
#### [options.url] {#options.url}
(optional)
The requested URL.
Type: string
#### [options.method='GET'] {#options.method}
(optional)
The HTTP method for the request.
Type: string
#### [options.params={}] {#options.params}
(optional)
[Parameters](https://unpoly.com/api/up.Params.md) that should be sent as the request's [query string](https://en.wikipedia.org/wiki/Query_string) or payload.
When making a `GET` request to a URL with a query string, the given `{ params }` will be added to the query parameters.
Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects) | [up.Params](https://unpoly.com/api/up.Params.md) | [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) | string | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
#### [options.headers={}] {#options.headers}
(optional)
An object of additional HTTP headers.
Unpoly will by default send a number of custom request headers. See [`up.protocol`](https://unpoly.com/api/up.protocol.md) for details.
Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_Objects)
#### [options.wrapMethod] {#options.wrapMethod}
(optional)
Whether to wrap non-standard HTTP methods in a POST request.
If this is set, methods other than GET and POST will be converted to a `POST` request and will carry their original method as a `_method` parameter. This is to [prevent unexpected redirect behavior](https://makandracards.com/makandra/38347).
Defaults to [`up.network.config`](https://unpoly.com/api/up.network.config.md#config.wrapMethod).
Type: boolean
#### [options.timeout] {#options.timeout}
(optional)
A timeout in milliseconds.
If the request is queued due to [many concurrent requests](https://unpoly.com/api/up.network.config.md#config.concurrency), the timeout will not include the time spent waiting in the queue.
Type: number
#### [options.contentType] {#options.contentType}
(optional)
The format in which to encode the request params.
Allowed values are `application/x-www-form-urlencoded` and `multipart/form-data`. Only `multipart/form-data` can transport binary data.
If this option is omitted Unpoly will prefer `application/x-www-form-urlencoded`, unless request params contains binary data.
Type: string
#### [options.payload] {#options.payload}
(optional)
A custom payload for this request.
By default Unpoly will build a payload from the given `{ params }` option. Therefore this option is not required when making a standard link or form request to a server that renders HTML.
A use case for this option is talking to a JSON API that expects requests with a `application/json` payload.
If a `{ payload }` option is given you must also pass a `{ contentType }`.
Type: string
#### [options.background=false] {#options.background}
(optional)
Whether this request will load in the background.
Background requests are deprioritized and won't show the [progress bar](https://unpoly.com/learn/progress-bar.md). See [Background requests](https://unpoly.com/learn/background-requests.md).
Type: boolean
#### [options.lateDelay] {#options.lateDelay}
(optional)
The number of milliseconds after which this request can cause an [`up:network:late`](https://unpoly.com/api/up:network:late.md) event.
Defaults to [`up.network.config.lateDelay`](https://unpoly.com/api/up.network.config.md#config.lateDelay).
Type: number
#### [options.fail] {#options.fail}
(optional)
Whether the response to this request should be considered an [error response](https://unpoly.com/learn/error-responses.md).
By [default](https://unpoly.com/api/up.network.config.md#config.fail), any HTTP status code other than 2xx or 304 is considered an error code. Pass `{ fail: false }` to handle _any_ response as successful, even with a 4xx or 5xx status code.
An error response will cause the [returned promise](#return-value) to reject.
Type: string | boolean | Function([up.Response](https://unpoly.com/api/up.Response.md)): boolean
### Caching {#parameters-caching}
#### [options.cache=false] {#options.cache}
(optional)
Whether to read from and write to the [cache](https://unpoly.com/learn/caching.md).
With `{ cache: true }`, Unpoly will try to reuse a cached response before connecting to the network. If no cached response exists, Unpoly will make a request and cache the server response.
With `{ cache: 'auto' }`, Unpoly will use the cache only if [`up.network.config.autoCache`](https://unpoly.com/api/up.network.config.md#config.autoCache) returns `true` for this request.
With `{ cache: false }` (the default), Unpoly will always make a network request.
Type: boolean
#### [options.expireCache] {#options.expireCache}
(optional)
Whether to [expire](https://unpoly.com/learn/caching.md#expiration) the [cache](https://unpoly.com/learn/caching.md) when this request is sent.
Defaults to the result of [`up.network.config.expireCache`](https://unpoly.com/api/up.network.config.md#config.expireCache), which defaults to expiring the entire cache for a non-GET request. Pass `false` to not expire any cache entries.
You may also pass a [URL pattern](https://unpoly.com/api/url-patterns.md) to only expire matching responses.
Type: boolean | string
#### [options.evictCache] {#options.evictCache}
(optional)
Whether to [evict](https://unpoly.com/learn/caching.md#eviction) the [cache](https://unpoly.com/learn/caching.md) when this request is sent.
Defaults to the result of [`up.network.config.evictCache`](https://unpoly.com/api/up.network.config.md#config.evictCache), which defaults to `false`.
You may also pass a [URL pattern](https://unpoly.com/api/url-patterns.md) to only evict matching responses.
Type: boolean | string
### Render context {#parameters-render-context}
#### [options.target='body'] {#options.target}
(optional)
The CSS selector that will be sent as an [`X-Up-Target`](https://unpoly.com/api/X-Up-Target.md) header.
The targets of concurrent requests to the same URL [may be merged](https://unpoly.com/api/X-Up-Target.md#merging).
Type: string
#### [options.failTarget='body'] {#options.failTarget}
(optional)
The CSS selector that will be sent as an [`X-Up-Fail-Target`](https://unpoly.com/api/X-Up-Fail-Target.md) header.
Type: string
#### [options.layer='current'] {#options.layer}
(optional)
The [layer](https://unpoly.com/api/up.layer.md) this request is associated with.
If this request is intended to update an existing fragment, this is that fragment's layer.
If this request is intended to [open an overlay](https://unpoly.com/learn/opening-overlays.md), the associated layer is the future overlay's parent layer.
Type: string
#### [options.failLayer='current'] {#options.failLayer}
(optional)
The [layer](https://unpoly.com/api/up.layer.md) this request is associated with if the server [sends an HTTP error status](https://unpoly.com/learn/error-responses.md).
Type: string
#### [options.origin] {#options.origin}
(optional)
The DOM element that caused this request to be sent, e.g. a hyperlink or form element.
Type: [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element)
---
## Return value {#return-value}
An object with information about the request.
The request object is also a promise for its [`up.Response`](https://unpoly.com/api/up.Response.md).
Type: [up.Request](https://unpoly.com/api/up.Request.md)