Turn any URL into model-ready web data from an MCP-aware agent using crawlbrulee's EU-hosted scraping API.
Scrape a single URL synchronously for markdown, cleaned/raw HTML, links, images, metadata, screenshots, and named CSS-selector elements.
Tune scraping with JS rendering, proxy tier, cleanup/exclude selectors, cache age, locale/country, and zero-data-retention mode.
Run long scrapes asynchronously: submit jobs, poll status, fetch results, and optionally receive signed completion webhooks.
Map sites by combining sitemap discovery and homepage links, with link-type filters, pagination, limits, and truncation metadata.
Check billing-cycle credit usage and concurrency, and identify the configured organization/token.
Report stable tool errors for auth, rate limits, validation, unreachable/blocked targets, billing caps, and other API failures.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@crawlbrulee-mcp Scrape the product page at https://crawlbrulee.com and return markdown with links"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
EU-native web scraping for AI agents & developers.
plug crawlbrulee into your agent. the official mcp server for crawlbrulee gives mcp-aware agents — Claude Code, Codex, Cursor, Claude Desktop — native tools to scrape pages, map sites, run background jobs, and check usage. one call turns any url into clean markdown, screenshots, metadata and links.
everything runs in the EU. the fetch, the render, the cache and your result never leave EU servers. the proxy exit is the one hop you choose: pick an EU exit and nothing leaves at all. gdpr-aligned, with a data processing agreement.
output made for models. markdown with ads, popups and cookie banners removed and the links kept, ready for the prompt. full-page screenshots can come back as tiles sized for an image model.
the hard parts, handled. headless Chrome when a page needs it, rotating proxies with country selection, automatic retries, ad and cookie-banner removal, caching, background jobs and signed webhooks.
start free. 750 credits, no credit card.
get a free api key → dashboard.crawlbrulee.com
the server:
npx-runnable — zero install.
wraps the @crawlbrulee/sdk under the hood; this mcp is just a thin protocol adapter.
stdio transport for terminal-based agents.
strict, fully-described tool schemas — agents see what every parameter does without reading docs.
this readme covers the mcp server itself — its tools and how to wire it into a host. for how the api behaves — endpoints, parameters, and error semantics — please see our api docs.
1. get a key. if you don't have a crawlbrulee account, sign up. the free plan needs no credit card. then, in the dashboard menu, open tokens and click create token.
2. put it in your environment. add it to your shell profile (for example ~/.zshrc),
then open a new terminal and start your agent from it. don't paste the key into your
agent's chat: anything in the chat stays in its history.
export CRAWLBRULEE_API_KEY="cwbl_..."3. add the server, with no key in its config. in Claude Code:
claude mcp add crawlbrulee -- npx -y @crawlbrulee/mcpother stdio hosts run the same command: npx -y @crawlbrulee/mcp. a few of them (Codex,
Cursor, Windsurf, Gemini CLI, Claude Desktop) need the key or the variable named in their
config file, and VS Code and the Claude Code plugin can ask for the key in a masked prompt.
the file and the entry for each one: mcp setup in the docs.
if a key stops working (invalid_credentials), it's expired, revoked or mistyped: create a
new one the same way, replace the old one, and start your agent again.
Related MCP server: snoopscan
env var | required | description |
| yes | api key sent as |
the mcp reads the env var on first tool invocation — not at startup — so a typo in your config surfaces as a clear tool-error message rather than the server failing to come up. see authentication for how the api consumes keys.
scrapefetch a single url and return the requested content (markdown, cleaned html, raw html, links, images, screenshot, page metadata).
input — only url is required; everything else has sane defaults.
{
"url": "https://example.com",
"extract": {
"markdown": true,
"links": true,
"screenshot": { "type": "full_page", "device_mode": "desktop" },
},
"require_js": false,
"proxy": "basic",
"cleanup": { "ads_and_popups": true, "exclude_selectors": ["nav", "footer"] },
"cache": { "max_age": 3600 },
"location": { "locale": "en-US", "country": "US" },
"zero_data_retention": false,
}zero_data_retention (boolean, default false) keeps the result out of the shared cache; anything stored to deliver it is kept for 24 hours, then deleted. it adds 1 credit and must be enabled for your organization. scrape_async takes it too. see zero data retention.
named values with extract.elements. to pull a few values from a page — prices, titles, links — give each one a name and a CSS selector, instead of reading the whole markdown. they come back in elements under the same names. all: true returns every match as a list, and fields reads named values inside each match. it costs no extra credits. scrape_async takes it too.
{
"url": "https://books.toscrape.com/",
"extract": {
"elements": {
"heading": "h1",
"books": {
"selector": "article.product_pod",
"all": true,
"fields": {
"title": { "selector": "h3 a", "output": "attribute", "attribute": "title" },
"price": ".price_color",
},
},
},
},
}
// → "elements": {
// "heading": "All products",
// "books": [{ "title": "A Light in the Attic", "price": "£51.77" }, ...]
// }a name with no match is null (or [] with all: true). limits and selector rules: see elements.
output — full scrape result. page metadata (title, OG tags, etc.) is returned under metadata. extracted images are returned as absolute urls — query strings are preserved, and relative srcs are resolved against the page url. screenshots are returned as signed download urls the agent can fetch separately. in rare cases a screenshot can't be captured: when you requested other outputs too, the screenshot field is simply left out while the rest is still returned — but a screenshot-only call that can't deliver errors instead (unsupported_screenshot_output, HTTP 422, when the content type can't be screenshotted) and isn't billed. the result also carries page_status_code and a top-level response_meta.usage block:
{
"url": "https://example.com",
"requested_url": "https://example.com",
"page_status_code": 200, // the site's own HTTP status for the final page
"markdown": "...",
"metadata": { "title": "Example Domain" },
"response_meta": {
"usage": {
// total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost
"total_credit_cost": 1,
"engine_credit_cost": 1, // http 1, browser 3, screenshot 5, cache 0
"proxy_multiplier": 1, // basic 1, advanced 5
"screenshot_slicing_credit_cost": 0, // 1 when the screenshot was split into slices, otherwise 0
"zero_data_retention_credit_cost": 0, // 1 when zero_data_retention added its credit, otherwise 0
"engine": "http", // "http" | "browser" | "screenshot" | "cache"
"proxy": "basic", // resolved tier actually used: "basic" | "advanced" (never "auto")
},
},
}a page the site served is a result, not an error. page_status_code is the HTTP status the site answered with for the final page, after redirects. a 404, 410 or 503 page comes back with its content and its status here, so check page_status_code before you trust the content: a 404 means the markdown is the site's "not found" page. 2xx and 4xx pages are billed, except 403, 407, 408, 429 and 451; 5xx pages are never billed. when the site can't be reached at all, the tool returns a target_unreachable error instead (see errors).
alongside response_meta.usage, the result surfaces any non-fatal warnings — stable string codes an agent can switch on. an outsized page is truncated rather than refused, and the code names which part was cut:
code | what it means for the payload |
| the page was taller than the scrolling-capture height cap; the screenshot covers the top of the page. |
| the page had more than 30,000 links; the |
| the page had more than 10,000 inline images; the |
| the page body exceeded 10,000,000 characters; |
| an |
one more code is not about size: screenshot_unavailable means a screenshot was asked for, but the page came back from the http engine without one. the rest of the result is still there.
and if you requested an extract that doesn't apply to the content type (e.g. metadata of a JSON file), the field name comes back in an unsupported_fields list — with the rest of the payload still returned.
every input field, its default, and its constraints are documented under the scrape endpoint — with extraction, screenshots, proxies & location, and caching covering the individual blocks.
scrape_asyncsubmit a scrape job to run asynchronously and get back a job_id immediately, instead of holding the connection open. use this for long-running scrapes (heavy js rendering, full-page screenshots of long pages); for a quick one-shot fetch prefer the synchronous scrape tool. then poll scrape_status until the job is done and fetch the page with scrape_result.
takes the same input as scrape plus an optional per-job completion webhook:
{
"url": "https://example.com",
"extract": { "markdown": true },
"webhook": {
// Endpoint that receives one signed `scrape.complete` POST when the job
// finishes. http/https (HTTPS required in production), max 2048 chars.
"url": "https://hooks.example.com/cwbl",
// Opaque correlation object echoed back verbatim in the delivery's
// `data.metadata`. Serializes to at most 2048 bytes.
"metadata": { "ref": "order-42" },
},
}output — { "job_id": "..." }.
when a webhook is attached, we deliver a single signed scrape.complete POST to your endpoint once the job reaches a terminal state, with your metadata echoed under data.metadata and the job's usage under data.response_meta.usage — so you can react to completion (and track cost) without polling. verify the X-Cwbl-Signature header with the sdk's verifyWebhookSignature (configure the signing secret in the dashboard under account → webhooks).
the job lifecycle is documented under async scrape; the delivery contract and payload shape under webhooks, with the signature scheme in webhook verification.
scrape_statuslook up the current lifecycle status of an async job: pending, running, done, or failed (with an error message when failed). once the job is done the response also carries a response_meta.usage block (total_credit_cost and its parts, billed engine, resolved proxy tier). a cache hit is represented by engine: "cache". a job whose page the site served ends done even when that page is a 404 — read page_status_code in the result. poll until done, then call scrape_result.
{ "job_id": "..." }scrape_resultfetch the extracted content of a completed async job — the same result shape as the synchronous scrape tool (including page_status_code, metadata, elements and response_meta.usage). errors if the job is still pending/running, so check scrape_status first.
{ "job_id": "..." }mapbuild (or fetch a cached) link-map for a website. combines sitemap discovery with homepage link extraction. use this to enumerate a site before scraping selected pages. each link is just { url }.
max_urls (default 5000, max 100000) is a discovery budget, not a trim at the end — discovery stops as soon as that many urls are found, so a smaller value is a faster, cheaper crawl. limit (default 5000, max 10000) only pages the answer.
returned urls are normalized the same way scrape normalizes its returned url, so map-then-scrape stays on one host. results are ordered with the most useful links first.
the response's response_meta carries pagination, truncation, and a usage block (total_credit_cost = engine_credit_cost × proxy_multiplier + zero_data_retention_credit_cost, billed engine, resolved proxy tier). map has no screenshot slicing and no page_status_code, since it reads many files, not one page. a map that found nothing because the site answered only with statuses we don't bill (a 5xx, for example), or not at all, is empty and free.
{
"url": "https://example.com",
"sitemap_only": false,
"types": { "internal": true, "external": false, "internal_subdomains": true },
"max_urls": 5000,
"page": 1,
"limit": 1000,
"zero_data_retention": false,
}zero_data_retention works as it does on scrape (see zero data retention).
a map stopped by your own max_urls returns exactly that many links with response_capped: false — the signal that the site has more is truncation.discovery_cap_reason:
{
"truncation": {
"storage_capped": false,
"response_capped": false,
"total_before_max_urls": 5000,
"total_detected_before_storage_cap": 5000,
"discovery_capped": true, // discovery stopped before reading every sitemap file
"sitemaps_skipped": 3, // files skipped or only partly read
"discovery_cap_reason": "max_urls", // retry with a higher max_urls
},
}discovery_cap_reason is one of max_urls, time, file_budget, depth, file_size, unread_files, or null when nothing stopped discovery. only max_urls is a limit you can raise from the request. unread_files means a sitemap file the site publishes could not be read at all this time — often temporary, so asking again later can return more. time, file_budget, depth and file_size mean the site itself is big, slow or deep, and a retry will not help.
see the map endpoint for discovery rules and pagination semantics.
usagereturns the current billing-cycle snapshot: total / used / available credits, used quota percent, max concurrency, and cycle reset timestamp. takes no arguments. what a call costs, and how credits are counted, is documented under credits & pricing.
whoamireturns the organization name, token name, and truncated token preview for the configured api key. useful for confirming which account is in use before credit-consuming operations.
every tool returns an mcp error result (isError: true) when the api call fails. the error text follows a stable format:
[<errorName>] <message> (HTTP <status>)a few codes add a short next step after that, e.g. target_unreachable and zero_data_retention_not_enabled. branch on the errorName code, not on the rest of the text.
agents can branch on the errorName code. the set comes from the sdk's ApiErrorName union plus two synthetic codes added by this mcp (missing_api_key, internal_error):
code | meaning |
|
|
| the api rejected the key: expired, revoked or mistyped. the message says how to get a new one. |
| temporary backend failure (HTTP 503). your key is fine — retry with backoff. |
| rate limit hit — back off and retry. |
| plan credit / concurrency cap exceeded. show |
| input failed server validation. |
| target url was rejected before fetching. |
| target url is on the blocklist. |
| origin's anti-bot defenses blocked the fetch. |
| origin redirected the fetch in a loop (HTTP 422). the target's doing — don't retry blindly. |
| the page's html was too large to process (HTTP 422). terminal — never retry it. |
| we could not reach the site at all (HTTP 502). not billed. retry later or check the url. |
|
|
| the scrape could not be completed. a page the site served, even a 404, is never this error. |
| screenshot-only request on a content type that can't be screenshotted (HTTP 422). not billed. |
| async job ID unknown, or submitted more than 24 hours ago ( |
| network / read timeout. safe to retry. |
| caller cancelled before completion. |
| unhandled server-side failure. |
| sdk error without a typed name. |
| bug in this mcp — please open an issue. |
the api docs carry the canonical error reference — every error name, what causes it, and how to recover.
pnpm install
pnpm typecheck # tsc --noEmit
pnpm lint # eslint
pnpm test # vitest run
pnpm build # tsup → dist/index.js with shebang
pnpm verify # all of the aboverun the built mcp locally:
CRAWLBRULEE_API_KEY=cwbl_... node ./dist/index.jsit will block waiting for an mcp client on stdio. combine with the MCP Inspector for interactive debugging.
this readme covers the mcp server itself — installing it, wiring it into a host, and the tools it exposes. for how the api behaves — endpoints, parameters, and error semantics — the api docs are canonical. the mcp guide covers host setup in more depth.
one api, many ways to call it:
js/ts sdk — @crawlbrulee/sdk (the sdk this mcp wraps)
python sdk — crawlbrulee on pypi
cli — npx crawlbrulee
mcp server — @crawlbrulee/mcp (this one)
agent skills — for skills-aware coding agents
docs: crawlbrulee.com/docs · dashboard: dashboard.crawlbrulee.com
Build (or fetch a cached) link-map for a website by combining sitemap discovery with homepage link extraction. Returns paginated lists of discovered URLs, each item just { url }. Filterable by link type (internal / external / subdomain). Use this to enumerate a site before scraping selected pages. max_urls (default 5000, max 100000) is a discovery budget, not a trim at the end: discovery stops as soon as that many URLs are found, so a smaller value is a faster, cheaper crawl. A map stopped that way returns exactly max_urls links with response_capped false — the signal that the site has more is response_meta.truncation.discovery_cap_reason. When that is "max_urls", ask again with a higher max_urls to get more; "unread_files" means a sitemap file could not be read this time and is often temporary, so asking again later can return more; "time", "file_budget", "depth" and "file_size" mean the site itself is big, slow or deep and a retry will not help. discovery_capped says discovery stopped early, sitemaps_skipped how many sitemap files were skipped or only partly read. limit (default 5000, max 10000) only pages the answer. Set zero_data_retention: true to keep the result out of the shared cache; anything stored to deliver it is kept for 24 hours, then deleted. It adds 1 credit and must be enabled for the organization (else a zero_data_retention_not_enabled error, not billed). See https://crawlbrulee.com/docs/zero-data-retention. Returned URLs are normalized the same way scrape normalizes its returned url, so map-then-scrape stays on one host. Results are ordered with the most useful links first. The response carries response_meta.usage: total_credit_cost = engine_credit_cost × proxy_multiplier + zero_data_retention_credit_cost, plus engine and proxy (the resolved tier, never auto). Map has no screenshot slicing and no page_status_code: it reads many files, not one page. A map that found nothing because the site answered only with statuses we don't bill (a 5xx, for example), or not at all, is empty and free. If the site cannot be reached, the tool can return a target_unreachable error (HTTP 502, not billed): retry later or check the URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The website URL to map. Mapping always targets the site root, so the path, query string and fragment are dropped; known tracking parameters are removed before the request is processed. | |
| page | No | Page number for paginated results | |
| cache | No | Cache settings for this request | |
| limit | No | Number of URLs to return per page. Default 5000, maximum 10000. | |
| proxy | No | Proxy tier to use for fetching | auto |
| types | No | Filter which link types to include | |
| location | No | Optional country emulation for the map | |
| max_urls | No | Maximum number of URLs to discover and store in the map. Default 5000, maximum 100000. Sitemap discovery stops as soon as this many URLs have been found, so a smaller value is a faster and lighter crawl, not just a smaller answer. | |
| sitemap_only | No | Only use sitemap.xml — skip homepage link extraction | |
| zero_data_retention | No | Keeps the result out of the shared cache; anything stored to deliver it is kept for 24 hours, then deleted. Adds 1 credit. Must be enabled for your organization. See https://crawlbrulee.com/docs/zero-data-retention. |
| Name | Required | Description |
|---|---|---|
| links | Yes | List of discovered URLs for the current page |
| response_meta | Yes | Response metadata including pagination, truncation, and usage info |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does most of it: it discloses caching behavior, the 24-hour retention for zero_data_retention, the +1 credit and org-enablement requirement, the credit formula, which empty results are free, and two named error modes (target_unreachable, zero_data_retention_not_enabled). It stops short of stating outright that the operation is read-only/non-destructive or describing auth/rate-limit behavior, which keeps it off a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the map-before-scrape routing are front-loaded, and every paragraph is topic-coherent. It is long for a tool description, and the dense enumeration of truncation reason strings plus the credit-cost formula push toward reference-doc territory, but the material is largely load-bearing rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema existing, the description covers the things the schema cannot: how to interpret `response_capped`, what each `discovery_cap_reason` implies for retry, free-vs-billed outcomes, and URL normalization parity with `scrape`. Nothing an agent needs in order to call this correctly or interpret the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds genuinely new meaning: `max_urls` is a discovery budget that halts the crawl early rather than a post-hoc trim, while `limit` only pages the answer. It also explains the `response_capped` flag, `truncation.discovery_cap_reason` values, and the cost/eligibility semantics of `zero_data_retention` — none of which the schema conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Build (or fetch a cached) link-map for a website by combining sitemap discovery with homepage link extraction' — and distinguishes itself from the scrape family by saying 'Use this to enumerate a site before scraping selected pages.' An agent can tell this apart from scrape, scrape_async, and scrape_result without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the workflow position (before scraping selected pages) and the alternative it feeds into. It goes further by giving decision rules for retries: raise max_urls when `discovery_cap_reason` is 'max_urls', retry later when 'unread_files', and do not retry for 'time', 'file_budget', 'depth', 'file_size'. This is unusually actionable when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single URL via the crawlbrulee scraping API and return the requested content (markdown, cleaned HTML, raw HTML, links, images, screenshot, page metadata in metadata). Use this for one-shot page extraction. For full-site discovery use the map tool first. To pull named values such as prices, titles or links, set extract.elements (name → CSS selector) instead of reading the whole markdown: they come back in elements, for no extra credits. Rules: https://crawlbrulee.com/docs/scrape/elements. Check page_status_code before you trust the content: it is the HTTP status the site answered with for the final page. A page the site served is a successful result whatever its status, so a 404 or 503 page comes back with its content, not as an error. A 404 means the markdown is the site's "not found" page, not the page you asked for. 2xx and 4xx pages are billed, except 403, 407, 408, 429 and 451; 5xx pages are never billed. If the site cannot be reached at all the tool returns a target_unreachable error (HTTP 502, not billed): retry later or check the URL. Screenshot URLs in the response are signed download links that expire 24 hours after the scrape: download the image if you need it later; do not keep the link. The response also carries response_meta.usage: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost, plus engine and proxy (the resolved tier — never auto). engine is the billed engine (http, browser, screenshot, cache); a cache hit is represented by engine: "cache". Set zero_data_retention: true to keep the result out of the shared cache; anything stored to deliver it is kept for 24 hours, then deleted. It adds 1 credit and must be enabled for the organization (else a zero_data_retention_not_enabled error, not billed). See https://crawlbrulee.com/docs/zero-data-retention. Extraction is capped per page: 30,000 links, 10,000 inline images and 10,000,000 characters of HTML. A page past a cap is truncated rather than refused, and the response warnings array names which one (links_truncated, inline_images_truncated, raw_html_truncated) — so treat that output as incomplete. elements_truncated means an elements value hit a limit. Use cleanup to control what is removed before any output is built: ads_and_popups (on by default) drops ads, cookie banners and chat widgets, and exclude_selectors removes anything else. It shapes markdown, cleaned_html, links, images and the screenshot, and NEVER raw_html — so request raw_html when you need the page exactly as it arrived. warnings also reports a section whose extraction failed outright (links_unavailable, inline_images_unavailable, metadata_unavailable): that field comes back omitted or empty while the rest of the scrape succeeded, so do NOT conclude the page had no links/images/metadata — re-run the scrape instead. An empty field with no such warning does mean the page had none. screenshot_unavailable means a screenshot was asked for, but the page came back from the http engine without one.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to scrape. Known tracking parameters are removed before the page is fetched, so they are neither sent to the target site nor part of the cache key. Every other query parameter is kept verbatim and is part of the cache key. | |
| cache | No | Cache settings for this request | |
| proxy | No | Proxy tier to use for fetching | auto |
| cleanup | No | What is removed from the page before any output is built. Applies to markdown, cleaned_html, links and images on every engine, and to the screenshot. Never applies to raw_html, which is always the page before we removed anything. | |
| extract | No | Which content formats to extract. Defaults to metadata + cleaned_html. | |
| location | No | Optional locale + country emulation for the scrape | |
| require_js | No | Use a headless browser to render JavaScript before scraping | |
| zero_data_retention | No | Keeps the result out of the shared cache; anything stored to deliver it is kept for 24 hours, then deleted. Adds 1 credit. Must be enabled for your organization. See https://crawlbrulee.com/docs/zero-data-retention. |
| Name | Required | Description |
|---|---|---|
| url | Yes | The URL that was actually scraped, after any redirects, in normalized form — the base that links, images, and internal labels are computed against |
| links | No | Links found on the page |
| images | No | Inline images found on the page |
| elements | No | The values asked for in `extract.elements`, under the same names. Each name is a string, an object (a spec with `fields`), a list of either (`all: true`), or null when nothing matched (`[]` with `all: true`). An object holds its field names with the same kinds of values, nested up to 3 levels. Every requested name is always present, at every level of `fields`. |
| markdown | No | Page content converted to clean Markdown |
| metadata | No | Extracted page metadata (title, OG tags, etc.) |
| raw_html | No | Raw, unprocessed HTML of the page |
| warnings | No | Non-error notices about the scrape. Truncation codes — `screenshot_truncated` (long page exceeded the scrolling-screenshot height cap), `links_truncated` / `inline_images_truncated` (page had more links/images than the per-page extraction caps), `raw_html_truncated` (rendered HTML exceeded the per-page size budget) — mean the field is present but capped. `elements_truncated` means at least one `elements` value hit a limit: a list was cut at 1,000 matches, the request reached 10,000 matches in total, or a value did not fit the ~1 MB of values allowed per request (that value is then null, never cut short). Unavailability codes — `links_unavailable` / `inline_images_unavailable` / `metadata_unavailable` — mean that optional field could not be extracted and was omitted (null/empty) while the rest of the scrape succeeded, so an empty field carrying one of these does NOT mean the page had none. `screenshot_unavailable` means a screenshot was asked for, but the page came back from the http engine without one. Stable string codes — clients can switch on them. Warnings are stored with the result: async result fetches and cache hits carry them too, filtered to the fields the request asked for. `metadata_truncated` is retired and no longer sent: metadata has no size limit of its own now, though the code can still appear on results stored before that change. |
| screenshot | No | Screenshot of the page, if requested |
| cleaned_html | No | Cleaned HTML of the main page content |
| content_type | No | Content-Type header returned by the server |
| requested_url | Yes | The URL you requested, echoed verbatim — before any redirects |
| response_meta | Yes | Request-level metadata. `response_meta.usage` reports what the request cost (total_credit_cost and its parts), the billed engine and the resolved proxy tier. |
| page_status_code | No | The HTTP status the site answered with for the final page, after redirects. Check it before you trust the content. A page the site served is a successful result whatever its status: a 404 or 503 page comes back with its content here, not as an error, so a 404 means the markdown is the site's "not found" page, not the page you asked for. Billing follows this status: 2xx and 4xx pages are billed, except 403, 407, 408, 429 and 451; 5xx pages are never billed. Older api versions do not send it; they only returned pages that loaded normally. |
| unsupported_fields | No | Extract fields that were requested but are not supported for this content type |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden and does so thoroughly: it explains that 4xx/5xx pages return as content rather than errors, the exact billing matrix (403/407/408/429/451 and 5xx free), `target_unreachable` (502, unbilled), screenshot links expiring after 24h, the credit formula, and zero_data_retention's cost and org prerequisite. It also disambiguates empty fields: a warning means extraction failed and should be retried, while an empty field without a warning means the page genuinely had none — a subtlety an agent would otherwise get wrong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the `map` alternative are front-loaded, and nearly every sentence carries operational weight (billing, truncation caps, warning semantics). It is nonetheless a dense wall of rules that partially duplicates schema descriptions of cleanup and extraction caps, costing some scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with nested objects and no annotations, the description covers everything an agent needs: success vs. error framing, billing, truncation and failure warnings, cache and retention behavior, and cleanup scope. An output schema exists, yet the description still supplies the interpretive keys (`page_status_code`, `warnings`, `response_meta.usage`) needed to read it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema: `extract.elements` as name→CSS selector returning in a top-level `elements` field at no extra credit, and the critical rule that `cleanup` shapes markdown/HTML/links/images/screenshot but never `raw_html`. It does not cover `require_js`, `proxy`, or `location` selection trade-offs, which remain schema-only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch a single URL via the crawlbrulee scraping API') and enumerates the returnable content formats. It also explicitly positions itself against a sibling ('For full-site discovery use the `map` tool first') and vs. multi-step workflows ('one-shot page extraction'), so an agent can pick it without reading any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear when-to-use guidance and names `map` as the alternative for site discovery, plus a concrete preference to use `extract.elements` rather than dumping full markdown. It does not, however, route against `scrape_async`/`scrape_status`/`scrape_result`, which are the most likely confusable siblings for long-running or batch work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a scrape job to run ASYNCHRONOUSLY and return a job_id immediately, instead of holding the connection open. Use this for long-running scrapes (heavy JS rendering, full-page screenshots of long pages) — for a quick one-shot fetch prefer the synchronous scrape tool, which blocks and returns the page directly. Poll the job with scrape_status and fetch the page with scrape_result once done. Takes extract.elements like scrape (named values by CSS selector, no extra credits); the result carries them in elements. Rules: https://crawlbrulee.com/docs/scrape/elements. Optionally attach a per-job completion webhook: we deliver a single signed scrape.complete POST to your endpoint when the job finishes (HTTPS required in production), and echoes your opaque webhook.metadata back in the delivery (under data.metadata, alongside data.page_status_code (on success) and data.response_meta.usage). Set zero_data_retention: true to keep the result out of the shared cache; anything stored to deliver it is kept for 24 hours, then deleted. It adds 1 credit and must be enabled for the organization (else a zero_data_retention_not_enabled error, not billed). See https://crawlbrulee.com/docs/zero-data-retention.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL to scrape. Known tracking parameters are removed before the page is fetched, so they are neither sent to the target site nor part of the cache key. Every other query parameter is kept verbatim and is part of the cache key. | |
| cache | No | Cache settings for this request | |
| proxy | No | Proxy tier to use for fetching | auto |
| cleanup | No | What is removed from the page before any output is built. Applies to markdown, cleaned_html, links and images on every engine, and to the screenshot. Never applies to raw_html, which is always the page before we removed anything. | |
| extract | No | Which content formats to extract. Defaults to metadata + cleaned_html. | |
| webhook | No | Completion webhook delivered when this async job finishes. Async-only: the synchronous `scrape` tool does not accept it. | |
| location | No | Optional locale + country emulation for the scrape | |
| require_js | No | Use a headless browser to render JavaScript before scraping | |
| zero_data_retention | No | Keeps the result out of the shared cache; anything stored to deliver it is kept for 24 hours, then deleted. Adds 1 credit. Must be enabled for your organization. See https://crawlbrulee.com/docs/zero-data-retention. |
| Name | Required | Description |
|---|---|---|
| job_id | Yes | Job identifier — pass it to the `scrape_status` / `scrape_result` tools |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly: immediate job_id return, webhook delivery as a single signed POST with signature header and metadata echo, zero_data_retention storage deleted after 24 hours, the 1-credit cost and organization-enablement prerequisite with named error `zero_data_retention_not_enabled` and 'not billed' clarification. These are material behaviors not present in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core routing information and async-vs-sync distinction are front-loaded, and most sentences add value. It is still a dense block with a long zero_data_retention paragraph that could be trimmed, but the structure remains logical and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given nine nested parameters and an output schema, the description covers the essential workflow: submission, immediate job_id, polling via `scrape_status`, retrieval via `scrape_result`, optional webhook completion, and retention semantics. An agent has enough to invoke and follow up correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description touches `extract.elements` and `webhook.metadata` but largely restates what the schema already documents in detail; it does not explain other significant parameters such as `cache`, `proxy`, `cleanup`, `location`, or `require_js`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Submit a scrape job') and immediately states the defining behavioral contrast: asynchronous with an immediate job_id instead of holding the connection open. It explicitly distinguishes itself from the synchronous `scrape` sibling, so an agent can route correctly without inspecting either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance ('long-running scrapes — heavy JS rendering, full-page screenshots of long pages') and when-not ('for a quick one-shot fetch prefer the synchronous `scrape` tool'). It also names the follow-up tools `scrape_status` for polling and `scrape_result` for fetching, completing the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the extracted content of a completed async scrape job (the same result shape as the synchronous scrape tool: markdown, cleaned HTML, raw HTML, links, images, screenshot, page metadata in metadata, values from extract.elements in elements, and response_meta.usage). Errors if the job is still pending/running — check scrape_status first (status done) before calling this. Check page_status_code before you trust the content: it is the HTTP status the site answered with for the final page. A page the site served is a successful result whatever its status, so a 404 or 503 page comes back with its content, not as an error. A 404 means the markdown is the site's "not found" page, not the page you asked for. 2xx and 4xx pages are billed, except 403, 407, 408, 429 and 451; 5xx pages are never billed. A job answers for 24 hours after it was submitted, then returns not_found. Screenshot URLs are signed download links that expire at the same moment, however late you fetch the result: download the image if you need it later.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job identifier returned by the `scrape_async` tool |
| Name | Required | Description |
|---|---|---|
| url | Yes | The URL that was actually scraped, after any redirects, in normalized form — the base that links, images, and internal labels are computed against |
| links | No | Links found on the page |
| images | No | Inline images found on the page |
| elements | No | The values asked for in `extract.elements`, under the same names. Each name is a string, an object (a spec with `fields`), a list of either (`all: true`), or null when nothing matched (`[]` with `all: true`). An object holds its field names with the same kinds of values, nested up to 3 levels. Every requested name is always present, at every level of `fields`. |
| markdown | No | Page content converted to clean Markdown |
| metadata | No | Extracted page metadata (title, OG tags, etc.) |
| raw_html | No | Raw, unprocessed HTML of the page |
| warnings | No | Non-error notices about the scrape. Truncation codes — `screenshot_truncated` (long page exceeded the scrolling-screenshot height cap), `links_truncated` / `inline_images_truncated` (page had more links/images than the per-page extraction caps), `raw_html_truncated` (rendered HTML exceeded the per-page size budget) — mean the field is present but capped. `elements_truncated` means at least one `elements` value hit a limit: a list was cut at 1,000 matches, the request reached 10,000 matches in total, or a value did not fit the ~1 MB of values allowed per request (that value is then null, never cut short). Unavailability codes — `links_unavailable` / `inline_images_unavailable` / `metadata_unavailable` — mean that optional field could not be extracted and was omitted (null/empty) while the rest of the scrape succeeded, so an empty field carrying one of these does NOT mean the page had none. `screenshot_unavailable` means a screenshot was asked for, but the page came back from the http engine without one. Stable string codes — clients can switch on them. Warnings are stored with the result: async result fetches and cache hits carry them too, filtered to the fields the request asked for. `metadata_truncated` is retired and no longer sent: metadata has no size limit of its own now, though the code can still appear on results stored before that change. |
| screenshot | No | Screenshot of the page, if requested |
| cleaned_html | No | Cleaned HTML of the main page content |
| content_type | No | Content-Type header returned by the server |
| requested_url | Yes | The URL you requested, echoed verbatim — before any redirects |
| response_meta | Yes | Request-level metadata. `response_meta.usage` reports what the request cost (total_credit_cost and its parts), the billed engine and the resolved proxy tier. |
| page_status_code | No | The HTTP status the site answered with for the final page, after redirects. Check it before you trust the content. A page the site served is a successful result whatever its status: a 404 or 503 page comes back with its content here, not as an error, so a 404 means the markdown is the site's "not found" page, not the page you asked for. Billing follows this status: 2xx and 4xx pages are billed, except 403, 407, 408, 429 and 451; 5xx pages are never billed. Older api versions do not send it; they only returned pages that loaded normally. |
| unsupported_fields | No | Extract fields that were requested but are not supported for this content type |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses the error condition for incomplete jobs, the crucial `page_status_code` semantics (4xx/5xx pages are returned as content, not errors), billing rules per status class, the 24-hour job lifetime ending in `not_found`, and expiry of signed screenshot URLs. This is exactly the non-obvious behavior an agent would otherwise get wrong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first clause, followed by return shape, then preconditions, then caveats, which is a sound ordering. It is dense and the billing exception list is somewhat tangential to a read call, but every claim is actionable rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still sketches the result shape and, more importantly, covers failure modes (pending/running, expired jobs) and trust caveats (page_status_code) that the schema cannot express. Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single `job_id` is already documented as coming from `scrape_async`, so the baseline is 3. The description goes beyond by explaining the identifier's useful lifetime (24 hours, then `not_found`), which tells the agent when a stored job_id stops working.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb + resource: 'Fetch the extracted content of a completed async scrape job'. It explicitly relates to the synchronous `scrape` tool's result shape and implies a distinct role from `scrape_async` (submit) and `scrape_status` (poll), so an agent can place it in the workflow without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit precondition and alternative: 'Errors if the job is still pending/running — check `scrape_status` first (status `done`) before calling this.' That is a named sibling plus the exact routing condition, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up the current lifecycle status of an async scrape job submitted via scrape_async. Returns the job state (pending, running, done, failed), with an error message when it failed and a response_meta.usage block (total_credit_cost and its parts, billed engine, resolved proxy tier) once it is done. A job whose page the site served ends done even when that page is a 404 or 503 — read page_status_code in the result. A job that could not reach the site at all ends failed (the error text is a general message, not the reason) and is not billed; retry later or check the url. Poll this until the status is done, then call scrape_result to fetch the page. If you registered a completion webhook on submit you can skip polling and react to the delivery instead. A job answers for 24 hours after it was submitted; after that this returns not_found, the same as for an unknown job id.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job identifier returned by the `scrape_async` tool |
| Name | Required | Description |
|---|---|---|
| error | No | Error message if the job ended in `failed`. A job whose page the site served, even a 404 page, ends `done`, not `failed`: read `page_status_code` in the `scrape_result`. |
| job_id | Yes | The job identifier |
| status | Yes | Current state of the job (pending, running, done, failed) |
| created_at | Yes | ISO-8601 UTC timestamp when the job was created |
| response_meta | No | Usage accounting for the finished job. Present only once the job is `done`; `response_meta.usage` reports what the job cost (total_credit_cost and its parts), the billed engine and the resolved proxy tier. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so: it enumerates the four states, explains that a site-served 404/503 still ends `done` (read `page_status_code`), that unreachable-site failures end `failed` with a generic error and are unbilled, and that jobs expire to `not_found` after 24 hours. Billing and TTL behavior are disclosed rather than left to inference.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and return shape, then the edge cases. Dense but every sentence carries distinct information; the state enumeration and expiry detail make it slightly longer than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still explains the meaningful return semantics (state values, error text, usage block, page_status_code) and the full job lifecycle, so an agent has everything needed to poll, interpret, and hand off to `scrape_result`.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single `job_id` parameter already documented as coming from `scrape_async`. The description adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('look up the current lifecycle status of an async scrape job') and explicitly ties it to the sibling `scrape_async` that creates the job, so it is distinguishable from `scrape_result` and `scrape_async` without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use routing: poll this until status is `done`, then call `scrape_result`; if a completion webhook was registered on submit, skip polling entirely. It also states the retry path for `failed` jobs. Alternatives and exclusions are both named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the current billing-cycle usage for the authenticated organization: total / used / available credits, used quota percent, max concurrency, and cycle reset time. Call this before launching large scrape jobs to confirm available credit.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| usage_reset | Yes | ISO 8601 UTC timestamp when the current billing cycle ends and used_credits resets. |
| used_credits | Yes | Credits spent so far in the current billing cycle. May exceed total_credits on plans that allow overages. |
| total_credits | Yes | Total credits available for the current billing cycle (plan base + purchased + gifted). |
| max_concurrency | Yes | Maximum number of concurrent jobs allowed for this organization (plan base + purchased + gifted extras). |
| available_credits | Yes | Remaining credits (max(0, total_credits - used_credits)). Clamped to 0 when in overage. |
| used_quota_percent | Yes | Percentage of total_credits used in the current cycle, rounded to 1 decimal. Not capped — values >100 indicate overage. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. 'Return' and 'authenticated organization' imply a read-only, org-scoped call with implicit auth, but it never states that it has no side effects, whether results are cached, or any rate/limit behavior. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what is returned, followed by the one actionable usage cue. No filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so enumerating return fields is a bonus rather than a necessity, and 0 params keep the call simple. The only real gap is not contrasting this with whoami for agents deciding which introspection tool to call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly implies no inputs are needed and implicitly scopes the call to the authenticated org.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific resource (billing-cycle usage for the authenticated organization) and enumerates the exact fields returned (credits, used percent, max concurrency, reset time). It is not confused with the scrape* or map siblings, though it never explicitly names whoami as a near-neighbor that also reports on the caller.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete triggering condition: call before launching large scrape jobs to confirm available credit. That ties it directly to the scrape siblings. It stops short of stating when not to call it (e.g., it's unnecessary for small jobs or for per-user checks).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the organization name, token name, and truncated token preview for the API key currently configured on the MCP server. Useful for confirming which account is in use before performing credit-consuming operations.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| token_name | Yes | User-assigned name of the API token authenticating the request. |
| token_preview | Yes | Truncated preview of the API token (e.g. `cwbl_…xyz`). Safe to display; does not authenticate. |
| organization_name | Yes | Display name of the organization that owns the token. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explicitly states the operation is a return (read-only) and discloses that the token preview is truncated, which is a useful security-related behavioral trait. It does not explicitly mention side effects or credit consumption, but for a whoami-style identity check the behavior is simple and adequately conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The first sentence front-loads the action and return values; the second adds a practical usage note. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is fully complete. It states what information is returned and provides a clear reason to call the tool. No additional context is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter detail, but none is needed since the input schema is empty and there is nothing to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with the verb 'Return' and specifies a concrete resource: the organization name, token name, and truncated token preview for the currently configured API key. This clearly identifies the tool's purpose and differentiates it from the scraping, mapping, and usage sibling tools without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit when-to-use situation: confirming which account is in use before credit-consuming operations. It does not name alternative tools or state when not to use it, but the siblings are so distinct that the context is sufficient for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.3.3map1 field changedInput schema / properties / cache / properties / max_age / anyOfPrevious value: -[
- {
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
- },
- {
- "format": "date-time",
- "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
- "type": "string"
- }
-]New value: +[
+ {
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+ },
+ {
+ "format": "date-time",
+ "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
+ "type": "string"
+ }
+]scrape5 fields changedInput schema / properties / cache / properties / max_age / anyOfPrevious value: -[
- {
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
- },
- {
- "format": "date-time",
- "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
- "type": "string"
- }
-]New value: +[
+ {
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+ },
+ {
+ "format": "date-time",
+ "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
+ "type": "string"
+ }
+]Output schema / properties / images / items / properties / alt / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / images / items / properties / alt / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / metadata / properties / favicon_url / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / metadata / properties / favicon_url / typeAdded value: +[
+ "string",
+ "null"
+]scrape_async1 field changedInput schema / properties / cache / properties / max_age / anyOfPrevious value: -[
- {
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
- },
- {
- "format": "date-time",
- "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
- "type": "string"
- }
-]New value: +[
+ {
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+ },
+ {
+ "format": "date-time",
+ "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
+ "type": "string"
+ }
+]scrape_result4 fields changedOutput schema / properties / images / items / properties / alt / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / images / items / properties / alt / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / metadata / properties / favicon_url / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / metadata / properties / favicon_url / typeAdded value: +[
+ "string",
+ "null"
+]usage1 field changedOutput schema / properties / usage_reset / patternPrevious value: -"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"New value: +"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"v1.1.1map5 fields changedInput schema / properties / zero_data_retentionAdded value: +{
+ "description": "Keeps the result out of the shared cache; anything stored to deliver it is kept for 24 hours, then deleted. Adds 1 credit. Must be enabled for your organization. See https://crawlbrulee.com/docs/zero-data-retention.",
+ "type": "boolean"
+}Output schema / properties / response_meta / properties / usage / descriptionPrevious value: -"What this map request cost: total_credit_cost = engine_credit_cost × proxy_multiplier, plus the billed engine and the resolved proxy tier."New value: +"What this map request cost: total_credit_cost = engine_credit_cost × proxy_multiplier + zero_data_retention_credit_cost, plus the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / properties / creditsRemoved value: -{
- "deprecated": true,
- "description": "Deprecated: use total_credit_cost, which always has the same value. This field will be removed in a future version.",
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
-}Output schema / properties / response_meta / properties / usage / properties / total_credit_cost / descriptionPrevious value: -"Credits charged for this map request. Always equals engine_credit_cost × proxy_multiplier. 0 for a cache hit, and for an empty map when the site answered only with statuses we do not bill (a 5xx, for example) or not at all. Older api versions do not send it; read `credits` then, which has the same value."New value: +"Credits charged for this map request. Always equals engine_credit_cost × proxy_multiplier + zero_data_retention_credit_cost. 0 for a cache hit, and for an empty map when the site answered only with statuses we do not bill (a 5xx, for example) or not at all. Older api versions do not send it."Output schema / properties / response_meta / properties / usage / properties / zero_data_retention_credit_costAdded value: +{
+ "description": "Credits added by zero data retention: 1 on a billed, fresh result, else 0. Older api versions do not send it.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}scrape14 fields changedInput schema / properties / extract / properties / cleaned_html / descriptionPrevious value: -"Extract cleaned HTML (main content only)"New value: +"Extract cleaned HTML: the page body with scripts, styles, ads and cookie banners removed"Input schema / properties / extract / properties / elementsAdded value: +{
+ "additionalProperties": {
+ "anyOf": [
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "all": {
+ "default": false,
+ "description": "Return every match as a list instead of the first. Defaults to false",
+ "type": "boolean"
+ },
+ "attribute": {
+ "description": "The attribute to read when `output` is `attribute`. `href` and `src` come back as full urls",
+ "maxLength": 100,
+ "minLength": 1,
+ "type": "string"
+ },
+ "fields": {
+ "additionalProperties": {
+ "anyOf": [
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "all": {
+ "default": false,
+ "type": "boolean"
+ },
+ "attribute": {
+ "maxLength": 100,
+ "minLength": 1,
+ "type": "string"
+ },
+ "fields": {
+ "additionalProperties": {
+ "anyOf": [
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "all": {
+ "default": false,
+ "type": "boolean"
+ },
+ "attribute": {
+ "maxLength": 100,
+ "minLength": 1,
+ "type": "string"
+ },
+ "fields": {
+ "additionalProperties": {
+ "anyOf": [
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "all": {
+ "default": false,
+ "type": "boolean"
+ },
+ "attribute": {
+ "maxLength": 100,
+ "minLength": 1,
+ "type": "string"
+ },
+ "output": {
+ "enum": [
+ "text",
+ "html",
+ "attribute"
+ ],
+ "type": "string"
+ },
+ "selector": {
+ "maxLength": 500,
+ "type": "string"
+ }
+ },
+ "required": [
+ "selector"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "output": {
+ "enum": [
+ "text",
+ "html",
+ "attribute"
+ ],
+ "type": "string"
+ },
+ "selector": {
+ "maxLength": 500,
+ "type": "string"
+ }
+ },
+ "required": [
+ "selector"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "output": {
+ "enum": [
+ "text",
+ "html",
+ "attribute"
+ ],
+ "type": "string"
+ },
+ "selector": {
+ "maxLength": 500,
+ "type": "string"
+ }
+ },
+ "required": [
+ "selector"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "description": "Used instead of `output`: turns each match into an object of named values, each read inside that match only. Same shape as `elements`; nests up to 3 levels",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "output": {
+ "description": "What to return for a match: `text` (default), `html` (the outer HTML) or `attribute`",
+ "enum": [
+ "text",
+ "html",
+ "attribute"
+ ],
+ "type": "string"
+ },
+ "selector": {
+ "description": "CSS selector, up to 500 characters",
+ "maxLength": 500,
+ "type": "string"
+ }
+ },
+ "required": [
+ "selector"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "description": "Named values to read from the page by CSS selector, returned in the top-level `elements` field under the same names. Each value is either a selector string (the text of the first match) or an object with `selector`, `output`, `attribute` and `all`. `fields` (instead of `output`) turns each match into an object of named values read inside that match only, so a list of product cards can return a title, price and url per card. A name with no match is null, or [] with `all: true`. Read after cleanup; `<script>` and `<style>` tags are not part of it. An invalid selector is a 400. No extra credits, also when the page comes from cache. Limits and selector rules: https://crawlbrulee.com/docs/scrape/elements.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}Input schema / properties / extract / properties / metadata / descriptionPrevious value: -"Extract page metadata (title, description, OG tags, etc.). Read from the page head, which is capped at 2,000,000 characters — a larger head is truncated and the response carries a `metadata_truncated` warning."New value: +"Extract page metadata (title, description, OG tags, etc.) from the page head"Input schema / properties / zero_data_retentionAdded value: +{
+ "description": "Keeps the result out of the shared cache; anything stored to deliver it is kept for 24 hours, then deleted. Adds 1 credit. Must be enabled for your organization. See https://crawlbrulee.com/docs/zero-data-retention.",
+ "type": "boolean"
+}Output schema / properties / elementsAdded value: +{
+ "additionalProperties": {},
+ "description": "The values asked for in `extract.elements`, under the same names. Each name is a string, an object (a spec with `fields`), a list of either (`all: true`), or null when nothing matched (`[]` with `all: true`). An object holds its field names with the same kinds of values, nested up to 3 levels. Every requested name is always present, at every level of `fields`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}Output schema / properties / response_meta / properties / usage / descriptionPrevious value: -"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost, plus the billed engine and the resolved proxy tier."New value: +"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost, plus the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / properties / creditsRemoved value: -{
- "deprecated": true,
- "description": "Deprecated: use total_credit_cost, which always has the same value. This field will be removed in a future version.",
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
-}Output schema / properties / response_meta / properties / usage / properties / screenshot_slicesRemoved value: -{
- "deprecated": true,
- "description": "Deprecated: use screenshot_slicing_credit_cost, which always has the same value. Despite its name this is a 0/1 charge, not a count of slices. This field will be removed in a future version.",
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
-}Output schema / properties / response_meta / properties / usage / properties / screenshot_slicing_credit_cost / descriptionPrevious value: -"The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it; read `screenshot_slices` then, which has the same value."New value: +"The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it."Output schema / properties / response_meta / properties / usage / properties / total_credit_cost / descriptionPrevious value: -"Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it; read `credits` then, which has the same value."New value: +"Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it."Output schema / properties / response_meta / properties / usage / properties / zero_data_retention_credit_costAdded value: +{
+ "description": "Credits added by zero data retention: 1 on a billed, fresh result, else 0. Older api versions do not send it.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / screenshot / properties / slices / items / properties / url / descriptionPrevious value: -"URL to download this slice image"New value: +"Signed link to download this slice image. It expires 24 hours after the scrape (for an async scrape, 24 hours after you submitted it). Download the image, do not keep the link"Output schema / properties / screenshot / properties / url / descriptionPrevious value: -"URL to download the full screenshot image"New value: +"Signed link to download the full screenshot image. It expires 24 hours after the scrape (for an async scrape, 24 hours after you submitted it). Download the image, do not keep the link"Output schema / properties / warnings / descriptionPrevious value: -"Non-error notices about the scrape. Truncation codes — `screenshot_truncated` (long page exceeded the scrolling-screenshot height cap), `links_truncated` / `inline_images_truncated` (page had more links/images than the per-page extraction caps), `raw_html_truncated` / `metadata_truncated` (rendered HTML exceeded the per-page size budget) — mean the field is present but capped. Unavailability codes — `links_unavailable` / `inline_images_unavailable` / `metadata_unavailable` — mean that optional field could not be extracted and was omitted (null/empty) while the rest of the scrape succeeded, so an empty field carrying one of these does NOT mean the page had none. Stable string codes — clients can switch on them. Warnings are stored with the result: async result fetches and cache hits carry them too, filtered to the fields the request asked for."New value: +"Non-error notices about the scrape. Truncation codes — `screenshot_truncated` (long page exceeded the scrolling-screenshot height cap), `links_truncated` / `inline_images_truncated` (page had more links/images than the per-page extraction caps), `raw_html_truncated` (rendered HTML exceeded the per-page size budget) — mean the field is present but capped. `elements_truncated` means at least one `elements` value hit a limit: a list was cut at 1,000 matches, the request reached 10,000 matches in total, or a value did not fit the ~1 MB of values allowed per request (that value is then null, never cut short). Unavailability codes — `links_unavailable` / `inline_images_unavailable` / `metadata_unavailable` — mean that optional field could not be extracted and was omitted (null/empty) while the rest of the scrape succeeded, so an empty field carrying one of these does NOT mean the page had none. `screenshot_unavailable` means a screenshot was asked for, but the page came back from the http engine without one. Stable string codes — clients can switch on them. Warnings are stored with the result: async result fetches and cache hits carry them too, filtered to the fields the request asked for. `metadata_truncated` is retired and no longer sent: metadata has no size limit of its own now, though the code can still appear on results stored before that change."scrape_async4 fields changedInput schema / properties / extract / properties / cleaned_html / descriptionPrevious value: -"Extract cleaned HTML (main content only)"New value: +"Extract cleaned HTML: the page body with scripts, styles, ads and cookie banners removed"Input schema / properties / extract / properties / elementsAdded value: +{
+ "additionalProperties": {
+ "anyOf": [
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "all": {
+ "default": false,
+ "description": "Return every match as a list instead of the first. Defaults to false",
+ "type": "boolean"
+ },
+ "attribute": {
+ "description": "The attribute to read when `output` is `attribute`. `href` and `src` come back as full urls",
+ "maxLength": 100,
+ "minLength": 1,
+ "type": "string"
+ },
+ "fields": {
+ "additionalProperties": {
+ "anyOf": [
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "all": {
+ "default": false,
+ "type": "boolean"
+ },
+ "attribute": {
+ "maxLength": 100,
+ "minLength": 1,
+ "type": "string"
+ },
+ "fields": {
+ "additionalProperties": {
+ "anyOf": [
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "all": {
+ "default": false,
+ "type": "boolean"
+ },
+ "attribute": {
+ "maxLength": 100,
+ "minLength": 1,
+ "type": "string"
+ },
+ "fields": {
+ "additionalProperties": {
+ "anyOf": [
+ {
+ "maxLength": 500,
+ "type": "string"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "all": {
+ "default": false,
+ "type": "boolean"
+ },
+ "attribute": {
+ "maxLength": 100,
+ "minLength": 1,
+ "type": "string"
+ },
+ "output": {
+ "enum": [
+ "text",
+ "html",
+ "attribute"
+ ],
+ "type": "string"
+ },
+ "selector": {
+ "maxLength": 500,
+ "type": "string"
+ }
+ },
+ "required": [
+ "selector"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "output": {
+ "enum": [
+ "text",
+ "html",
+ "attribute"
+ ],
+ "type": "string"
+ },
+ "selector": {
+ "maxLength": 500,
+ "type": "string"
+ }
+ },
+ "required": [
+ "selector"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "output": {
+ "enum": [
+ "text",
+ "html",
+ "attribute"
+ ],
+ "type": "string"
+ },
+ "selector": {
+ "maxLength": 500,
+ "type": "string"
+ }
+ },
+ "required": [
+ "selector"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "description": "Used instead of `output`: turns each match into an object of named values, each read inside that match only. Same shape as `elements`; nests up to 3 levels",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "output": {
+ "description": "What to return for a match: `text` (default), `html` (the outer HTML) or `attribute`",
+ "enum": [
+ "text",
+ "html",
+ "attribute"
+ ],
+ "type": "string"
+ },
+ "selector": {
+ "description": "CSS selector, up to 500 characters",
+ "maxLength": 500,
+ "type": "string"
+ }
+ },
+ "required": [
+ "selector"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "description": "Named values to read from the page by CSS selector, returned in the top-level `elements` field under the same names. Each value is either a selector string (the text of the first match) or an object with `selector`, `output`, `attribute` and `all`. `fields` (instead of `output`) turns each match into an object of named values read inside that match only, so a list of product cards can return a title, price and url per card. A name with no match is null, or [] with `all: true`. Read after cleanup; `<script>` and `<style>` tags are not part of it. An invalid selector is a 400. No extra credits, also when the page comes from cache. Limits and selector rules: https://crawlbrulee.com/docs/scrape/elements.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}Input schema / properties / extract / properties / metadata / descriptionPrevious value: -"Extract page metadata (title, description, OG tags, etc.). Read from the page head, which is capped at 2,000,000 characters — a larger head is truncated and the response carries a `metadata_truncated` warning."New value: +"Extract page metadata (title, description, OG tags, etc.) from the page head"Input schema / properties / zero_data_retentionAdded value: +{
+ "description": "Keeps the result out of the shared cache; anything stored to deliver it is kept for 24 hours, then deleted. Adds 1 credit. Must be enabled for your organization. See https://crawlbrulee.com/docs/zero-data-retention.",
+ "type": "boolean"
+}scrape_result10 fields changedOutput schema / properties / elementsAdded value: +{
+ "additionalProperties": {},
+ "description": "The values asked for in `extract.elements`, under the same names. Each name is a string, an object (a spec with `fields`), a list of either (`all: true`), or null when nothing matched (`[]` with `all: true`). An object holds its field names with the same kinds of values, nested up to 3 levels. Every requested name is always present, at every level of `fields`.",
+ "propertyNames": {
+ "type": "string"
+ },
+ "type": "object"
+}Output schema / properties / response_meta / properties / usage / descriptionPrevious value: -"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost, plus the billed engine and the resolved proxy tier."New value: +"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost, plus the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / properties / creditsRemoved value: -{
- "deprecated": true,
- "description": "Deprecated: use total_credit_cost, which always has the same value. This field will be removed in a future version.",
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
-}Output schema / properties / response_meta / properties / usage / properties / screenshot_slicesRemoved value: -{
- "deprecated": true,
- "description": "Deprecated: use screenshot_slicing_credit_cost, which always has the same value. Despite its name this is a 0/1 charge, not a count of slices. This field will be removed in a future version.",
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
-}Output schema / properties / response_meta / properties / usage / properties / screenshot_slicing_credit_cost / descriptionPrevious value: -"The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it; read `screenshot_slices` then, which has the same value."New value: +"The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it."Output schema / properties / response_meta / properties / usage / properties / total_credit_cost / descriptionPrevious value: -"Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it; read `credits` then, which has the same value."New value: +"Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it."Output schema / properties / response_meta / properties / usage / properties / zero_data_retention_credit_costAdded value: +{
+ "description": "Credits added by zero data retention: 1 on a billed, fresh result, else 0. Older api versions do not send it.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / screenshot / properties / slices / items / properties / url / descriptionPrevious value: -"URL to download this slice image"New value: +"Signed link to download this slice image. It expires 24 hours after the scrape (for an async scrape, 24 hours after you submitted it). Download the image, do not keep the link"Output schema / properties / screenshot / properties / url / descriptionPrevious value: -"URL to download the full screenshot image"New value: +"Signed link to download the full screenshot image. It expires 24 hours after the scrape (for an async scrape, 24 hours after you submitted it). Download the image, do not keep the link"Output schema / properties / warnings / descriptionPrevious value: -"Non-error notices about the scrape. Truncation codes — `screenshot_truncated` (long page exceeded the scrolling-screenshot height cap), `links_truncated` / `inline_images_truncated` (page had more links/images than the per-page extraction caps), `raw_html_truncated` / `metadata_truncated` (rendered HTML exceeded the per-page size budget) — mean the field is present but capped. Unavailability codes — `links_unavailable` / `inline_images_unavailable` / `metadata_unavailable` — mean that optional field could not be extracted and was omitted (null/empty) while the rest of the scrape succeeded, so an empty field carrying one of these does NOT mean the page had none. Stable string codes — clients can switch on them. Warnings are stored with the result: async result fetches and cache hits carry them too, filtered to the fields the request asked for."New value: +"Non-error notices about the scrape. Truncation codes — `screenshot_truncated` (long page exceeded the scrolling-screenshot height cap), `links_truncated` / `inline_images_truncated` (page had more links/images than the per-page extraction caps), `raw_html_truncated` (rendered HTML exceeded the per-page size budget) — mean the field is present but capped. `elements_truncated` means at least one `elements` value hit a limit: a list was cut at 1,000 matches, the request reached 10,000 matches in total, or a value did not fit the ~1 MB of values allowed per request (that value is then null, never cut short). Unavailability codes — `links_unavailable` / `inline_images_unavailable` / `metadata_unavailable` — mean that optional field could not be extracted and was omitted (null/empty) while the rest of the scrape succeeded, so an empty field carrying one of these does NOT mean the page had none. `screenshot_unavailable` means a screenshot was asked for, but the page came back from the http engine without one. Stable string codes — clients can switch on them. Warnings are stored with the result: async result fetches and cache hits carry them too, filtered to the fields the request asked for. `metadata_truncated` is retired and no longer sent: metadata has no size limit of its own now, though the code can still appear on results stored before that change."scrape_status6 fields changedOutput schema / properties / response_meta / properties / usage / descriptionPrevious value: -"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost, plus the billed engine and the resolved proxy tier."New value: +"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost, plus the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / properties / creditsRemoved value: -{
- "deprecated": true,
- "description": "Deprecated: use total_credit_cost, which always has the same value. This field will be removed in a future version.",
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
-}Output schema / properties / response_meta / properties / usage / properties / screenshot_slicesRemoved value: -{
- "deprecated": true,
- "description": "Deprecated: use screenshot_slicing_credit_cost, which always has the same value. Despite its name this is a 0/1 charge, not a count of slices. This field will be removed in a future version.",
- "maximum": 9007199254740991,
- "minimum": 0,
- "type": "integer"
-}Output schema / properties / response_meta / properties / usage / properties / screenshot_slicing_credit_cost / descriptionPrevious value: -"The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it; read `screenshot_slices` then, which has the same value."New value: +"The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it."Output schema / properties / response_meta / properties / usage / properties / total_credit_cost / descriptionPrevious value: -"Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it; read `credits` then, which has the same value."New value: +"Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost + zero_data_retention_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it."Output schema / properties / response_meta / properties / usage / properties / zero_data_retention_credit_costAdded value: +{
+ "description": "Credits added by zero data retention: 1 on a billed, fresh result, else 0. Older api versions do not send it.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}v1.1.0map7 fields changedOutput schema / properties / response_meta / properties / usage / descriptionPrevious value: -"Usage accounting for this map request: credits charged, the billed engine, and the resolved proxy tier."New value: +"What this map request cost: total_credit_cost = engine_credit_cost × proxy_multiplier, plus the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / properties / credits / deprecatedAdded value: +trueOutput schema / properties / response_meta / properties / usage / properties / credits / descriptionPrevious value: -"Credits charged for this map request"New value: +"Deprecated: use total_credit_cost, which always has the same value. This field will be removed in a future version."Output schema / properties / response_meta / properties / usage / properties / engine_credit_costAdded value: +{
+ "description": "The engine base charged, before the proxy multiplier: 1 for \"http\", 0 for \"cache\". Also 0 for an empty map that is not billed. Older api versions do not send it.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / proxy_multiplierAdded value: +{
+ "description": "The multiplier of the proxy tier the request ran on: 1 for \"basic\", 5 for \"advanced\". Always reported, even when the engine cost is 0. Older api versions do not send it.",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / total_credit_costAdded value: +{
+ "description": "Credits charged for this map request. Always equals engine_credit_cost × proxy_multiplier. 0 for a cache hit, and for an empty map when the site answered only with statuses we do not bill (a 5xx, for example) or not at all. Older api versions do not send it; read `credits` then, which has the same value.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / requiredPrevious value: -[
- "credits",
- "engine",
- "proxy"
-]New value: +[
+ "engine",
+ "proxy"
+]scrape14 fields changedOutput schema / properties / page_status_codeAdded value: +{
+ "description": "The HTTP status the site answered with for the final page, after redirects. Check it before you trust the content. A page the site served is a successful result whatever its status: a 404 or 503 page comes back with its content here, not as an error, so a 404 means the markdown is the site's \"not found\" page, not the page you asked for. Billing follows this status: 2xx and 4xx pages are billed, except 403, 407, 408, 429 and 451; 5xx pages are never billed. Older api versions do not send it; they only returned pages that loaded normally.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Output schema / properties / response_meta / descriptionPrevious value: -"Request-level metadata. `response_meta.usage` reports credits charged, the billed engine, the resolved proxy tier, and any screenshot-slice add-on."New value: +"Request-level metadata. `response_meta.usage` reports what the request cost (total_credit_cost and its parts), the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / descriptionPrevious value: -"Usage accounting for this request: credits charged, billed engine, resolved proxy tier, and screenshot-slice add-on."New value: +"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost, plus the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / properties / credits / deprecatedAdded value: +trueOutput schema / properties / response_meta / properties / usage / properties / credits / descriptionPrevious value: -"Credits actually charged for this request. Always equals the engine base × the proxy multiplier, plus screenshot_slices. A cache hit has engine \"cache\" (base 0), so it costs only the parts we still had to compute — a newly produced screenshot-slice variant — and is otherwise free."New value: +"Deprecated: use total_credit_cost, which always has the same value. This field will be removed in a future version."Output schema / properties / response_meta / properties / usage / properties / engine / descriptionPrevious value: -"The engine base the request was billed at — \"http\" (1 credit), \"browser\" (3), \"screenshot\" (5), or \"cache\" (0, the result was served from cache) — before the proxy multiplier. Reflects what was delivered, never what was requested."New value: +"The engine the request was billed at — \"http\", \"browser\", \"screenshot\", or \"cache\" (the result was served from cache). Reflects what was delivered, never what was requested."Output schema / properties / response_meta / properties / usage / properties / engine_credit_costAdded value: +{
+ "description": "The engine base charged, before the proxy multiplier: 1 for \"http\", 3 for \"browser\", 5 for \"screenshot\", 0 for \"cache\". Also 0 when the page is not billed (see page_status_code). Older api versions do not send it.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / proxy / descriptionPrevious value: -"The proxy tier the request actually ran on (resolved value — never `auto`; `auto` is resolved server-side to `basic` or `advanced`)."New value: +"The proxy tier the request actually ran on (resolved value — never `auto`; `auto` is resolved server-side to `basic` or `advanced`). \"advanced\" multiplies the engine base by 5."Output schema / properties / response_meta / properties / usage / properties / proxy_multiplierAdded value: +{
+ "description": "The multiplier of the proxy tier the request ran on: 1 for \"basic\", 5 for \"advanced\". Always reported, even when the engine cost is 0. Older api versions do not send it.",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / screenshot_slices / deprecatedAdded value: +trueOutput schema / properties / response_meta / properties / usage / properties / screenshot_slices / descriptionPrevious value: -"Whether this request was billed the screenshot-split add-on: 1 when the screenshot was split on this request (a flat +1 credit outside the proxy multiplier, regardless of how many slices the split produced), else 0 — including a cache hit that reused an already-existing slice variant."New value: +"Deprecated: use screenshot_slicing_credit_cost, which always has the same value. Despite its name this is a 0/1 charge, not a count of slices. This field will be removed in a future version."Output schema / properties / response_meta / properties / usage / properties / screenshot_slicing_credit_costAdded value: +{
+ "description": "The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it; read `screenshot_slices` then, which has the same value.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / total_credit_costAdded value: +{
+ "description": "Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it; read `credits` then, which has the same value.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / requiredPrevious value: -[
- "credits",
- "engine",
- "proxy",
- "screenshot_slices"
-]New value: +[
+ "engine",
+ "proxy"
+]scrape_result14 fields changedOutput schema / properties / page_status_codeAdded value: +{
+ "description": "The HTTP status the site answered with for the final page, after redirects. Check it before you trust the content. A page the site served is a successful result whatever its status: a 404 or 503 page comes back with its content here, not as an error, so a 404 means the markdown is the site's \"not found\" page, not the page you asked for. Billing follows this status: 2xx and 4xx pages are billed, except 403, 407, 408, 429 and 451; 5xx pages are never billed. Older api versions do not send it; they only returned pages that loaded normally.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+}Output schema / properties / response_meta / descriptionPrevious value: -"Request-level metadata. `response_meta.usage` reports credits charged, the billed engine, the resolved proxy tier, and any screenshot-slice add-on."New value: +"Request-level metadata. `response_meta.usage` reports what the request cost (total_credit_cost and its parts), the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / descriptionPrevious value: -"Usage accounting for this request: credits charged, billed engine, resolved proxy tier, and screenshot-slice add-on."New value: +"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost, plus the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / properties / credits / deprecatedAdded value: +trueOutput schema / properties / response_meta / properties / usage / properties / credits / descriptionPrevious value: -"Credits actually charged for this request. Always equals the engine base × the proxy multiplier, plus screenshot_slices. A cache hit has engine \"cache\" (base 0), so it costs only the parts we still had to compute — a newly produced screenshot-slice variant — and is otherwise free."New value: +"Deprecated: use total_credit_cost, which always has the same value. This field will be removed in a future version."Output schema / properties / response_meta / properties / usage / properties / engine / descriptionPrevious value: -"The engine base the request was billed at — \"http\" (1 credit), \"browser\" (3), \"screenshot\" (5), or \"cache\" (0, the result was served from cache) — before the proxy multiplier. Reflects what was delivered, never what was requested."New value: +"The engine the request was billed at — \"http\", \"browser\", \"screenshot\", or \"cache\" (the result was served from cache). Reflects what was delivered, never what was requested."Output schema / properties / response_meta / properties / usage / properties / engine_credit_costAdded value: +{
+ "description": "The engine base charged, before the proxy multiplier: 1 for \"http\", 3 for \"browser\", 5 for \"screenshot\", 0 for \"cache\". Also 0 when the page is not billed (see page_status_code). Older api versions do not send it.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / proxy / descriptionPrevious value: -"The proxy tier the request actually ran on (resolved value — never `auto`; `auto` is resolved server-side to `basic` or `advanced`)."New value: +"The proxy tier the request actually ran on (resolved value — never `auto`; `auto` is resolved server-side to `basic` or `advanced`). \"advanced\" multiplies the engine base by 5."Output schema / properties / response_meta / properties / usage / properties / proxy_multiplierAdded value: +{
+ "description": "The multiplier of the proxy tier the request ran on: 1 for \"basic\", 5 for \"advanced\". Always reported, even when the engine cost is 0. Older api versions do not send it.",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / screenshot_slices / deprecatedAdded value: +trueOutput schema / properties / response_meta / properties / usage / properties / screenshot_slices / descriptionPrevious value: -"Whether this request was billed the screenshot-split add-on: 1 when the screenshot was split on this request (a flat +1 credit outside the proxy multiplier, regardless of how many slices the split produced), else 0 — including a cache hit that reused an already-existing slice variant."New value: +"Deprecated: use screenshot_slicing_credit_cost, which always has the same value. Despite its name this is a 0/1 charge, not a count of slices. This field will be removed in a future version."Output schema / properties / response_meta / properties / usage / properties / screenshot_slicing_credit_costAdded value: +{
+ "description": "The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it; read `screenshot_slices` then, which has the same value.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / total_credit_costAdded value: +{
+ "description": "Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it; read `credits` then, which has the same value.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / requiredPrevious value: -[
- "credits",
- "engine",
- "proxy",
- "screenshot_slices"
-]New value: +[
+ "engine",
+ "proxy"
+]scrape_status14 fields changedOutput schema / properties / error / descriptionPrevious value: -"Error message if the job ended in `failed`"New value: +"Error message if the job ended in `failed`. A job whose page the site served, even a 404 page, ends `done`, not `failed`: read `page_status_code` in the `scrape_result`."Output schema / properties / response_meta / descriptionPrevious value: -"Usage accounting for the finished job. Present only once the job is `done`; `response_meta.usage` reports credits charged, the billed engine, the resolved proxy tier, and any screenshot-slice add-on."New value: +"Usage accounting for the finished job. Present only once the job is `done`; `response_meta.usage` reports what the job cost (total_credit_cost and its parts), the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / descriptionPrevious value: -"Usage accounting for this request: credits charged, billed engine, resolved proxy tier, and screenshot-slice add-on."New value: +"What this request cost and why: total_credit_cost = engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost, plus the billed engine and the resolved proxy tier."Output schema / properties / response_meta / properties / usage / properties / credits / deprecatedAdded value: +trueOutput schema / properties / response_meta / properties / usage / properties / credits / descriptionPrevious value: -"Credits actually charged for this request. Always equals the engine base × the proxy multiplier, plus screenshot_slices. A cache hit has engine \"cache\" (base 0), so it costs only the parts we still had to compute — a newly produced screenshot-slice variant — and is otherwise free."New value: +"Deprecated: use total_credit_cost, which always has the same value. This field will be removed in a future version."Output schema / properties / response_meta / properties / usage / properties / engine / descriptionPrevious value: -"The engine base the request was billed at — \"http\" (1 credit), \"browser\" (3), \"screenshot\" (5), or \"cache\" (0, the result was served from cache) — before the proxy multiplier. Reflects what was delivered, never what was requested."New value: +"The engine the request was billed at — \"http\", \"browser\", \"screenshot\", or \"cache\" (the result was served from cache). Reflects what was delivered, never what was requested."Output schema / properties / response_meta / properties / usage / properties / engine_credit_costAdded value: +{
+ "description": "The engine base charged, before the proxy multiplier: 1 for \"http\", 3 for \"browser\", 5 for \"screenshot\", 0 for \"cache\". Also 0 when the page is not billed (see page_status_code). Older api versions do not send it.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / proxy / descriptionPrevious value: -"The proxy tier the request actually ran on (resolved value — never `auto`; `auto` is resolved server-side to `basic` or `advanced`)."New value: +"The proxy tier the request actually ran on (resolved value — never `auto`; `auto` is resolved server-side to `basic` or `advanced`). \"advanced\" multiplies the engine base by 5."Output schema / properties / response_meta / properties / usage / properties / proxy_multiplierAdded value: +{
+ "description": "The multiplier of the proxy tier the request ran on: 1 for \"basic\", 5 for \"advanced\". Always reported, even when the engine cost is 0. Older api versions do not send it.",
+ "exclusiveMinimum": 0,
+ "maximum": 9007199254740991,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / screenshot_slices / deprecatedAdded value: +trueOutput schema / properties / response_meta / properties / usage / properties / screenshot_slices / descriptionPrevious value: -"Whether this request was billed the screenshot-split add-on: 1 when the screenshot was split on this request (a flat +1 credit outside the proxy multiplier, regardless of how many slices the split produced), else 0 — including a cache hit that reused an already-existing slice variant."New value: +"Deprecated: use screenshot_slicing_credit_cost, which always has the same value. Despite its name this is a 0/1 charge, not a count of slices. This field will be removed in a future version."Output schema / properties / response_meta / properties / usage / properties / screenshot_slicing_credit_costAdded value: +{
+ "description": "The screenshot slicing add-on: 1 when the screenshot was split into slices on this request (a flat +1 credit outside the proxy multiplier, however many slices it made), else 0. A cache hit that reused slices that already existed costs 0. Older api versions do not send it; read `screenshot_slices` then, which has the same value.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / properties / total_credit_costAdded value: +{
+ "description": "Credits charged for this request. Always equals engine_credit_cost × proxy_multiplier + screenshot_slicing_credit_cost. 0 when nothing is billed: a cache hit, or a page whose status is not billed (see page_status_code). Older api versions do not send it; read `credits` then, which has the same value.",
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+}Output schema / properties / response_meta / properties / usage / requiredPrevious value: -[
- "credits",
- "engine",
- "proxy",
- "screenshot_slices"
-]New value: +[
+ "engine",
+ "proxy"
+]v1.0.3mapscrapescrape_asyncscrape_resultscrape_statususagewhoamiScored across 7 tools
Most tools have clearly distinct roles: map for discovery, scrape for one-shot fetches, and the async trio (scrape_async/scrape_status/scrape_result) split cleanly by submit/poll/fetch. The main overlap is scrape vs scrape_async, which both extract page content; the descriptions explicitly steer toward sync for quick fetches and async for long jobs, but an agent could still misselect. whoami and usage are related (account/credits) yet distinguishable.
All names are lowercase snake_case, which is consistent. There is a minor convention mismatch within the scrape family: scrape_async is verb-first while scrape_status and scrape_result are noun-first, but each name remains immediately readable and grouped by the 'scrape' prefix. map, whoami and usage are single-word outliers but recognizable.
Seven tools is well-scoped for a scraping API wrapper: four cover the scrape lifecycle (sync, async submit, status, result), one for discovery, and two for account/billing introspection. No tool feels redundant or missing at the count level.
The core lifecycle is covered: site discovery via map, sync and async scraping, polling and result retrieval, plus auth and usage checks. Minor gaps exist — no cancel/abort for async jobs, no job listing, and no recursive multi-page crawl beyond map+scrape — but these are workable for typical agent workflows.
Web scraping, extraction and search for AI agents. Hosted MCP with workspace API keys.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Markdown scrape, site map, page metadata, screenshots, web search and PDF to text. Pay per call
Web scraping for agents. Point it at a URL and it returns the page as clean markdown, JavaScript-rendered pages included. Point it at a site and it maps the URLs or crawls the section you need in the background, a few pages at a time so results fit in the conversation. Search the web and read full pages, extract fields with a JSON schema you define (validated, never invented), read a store's catalogue or a blog's posts from the platform's own feed, and check whether a page has changed. Failed requests cost nothing. The free plan includes 1,500 credits a month.
