Range

The HTTP Range request header is included by the client to indicate to the server which subset of a document it returns with the HTTP response.

Usage

The HTTP Range request header is used to retrieve parts of a document. Multiple ranges can be specified in a single HTTP request and will be returned as such, provided the server supports range requests.

Clients can check to see if a server supports range requests by first submitting an HTTP HEAD request. If the server includes the HTTP Accept-Ranges header with a value other than Accept-Ranges: none, then it supports range requests.

The directives are unit, range-start, range-end, and suffix-length.

The unit specifies the data type in which ranges are specified. Typically, this is bytes. The range-start is a mandatory value that indicates the starting index, assuming the specified unit, of the document. The range-end is an optional value to indicate the last index in the range to be retrieved. If this range-end is not included then it is assumed to be the end of the document. The suffix-length, which is also optional, indicates the number of units and the end of the document to return with the HTTP response.

If a Range Request is successful then the server will return with the 206 Partial Content status code. Generally, when range requests fail, it is because the range is invalid. If, for example, the range is out of bounds then the server may return the 416 Range Not Satisfiable status code. In other instances, the entire resource will be returned and the request for a specific range or ranges is ignored.

Syntax

Range: <unit>=<range-start>
Range: <unit>=<range-start>-<range-end>
Range: <unit>=<range-start>-<range-end>, …, <range-start>-<range-end>
Range: <unit>=-<suffix-length>

Example

In this example, the client has requested the first 1000 bytes of a large JPEG image file. The server responds with the 206 Partial Content status code, and the HTTP Content-Range header indicates which byte range is sent, as well as the total length of the file.

Request

GET /largeimage.jpg HTTP/1.1
Host: www.example.re
Range: bytes=0-999

Response

HTTP/1.1 206 Partial Content
Content-Type: image/jpeg
Content-Length: 1000
Content-Range: bytes 0-999/25000

<1000 bytes of image data are included in the message body>

Takeaway

The HTTP Range request header is used by a client to tell the server which parts of a document it wants to receive in the HTTP response to an HTTP GET request.

See also

Last updated: August 2, 2023