Skip to main content
Browser resources are the evidence and control-plane objects around a managed browser. They are how browser work becomes inspectable, reviewable, and useful to another process.
ResourceUse it forCommon surface
PagesInspect active and open browser pages.SDK, CLI, REST
FilesStage browser-readable files or retrieve generated files.SDK, REST
DownloadsCapture files produced by a site.SDK, CLI, REST
DialogsAccept or dismiss JavaScript dialogs.SDK, CLI, REST
PermissionsGrant, deny, clear, or reset browser permissions.SDK, REST
RecordingsReplay a browser run after it finishes.SDK, CLI, REST
EventsFollow runtime activity over time.SDK, REST
Browser-agent workflows surface important resources through result.artifacts, result.steps, status, and browser IDs. Use direct resource APIs when your application needs lower-level control.

​
Common recipes

​
Upload a file

const file = await browser.files.createFromPath("./contract.pdf", {
  name: "contract.pdf",
});

await browser.playwright.execute({
  code: `
    const inputPath = await files.path("${file.id}");
    await page.getByLabel("Upload").setInputFiles(inputPath);
  `,
});
Inside Playwright execution, use files.path(fileId) to resolve a staged file to a runtime-local path. Prefer staged files over embedding large data directly into prompts.

​
Save a download

const downloads = await browser.downloads.list();
const firstDownload = downloads.data[0];

if (firstDownload) {
  await browser.downloads.save(firstDownload.id, "./downloaded-report.pdf");
}
Use maxBytes and overwrite in production: 
await browser.downloads.save(firstDownload.id, "./downloads/report.pdf", {
  maxBytes: 25_000_000,
  overwrite: true,
});

​
Handle a dialog

const dialogs = await browser.dialogs.list({ status: "open" });
const dialog = dialogs.data[0];

if (dialog?.type === "confirm") {
  await browser.dialogs.dismiss(dialog.id);
}
Handle dialogs deliberately. A confirm dialog can represent a destructive or irreversible action.

​
Grant and clear permissions

await browser.permissions.grant({
  origin: "https://example.com",
  permissions: ["geolocation"],
  geolocation: { latitude: 37.7749, longitude: -122.4194 },
});

await browser.permissions.clear({ origin: "https://example.com" });
Grant permissions only for the origin that needs them, then clear overrides when the workflow is done.

​
Inspect events

const events = await browser.events({
  category: "browser",
  limit: 50,
});

console.log(events.data);
Use events and recordings together when a run needs an audit trail.

​
Download recording evidence

const segments = await browser.recordings.segments({ limit: 5 });
const segment = segments.data[0];

if (segment) {
  await browser.recordings.download(segment.id, "./recordings", {
    overwrite: true,
  });
}
Recordings require recording: true when the browser is created.

​
Inspect pages

const pages = await browser.pages();
const active = pages.find((page) => page.active);

console.log(active?.url, active?.title);
Use page IDs only when targeting a known non-active page. Ordinary Playwright execution should use the active page.

​
Check blockers and CAPTCHA state

const status = await browser.status();
const captcha = await browser.captcha.status();

return {
  readiness: status.readiness,
  blocker: status.blocker?.state,
  captcha: captcha.captcha?.state,
};
Return blocker evidence when a workflow cannot continue. Do not describe CAPTCHA or WAF handling as guaranteed access. Reference: SDK resources reference, SDK browser reference, and API reference.