Core Concepts

WebUplink is built around a simple mental model: browse → observe → act → repeat. This page explains the key concepts.

PageMap

When you browse a page, WebUplink returns a PageMap — a structured representation of everything the agent can see and do. A PageMap contains:

• Summary — A 1-3 sentence overview of the page for quick decisions
• Tools — Available actions the agent can perform
• Page Content (opt-in) — A detailed, curated breakdown of the page's content

The summary and tools are generated in a single LLM call, so observation is always fast.

Tools

Tools are the actions available on a page. Each tool has:

Tools are page-specific — they change based on what's currently visible. A search results page has filter_by_price and select_product; a questions page has search_questions and navigate_to_question.

{
  "name": "search_flights",
  "description": "Search for flights with the given criteria",
  "params": [
    { "name": "origin", "description": "Departure city or airport code" },
    { "name": "destination", "description": "Arrival city or airport code" },
    { "name": "departure_date", "description": "Departure date (YYYY-MM-DD)" }
  ]
}

Sessions

A session is a short-lived browser context. When you browse a URL, WebUplink creates a session with a real, isolated browser. Within the session, cookies, auth state, and navigation history carry across requests; when the session expires, that state is destroyed with it.

Lifecycle

Timeouts

• Idle timeout: ~2 minutes of no requests → auto-expire
• Hard cap: approximately 15 minutes total → auto-expire regardless of activity

Both caps are flat across all plans. Complete a task within one session and start a fresh one — re-running login if needed — for the next; see the Sessions guide for the pattern. Don't ping a session to keep it alive: every call bills at least one action.

Always call closeSession() when done to free resources immediately.

Actions (Billing Unit)

An action is the billing unit in WebUplink. Each POST /v1/browse call consumes one action per tool executed, plus one for the page perception — so an observe-only call is 1 action and a 3-tool batch is 4. The X-Actions-Charged response header reports the exact count.

• Free resets on the calendar month and hard-caps at 250 actions — at the cap, requests return QUOTA_EXCEEDED until the reset (or an upgrade). No credit card required.
• Paid plans reset on your billing anniversary (your invoice defines the period — GET /v1/usage reports it). Beyond the included allowance, metered overage bills per action.
• Spend caps are on by default on paid plans ($200/mo Builder, $500/mo Pro) so overage is always bounded. Raise or lower the cap anytime in the dashboard; it can't be turned off.
• The optional 14-day Builder trial (card required) includes 1,000 actions for the trial window — not a calendar month — with no overage. It auto-converts to Builder on day 14 unless cancelled.

Caching

WebUplink caches PageMap responses to avoid redundant LLM calls. Cache behavior depends on your plan:

Cache hits are indicated by the X-Cache: HIT response header. Cached responses don't consume additional LLM tokens but still count as one action for billing.