Extract HTML Tables

web.extract_tables

ProductionEngine wrapper (Class A)Deterministicstrictmoderatev1.0.0

File inputNo network

Overview

You send HTML containing tables and we hand back each one as rows of strings plus records keyed by column name. Rowspan and colspan are expanded onto a grid so every row has the same width, headers are chosen by document structure rather than by guessing what a column means, and repeated header names get a numbered suffix so the record keys stay unique. Every value stays a string — we never decide that something looks like a number, a date, or a currency — and nothing is fetched. Accepts file input via file_ref — no need to extract file content first.

Tables with merged cells and stray header rows are easy to misread, and a wrong row silently poisons whatever you do next.

Reliability

Same markup and same options always give the same rows, and nothing leaves the platform. Expect these habits: every value is a string, a missing cell becomes an empty string so rows stay rectangular, a table with no resolvable header returns empty columns and empty records while rows still work, duplicate header names get a numbered suffix and a warning, a blank header becomes column_N by position, and sourceIndex counts the elements your selector matched, so skipped nested tables leave gaps. Four failures stop the call and mean the request has to change; retrying the same input cannot help. TABLE_SELECTOR_INVALID — the selector does not parse or is over 512 characters, so fix the selector text; TABLE_SPAN_INVALID — two spans claim the same cell, which means the markup itself is contradictory, so repair the table or turn the expand options off; TABLE_DIMENSION_LIMIT_EXCEEDED — a table is wider than 1000 columns once spans are expanded, so narrow the selector to smaller tables; TABLE_CELL_LIMIT_EXCEEDED — the expanded cells across all tables passed maxCells, so raise it, lower maxTables, or select fewer tables.

Context footprint

Rows and records both come back, so the reply is roughly twice the table's own size; a large page of tables can be very large. A successful call costs 1 execution credit.

When to use it

When you hold markup and want each table as rows, records, and column names.

When the page still needs fetching, or when you want values converted into numbers, dates, or anything other than strings.

Runs on jsoup, whose HTML and selector engines follow the browser parsing rules.

Scope

Note

We turn the tables in markup you hold into rows and records, handling headers and spans the same way every time.

Non-goals

Does not guess that a column holds numbers, dates, or money
Does not fetch the page
Does not name a column from its meaning, only from the markup
Does not reconcile tables across pages or merge them

Properties

IdempotentRetry safeStreaming supportedFile input supportedRequires external service

Capabilities

data-transformationparsing

Cost & billing

Flat rate per invocation

MetercallsBillable onsuccessCost per call1 credit

File handling

Accepts file_refProduces file_refMax input2 MBMax file size2 MB

File limits

Constraints this skill applies to your input and generated files. The “Limited by” column shows the static source of each cap; none of these can be raised by upgrading your plan.

Limit	Value	Limited by
Maximum size per input file	2 MiB	Skill maximum

How we handle your data

Sensitive input, safe output

What this means

This skill may receive sensitive content, but it does not target sensitive data and returns only a structured non-sensitive result.

Squillify guarantees

Runs inside Squillify
This skill runs inside Squillify.
Payloads are not sent to an external service by this skill.
Squillify does not permanently store submitted payloads.
Telemetry records metadata only, not submitted content.
Submitted payloads are not used for training.
Submitted payloads are not reviewed by humans.
This skill does not target sensitive data.
The response does not contain submitted content.

Your responsibility

Squillify does not determine whether submitted content is sensitive. Your application is responsible for deciding what data it is allowed to submit. Your application is responsible for securing the response.

Read the Microskill Data Handling Policy

Input schema

Field	Type	Required	Description
html	string	No	Bounded inline source. Required unless file_ref is provided.
file_ref	string	No	Tenant-scoped opaque file reference. Omit it when inline source is supplied.
selector	string	No	Optional CSS selector restricting tables; omit it to inspect every table.
options	object	No	Purpose-bound bounded table-extraction option object; omit it to use safe defaults. It contains from 0 through 256 purpose-bound properties — unconstrained RFC 8259 JSON items.

Output schema

Field	Type	Required	Description
tables	array	Yes	Bounded array of table receipts in document order with headers, rows, caption, and source index. The item shape is defined by the nested schema and the array contains from 0 through 10000 items.
tableCount	integer	Yes	Returned table count.
warnings	array	Yes	Bounded array of non-fatal safe warning strings. The item shape is defined by the nested schema and the array contains from 0 through 20000 items.
_meta	object	Yes	Closed extraction metadata receipt with source and truncation details. Its documented web receipt properties are bounded to 128 entries — unconstrained RFC 8259 JSON items.

API contract

POST /v1/execute

curl

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"web.extract_tables","input":{"html":"<table><tr><th>Plan</th></tr><tr><td>Team</td></tr></table>"}}'

Integrations

TypeScript SDK

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("web.extract_tables", {"html":"<table><caption>Plans</caption><tr><th>Plan</th><th>Seats</th></tr><tr><td>Team</td><td>25</td></tr></table>"});

Errors

Code	HTTP	Retryable	Description
VALIDATION_ERROR	400	No	The request payload failed schema validation.
UNAUTHORIZED	401	No	Missing or invalid API key.
SKILL_NOT_ACCESSIBLE	403	No	The API key is not granted access to this skill.
SKILL_NOT_AVAILABLE_FOR_PLAN	403	No	This skill is not included in your current plan.
PLAN_ELIGIBILITY_UNAVAILABLE	503	Yes	Plan eligibility could not be decided. Retry after backoff.
SKILL_NOT_FOUND	404	No	The requested skill or version does not exist.
TENANT_RATE_LIMITED	429	Yes	Request rate limit exceeded. Retry after backoff.
QUOTA_EXCEEDED	429	Yes	Plan quota exhausted. Retryable once the quota period resets.
EXECUTION_TIMEOUT	504	Yes	Execution exceeded the allowed time budget.
TABLE_SELECTOR_INVALID	400	No	The request payload failed this skill's input validation.
TABLE_SPAN_INVALID	400	No	The request payload failed this skill's input validation.
TABLE_DIMENSION_LIMIT_EXCEEDED	429	No	A size, quota, rate, or time limit was exceeded.
TABLE_CELL_LIMIT_EXCEEDED	429	No	A size, quota, rate, or time limit was exceeded.

Other limits

Limit	Value
Recommended inline bytes	32 KiB

Limitations

Does not guess that a column holds numbers, dates, or money
Does not fetch the page
Does not name a column from its meaning, only from the markup
Does not reconcile tables across pages or merge them
Fetching the page — bring the markup with you
Deciding what type or unit a column holds

How to call

POST /v1/execute (requires authentication)

Request bodyjson

{
  "skillKey": "web.extract_tables",
  "input": {
    "html": "<table><caption>Plans</caption><tr><th>Plan</th><th>Seats</th></tr><tr><td>Team</td><td>25</td></tr></table>"
  }
}

Examples

Table with a header row becomes records

Inputjson

{
  "html": "<table><caption>Plans</caption><tr><th>Plan</th><th>Seats</th></tr><tr><td>Team</td><td>25</td></tr></table>"
}

Expected outputjson

{
  "_meta": {
    "extractionProfile": "html-tables-1",
    "cellsProcessed": 4
  },
  "tables": [
    {
      "sourceIndex": 0,
      "caption": "Plans",
      "columns": [
        "plan",
        "seats"
      ],
      "headerTexts": [
        "Plan",
        "Seats"
      ],
      "rowCount": 1,
      "columnCount": 2,
      "rows": [
        [
          "Team",
          "25"
        ]
      ],
      "records": [
        {
          "seats": "25",
          "plan": "Team"
        }
      ]
    }
  ],
  "warnings": [],
  "tableCount": 1
}

Header mode none returns raw rows only