Search the web

Searches the web for `query` and returns up to `limit` results in the provider's order, each with its URL, title and description. The node sends the query to its search provider (the Brave Search API) with the node's key and nothing that identifies your organization; the result sites are not contacted unless you ask for their pages. With `scrape`, every result is also scraped with those options, through the same egress guard and politeness as a scrape, and its document is in the result's `scrape`; a result whose scrape fails has `error` instead, and the search still answers 200 with a `scrape_failed` warning. One answer holds at most 64 MiB of pages; a result past that has `error` `search_answer_too_large` and is not billed. A search's results get no custom `headers`, `profile`, `actions` or `json` format: scrape the URLs you trust with those. Bills one `vision.page` per search that returns at least one result, plus one `vision.page` per scraped result (as a scrape bills). A search with no results bills nothing. Each search counts against `vision.search.monthly` (searches per UTC calendar month) and `vision.search.rpm`; it answers 429 `quota_exceeded` or `rate_limited` when they are used up. A node without a search key answers 503 `search_unavailable`.

POST /v1/vision/search
Searches the web for `query` and returns up to `limit` results in the provider's order, each with its URL, title and description. The node sends the query to its search provider (the Brave Search API) with the node's key and nothing that identifies your organization; the result sites are not contacted unless you ask for their pages. With `scrape`, every result is also scraped with those options, through the same egress guard and politeness as a scrape, and its document is in the result's `scrape`; a result whose scrape fails has `error` instead, and the search still answers 200 with a `scrape_failed` warning. One answer holds at most 64 MiB of pages; a result past that has `error` `search_answer_too_large` and is not billed. A search's results get no custom `headers`, `profile`, `actions` or `json` format: scrape the URLs you trust with those. Bills one `vision.page` per search that returns at least one result, plus one `vision.page` per scraped result (as a scrape bills). A search with no results bills nothing. Each search counts against `vision.search.monthly` (searches per UTC calendar month) and `vision.search.rpm`; it answers 429 `quota_exceeded` or `rate_limited` when they are used up. A node without a search key answers 503 `search_unavailable`.

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token)

Request Body required

application/json
query string REQUIRED
What to search for, at most 50 words. Operators the provider supports pass through: `site:`, quotes, `-word`.
limit integer
Most results to return.
country string
Two-letter country code to rank results for, like `us` or `de`. Default the provider's. A code the provider does not cover answers `400 invalid_request` on this field.
lang string
Language of the results, like `en`, `de` or `pt-br`.
freshness string
Only results the provider found within this past period.
Enum: day, week, month, year
safe_search string
Filter adult content.
Enum: off, moderate, strict
timeout_ms integer
Time for the whole search, the results' scrapes included. A scrape it cuts short is that result's `scrape_timeout` error.
scrape object
Scrape every result with these options. `headers`, `profile`, `actions` and the `json` format are refused (`400 invalid_request`): results are pages a third party's index chose.
formats string[]
Array of: string
only_main_content boolean
Drop headers, navigation, footers and sidebars.
include_tags string[]
CSS selectors to keep; everything else is dropped.
Array of: string
exclude_tags string[]
CSS selectors to drop.
Array of: string
engine string
Which tier may serve the page. `auto` (default): cache, then HTTP fetch, then a browser when the fetch may not be enough. `fetch`: never start a browser. `browser`: always render in Chrome (needed for `actions`, `screenshot` and profiles; implied by them). With `auto`, a browser runs when the page needs JavaScript, when the fetch came back thin or mostly script, and when the fetch failed in a way a browser may not.
Enum: auto, fetch, browser
browser string
Which browser renders the page when the browser tier runs (`engine: browser`, or an `auto` scrape that renders); not allowed with `engine: fetch`. The scrape pool runs `headless-shell`. `chrome` renders in a browser of its own, which counts toward `vision.sessions.concurrent` while it runs, as a scrape with a `profile` does.
wait_for_ms integer
Extra wait after the page is ready, before capture.
timeout_ms integer
max_age_ms integer
Accept a cached copy up to this old (default 2 days). `0` always fetches.
cache_only boolean
Answer from the page cache only, with no outbound request at all (with `respect_robots`, only a robots.txt this node already holds is checked): a cached copy (within `max_age_ms` when it is given) or `404 scrape_no_cached_data`, which is not billed. Cannot be combined with `headers`, `profile`, `actions` or a screenshot, which never use the cache. The share of pages the cache serves is the `b3os_vision_cache_served_ratio` metric.
store_in_cache boolean
Store the result in the cache. Requests with headers, a profile or actions are never shared across organizations.
respect_robots boolean
Check the site's robots.txt (RFC 9309, product token `B3OSBot`) and Content Signals before fetching: a URL they disallow (or `ai-input=no`) answers `403 robots_disallowed`, which is not billed. Off by default: vision does not consult robots.txt unless asked. In a crawl's `scrape` options it means the same as the crawl's own `respect_robots`.
headers object
Extra request headers, sent only to the target URL's origin (scheme, host and port): in a browser to the page and its same-origin subresources and fetches, never to the other hosts the page loads from, and on both tiers never along a redirect to another origin. A header you set replaces the browser's header of the same name (one value is sent, yours). A request with custom headers bypasses the cache. In a browser, a `Cookie` header becomes cookies for the page's host (path `/`), so it reaches the origin as on an HTTP fetch.
profile string
A profile ID or name to load cookies and storage from. Implies `engine: browser`. The page renders in a browser of its own (never one shared with other organizations), which counts toward `vision.sessions.concurrent` while it runs: a single scrape answers 429 when no slot is free, a batch or crawl page waits for one. Not served (503 `product_unavailable`) on a node whose Chrome runs without its own sandbox.
actions (object | object | object | object | object | object | object | object | object | object | object | object)[]
Browser actions to run before capture. Implies `engine: browser`.
Array of:
One of:
Option 1
kind string REQUIRED
Enum: navigate
url string (uri) REQUIRED
wait_until string
Enum: load, domcontentloaded, networkidle
timeout_ms integer
settle boolean | object
After the action's input, wait until the page settles, and report how long that took (`settled_ms`, from the browser's acknowledgement of the input) and how it ended (`settled_by`). The page is settled when the document is at least interactive (loaded, when the input led to a new document), no document load and no `fetch` or XHR to the page's own site (sent since the action began) is in flight, and no DOM mutation and no such request has started or ended for `quiet_ms`. Third-party requests, images, scripts and streams do not hold it. Reaching `timeout_ms` is not an error: the action succeeds with `settled_by: deadline`. `true` takes the defaults. A click that changes nothing settles in about `quiet_ms`. The observer runs in an isolated world, so the page's scripts never see it.
One of:
Option 1boolean
Option 2
quiet_ms integer
timeout_ms integer
The longest the settle waits (within the batch's own time).
Option 2
kind string REQUIRED
Enum: click
target unknown | unknown | unknown | object REQUIRED
The element an action works on: a `Target` (found by selector, text or role when the step runs), or a `ref` from a `snapshot` step, which names the element that snapshot listed and nothing else.
One of:
Option 1
selector string
text string
exact boolean
role string
name string
within string
CSS selector of the scope.
nth integer
Option 2
ref string REQUIRED
button string
Enum: left, right, middle
count integer
modifiers string[]
Modifier keys held during the action.
Array of: string
timeout_ms integer
How long to wait for the target to appear.
settle boolean | object
After the action's input, wait until the page settles, and report how long that took (`settled_ms`, from the browser's acknowledgement of the input) and how it ended (`settled_by`). The page is settled when the document is at least interactive (loaded, when the input led to a new document), no document load and no `fetch` or XHR to the page's own site (sent since the action began) is in flight, and no DOM mutation and no such request has started or ended for `quiet_ms`. Third-party requests, images, scripts and streams do not hold it. Reaching `timeout_ms` is not an error: the action succeeds with `settled_by: deadline`. `true` takes the defaults. A click that changes nothing settles in about `quiet_ms`. The observer runs in an isolated world, so the page's scripts never see it.
One of:
Option 1boolean
Option 2
quiet_ms integer
timeout_ms integer
The longest the settle waits (within the batch's own time).
Option 3
kind string REQUIRED
Enum: hover
target unknown | unknown | unknown | object REQUIRED
The element an action works on: a `Target` (found by selector, text or role when the step runs), or a `ref` from a `snapshot` step, which names the element that snapshot listed and nothing else.
One of:
Option 1
selector string
text string
exact boolean
role string
name string
within string
CSS selector of the scope.
nth integer
Option 2
ref string REQUIRED
timeout_ms integer
Option 4
kind string REQUIRED
Enum: type
target unknown | unknown | unknown | object
The element an action works on: a `Target` (found by selector, text or role when the step runs), or a `ref` from a `snapshot` step, which names the element that snapshot listed and nothing else.
One of:
Option 1
selector string
text string
exact boolean
role string
name string
within string
CSS selector of the scope.
nth integer
Option 2
ref string REQUIRED
text string REQUIRED
clear boolean
Clear the field before typing.
interval_ms integer
Delay between characters.
timeout_ms integer
settle boolean | object
After the action's input, wait until the page settles, and report how long that took (`settled_ms`, from the browser's acknowledgement of the input) and how it ended (`settled_by`). The page is settled when the document is at least interactive (loaded, when the input led to a new document), no document load and no `fetch` or XHR to the page's own site (sent since the action began) is in flight, and no DOM mutation and no such request has started or ended for `quiet_ms`. Third-party requests, images, scripts and streams do not hold it. Reaching `timeout_ms` is not an error: the action succeeds with `settled_by: deadline`. `true` takes the defaults. A click that changes nothing settles in about `quiet_ms`. The observer runs in an isolated world, so the page's scripts never see it.
One of:
Option 1boolean
Option 2
quiet_ms integer
timeout_ms integer
The longest the settle waits (within the batch's own time).
Option 5
kind string REQUIRED
Enum: key
key string REQUIRED
`KeyboardEvent.key`, such as `Enter`, `Tab` or `a`.
modifiers string[]
Modifier keys held during the action.
Array of: string
settle boolean | object
After the action's input, wait until the page settles, and report how long that took (`settled_ms`, from the browser's acknowledgement of the input) and how it ended (`settled_by`). The page is settled when the document is at least interactive (loaded, when the input led to a new document), no document load and no `fetch` or XHR to the page's own site (sent since the action began) is in flight, and no DOM mutation and no such request has started or ended for `quiet_ms`. Third-party requests, images, scripts and streams do not hold it. Reaching `timeout_ms` is not an error: the action succeeds with `settled_by: deadline`. `true` takes the defaults. A click that changes nothing settles in about `quiet_ms`. The observer runs in an isolated world, so the page's scripts never see it.
One of:
Option 1boolean
Option 2
quiet_ms integer
timeout_ms integer
The longest the settle waits (within the batch's own time).
Option 6
kind string REQUIRED
Enum: scroll
target unknown | unknown | unknown | object
The element an action works on: a `Target` (found by selector, text or role when the step runs), or a `ref` from a `snapshot` step, which names the element that snapshot listed and nothing else.
One of:
Option 1
selector string
text string
exact boolean
role string
name string
within string
CSS selector of the scope.
nth integer
Option 2
ref string REQUIRED
to object
A position in CSS pixels.
x number REQUIRED
y number REQUIRED
by object
A position in CSS pixels.
x number REQUIRED
y number REQUIRED
Option 7
kind string REQUIRED
Enum: select
target unknown | unknown | unknown | object REQUIRED
The element an action works on: a `Target` (found by selector, text or role when the step runs), or a `ref` from a `snapshot` step, which names the element that snapshot listed and nothing else.
One of:
Option 1
selector string
text string
exact boolean
role string
name string
within string
CSS selector of the scope.
nth integer
Option 2
ref string REQUIRED
value string REQUIRED
The option value to select.
settle boolean | object
After the action's input, wait until the page settles, and report how long that took (`settled_ms`, from the browser's acknowledgement of the input) and how it ended (`settled_by`). The page is settled when the document is at least interactive (loaded, when the input led to a new document), no document load and no `fetch` or XHR to the page's own site (sent since the action began) is in flight, and no DOM mutation and no such request has started or ended for `quiet_ms`. Third-party requests, images, scripts and streams do not hold it. Reaching `timeout_ms` is not an error: the action succeeds with `settled_by: deadline`. `true` takes the defaults. A click that changes nothing settles in about `quiet_ms`. The observer runs in an isolated world, so the page's scripts never see it.
One of:
Option 1boolean
Option 2
quiet_ms integer
timeout_ms integer
The longest the settle waits (within the batch's own time).
Option 8
kind string REQUIRED
Enum: wait
ms integer
for object
Exactly one condition to wait for (the same as a timeline `wait` action's `for`).
selector string
An element matching this CSS selector is visible.
text string
This text is visible.
url string
The page URL contains this substring.
network_idle boolean
The network has been quiet.
Enum: true
timeout_ms integer
Option 9
kind string REQUIRED
Enum: evaluate
expression string REQUIRED
JavaScript evaluated in the page; a returned promise is awaited and the JSON-serializable result is returned.
Option 10
kind string REQUIRED
Enum: screenshot
target unknown | unknown | unknown | object
The element an action works on: a `Target` (found by selector, text or role when the step runs), or a `ref` from a `snapshot` step, which names the element that snapshot listed and nothing else.
One of:
Option 1
selector string
text string
exact boolean
role string
name string
within string
CSS selector of the scope.
nth integer
Option 2
ref string REQUIRED
full_page boolean
format string
Enum: jpeg, png, webp
quality integer
Option 11
kind string REQUIRED
Enum: markdown
only_main_content boolean
Option 12
kind string REQUIRED
Enum: snapshot
mode string
Enum: skeleton, full
root string
CSS selector of the element to outline (the body by default).
max_tokens integer
locale string
BCP 47 locale for `Accept-Language` and the browser. Defaults to the locale of the node's egress location (`en-US` on every node today).
timezone string
IANA time zone for the browser, such as `Europe/Berlin`. Defaults to the time zone of the node's egress location (`America/Los_Angeles` on every node today).
mobile boolean
Emulate a phone (viewport, user agent, touch).
viewport object
Browser viewport in CSS pixels.
width integer REQUIRED
height integer REQUIRED
block_ads boolean
Block ads, trackers and cookie banners.
block_resources string[]
Resource types the browser does not download. Defaults to images, media and fonts unless a screenshot is requested.
Array of: string
screenshot object
Options for the `screenshot` format.
full_page boolean
format string
Enum: jpeg, png, webp
quality integer
JPEG and WebP quality.
json object
Options for the `json` format. The node's model fills `schema` from the page.
schema object
A JSON Schema the result must match.
prompt string
Guidance for the model.
walls string
What a wall (`page_state` `blocked` or `captcha`) costs. `free`: no `vision.page`, and the result carries no page content, only `page_state`, `status_code`, `final_url` and `content_withheld: true`. `bill`: the wall bills like any page and its content is returned. A scrape with `actions` bills either way.
Enum: free, bill

Responses

200 The results.
application/json
object string REQUIRED
Enum: search
query string REQUIRED
results object[] REQUIRED
Array of:
position integer REQUIRED
Rank in the provider's order, from 1.
url string (uri) REQUIRED
title string REQUIRED
description string
scrape object
object string REQUIRED
Enum: scrape
url string (uri) REQUIRED
The requested URL.
final_url string (uri) REQUIRED
The URL of the page the answer was read from: the URL after redirects or, for a page the browser rendered, the page the browser read. When a script moved the browser to another host or path after the load, or changed the address to another path with `history.pushState` or `replaceState`, it is that address. A change of query or fragment alone after the load leaves it at the URL after redirects.
status_code integer REQUIRED
The HTTP status the site returned. A 404 page is still a successful scrape. For a page the browser rendered, it is the status the browser got when it loaded the page, so after a script moved the browser to another page (see `final_url`) it can be the status of the page before the move.
content_type string
tier string REQUIRED
What served the page.
Enum: cache, fetch, browser
cache object REQUIRED
state string REQUIRED
`hit` served from cache; `miss` fetched and stored; `bypass` fetched and not shared (custom headers, profile, actions).
Enum: hit, miss, bypass
age_s integer REQUIRED
Age of the served copy in seconds.
markdown string
html string
raw_html string
text string
links string[]
Array of: string
screenshot object
format string REQUIRED
Enum: jpeg, png, webp
width integer REQUIRED
height integer REQUIRED
data_base64 string (byte) REQUIRED
json unknown
Data matching `json.schema`, when the `json` format was requested.
metadata object
Metadata read from the page.
title string
description string
language string
canonical_url string (uri)
favicon string (uri)
og object
Open Graph properties, keyed without the `og:` prefix.
published_time string
modified_time string
robots string
The page's robots meta tag.
actions object[]
Results of `actions`, in order.
Array of:
kind string REQUIRED
Enum: navigate, click, hover, type, key, scroll, select, wait, evaluate, screenshot, markdown, snapshot
status string REQUIRED
Enum: ok, failed, skipped
duration_ms number REQUIRED
url string
`navigate`: the URL after redirects.
status_code integer
`navigate`: the HTTP status.
value unknown
`evaluate`: the JSON result.
screenshot object
format string REQUIRED
Enum: jpeg, png, webp
width integer REQUIRED
height integer REQUIRED
data_base64 string (byte) REQUIRED
markdown string
`markdown`: the page as Markdown.
snapshot object
id string REQUIRED
The snapshot's id, the first part of its refs.
mode string REQUIRED
Enum: skeleton, full
text string REQUIRED
The outline, one element per line; controls and headings end in `[ref=<id>:e<n>]`.
refs integer REQUIRED
How many refs the outline holds.
nodes integer REQUIRED
How many elements the outline lists.
tokens integer REQUIRED
The outline's size in tokens, counted as characters / 4.
complete boolean REQUIRED
Every element of the mode's kinds is listed (none counted instead, nothing cut by the budget).
truncated boolean REQUIRED
The budget (`max_tokens`) cut the outline.
error object
An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize.
type string (uri) REQUIRED
`https://docs.beta.b3os.org/errors#<code>`.
title string REQUIRED
Short summary of the problem type.
status integer REQUIRED
The HTTP status code, repeated for convenience.
code string REQUIRED
Stable machine-readable error code from the errors catalog.
detail string REQUIRED
Explanation of this occurrence. Never contains secrets.
instance string
The request ID (`req_…`) of the request that failed. Include it when you contact support.
errors object[]
Validation problems, one per field (`invalid_request` and the other codes that list `errors`).
...
reason string
Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).
required_scope string
The scope that was missing (`forbidden` with `reason: scope`).
retry_after_s integer
Same value as the `Retry-After` header, for clients that only read the body.
limit object
The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.
...
current_status string
The object's current status, for state conflicts such as `sandbox_not_running`.
upstream_status integer
The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).
step string
The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).
pack_error object
The error a pack's error mapping chose (`upstream_error` from pack actions).
...
dialogs object[]
JavaScript dialogs the page opened while the action ran, in order. Left out when there were none.
Array of: ...
delivery string REQUIRED
Whether the action's input reached the page, on every result, failed and skipped ones included. `delivered_verified`: sent, and the page's answer was seen (a `navigate` whose document loaded). `delivered_unverified`: sent and acknowledged by the browser (a click, typed text, a key, a select, an `evaluate`); what the page did with it is not checked. `delivery_uncertain`: part of it may have reached the page (a `navigate` that timed out, `type` with `interval_ms` cut off). `not_delivered`: nothing was sent: the target was missing, covered (`target_covered`) or stale (`stale_ref`), a field or option check refused, the step was skipped, or the action sends no input (`wait`, `screenshot`, `markdown`, `snapshot`). `unknown`: the browser stopped answering, or the batch ran out of time, after the input was sent.
Enum: delivered_verified, delivered_unverified, delivery_uncertain, not_delivered, unknown
retry string REQUIRED
Whether sending the action again is safe. `safe`: nothing was sent, or the action does the same thing twice (`navigate`, `hover`, `scroll`, the read actions). `unsafe`: its input landed and a second send repeats it (a second click, the text typed twice). `unknown`: whether its input landed cannot be told (`delivery` `unknown`, or an `evaluate` that threw part way).
Enum: safe, unsafe, unknown
settled_ms number
With `settle`: milliseconds from the browser's acknowledgement of the input until the page settled (or the settle's deadline). Left out without `settle`.
settled_by string
With `settle`: `quiet` (the page went quiet), `navigation` (the input led to a new document, which loaded and went quiet; a `navigate` always ends this way) or `deadline` (`timeout_ms` came first; the action still succeeded).
Enum: quiet, navigation, deadline
warnings string[]
What changed this action's answer, each starting with its code as a scrape's `warnings` do: a `screenshot` cut at the 16,384 px screenshot limit (`screenshot_truncated:` with the page's or the element's real size), a `markdown` read that returned the whole page because main content was under a quarter of it, or one that a markup limit or the extraction deadline shortened. Left out when there is nothing to say.
Array of: ...
page_state object
What kind of page the scrape returned (the page your `actions` left, when there are any), from heuristics on the HTML, the status and the amount of text (no model call): `ok` (the page), `blocked` (a bot-management interstitial or refusal), `captcha` (a challenge for a person), `cookie_wall` (consent before content), `login` (a sign-in form instead of content), `error` (an error status, or a 200 whose title says the page is missing) or `loading` (an unfinished shell). `blocked` and `captcha` are walls, and when the signals are unclear the state is `ok`, since a wall's content is withheld. A wall has little text (under about 2,500 bytes of visible text, counted outside the head whether or not the document has a `<body>` tag, and under 2,000 bytes of Markdown of the default main content, whatever `include_tags`, `exclude_tags` or `only_main_content` ask for) and either a 403 or 429 status or an interstitial signal: a challenge or refusal title (whole words, such as "Just a moment" or "Access denied"), a resource only a vendor's challenge loads (such as Cloudflare's `/cdn-cgi/challenge-platform/.../orchestrate/` or DataDome's `captcha-delivery.com`), an element only a vendor's challenge or block page has (Cloudflare's `cf-error-details` only with a 403 or 429 status or its "you have been blocked" headline: its 5xx origin-error pages, 520 to 526, use the same template and are `error`), or a CAPTCHA widget (`g-recaptcha`, `h-captcha`, `cf-turnstile`, or a rendered Turnstile widget's frame) on a page without a form field to fill in. Scripts that sites load on every page are not signals (reCAPTCHA v3, Cloudflare's JavaScript detections, PerimeterX, Kasada or Imperva loaders), so a small page that carries one is `ok`; vendor names count only in markup (classes, ids, resource URLs, inline scripts, comments), never in visible text; and a body that is not HTML (JSON, text) is judged by its status alone. Without an error status a wall is also small, at most 16 KiB of markup: a thin page with more keeps its content in scripts (a single-page app's inline state) and is not a wall. A marker or refusal word that the requested or final URL also carries (percent-decoded, in any case, a slug's words included) does not count: a page that echoes its own address, such as a search page with the query in its title or a tag page titled after its slug, is not refusing it. The markup judged is the document as served or, in a browser, the whole DOM with its scripts when the page shows fewer than 6,000 characters of text (counted in the DOM itself, the same whatever `formats` asks for); a page that shows more is judged by that text, and no rule that reads markup applies to it. So `formats` does not change the state, and neither does which copy of a page the cache holds for the same tier; a `cache_only` scrape with `engine: "auto"` reads whichever tier's copy is cached, and the fetch tier and the browser can judge the same page differently. A page whose content is visible text is not a wall, whatever its status or markers: with a consent banner or a CAPTCHA widget it is `ok`, answered with 403 or 429 it is `error`. A thin page that keeps its content in scripts and is answered with 403 or 429 is a wall, so its content is withheld unless `walls: "bill"`. Your own `actions` can make a wall (an `evaluate` step that empties the page), and the state then says so. A wall is free (no `vision.page`, not counted against the allowance; Firecrawl's `creditsUsed` is 0) and its content withheld (`content_withheld`), unless the request sets `walls: "bill"` or runs `actions`, which bill like any page. The other states are billed: they are the site's answer.
state string REQUIRED
Enum: ok, blocked, captcha, cookie_wall, login, error, loading
signal string
What decided it, such as `cloudflare_challenge`, `recaptcha`, `onetrust`, `password_form`, `status`, `title` or `empty_spa_root`.
content_withheld boolean
Present (`true`) when the page is a wall and the scrape was free (`walls: free`): the result then has no `markdown`, `html`, `raw_html`, `text`, `links`, `metadata`, `screenshot`, `json`, `actions` or `content_type`, only the state, `status_code` and `final_url`.
warnings string[] REQUIRED
Non-fatal problems, such as a format that could not be produced.
Array of: string
timing object REQUIRED
Server-side phase durations in milliseconds with microsecond resolution: the same phases as the `Server-Timing` header, keyed `<phase>_ms`. `total_ms` is always present. Phase names are product-specific and documented per operation. Example values in this reference are illustrative, not measurements.
total_ms number REQUIRED
error object
An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize.
type string (uri) REQUIRED
`https://docs.beta.b3os.org/errors#<code>`.
title string REQUIRED
Short summary of the problem type.
status integer REQUIRED
The HTTP status code, repeated for convenience.
code string REQUIRED
Stable machine-readable error code from the errors catalog.
detail string REQUIRED
Explanation of this occurrence. Never contains secrets.
instance string
The request ID (`req_…`) of the request that failed. Include it when you contact support.
errors object[]
Validation problems, one per field (`invalid_request` and the other codes that list `errors`).
Array of:
pointer string REQUIRED
Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.
detail string REQUIRED
What is wrong there.
reason string
Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).
required_scope string
The scope that was missing (`forbidden` with `reason: scope`).
retry_after_s integer
Same value as the `Retry-After` header, for clients that only read the body.
limit object
The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.
id string REQUIRED
Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.
limit number REQUIRED
The limit's value.
unit string REQUIRED
What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.
window_s integer
Window length in seconds for rate limits and quotas.
current number
Current usage against the limit, when known.
current_status string
The object's current status, for state conflicts such as `sandbox_not_running`.
upstream_status integer
The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).
step string
The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).
pack_error object
The error a pack's error mapping chose (`upstream_error` from pack actions).
code string REQUIRED
message string REQUIRED
retryable boolean REQUIRED
warnings string[]
`scrape_failed: <n> of <m> results could not be scraped; each has its error`, and `empty_page: <n> of <m> results came back with no text in their Markdown; each has its warning`.
Array of: string
timing object REQUIRED
`search_ms` and `total_ms`, and `scrape_ms` when the request has `scrape` and the search found results.
total_ms number REQUIRED
400 The request failed validation (`invalid_request`, `invalid_url`).
401 Missing, malformed, expired or revoked credentials (`unauthorized`).
402 The organization has no credits left, or the key reached its spend cap.
403 Authenticated but not allowed (`forbidden`, `egress_denied`).
413 The request body exceeds this operation's limit.
415 The Content-Type is not accepted by this operation.
429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).
500 Something failed inside B3OS (`internal`). Retry with backoff.
502 The search provider did not answer in time, was busy or failed (`search_failed`).
503 This node has no search key, or the provider refused it (`search_unavailable`). 
curl -X POST 'https://beta-api.b3os.org/v1/vision/search' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "query": "rust async runtime",  "limit": 2,  "scrape": {    "formats": [      "markdown"    ]  }}'
const response = await fetch('https://beta-api.b3os.org/v1/vision/search', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "query": "rust async runtime",    "limit": 2,    "scrape": {      "formats": [        "markdown"      ]    }  })});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://beta-api.b3os.org/v1/vision/search', headers=headers, json={  "query": "rust async runtime",  "limit": 2,  "scrape": {    "formats": [      "markdown"    ]  }})print(response.json())
200 Response 
{  "object": "search",  "query": "rust async runtime",  "results": [    {      "position": 1,      "url": "https://tokio.rs/",      "title": "Tokio - An asynchronous Rust runtime",      "description": "Tokio is an asynchronous runtime for the Rust programming language.",      "scrape": {        "object": "scrape",        "url": "https://tokio.rs/",        "final_url": "https://tokio.rs/",        "status_code": 200,        "tier": "fetch",        "cache": {          "state": "miss",          "age_s": 0        },        "markdown": "# Tokio\n\nBuild reliable network applications without compromising speed.\n",        "warnings": [],        "timing": {          "fetch_ms": 88.4,          "extract_ms": 2.1,          "total_ms": 91        }      }    },    {      "position": 2,      "url": "https://docs.rs/tokio/latest/tokio/",      "title": "tokio - Rust",      "description": "A runtime for writing reliable network applications without compromising speed.",      "scrape": {        "object": "scrape",        "url": "https://docs.rs/tokio/latest/tokio/",        "final_url": "https://docs.rs/tokio/latest/tokio/",        "status_code": 200,        "tier": "fetch",        "cache": {          "state": "miss",          "age_s": 0        },        "markdown": "# Crate tokio\n\nA runtime for writing reliable network applications without compromising speed.\n",        "warnings": [],        "timing": {          "fetch_ms": 96.2,          "extract_ms": 3,          "total_ms": 99.7        }      }    }  ],  "timing": {    "search_ms": 412.6,    "scrape_ms": 101.3,    "total_ms": 515.2  }}
Previous Map a site's URLs
Next Read a URL as Markdown
Ask a question... ⌘I