Response

Complete API reference for the Response object

Navigation

See how pages expose Response objects from navigation methods

Overview

Response mirrors Playwright’s Response interface and is returned from Stagehand navigation helpers such as page.goto(), page.reload(), page.goBack(), and page.goForward(). It provides a convenient way to inspect the HTTP metadata associated with a navigation, retrieve the response body on demand, and monitor when the underlying request finishes.

Stagehand automatically returns null for navigations that do not yield a network request (for example data: URLs, about:blank, or same-document history changes), matching Playwright’s behaviour.

Getting a Response

const response = await page.goto("https://example.com", {
  waitUntil: "networkidle",
});

if (!response) {
  throw new Error("Navigation did not produce a network response");
}

console.log("Status", response.status(), response.statusText());
const body = await response.text();

When a navigation does not produce a response object you will receive null, allowing you to branch early:

const inline = await page.goto("data:text/html,<h1>inline</h1>");
if (inline === null) {
  // No network fetch happened; handle accordingly
}

Status & Metadata

url()

response.url(): string

Returns the final URL associated with the navigation request.

status()

response.status(): number

Returns the HTTP status code.

statusText()

response.statusText(): string

Returns the human-readable status text (for example OK).

ok()

response.ok(): boolean

Convenience helper that resolves to true for 2xx responses and false otherwise.

frame()

response.frame(): Frame | null

Returns the Stagehand Frame that initiated the navigation. When the frame is no longer available, null is returned.

fromServiceWorker()

response.fromServiceWorker(): boolean

Indicates whether the response was served from a Service Worker fetch handler.

securityDetails()

await response.securityDetails(): Promise<Protocol.Network.SecurityDetails | null>

Resolves with TLS/security metadata when available (issuer, protocol, validity window). Returns null for insecure or non-network responses.

serverAddr()

await response.serverAddr(): Promise<{ ipAddress: string; port: number } | null>

Provides the remote IP/port reported by Chrome, when known.

Header Helpers

headers()

response.headers(): Record<string, string>

Returns a lowercase header map, matching Playwright’s headers() behaviour.

allHeaders()

await response.allHeaders(): Promise<Record<string, string>>

Includes additional headers only surfaced via Chrome’s responseReceivedExtraInfo event (such as set-cookie).

headerValue()

await response.headerValue(name: string): Promise<string | null>

Returns a comma-joined string of all values for the specified header. Resolves to null when the header is absent.

headerValues()

await response.headerValues(name: string): Promise<string[]>

Returns an array of header values, keeping multiple entries separate.

headersArray()

await response.headersArray(): Promise<Array<{ name: string; value: string }>>

Returns the header list while preserving the original casing and order reported by the browser.

Body Helpers

body()

await response.body(): Promise<Buffer>

Fetches the raw response body. The buffer is base64-decoded for you when Chrome sends it that way.

text()

await response.text(): Promise<string>

Returns the response body decoded as UTF-8 text.

json()

await response.json<T = unknown>(): Promise<T>

Parses the response body as JSON. Throws if the body cannot be parsed or is not valid JSON.

All body helper calls (body(), text(), json()) only succeed once the browser reports the response body is available. Stagehand handles this timing automatically.

Completion

finished()

await response.finished(): Promise<null | Error>

Resolves to null when the main navigation request completes successfully, or to an Error if Chrome reports Network.loadingFailed. This mirrors Playwright’s response.finished() contract and is especially helpful for catching late failures such as network resets or blocked responses.

const result = await response.finished();
if (result instanceof Error) {
  console.error("Navigation failed", result.message);
}

Usage Patterns

Inspect status and headers

const response = await page.goto("https://httpbin.org/headers");

if (response) {
  console.log(response.status(), response.statusText());
  const headers = await response.headersArray();
  headers.forEach(({ name, value }) => {
    console.log(`${name}: ${value}`);
  });
}

Handle non-network navigations

const result = await page.goto("data:text/html,<p>inline</p>");

if (result === null) {
  console.log("No network response (data URL)");
} else {
  // Process as usual
}

Await completion

const response = await page.goto("https://example.com/slow");

if (response) {
  const finished = await response.finished();
  if (finished instanceof Error) {
    console.error("Navigation failed", finished.message);
  }
}

Returned From

• await page.goto(url, options?)
• await page.reload(options?)
• await page.goBack(options?)
• await page.goForward(options?)

Each method resolves with Response | null depending on whether Chrome reported a document-level network response.

See Also

• Page reference for details on navigation helpers