Twin Browser
Get an API key
PlatformOverviewHow it worksAll toolsREST APIMCP serverIntegrationsDocs
CapabilitiesSemantic dispatch cacheDeterministic replayCross-tenant skill corpusToken-efficient DOMHuman-in-the-loopLive view & videoCredential vaultOverviewSolutions
SolutionsAll use casesAI agentsRPA replacementQA & test automationData extraction
ResourcesGuidesGlossaryBlogCompareFAQStatus
Pricing
Log in

CAPABILITY · DOM

A compact indexed map of the page, not raw HTML

The live page is serialized into a numerically-indexed list of its interactive elements under a token budget, so the planner reasons over signal instead of markup.

Start freeAPI reference
POST /api/v1/observe

Capability

Inside token-efficient dom state

Feeding raw HTML to a model is slow and expensive — most of a page is layout, scripts and decoration. The engine walks the live DOM for actionable elements, records their role and label, assigns each a stable numeric index, and trims the result to a token budget. The planner then emits "click [4]" rather than a CSS selector, which is both cheaper to reason about and more robust to cosmetic change.

Interactive elements only

Buttons, links, inputs, comboboxes and ARIA roles are extracted with their labels. Layout containers, scripts and decoration are dropped before the model sees anything.

Numeric addressing

Actions reference [1], [2], [3] — indices into the observed map — rather than CSS or XPath. A compiled path survives class-name churn that would break a selector.

A budget, not a hope

The map is trimmed to fit a token budget regardless of page size, so a huge listing page costs about the same to plan against as a small form.

Observable on its own

POST /api/v1/observe returns the indexed state without taking any action, which is how you inspect what the planner will see before you let it act.

How it works

The mechanism, in execution order

4 stages, in the order the runtime performs them — not a summary of them.

DOM → INDEXED STATE<html>layout · scripts · noisecompileindexed state1link“Calendar”2button“Tuesday”3combobox“Time slot”4button“Reserve”capped to a token budgetstable numeric indices — not CSS selectors that break on a redesign
  1. 1Load and settleThe engine drives a real browser to the URL and waits for the interactive state to settle before reading anything.
  2. 2Walk for actionablesThe DOM is traversed for elements a person could act on, with their roles and accessible labels.
  3. 3Index and trimEach survivor gets a stable numeric index; the list is trimmed to the token budget.
  4. 4Plan by indexThe planner chooses an action against an index, and the executor maps that index back to the real element.

In practice

A call you can paste and run

A live page reduced to the four things you can act on — the same state the planner receives, and nothing else.

observe.shbash
curl -X POST https://twin-browser.com/api/v1/observe \
  -H "Authorization: Bearer $TWIN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://app.example.com/calendar"}'

# {
#   "indexedState": {
#     "elements": [
#       { "i": 1, "role": "link",     "label": "Calendar" },
#       { "i": 2, "role": "button",   "label": "Tuesday" },
#       { "i": 3, "role": "combobox", "label": "Time slot" },
#       { "i": 4, "role": "button",   "label": "Reserve" }
#     ]
#   },
#   "credits_charged": 1
# }
api.twin-browser.com
  1. Load and settledone
  2. Walk for actionablesrunning
  3. Index and trimqueued
  4. Plan by indexqueued

What it costs, how to switch it on

Priced from the same rate card the API serves

Every credit figure on this page is read from the rate card behind GET /api/v1/pricing — it is not typed into the copy, so it cannot drift from what you are billed.

1 credit per observation

POST /api/v1/observe bills a flat 1-credit floor and makes no model call — it serializes, it does not reason. The same serialization happens inside every planned run, where it is part of the 10-credit run rather than a separate charge.

Full rate card

Turning it on

  1. 1Nothing to enableIndexed state is how the runtime sees every page. There is no flag.
  2. 2Inspect it directlyPOST /api/v1/observe with a URL when you want to see the map before letting an agent act on it.
  3. 3Use it as a cheap probeOver MCP, observe_page is the read-only tool an agent can call to check a page without spending a run.
  4. 4Pair it with a monitorA monitor with check_type "observe" watches this same serialization on a schedule and only fires when it changes.

At a glance

The contract, in the fewest rows that say it

PropertyTwin Browser
EndpointPOST /api/v1/observe
Input`url` (the authorization signal)
OutputIndexed interactive map
AddressingStable numeric indices
DroppedLayout, scripts, decoration
Actions takenNone

Limits

Where it stops, and what it deliberately does not do

A capabilities page with no limits section is a brochure. These are the ceilings, the defaults that will surprise you, and the things this capability is not.

Limits and defaults

  • The map is capped to a token budget. On a very large page the tail is trimmed, and the elements you want may not be in the first screenful of state.
  • Indices are stable for one observation, not across page navigations — a compiled path re-observes as it goes.
  • Elements rendered only after an interaction (a menu that opens on click) are not in the initial map by definition.
  • A page that never settles is bounded by the readiness wait, not by the page.

What it does not do

  • It does not return the page HTML. If you want the markup, that is not this endpoint.
  • It does not extract data. A structured read is POST /api/v1/extract; observe returns the interactive surface, not the content.
  • It does not take an action, click anything, or leave a session behind.
  • It does not set a token-count response header — the model-facing budget is internal, and no route publishes it.

FAQ

Questions about token-efficient dom state

Why not just send the model the HTML?
Because most of it is not actionable. A page that is tens of thousands of tokens of markup reduces to a short list of the elements a person could actually use, which is cheaper to reason about and far more robust to cosmetic change.
What keeps a compiled path from breaking on a layout tweak?
Actions address elements by index and role rather than by CSS or XPath, and the path re-observes as it executes. A class rename or a moved container usually changes nothing the path depends on.
How big can a page be?
Any size — the map is trimmed to a fixed token budget. The trade is that on a very large page the trimmed tail is genuinely gone, so scope the run to the view that matters (or use extract with a row selector for a long listing).
Can I see the state without running anything?
Yes. POST /api/v1/observe returns the indexed map with no action taken, for a 1-credit floor and no model call.

Keep reading

The rest of the platform

The capabilities this one works with, the tools that expose it, the guides that use it end to end, and the vocabulary behind it.

Structured extraction

Ask for fields or a JSON schema and get typed data back — or match a per-host template, expand a row selector, or capture the page's own XHR, and pay no model cost at all.

Deterministic replay

A successful run is minimized into a named, versioned skill — an ordered action path with its variable parts lifted out — and replaying it is a program, not a prompt.

Change monitoring

A monitor reads a value on a cadence, hashes it, compares it to last time, and posts an HMAC-signed webhook only when it actually moved.

Tools that expose it

observe_pagescreenshotextract

Put your agent to work. Keep the decision.

Start free. Hand your agent a goal on a site you authorize, set the guardrails, and let the first successful run compile the skill every run after it replays.

Start freeRead the docs