Guide to using the Fetch API in JavaScript

The Fetch API is the modern way to send and receive data in JavaScript.

The syntax for fetching some data is simple:


This immediately returns a promise that resolves to a Response object. This provides you with information about the status of the response and headers the data is read.

.then((res) => {
  console.log(res.status); // 200
  console.log(res.statusText); // OK
  // Headers { "content-length" → "456", "content-type" → "application/json" }

The data can be read from the Response object via a ReadableStream on its body property. This also returns a promise.

You can read it by calling a method on the Response object. The most common is res.json() to read data that is in JSON format to a JS object:

.then(res => res.json()) // Wait for Response object and read to JS object
.then(data => console.log(data)) // Wait for ReadableStream to be read
.catch(err => console.error(err)) // Runs if error occurs in previous steps

It’s also possible to read the data into a file container using res.blob() or string format with res.text().

An error is not throw automaticaly if you receive an non-success response code to your request. To add this, you can query the statusText and status (response code) properties on the Response object:

.then(res => {
    if (!res.statusText === "OK") {
        throw new Error(`Bad server response (${res.status})`);
    return res.json();
.then(data => console.log(data))
.catch(err => console.log(err)); // Now runs if there is a bad response code

Sending data

You can make a POST request with Fetch by passing in a configuration object as a second argument when calling it.

Setting a value for a method property determines the type of request and the data to be sent is set on body:

const obj = { a: "1", b: "2", c: "3" };
const payload = JSON.stringify(obj);

fetch('', {
  method: "POST",
  body: payload,
  headers: {
    "Content-type": "application/json",
.then(res => res.json())
.then(data => console.log(data))

If sending a form data payload created using the FormData() constructor, you do not need to set any headers as these will be set automatically. Doing so can cause an error.

With async/await

Because fetch() returns a promise (and so does reading the data from its Response object) its result can be handled using async/await syntax, using the await keyword to await the results of the promises.

Errors can be handled in a catch block that runs if the fetch request, made in a try block, fails:

async function getData(url) {
  try {
    const res = await fetch(url); // Wait for Repsonse object
    const data = await res.json(); // Wait for parsing of data
  } catch(err) {
    console.error(err); // Runs if there is an error in try block


Download progress

It is possible to track the download progress of a fetch request, though a little long-winded.

To do so, call getReader() on the body of the response to generate a new reader. Download progress can be obtained via calling read() on it and accessing its result, which is in an object returned in a promise every time a chunk of data is read.

At the same time, the data being read needs to be returned in a promise to the next .then() method. Therefore, this entire process is nested in the creation of a new Response object with a ReadableStream on it.

.then(res => {
  const contentLength = res.headers.get('content-length');
  let loaded = 0;
  // Create new Response object with ReadableStream:
  return new Response(
    new ReadableStream({
      start(controller) {
        // At the same time read body of original response with progress:
        const reader = res.body.getReader();
        (function read() {

          .then((progressEvent) => {
            if (progressEvent.done) {
            loaded += progressEvent.value.byteLength;
            // Push new read value into new ReadableStream:
.then(res => res.blob()) // Reads new ReadableStream
.then(blob => {
  const url = URL.createObjectURL(blob); // Creates URL to blob
  const img = new Image();
  img.src = url; // Sets as src of new image
  document.body.appendChild(img); // Inserts image in DOM