JavaScript fetch: response.json() Promise

If your JavaScript code says the API data exists but you get a Promise instead of the actual data, the problem is often how you handle response.json().
This is a common mistake when working with fetch() and APIs.

The Common Mistake​

Consider this code:

const response = await fetch("/api/users");
const data = response.json();
console.log(data);

At first glance, it looks correct. You wait for fetch(), so you might expect data to contain the users.
But there is an important detail:
response.json() returns a Promise.
It does not immediately return the parsed JSON data.

---

The Correct Way​

Use await when reading the response body:

const response = await fetch("/api/users");
const data = await response.json();
console.log(data);

Now data contains the parsed JSON value returned by the API.

❌ Incorrect​

const data = response.json();

✅ Correct​

const data = await response.json();

The key difference is the await.

---

Why Does This Happen?​

The fetch() function is asynchronous, and reading the response body is also asynchronous.
When you call:

response.json()

JavaScript starts reading and parsing the response, but the result is returned through a Promise.
You can think of it like this:

response.json() // Promise
await response.json() // Parsed JSON data

So if you forget await, you may end up working with a Promise instead of the actual API data.

---

A Simple Example​

Suppose the API returns:

{
"name": "John",
"role": "Developer"
}

With:

const data = response.json();
console.log(data);

data is a Promise.
With:

const data = await response.json();
console.log(data);

data contains the parsed object:

{
name: "John",
role: "Developer"
}

💡 The API may be returning the correct data. The problem can simply be that your code has not awaited the response body yet.

---

The Important Difference​

Keep this distinction in mind when working with fetch():

Code	What you get
fetch(url)	Promise for a Response
await fetch(url)	Response object
response.json()	Promise for parsed JSON
await response.json()	Parsed JSON data

This is why using await in both places is common:

const response = await fetch("/api/users");
const data = await response.json();

The first await waits for the HTTP response.
The second await waits for the response body to be parsed as JSON.

---

Common Debugging Tip​

If your API request appears to work but the variable contains a Promise instead of the expected data, check whether you forgot await before response.json().
You can also inspect the value directly:

console.log(response);
console.log(response.json());

If you see a Promise, that is a strong sign that you are looking at the asynchronous JSON parsing operation rather than its completed result.
🔎 Before rewriting your API code, check the type of value you are actually receiving. The issue may not be the API at all—it may be the way your JavaScript code is handling the Promise.

---

Key Takeaway​

When using fetch(), remember that receiving the HTTP response and reading its JSON body are two separate asynchronous steps.
Use:

const response = await fetch("/api/users");
const data = await response.json();

If response.json() gives you a Promise, that is expected. Use await to get the parsed JSON data.

---

Frequently Asked Questions​

------------------

Why does response.json() return a Promise?​

Because the response body may need to be read and parsed asynchronously. response.json() returns a Promise that resolves to the parsed JSON data.

Do I need await for both fetch() and response.json()?​

When using async/await, you normally use await for both operations:

const response = await fetch("/api/users");
const data = await response.json();

Is response.json() returning undefined?​

Not normally. response.json() returns a Promise. If you are seeing undefined, there may be another issue in your code, such as accessing a missing property, not returning a value from a function, or using the data before the Promise has resolved.