Executing Actions
Execute single and batch tool actions on pages with WebUplink.
Executing Actions
After observing a page, your agent can execute tools to interact with it. Tool execution is available on all plans, including Free (subject to your monthly action limit).
Single Tool Execution
Execute one tool at a time using tool and params:
// Step 1: Browse a page
const page = await client.browse('https://google.com/travel/flights');
// page.tools → [{ name: "search_flights", params: [...] }]
// Step 2: Execute a tool
const results = await client.browse({
session_id: page.session_id,
tool: 'search_flights',
params: {
origin: 'SFO',
destination: 'Barcelona',
departure_date: '2026-07-01',
},
});
// Step 3: Check the result
console.log(results.results);
// [{ tool: "search_flights", success: true }]
console.log(results.summary);
// "12 flights from SFO to BCN. Cheapest: United $487..."Batch Tool Execution
Execute multiple tools sequentially in a single request:
const result = await client.browse({
session_id: page.session_id,
tools: [
{ tool: 'fill_shipping', params: { name: 'Jane Doe', address: '123 Main' } },
{ tool: 'select_shipping_speed', params: { speed: 'express' } },
{ tool: 'continue_to_payment', params: {} },
],
});Batch Execution Rules
- Tools execute sequentially, one at a time
- After each tool, WebUplink waits for the page to settle
- If a navigation occurs (page changes), execution stops
- If a tool fails, execution stops
- PageMap perception happens once at the end (not after every tool)
Handling stopped_reason
When batch execution stops early:
if (result.stopped_reason === 'navigation') {
// Page navigated mid-batch — remaining tools were skipped
console.log('Completed:', result.results?.length);
console.log('New page:', result.summary);
}
if (result.stopped_reason === 'timeout') {
// Operation timed out
}Partial Success
results always reflects exactly which tools were attempted:
const r = await client.browse({
session_id,
tools: [
{ tool: 'filter_questions', params: { sortId: 'MostVotes' } },
{ tool: 'navigate_to_question', params: { url: 'https://stackoverflow.com/questions/11227809' } },
{ tool: 'change_page_size', params: { pagesize: '50' } },
],
});
// If step 2 navigated to the question page:
// r.results.length === 2
// r.stopped_reason === 'navigation'
// r.summary describes the NEW pageFree Plan Limits
The Free plan can execute tools — the same browse + tool API as paid plans. It's bounded by:
- 250 actions every month, hard-capped (no overage). At the cap, requests return
QUOTA_EXCEEDEDuntil the next calendar-month reset or an upgrade. - 1 concurrent session and 30 requests/minute.
- No cache reads (paid plans reuse cached PageMaps; Free always recomputes).
Each request bills (tools executed) + 1 actions, so a 3-tool batch uses 4 of your monthly actions — the X-Actions-Charged header reports the exact count.
{
"error": "QUOTA_EXCEEDED",
"message": "Monthly action quota exhausted (250/250). Upgrade to Builder for 1,000 actions/month with overage, or start a free 14-day Builder trial: https://webuplink.ai/dashboard?upgrade=true",
"upgrade": { "trial": true, "plans": ["builder", "pro"], "url": "https://webuplink.ai/dashboard?upgrade=true" }
}The upgrade object is machine-readable — see the Error Reference for the full shape.