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();
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
}
url()
Returns the final URL associated with the navigation request.
status()
response.status(): number
statusText()
response.statusText(): string
OK).
ok()
Convenience helper that resolves to true for 2xx responses and false otherwise.
frame()
response.frame(): Frame | null
Frame that initiated the navigation. When the frame is no longer available, null is returned.
fromServiceWorker()
response.fromServiceWorker(): boolean
securityDetails()
await response.securityDetails(): Promise<Protocol.Network.SecurityDetails | null>
null for insecure or non-network responses.
serverAddr()
await response.serverAddr(): Promise<{ ipAddress: string; port: number } | null>
response.headers(): Record<string, string>
headers() behaviour.
await response.allHeaders(): Promise<Record<string, string>>
responseReceivedExtraInfo event (such as set-cookie).
await response.headerValue(name: string): Promise<string | null>
null when the header is absent.
await response.headerValues(name: string): Promise<string[]>
await response.headersArray(): Promise<Array<{ name: string; value: string }>>
Body Helpers
body()
await response.body(): Promise<Buffer>
text()
await response.text(): Promise<string>
json()
await response.json<T = unknown>(): Promise<T>
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>
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
