Responses

Every request resolves with a Response. The whole body has already arrived by then. There's no stream to consume, so you can read it as often as you like.

const res = await session.get("https://httpbin.org/json");
console.log(res.ok, res.status, res.usedProtocol); // true 200 HTTP/2.0

// Every header value is an array.
console.log(res.headers["Content-Type"]); // [ 'application/json' ]

const data = await res.json(); // or res.text(), or res.body
console.log(data.slideshow.title); // Sample Slide Show

PropertiesCopy Anchor Link

MethodsCopy Anchor Link

text()Copy Anchor Link

res.text(): Promise<string>

The body as a string (same as res.body).

json<T>()Copy Anchor Link

res.json<T>(): Promise<T>

The body parsed with JSON.parse. Rejects with a SyntaxError if the body isn't JSON, including the error text of a status: 0 response.

Headers are arraysCopy Anchor Link

res.headers maps each header name to a string[], because a header can appear more than once (Set-Cookie usually does). Names come back in canonical case: Content-Type, not content-type.

const type = res.headers["Content-Type"]?.[0]; // "application/json"
const setCookies = res.headers["Set-Cookie"] ?? [];

The TypeScript type is Node's IncomingHttpHeaders, which says string. Treat every value as an array regardless.

Binary downloadsCopy Anchor Link

The body is a string. For images, PDFs and other binary files, pass byteResponse: true. The body then comes back as a data: URL that you can decode:

const image = await session.get("https://httpbin.org/image/png", {
  byteResponse: true,
});
// The body is a data URL: data:image/png;base64,iVBORw0KGgo…
const base64 = image.body.slice(image.body.indexOf(",") + 1);
writeFileSync("image.png", Buffer.from(base64, "base64"));

The MIME type in the data URL is sniffed from the content, not taken from the Content-Type header.

Failed requestsCopy Anchor Link

When a request doesn't get an HTTP response at all (DNS failure, refused connection, TLS error, proxy error, timeout), the promise still resolves. status is 0, ok is false, and body holds the error message:

const failed = await session.get("https://does-not-exist.invalid/");
if (failed.status === 0) {
  console.log(failed.body); // failed to do request: … no such host
}

res.json() on such a response rejects with a SyntaxError, so check status first. See Errors and debugging for a helper.

Which protocol was usedCopy Anchor Link

res.usedProtocol is "HTTP/1.1", "HTTP/2.0" or "HTTP/3.0". HTTP/2 is normal for browser profiles. See HTTP/3 and Connection tuning to change it.