What Is a Headless Browser API (2026 Guide)

The scraper ran fine on a laptop for weeks. Then it moved to a server with no screen, a teammate added more workers to clear a backlog, and by Friday the machine was full of Chrome processes nobody had closed and pages that never finished loading.

That is usually the week a team starts searching for a headless browser API: a hosted service that starts a real browser with no screen when code asks for it, hands back a connection URL that Playwright, Puppeteer or any CDP client can drive, and shuts the browser down when the job ends. The service owns the browser's lifecycle and capacity, while the team's code keeps owning what happens on the page. Solari runs its Cloud Browsers this way, and this guide walks through how the pieces fit, how existing code connects, what it costs and the limits worth planning around.

How a Headless Browser API Works

The term has two halves, and the first is the browser itself. A headless browser is a browser without a graphical interface, and Chrome ships this as Headless mode, so the same engine renders pages, runs JavaScript and stores cookies with nothing drawn on a screen.

The second half is the API, and on Solari it splits the work in two. Plain HTTP calls handle lifecycle only: create a session, check on it, release it. Driving the page happens over a WebSocket, a two-way connection that carries the Playwright wire protocol or raw Chrome DevTools Protocol commands, as the Solari API reference sets out.

That split is what lets existing browser code move without a rewrite, which is the next question most teams ask.

How Existing Playwright or Puppeteer Code Connects

Most teams arrive with scripts already written, so the connection step decides how much of that code survives. A Solari session opens either with the SDK's launch(), which starts the browser and connects in a single call, or with sessions.create(), which returns a cdpEndpoint for the client a team already uses. Playwright attaches to that endpoint with connectOverCDP, and Puppeteer and browser-use connect the same way.

The bring-your-own-client path keeps the Playwright code as it was and adds a release at the end:

import { chromium } from "playwright-core"

const session = await client.sessions.create()
const browser = await chromium.connectOverCDP(session.cdpEndpoint)
try {
  const page = await browser.newPage()
  await page.goto(targetUrl)
} finally {
  await browser.close()
  await client.sessions.releaseAndWait(session.id)
}

import { chromium } from "playwright-core"

const session = await client.sessions.create()
const browser = await chromium.connectOverCDP(session.cdpEndpoint)
try {
  const page = await browser.newPage()
  await page.goto(targetUrl)
} finally {
  await browser.close()
  await client.sessions.releaseAndWait(session.id)
}

import { chromium } from "playwright-core"

const session = await client.sessions.create()
const browser = await chromium.connectOverCDP(session.cdpEndpoint)
try {
  const page = await browser.newPage()
  await page.goto(targetUrl)
} finally {
  await browser.close()
  await client.sessions.releaseAndWait(session.id)
}

The cdpEndpoint and wsEndpoint URLs are credentials: anyone holding one can drive the browser until the session is released or expires. They belong outside logs, error reports and any client-side code a team does not control.

A connected browser starts blank, though, and the session options decide what it starts with.

What the API Adds Beyond a Bare Browser

A local headless Chrome gives an agent a page; a hosted API can also give it a login, a network location and a record of what happened. On Solari every session option is opt-in, and the default is a fast headless browser with no profile, recording, proxy or stealth.

A profile starts the session already signed in, reopening the cookies and site data an earlier run saved, so the agent skips the login form. Stealth makes the browser look and behave like a real person's, and it is the switch that proxies and captcha solving require. Session recording keeps a replay of the run; because it captures input values by default, sessions that type passwords are better left unrecorded.

Each of those options draws on the same balance as the browser itself, so the cost comes next.

What a Headless Browser API Costs

Headless browser APIs are usually priced per browser hour, and on Solari the rate and the limits move together by plan, as the figure below shows.

The rows come from the Solari pricing page, where browsers bill per hour while a session is open. A browser left open costs the same as a browser doing work, which is why the finally block in the code above matters more than any plan choice. Credits refill each month, and Solari bills only from the balance a team holds, so the month closes without an overage invoice.

The concurrency column matters more than the rate once a fleet grows, and that is where the limits come in.

Limits to Plan Around

A hosted API turns resource exhaustion into an error code, and knowing which codes to retry keeps a fleet steady. When an organization reaches its concurrent-session cap, Solari answers with a 429 and the code ConcurrencyLimitExceeded, and retrying does not help: the worker should wait for a session to be released instead.

The 502, 503 and 504 statuses are different. The error reference linked above treats them as transient failures, to be retried with exponential backoff and jitter.

Stealth sessions also carry their own, lower cap, counted in addition to concurrent browsers, so a team can hit the stealth ceiling with ordinary browser slots still free. The max session column in the table is a backstop rather than a timer, since a session that outlives its job keeps billing until it ends.

With the limits in view, the whole picture fits in a short recap.

Choosing the Right Setup

A headless browser API comes down to a browser with no screen, an HTTP lifecycle wrapped around it and a WebSocket that carries the commands. Existing Playwright or Puppeteer code moves over through the endpoint, provided every session is released and its URLs are treated as secrets. Profiles, stealth and recording are added only when the job calls for them. Cost follows the hours a session stays open, and the cap behind the concurrency error above is the signal for a bigger plan rather than a retry loop.

Get Started With Solari

The first step is to point an existing Playwright script at a Solari session and close it in a finally block, with Cloud Browsers Explained as the companion for proxies and replay. Solari makes that the fastest and cheapest way to start: 2,000+ engineers at 100+ companies build on it, the Professional rate in the table above keeps a growing fleet inexpensive, and the same account adds sandboxes and desktops. The Free plan includes $3 of monthly credits, so a free Solari account covers the first sessions.