Tools

HTML PageWorkers Preview

html_pageworkers_preview MCP Content

Preview PageWorkers.

Get the preview for PageWorkers descriptor for a selector or templates rendering.

Playground

Organization Project

POST

item

url required

The URL to be used

options

Preview options

use_liquid_engine

Whether or not to use liquid engine

selectors

Optional list of extracts to preview. Each entry is an ExtractPreviewConfig object (kind: singleValue / multiValue / arrayOfObjects / jsonLd, with `type` for jsonLd) — the same shape as `extracts`. Config keys use snake_case (css_selector, container_selector, extract_type) and are converted to camelCase before hitting the JS engine. A bare string is also accepted as shorthand for a singleValue CSS selector (the legacy `list[str]` contract). Each entry returns the touched element descriptors plus the extracted value, serialized and truncated for display.

templates

Optional list of PageWorkers templates to preview. Each entry should be a JSON stringified version of a template, with the `extract` and `context` fields.

extracts

Optional map of named extracts to resolve against the page. Each value follows the ExtractPreviewConfig shape (singleValue / multiValue / arrayOfObjects / jsonLd). Config keys use snake_case (css_selector, container_selector, extract_type) to match the rest of the API; they are converted to camelCase before being passed to the JS engine. Unlike templates, the raw extracted values are returned to the caller without template rendering or truncation.

detect_json_ld_types

If true, return the list of unique @type values found in the page's JSON-LD blocks. Useful to discover what structured data is available before requesting an `extracts` with kind: jsonLd.

include_default_variables

If true, also return the PageWorkers default variables of the page (`_currentUrl`, `_currentTitle`...), the values the tag gives every template.

Credits

Fixed cost per URL requested. The preview is rendered inside Botify. Beyond the call you pay only for fetching the page: nothing if it is in your SiteCrawler crawl, a live page fetch otherwise.

These usage SKUs can be charged on a call, including SKUs from tools this one may call.

SKU	Credits	Description	Used by
Tool call	1 per request	Charged once per successful item, on top of any usage below.	This tool
Live page fetch	5 per 10 page	Fetches a page from the live web as an ordinary visitor would.	HTML Fetch `html_fetch`
Live page fetch, hard-blocked page	75 per 10 page	A page that refused every gentler attempt. Charged instead of them: the attempts it refused cost nothing.	HTML Fetch `html_fetch`
Live page fetch, protected page	25 per 10 page	A page that refused an ordinary fetch and had to be retried. Charged instead of the ordinary fetch, not on top of it.	HTML Fetch `html_fetch`

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object

Properties

url string required

The URL to be used

options PreviewOptions

Preview options

Type: PreviewOptions

Default: {"use_liquid_engine": false}

selectors array | null

Default: null

templates array | null

Optional list of PageWorkers templates to preview. Each entry should be a JSON stringified version of a template, with the `extract` and `context` fields.

Default: null

extracts object | null

Default: null

detect_json_ld_types boolean

If true, return the list of unique @type values found in the page's JSON-LD blocks. Useful to discover what structured data is available before requesting an `extracts` with kind: jsonLd.

Default: false

include_default_variables boolean

If true, also return the PageWorkers default variables of the page (`_currentUrl`, `_currentTitle`...), the values the tag gives every template.

Default: false

Example

{
  "url": "string",
  "options": {
    "use_liquid_engine": false
  },
  "selectors": null,
  "templates": null,
  "extracts": null,
  "detect_json_ld_types": false,
  "include_default_variables": false
}

Type Definitions

1 type

These are the available sub-object types that can be used in the properties above.

PreviewOptions object

use_liquid_engine boolean

Whether or not to use liquid engine

Default: false

Response

object

Properties

crawl string | null

If fetched from sitecrawler, the crawl where the URL was found

Default: ""

selectors_preview CssSelectorPreview

Preview of the elements matched by the CSS selectors

Items: CssSelectorPreview

Default: null

templates_preview TemplatePreview

Preview of the rendered templates

Items: TemplatePreview

Default: null

extracts ExtractResult

Resolved extracts for the requested keys. Each entry holds the native extracted value and a per-key error if extraction failed for that key on this page.

Type: ExtractResult

Default: null

json_ld_types array | null

Unique JSON-LD @type values present on the page, when `detect_json_ld_types` was requested.

Default: null

default_variables DefaultVariables

The PageWorkers default variables of the page, when `include_default_variables` was requested and they could be read.

Type: DefaultVariables

Default: null

Example

{
  "crawl": "",
  "selectors_preview": null,
  "templates_preview": null,
  "extracts": null,
  "json_ld_types": null,
  "default_variables": null
}

Type Definitions

7 types

These are the available sub-object types that can be used in the properties above.

CssSelectorPreview object

descriptors PreviewDescriptor

Items: PreviewDescriptor

Default: null

error string | null

Default: null

DefaultVariables object

The PageWorkers default variables of the page, as the tag gives them to every template. A template reads each one under two names: `current_url` is `_currentUrl` and `$currentUrl`. They are computed the way the server-side tag computes them: the protocol has no `:` and the query string no `?`. The bot id, device and environment are fixed preview values, as there is no requester here.

current_url string required

current_protocol string required

current_host string required

current_path string required

current_query_string string required

current_title string required

current_description string required

current_canonical string required

current_h1 string required

current_bot_id integer | null required

current_device string required

current_environment string required

ExtractResult object

value null

Default: null

error string | null

Default: null

PreviewAttribute object

key string required

value string | null required

truncated boolean required

PreviewDescriptor object

tag string required

first_attributes array required

Items: PreviewAttribute

inner_html_excerpt PreviewExcerpt required

Type: PreviewExcerpt

inner_text_excerpt PreviewExcerpt required

Type: PreviewExcerpt

has_other_attributes boolean required

PreviewExcerpt object

value string | null

Default: null

truncated boolean | null

Default: null

TemplatePreview object

result string | null

Default: null

error string | null

Default: null

truncated boolean

Default: false

Endpoints

POST http://agents.botify.com/{organization}/{project}/html_pageworkers_preview/process

POST http://agents.botify.com/{organization}/{project}/html_pageworkers_preview/batch_process

POST http://agents.botify.com/{organization}/{project}/html_pageworkers_preview/async_process

POST http://agents.botify.com/{organization}/{project}/html_pageworkers_preview/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/html_pageworkers_preview/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "url": "<url>"
  }
}'

Over MCP

This tool is exposed as the MCP tool html_pageworkers_preview. An MCP client passes organization, project and item as tool arguments. Set up MCP →

Raw metadata

GET /agents/html_pageworkers_preview — this page as JSON.
/agents/html_pageworkers_preview/skill.md — Markdown for coding agents.