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

FieldPresent whenWhat it is
okalwaystrue for ok and partial, false for error and needs_user
statusalwaysok | error | partial | needs_user
resultalwaysWhat your script returned. null on error, needs_user, and a partial cut off by a limit
logsalwaysYour log(...) lines, in order
erroralwaysWhy the run failed, or null
msalwaysHow long the run took, not counting time queued
runIdonce the run was queuedPass it to report when a result looks wrong
queuedMswhen queueing took a second or moreTime spent waiting to start
incompleteon partialWhat was missed. See Partial results
emptyHandedwhen your script returned nothing but its calls returned rowsThe calls and the values you likely need to match on
noteswhen a call left a caveatHow an answer was reached, or a caveat for using it. Nothing is missing
needson needs_userWhich sites need a sign-in
secretNeedson needs_user caused by a stored secret going stale{ secret, reason, expiredAt? }
savedSecretswhen the script stored a secret{ name, type, viewUrl }. Give the user the link, never the value
savedFileswhen the script called bowmark.files.save{ id, name, contentType, bytes, url, expiresAt }
metawhen there is something to carryhandoff, wwwAuthenticate, accountRequired, concurrency, report
noticewhen the account has not accepted the current TermsA 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.

FieldWhat it tells you
incomplete.summaryWhat happened, in one sentence
incomplete.failuresEach call that threw, and what the site said
incomplete.degradedEach call that answered with a thinner result
incomplete.cutOffOnly when a limit stopped the run. See below

Each entry in incomplete.failures tells you what to do next:

FieldMeaningWhat to do
fixabletrue: your argument was wrongFix the call, using what the error names, and retry
egressFailure"own-network": the failure was on Bowmark's side, not the site'sYour 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:

FieldWhat it is
cutOff.by"time" or "memory"
cutOff.finishedEach call that answered, as { call, args, value }
cutOff.unfinishedEach 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 / codeWhenWhat to do
BowmarkNeedsUserErrorA call needs the user signed inOpen err.handoff.url, then call again. A session() stays open
no_api_keyNo key passed and BOWMARK_API_KEY is unsetCreate a key at bowmark.ai/dashboard/keys
bad_argumentThe function does not accept that argumentFix it. The message names the path and what was expected
wire_refusedAn argument that cannot be sent as JSONFix it. The message names the path, e.g. args[0].when.checkIn
unknown_functionNo such functionCheck the name in get_library, or upgrade the package
rung_undeclaredread.page or read.pages called outside run()Call it through run(): await run("return await bowmark.read.page(url)")
run_onlybrowser_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.
  • 0 as 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>"}}}'