Skip to content
Cloudflare Docs
Workers
Cloudflare Docs
Workers
Search icon (depiction of a magnifying glass)
GitHub icon
Visit Workers on GitHub
Set theme to dark (⇧+D)

Request

The Request interface represents an HTTP request, and is part of the Fetch API.

Background

The most common way you’ll encounter a Request object is as a property of an incoming FetchEvent.

addEventListener("fetch", event => {  let request = event.request // Request object
  // ...})

You may also want to construct a Request yourself when you need to modify a request object, because a FetchEvent’s request property is immutable.

addEventListener("fetch", event => {  const request = event.request  const url = "https://example.com"
  const modifiedRequest = new Request(url, {    body: request.body,    headers: request.headers,    method: request.method,    redirect: request.redirect  })
  // ...})

The global fetch method itself invokes the Request constructor, thus the RequestInit and RequestInitCfProperties types defined below also describe the valid parameters that can be passed to fetch.

Constructor

let request = new Request(input [, init])

Parameters

  • input string | Request

    • Either a string that contains a URL, or an existing Request object.

  • init RequestInit optional

    • Optional options object that contains settings to apply to the Request.

RequestInit

  • cf RequestInitCfProperties optional

    • Cloudflare-specific properties that can be set on the Request that control how Cloudflare’s edge handles the request.

  • method string optional

    • The HTTP request method. The default is GET.

  • headers Headers optional

  • body string | ReadableStream | FormData | URLSearchParams optional

    • The request body, if any.

  • redirect string optional

    • The redirect mode to use: follow, error, or manual. The default for a new Request object is follow. Note, however, that the incoming Request property of a FetchEvent will have redirect mode manual.

RequestInitCfProperties

An object containing Cloudflare-specific properties that can be set on the Request object. For example:

// Disable ScrapeShield for this request.fetch(event.request, { cf: { scrapeShield: false } })

Invalid or incorrectly-named keys in the cf object will be silently ignored. Consider using TypeScript and @cloudflare/workers-types to ensure proper use of the cf object.

Properties

All properties of an incoming Request object (i.e. event.request) are read only. To modify a request, you must create a new Request object and pass the options to modify to its constructor.

  • body ReadableStream read-only

    • Stream of the body contents.

  • bodyUsed Boolean read-only

    • Declares whether the body has been used in a response yet.

  • cf IncomingRequestCfProperties read-only

    • An object containing properties about the incoming request provided by Cloudflare’s edge network.

  • headers Headers read-only

  • method string read-only

    • Contains the request’s method, e.g. GET, POST, etc.

  • redirect string read-only

    • Contains the mode for how redirects are handled. It may be one of follow, error, or manual.

  • url string read-only

    • Contains the URL of the request.

IncomingRequestCfProperties

In addition to the properties on the standard Request object, the request.cf object on an inbound Request contains information about the request provided by Cloudflare’s edge.

  • asn string

    • ASN of the incoming request, e.g. 395747.

  • colo string

    • The three-letter airport code of the data center that the request hit, e.g. "DFW".

  • tlsCipher string

    • The cipher for the connection to Cloudflare, e.g. "AEAD-AES128-GCM-SHA256".

  • country string | null

    • Country of the incoming request. The two-letter country code in the request. This is the same value as that provided in the CF-IPCountry header, e.g. "US".

  • tlsClientAuth Object | null

    • Only set when using Cloudflare Access. Object with the following properties: certIssuerDNLegacy, certIssuerDN, certIssuerDNRFC2253, certSubjectDNLegacy, certVerified, certNotAfter, certSubjectDN, certFingerprintSHA1, certNotBefore, certSerial, certPresented, certSubjectDNRFC2253.

  • tlsVersion string

    • The TLS version of the connection to Cloudflare, e.g. TLSv1.3.

  • requestPriority string | null

    • The browser-requested prioritization information in the request object, e.g. "weight=192;exclusive=0;group=3;group-weight=127".

  • city string | null

    • City of the incoming request, e.g. "Austin".

  • continent string | null

    • Continent of the incoming request, e.g. "NA".

  • httpProtocol string

    • HTTP Protocol, e.g. "HTTP/2".

  • latitude string | null

    • Latitude of the incoming request, e.g. "30.27130".

  • longitude string | null

    • Longitude of the incoming request, e.g. "-97.74260".

  • postalCode string | null

    • Postal code of the incoming request, e.g. "78701".

  • metroCode string | null

    • Metro code (DMA) of the incoming request, e.g. "635".

  • region string | null

  • regionCode string | null

  • timezone string

    • Timezone of the incoming request, e.g. "America/Chicago".

Methods

Instance methods

These methods are only available on an instance of a Request object or through its prototype.

  • clone() Promise<Request>

    • Creates a copy of the Request object.

  • arrayBuffer() Promise<ArrayBuffer>

    • Returns a promise that resolves with an ArrayBuffer representation of the request body.

  • formData() Promise<FormData>

    • Returns a promise that resolves with a FormData representation of the request body.

  • json() Promise<Object>

    • Returns a promise that resolves with a JSON representation of the request body.

  • text() Promise<string>

    • Returns a promise that resolves with a string (text) representation of the request body.

The request context

The Request context is the context of the "fetch" event callback. It is important to note that due to how workers are executed, asynchronous tasks (e.g. fetch) can only be run inside the request context.

The request context is available inside of the FetchEvent handler:

addEventListener("fetch", event => {  // Request context available here  event.respondWith(/*...*/)})

When passing a promise to fetch event .respondWith()

If you pass a Response promise to the fetch event .respondWith() method, the request context is active during any asynchronous tasks which run before the Response promise has settled. You can pass the event to an async handler, for example:

addEventListener("fetch", event => {  event.respondWith(eventHandler(event))})
// No request context available here
async function eventHandler(event){  // Request context available here  return new Response("Hello, Workers!")}

Errors when attempting to access an inactive Request context

Any attempt to use APIs such as fetch() or access the Request context during script startup will throw an exception:

const promise = fetch("https://example.com/") // Errorasync function eventHandler(event){..}

This code snippet will throw during script startup, and the "fetch" event listener will never be registered.