# Read the response (/docs/responses)

Every `run` returns the same object. Check `status` first: it is `ok`, `error`, `partial` or
`needs_user`.

```json
{
  "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](#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](#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:

```js
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](#report-a-wrong-result) |
| `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 }`        |

  **Node / TypeScript**
    ```ts
    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;
    }
    ```

  **Python**
    ```python
    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](/docs/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](https://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:

```js
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](/status).

## 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:

```sh
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>"}}}'
```
