Agentic Platform
Documentation API reference Tools Skills

Tools

HTML Executor

html_code_executor MCP

Execute a JavaScript function on HTML from SiteCrawler crawls.

Execute custom JavaScript extraction functions on HTML content from SiteCrawler. This agent is optimized for batch processing - when processing multiple URLs, they are sent to javascript executor together for better performance. The JavaScript function should be in the format 'function() { ... }' and has access to a `document` object for DOM traversal (querySelector, querySelectorAll, etc.). If no crawl is specified (analysis_slug in config), the last successful crawl is used. Temporary uploaded URLs on https://app.botify.com/:organization/:project/o/storage/tmp are resolved from project storage and do not require a crawl. Each input URL may carry a list of quality control expectations. When set, the agent evaluates them against the extracted JSON result and reports, per item, whether all expectations passed and the details of any failures.

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 URL to execute the JavaScript function on. Temporary uploaded URLs on https://app.botify.com/:organization/:project/o/storage/tmp are allowed.
expectations Quality control expectations the extracted result must satisfy. When provided, the agent evaluates them against the extracted JSON and reports any failures.
config
function required JavaScript function to execute on the HTML. Should be in the format 'function() { ... }' and return the extracted data.

Billing

Fixed cost per item requested. The code runs against HTML you have already supplied, inside Botify, so nothing further is billed.

These usage SKUs can be charged on a call.

SKU Credits Description
Tool call 1 per request Charged once per successful item.

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

URL to execute the JavaScript function on. Temporary uploaded URLs on https://app.botify.com/:organization/:project/o/storage/tmp are allowed.

expectations array

Quality control expectations the extracted result must satisfy. When provided, the agent evaluates them against the extracted JSON and reports any failures.

Items: Expectation

Default: []

Example
{
  "url": "string",
  "expectations": []
}

Type Definitions

2 types

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

ArrayItemMatch object
#

A sub-object pattern that at least one array item must match. The mapping ``fields`` is keyed by the sub-object's attribute names (e.g. ``{"review_text": "great", "review_rating": 5}``). Keys not listed here are not checked. For convenience, a bare sub-object is accepted as a shorthand for ``fields``: ``{"name": "Année", "value": "1982"}`` is normalised to ``{"fields": {"name": "Année", "value": "1982"}}``. To match an array of *scalars* (e.g. a list of URLs), pass the scalar directly in ``expected_array_items`` rather than an :class:`ArrayItemMatch`.

fields object

Sub-object fields to match (subset, no exhaustivity required)

instructions string | null

Free-form note describing how to locate this item in the page. Never used by the evaluator — purely informational.

Default: null

Expectation object
#

An expectation about a single field of the extracted JSON. Exactly one of ``expected_value`` (for scalar fields), ``expected_array_items`` (for array-item patterns) or ``expected_length`` (for the length of an array field) must be set. The ``operator`` is only meaningful for scalar and length expectations.

field string required

Name of the extracted JSON field to check. Supports dotted paths for nested objects (e.g. ``dimensions.width``).

operator string

Predicate applied between the actual value and ``expected_value`` (scalar expectations) or between the array length and ``expected_length`` (length expectations). Defaults to ``equals``. Length expectations support only ``equals`` / ``gt`` / ``gte`` / ``lt`` / ``lte``.

Values: equals contains matches_regex gt gte lt lte

Default: "equals"

expected_value null

Expected scalar value (set when the field is a scalar)

Default: null

expected_array_items ArrayItemMatch

Patterns to match against array items (set when the field is an array). Each pattern is either a scalar — the array must contain an item equal to it (use this for arrays of strings or numbers, e.g. image URLs) — or a sub-object of fields, in which case at least one array item must match all the listed fields. For each pattern, at least one item must match.

Items: ArrayItemMatch

Default: null

expected_length integer | null

Expected number of items of an array field (set to assert on the array length). Combined with ``operator`` (equals / gt / gte / lt / lte).

Default: null

instructions string | null

Free-form note describing how to locate this field on the page. Never used by the evaluator — purely informational.

Default: null

Configuration

object
Properties
function string required

JavaScript function to execute on the HTML. Should be in the format 'function() { ... }' and return the extracted data.

Example
{
  "function": "string"
}

Response

object

Output from HTML executor agent.

Properties
url string required

The URL that was processed

crawl string | null

Crawl Slug from SiteCrawler

Default: null

url_found boolean | null

Whether the URL was found in the crawl index

Default: false

result null

Result of executing the function on the HTML

Default: null

error string | null

Error if function execution failed

Default: null

quality_control_passed boolean | null

True when every expectation holds against the extracted result, False when at least one fails, None when no expectations were provided.

Default: null

quality_control_failures array

One entry per failed expectation (empty when passed or when no expectations were provided).

Items: ExpectationFailure

Default: []

Example
{
  "url": "string",
  "crawl": null,
  "url_found": false,
  "result": null,
  "error": null,
  "quality_control_passed": null,
  "quality_control_failures": []
}

Type Definitions

1 type

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

ExpectationFailure object
#

A single expectation that did not hold against the extracted JSON.

attribute string required

The (possibly dotted) field that failed

expected null

What was expected (scalar value or array patterns)

Default: null

result null

The value actually extracted (None when absent/null)

Default: null

message string required

Human-readable error message

Endpoints

POST http://agents.botify.com/{organization}/{project}/html_code_executor/process
POST http://agents.botify.com/{organization}/{project}/html_code_executor/batch_process
POST http://agents.botify.com/{organization}/{project}/html_code_executor/async_process
POST http://agents.botify.com/{organization}/{project}/html_code_executor/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_code_executor/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "url": "<url>"
  },
  "config": {
    "function": "<function>"
  }
}'

Over MCP

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

Raw metadata