> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stagehand.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Response

> Complete API reference for the Response object

export const V3Banner = () => null;

<V3Banner />

<CardGroup cols={1}>
  <Card title="Navigation" icon="compass" href="/v3/references/page">
    See how pages expose Response objects from navigation methods
  </Card>
</CardGroup>

## Overview

`Response` mirrors Playwright’s [Response](https://playwright.dev/docs/api/class-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

```typescript theme={null}
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:

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

## Status & Metadata

### url()

```typescript theme={null}
response.url(): string
```

Returns the final URL associated with the navigation request.

### status()

```typescript theme={null}
response.status(): number
```

Returns the HTTP status code.

### statusText()

```typescript theme={null}
response.statusText(): string
```

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

### ok()

```typescript theme={null}
response.ok(): boolean
```

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

### frame()

```typescript theme={null}
response.frame(): Frame | null
```

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

### fromServiceWorker()

```typescript theme={null}
response.fromServiceWorker(): boolean
```

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

### securityDetails()

```typescript theme={null}
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()

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

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

## Header Helpers

### headers()

```typescript theme={null}
response.headers(): Record<string, string>
```

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

### allHeaders()

```typescript theme={null}
await response.allHeaders(): Promise<Record<string, string>>
```

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

### headerValue()

```typescript theme={null}
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()

```typescript theme={null}
await response.headerValues(name: string): Promise<string[]>
```

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

### headersArray()

```typescript theme={null}
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()

```typescript theme={null}
await response.body(): Promise<Buffer>
```

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

### text()

```typescript theme={null}
await response.text(): Promise<string>
```

Returns the response body decoded as UTF-8 text.

### json()

```typescript theme={null}
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.

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

## Completion

### finished()

```typescript theme={null}
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.

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

## Usage Patterns

### Inspect status and headers

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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](/v3/references/page) for details on navigation helpers