Agentic Platform
Documentation API reference Tools Skills

Tools

HTML PageWorkers Preview

html_pageworkers_preview MCP Content

Preview PageWorkers.

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

Playground

Your organization, project and token stay in this browser's local storage and are sent straight to the API — this page never sees them.

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.

Billing

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 495 per 1,000 page Fetches a page from the live web as an ordinary visitor would.
Live page fetch, hard-blocked page 7,425 per 1,000 page A page that refused every gentler attempt. Charged on top of them, so a hard-blocked page costs the whole sequence.
Live page fetch, protected page 2,475 per 1,000 page A page that refused an ordinary fetch and had to be retried. Charged on top of the ordinary attempt, not instead of it.

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

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.

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

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.

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

Example
{
  "url": "string",
  "options": {
    "use_liquid_engine": false
  },
  "selectors": null,
  "templates": null,
  "extracts": null,
  "detect_json_ld_types": 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

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

Type Definitions

6 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

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