Skip to main content
A network policy is a saved list of domains. A session opened with a policy can reach only what the policy allows. Edit the policy and every running session that uses it follows within seconds. Policies cost nothing.

Create a policy

Get an API key in the Quickstart. Name the policy, then list domains. This one is an allowlist: it blocks everything except example.com and bun.com.
To block a few sites and allow the rest, leave defaultAction out, which means allow, and list the sites in block.domains. A domain such as example.com covers itself and every subdomain. When two entries match, the most specific wins. Domains are trimmed, lower-cased and de-duplicated, and a leading *. is dropped.

Apply it to a session

Send the policy id as networkPolicyId when you open the session.
The session answer shows networkPolicyId and networkPolicyVersion, the version of the policy the session enforces now. Visit one allowed site and one blocked site with Execute:
The real result:
A blocked domain fails to connect, so the page does not load. Blocks apply to every request the session makes, not only to the address you open. For a short list that belongs to one session, send allowedDomains instead, up to 100 domains. Only those domains load. It cannot be sent with networkPolicyId.

Change a running session

PATCH /v1/browser/network-policies/{policy_id} changes the policy and every running session that uses it. Each field you send replaces the old one, and a list replaces the whole list. This adds example.org:
The change reached the running session before the call answered: appliedSessions is 1 and the session now shows networkPolicyVersion 2. The same visit then returned Example Domain for both sites. A session the call could not reach is in pendingSessionIds, and the change is retried every few seconds until it arrives. A session behind the policy’s version has not received the change yet. When a change blocks a host, open connections to it are closed, and closedConnections counts them.

Manage policies

Options

Limits and errors

  • A policy holds at most 10,000 domains in allow and block together, and an account at most 100 policies.
  • A URL, a path, a port, an IP address, another wildcard, or a domain in both lists returns 400 invalidRequest. A real answer for a URL: allow.domains.0: "https://example.com/page": Expected a domain such as example.com. It covers its subdomains too. A leading *. is allowed. URLs, paths, ports, IP addresses and other wildcards are not.
  • Deleting a policy that a running session uses returns 409 invalidRequest: 1 running browser session uses this policy. Close it or wait for it to end, then delete the policy.
  • An unknown policy id returns 404 notFound.