Read the response
What a run returns, what to do when it is partial or needs a sign-in, and what each error means.
Every run returns the same object. Check status first: it is ok, error, partial or
needs_user.
{
"ok": true,
"status": "ok",
"result": { "title": "Example Domain", "chars": 156, "warnings": [] },
"logs": [],
"error": null,
"ms": 8152,
"runId": "8fddd5dd-7b95-421d-9f88-a36b485e4341"
}The typed client's plain calls throw instead of returning this. See Errors.
Every field
| Field | Present when | What it is |
|---|---|---|
ok | always | true for ok and partial, false for error and needs_user |
status | always | ok | error | partial | needs_user |
result | always | What your script returned. null on error, needs_user, and a partial cut off by a limit |
logs | always | Your log(...) lines, in order |
error | always | Why the run failed, or null |
ms | always | How long the run took, not counting time queued |
runId | once the run was queued | Pass it to report when a result looks wrong |
queuedMs | when queueing took a second or more | Time spent waiting to start |
incomplete | on partial | What was missed. See Partial results |
emptyHanded | when your script returned nothing but its calls returned rows | The calls and the values you likely need to match on |
notes | when a call left a caveat | How an answer was reached, or a caveat for using it. Nothing is missing |
needs | on needs_user | Which sites need a sign-in |
secretNeeds | on needs_user caused by a stored secret going stale | { secret, reason, expiredAt? } |
savedSecrets | when the script stored a secret | { name, type, viewUrl }. Give the user the link, never the value |
savedFiles | when the script called bowmark.files.save | { id, name, contentType, bytes, url, expiresAt } |
meta | when there is something to carry | handoff, wwwAuthenticate, accountRequired, concurrency, report |
notice | when the account has not accepted the current Terms | A notice to pass to the account owner |
Large results over MCP come back as a link. Past 25,000 characters, result is replaced
by a line with a URL, and the full result is saved to your files for 30 days. Plain HTTP has no
such limit. To stay inline, return only the fields you need. To keep the bulk, save it with
bowmark.files.save({ name, text }) and return its url.
To read a saved file back in a later script, get it with its content:
const saved = await bowmark.files.get(id, { content: true });
const data = JSON.parse(saved.text);Partial results
partial means the script ran and result is real, but some calls did not answer. ok is
still true. Say what was missed when you show the result, and never call it complete.
| Field | What it tells you |
|---|---|
incomplete.summary | What happened, in one sentence |
incomplete.failures | Each call that threw, and what the site said |
incomplete.degraded | Each call that answered with a thinner result |
incomplete.cutOff | Only when a limit stopped the run. See below |
Each entry in incomplete.failures tells you what to do next:
| Field | Meaning | What to do |
|---|---|---|
fixable | true: your argument was wrong | Fix the call, using what the error names, and retry |
egressFailure | "own-network": the failure was on Bowmark's side, not the site's | Your script is fine. Retry later |
side | "bowmark", with cause: "shape" (the site changed its page) or cause: "coverage" (Bowmark does not read where this lives yet) | Not fixed by retrying. Report it |
retry | "now", "later" or "no" | On "no", don't retry. On "later", wait first |
A run that hit a limit
A run that passes its 90-second ceiling or its memory limit is stopped. If some calls had
answered, the run is partial with result: null, and the answers are in incomplete.cutOff:
| Field | What it is |
|---|---|
cutOff.by | "time" or "memory" |
cutOff.finished | Each call that answered, as { call, args, value } |
cutOff.unfinished | Each call still running, as { call, args } |
const env = await run(`return await bowmark.read.urls("https://www.dhl.com", { depth: 2 });`);
if (env.status === "partial" && env.result === null && env.incomplete?.cutOff) {
const done = env.incomplete.cutOff.finished.map((f) => f.value); // use what answered
// re-run only `unfinished`, narrower (pathPrefix, depth: 1)
} else if (env.status === "ok" || env.status === "partial") {
const urls = env.result.urls;
}env = await run('return await bowmark.read.urls("https://www.dhl.com", { depth: 2 });')
cut = (env.get("incomplete") or {}).get("cutOff")
if env["status"] == "partial" and env["result"] is None and cut:
done = [f["value"] for f in cut["finished"]] # use what answered
# re-run only cut["unfinished"], narrower (pathPrefix, depth 1)
elif env["status"] in ("ok", "partial"):
urls = env["result"]["urls"]Sending the same script again hits the same limit. Ask for less.
needs_user
A site needs the user signed in. It is a pause, not a failure.
needs lists the sites. meta.handoff.url is a single-use sign-in link.
Give the user the link, say which sites it covers, and wait.
When they are done, send the same script again, unchanged.
Don't retry before then, don't sign in yourself, and never ask for a password. In the typed
client this is BowmarkNeedsUserError: open err.handoff.url, then call again. More on
Signed-in sites.
warnings
Some functions return { rows, warnings } (flights, hotels, cars). Others return a bare array.
Check the signature in get_library.
Where there is one, warnings names any site left out of that answer. It is the only sign
that an answer is thin. Read it before you describe a result.
Errors
The typed client throws these. Branch on code, not on the message.
Class / code | When | What to do |
|---|---|---|
BowmarkNeedsUserError | A call needs the user signed in | Open err.handoff.url, then call again. A session() stays open |
no_api_key | No key passed and BOWMARK_API_KEY is unset | Create a key at bowmark.ai/dashboard/keys |
bad_argument | The function does not accept that argument | Fix it. The message names the path and what was expected |
wire_refused | An argument that cannot be sent as JSON | Fix it. The message names the path, e.g. args[0].when.checkIn |
unknown_function | No such function | Check the name in get_library, or upgrade the package |
rung_undeclared | read.page or read.pages called outside run() | Call it through run(): await run("return await bowmark.read.page(url)") |
run_only | browser_agent called outside run() | Call it through run(). Your key is fine |
A bad argument is refused in your own process, before any request, and is never billed.
Is it the site, or is it Bowmark?
Read error first. this domain does not resolve means the hostname does not exist. A
certificate error means the site serves a broken certificate. Neither is fixed by retrying.
When a call never reached its site (status: 0 from read.page, HTTP 0 from a provider),
read a page that never blocks anyone:
return (await bowmark.read.page("https://example.com")).status;200: Bowmark is fine. The site you called is refusing or down. Retrying straight away rarely helps.0as well: the problem is on Bowmark's side. Try again in a few minutes, and check the status page.
Requests Bowmark declines
Some tasks are declined whoever asks:
- collecting personal data about people in bulk, or tracking down a private person
- getting into an account that is not yours, or past someone's sign-in
- getting around a site's blocks or rate limits, or sniping limited stock
- moving money, buying regulated goods, sending messages in bulk, or exploiting a site
A run that makes more than 100 sending calls (send, message, comment, reply) has the 101st
refused. Public business information, like a shop's prices or opening hours, is fine. A
get_library query in one of these categories may carry a screenDemand warning.
Report a wrong result
Call the report MCP tool with what went wrong and the runId. Leave out runId to ask for a
site Bowmark does not cover yet. From code, call it over /mcp with your key:
curl -s -X POST https://api.bowmark.ai/mcp \
-H "Authorization: Bearer $BOWMARK_API_KEY" \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"report",
"arguments":{"report":"what failed or what is missing","runId":"<optional run id>"}}}'Write a script
Find the functions you need with get_library, then call them in a short JavaScript script with run, from an agent or from your own Node or Python code.
Signed-in sites
Let your AI agent log in to websites as your user. The user signs in once on the real site, and later calls act as their account without the agent ever seeing a password.