Do the task on the live websites and return the result
runExecutes the task on live websites and returns the result. Call get_library FIRST, then run({ script }). The same script can run from your app: POST https://api.bowmark.ai/v1/run with your API key; see bowmark.ai/docs/http-api.
THE SCRIPT is a plain async JavaScript body, not a wrapping function. bowmark is a ready global: await bowmark.<capability>.<fn>(...), or one site via await bowmark.providers.<provider>.<fn>(...). return what you want back; log(...) for progress. Built-ins plus URL/URLSearchParams exist; fetch, import, setTimeout and a filesystem do not — bowmark is the only I/O.
MIND THE CLOCK. Your client times out around 55 seconds; calls may take 30-55 seconds; default to ONE per script. Several? Use Promise.allSettled together (a dropped leg still returns partial), never one after another or inside a for loop. Keep under ~25,000 chars.
CHECK status BEFORE ok — ok | error | partial | needs_user | running:
• running: it is still going. Call run({ runId }) to wait for the SAME run; never resend the script.
• partial: result is real but narrower than asked, usually the site's doing; incomplete names what did not answer. Tell your user — never call it complete. incomplete.failures[].fixable: true means your argument was wrong: fix it and rerun.
• needs_user: a site needs your user signed in; not a failure. Give them meta.handoff.url, name the sites, then call wait_for_sign_in with meta.handoff.ref. On done, send the SAME script unchanged.
• error: there is no result; error says why.
Saving files, one exit IP, saved secrets, warnings, emptyHanded, and the billed browser_agent/delegate fallbacks: get_library({ query: "run guide" }).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| runId | No | Send EXACTLY ONE of `script` or `runId`, never both and never neither. `runId` is only to collect a run an earlier call answered `status: "running"` for: pass its `runId` alone, with no `script`, and this call waits for that same run's result. Leave it out when starting a run. | |
| egress | No | Optional. `"link"` sends every request of this run through the user's own Chrome (Bowmark Link) and fails with "Link not connected" when it is not open; `"link-first"` tries the user's Chrome first and falls back to Bowmark's own route (use it when the answer must come from the user's own address, e.g. a YouTube stream URL that will play in their browser); `"default"` or leaving it out uses Bowmark's own route. The result echoes what was applied as `egress` (`"default"` when a `"link-first"` run found no Chrome). | |
| script | No | Send EXACTLY ONE of `script` or `runId`, never both and never neither; `script` starts a new run. The JavaScript script body to execute (async, against the `bowmark` global). e.g. `const { flights, warnings } = await bowmark.flights.search({from:'SFO',to:'JFK',depart:'2026-09-01'}); return { best: flights.sort((a,b)=>a.price-b.price)[0], warnings };` |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ms | No | ||
| ok | Yes | ||
| logs | No | ||
| meta | No | ||
| error | No | ||
| needs | No | ||
| notes | No | ||
| runId | No | ||
| egress | No | ||
| notice | No | ||
| result | No | ||
| status | No | ||
| queuedMs | No | ||
| incomplete | No | ||
| savedFiles | No | ||
| emptyHanded | No | ||
| secretNeeds | No | ||
| savedSecrets | No |