---
title: "Update browser session"
method: PATCH
path: "/browsers/{id_or_name}"
tags: ["Browsers"]
---

# Update browser session

`PATCH /browsers/{id_or_name}`

Update a browser session.

## Path parameters

- `id_or_name` string, required

## Request body

- BrowserUpdateRequest — Request body for updating a browser session.
  - `name` string, nullable — Human-readable name for the browser session. Omit to leave unchanged, set to an empty string to clear the name. When set, must be unique among active sessions within the project.
  - `tags` Tags — User-defined key-value tags.
  - `proxy_id` string, nullable — ID of the proxy to use. Omit to leave unchanged, set to empty string to remove proxy.
  - `disable_default_proxy` boolean — If true, stealth browsers connect directly instead of using the default stealth proxy.
  - `profile` union — Profile selection for the browser session. Provide either id or name. If specified, the matching profile will be loaded into the browser session. Profiles must be created beforehand.
    - object
      - `id` string, required — Profile ID to load for this browser session
      - `name` string — Profile name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
      - `save_changes` boolean — If true, save changes made during the session back to the profile when the session ends.
    - object
      - `id` string — Profile ID to load for this browser session
      - `name` string, required — Profile name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
      - `save_changes` boolean — If true, save changes made during the session back to the profile when the session ends.
  - `viewport` BrowserViewportUpdate — Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). For GPU images, the default is 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60, 768x1024@60, 390x844@60. For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable).
    - `width` integer, required — Browser window width in pixels. Any positive integer is accepted.
    - `height` integer, required — Browser window height in pixels. Any positive integer is accepted.
    - `refresh_rate` integer — Display refresh rate in Hz. Any positive integer is accepted; if omitted, automatically determined from width and height.
    - `force` boolean — If true, allow the viewport change even when a live view or recording/replay is active. Active recordings will be gracefully stopped and restarted at the new resolution as separate segments. If false (default), the resize is refused when a live view or recording is active.
  - `telemetry` BrowserTelemetryRequestConfig — Telemetry request configuration for a browser session.
    - `enabled` boolean — Request shortcut for browser telemetry capture. True enables capture; with no browser category settings it captures the default set (control, connection, system, captcha), and any browser category settings are layered onto that default set. On update, enabled=true resolves the config fresh from the default set plus any provided categories, replacing the session's current selection rather than merging onto it; omit enabled to merge categories onto the current selection instead. False stops capture on update and starts no capture on create. enabled=false cannot be combined with browser category settings.
    - `browser` BrowserTelemetryCategoriesConfig — Per-category telemetry capture settings layered onto the default set. The operational signals (control, connection, system, captcha) are on by default and are opt-out: set one to enabled=false to stop capturing it. The CDP categories (console, network, page, interaction) and screenshot are off by default and are opt-in: set enabled=true to capture them.
      - `console` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `page` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `interaction` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `network` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `control` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `connection` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `system` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `screenshot` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `captcha` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.

## Response `200`

Browser session updated successfully

- Browser
  - `created_at` string, date-time, required — When the browser session was created.
  - `cdp_ws_url` string, required — Websocket URL for Chrome DevTools Protocol connections to the browser session
  - `webdriver_ws_url` string, required — Websocket URL for WebDriver BiDi connections to the browser session
  - `browser_live_view_url` string — Remote URL for live viewing the browser session. Only available for non-headless browsers.
  - `base_url` string — Metro-API HTTP base URL for this browser session.
  - `headless` boolean, required — Whether the browser session is running in headless mode.
  - `stealth` boolean, required — Whether the browser session is running in stealth mode.
  - `gpu` boolean — Whether GPU acceleration is enabled for the browser session (only supported for headful sessions).
  - `session_id` string, required — Unique identifier for the browser session
  - `name` string — Human-readable name of the browser session, if one was set at creation.
  - `timeout_seconds` integer, required — The number of seconds of inactivity before the browser session is terminated.
  - `profile` Profile — Browser profile metadata.
    - `id` string, required — Unique identifier for the profile
    - `name` string, nullable — Optional, easier-to-reference name for the profile
    - `created_at` string, date-time, required — Timestamp when the profile was created
    - `updated_at` string, date-time — Timestamp when the profile was last updated
    - `last_used_at` string, date-time — Timestamp when the profile was last used
  - `proxy_id` string — ID of the proxy associated with this browser session, if any.
  - `pool` BrowserPoolRef — Browser pool this session was acquired from, if any.
    - `id` string, required — Browser pool ID
    - `name` string — Browser pool name, if set
  - `viewport` BrowserViewport — Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). For GPU images, the default is 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60, 768x1024@60, 390x844@60. For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable).
    - `width` integer, required — Browser window width in pixels. Any positive integer is accepted.
    - `height` integer, required — Browser window height in pixels. Any positive integer is accepted.
    - `refresh_rate` integer — Display refresh rate in Hz. Any positive integer is accepted; if omitted, automatically determined from width and height.
  - `kiosk_mode` boolean — Whether the browser session is running in kiosk mode.
  - `start_url` string — URL the session was asked to navigate to on creation, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded.
  - `chrome_policy` object — Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names.
  - `tags` Tags — User-defined key-value tags.
  - `deleted_at` string, date-time — When the browser session was soft-deleted. Only present for deleted sessions.
  - `usage` BrowserUsage — Session usage metrics.
    - `uptime_ms` integer, required — Time in milliseconds the session was actively running.
  - `telemetry` BrowserTelemetryConfig — Active telemetry configuration for a browser session.
    - `browser` BrowserTelemetryCategoriesConfig — Per-category telemetry capture settings layered onto the default set. The operational signals (control, connection, system, captcha) are on by default and are opt-out: set one to enabled=false to stop capturing it. The CDP categories (console, network, page, interaction) and screenshot are off by default and are opt-in: set enabled=true to capture them.
      - `console` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `page` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `interaction` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `network` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `control` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `connection` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `system` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `screenshot` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `captcha` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.

## Other responses

- `400` — Bad Request – invalid input
- `401` — Unauthorized – missing or invalid authorization token
- `403` — Forbidden – insufficient permissions or plan
- `404` — Resource not found
- `409` — Conflict – resource already exists
- `500` — Internal Server Error

---

[API](https://skmtc.net/kernel/apis/kernel-api.md) · [All operations](https://skmtc.net/kernel/apis/kernel-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kernel/kernel-api/versions/9e8ce9fcf5e1/schema)