Skip to content
Browserberg Browserberg

Provenance and routing tiers

Every verb response carries a provenance block. What each field means, how to spot a cached replay that made no model call, and what tier tells you.

Last updated:

What provenance is for

Every verb response — observe, act and extract alike — carries a provenance block. It answers the questions you would otherwise reconstruct from logs and invoices: did this call hit the plan cache, how many inference calls did it make, which routing tier served it, and where in the browser the perception code ran.

The provenance fields

Name Type Description
planCacheHit boolean True when a cached plan was replayed instead of planning afresh. A replay makes no model call.
healApplied boolean True when the cached plan no longer matched the page exactly and was repaired before replay.
inferenceCalls integer How many model calls this request made. Zero for instruction-free observes and clean cache replays.
tier string | null Which routing tier served the inference: performance or sovereign, null when no model was called. The enum is open.
world string Where perception ran. extension means the bundle shipped inside the session browser's extension; cdp-fallback means it was injected over CDP instead.
requestId string The id to quote in a support request, or to correlate with the audit log.
durationMs integer Wall-clock time the verb took, end to end.

Reading provenance

The block is on every response — printing it after an instruction-free observe shows the zero-inference case.

Requires: api-key 

import { Browserberg } from '@browserberg/sdk';

const bb = new Browserberg({
  apiKey: process.env.BROWSERBERG_API_KEY!,
  baseUrl: 'https://browserberg.com',
});

await using session = await bb.sessions.create({ ttlSeconds: 300 });
await session.act({
  steps: [{
    encodedId: null, action: 'navigate', role: 'none',
    description: 'open example.com', value: 'https://example.com',
  }],
});

// An instruction-free observe reads the page without a model call, and the
// provenance block says so: this is how you tell a cached replay from a paid
// inference call without reading your bill.
const observed = await session.observe();
console.log(JSON.stringify(observed.provenance, null, 2));

Plan cache economics

A replayed plan costs no inference: planCacheHit: true with inferenceCalls: 0 is the steady state of a stable automation. healApplied marks the middle ground — the page drifted, the cached plan was repaired, and the repair may have cost a call the clean replay would not have. Watching these three fields over a week tells you what your automations really cost, and which ones are living off the cache.