| name | nimble-extract-templates-reference |
| description | Reference for Nimble Extraction Templates — reusable, site-specific structured scrapers.
Load for Step 0 when a named site has a direct item to look up (by URL or identifier).
Covers: discover (list), inspect (get → input_schema/output_schema), run/async/batch,
response shapes, and the no-template→Web Search Agent routing rule. Existing templates only.
|
nimble extract:templates — reference
An Extraction Template is a reusable, preconfigured parser for one specific site: set up
once against that site's structure, then run repeatedly against known items (a URL, an ASIN,
a business ID) without rediscovering anything. Use a template whenever a matching one exists —
it returns clean, structured fields with zero selector work.
Existing templates only. Building or publishing new templates is out of scope here. If no
template covers a site, do not fall back to a raw extract (that pushes parsing onto the
user) and do not try to build one — route to a Web Search Agent instead
(references/nimble-agents/SKILL.md), which reasons about any site's structure without a
maintained template.
REST/SDK surface: POST /v2/extract/templates/{run,async,batch}.
Table of Contents
1. Discover templates
nimble --client-source nimble-agent-skills extract:templates list --limit 100
Parameters: --limit (int), --offset (int).
List JSON shape — each item carries the template name (the identifier used to run it)
and its published version's schemas:
{
"items": [
{
"id": "…",
"name": "reddit_post_comments_2026_07_19_8acvxcb0",
"published_version": {
"input_schema": { "type": "object", "required": ["…"], "properties": { … } },
"output_schema": { "type": "array", "items": { … } },
"metadata": { "display_name": "Reddit Post Comments", "domain": "reddit.com",
"vertical": "Social Media", "entity_type": "Product Detail Page (PDP)" }
}
}
]
}
Match by metadata.domain / metadata.display_name; run with the top-level name
(NOT the display_name).
2. Inspect a template (schema)
Always inspect the schema before running — it tells you the required inputs and the exact
output shape.
nimble --client-source nimble-agent-skills extract:templates get \
--extract-template-name <template_name>
Parameter: --extract-template-name — the template name (required).
Read input_schema.required for the params you must supply, and output_schema for the
records you'll get back (see Response shapes).
3. Run a template (realtime)
nimble --client-source nimble-agent-skills extract:templates run \
--template <template_name> \
--params '{"subreddit": "frugal", "post_id": "1ikbpew"}'
Parameters:
| Parameter | Type | Description |
|---|
--template | string | Template name (required) |
--params | JSON/YAML map | Inputs matching the template's input_schema (required) |
--format | string (repeat) | Extra response content formats to include (all disabled by default) |
--localization | bool | Enable zip_code/store_id localization (template-dependent) |
--params is a mapping, not key=value. Pass a JSON object ('{"asin":"B0…"}') or a
YAML mapping — --params 'key=value' is rejected.
4. Run async
For long jobs, submit and poll instead of blocking:
nimble --client-source nimble-agent-skills extract:templates async \
--template <template_name> --params '{…}'
Returns a task to poll. States: pending → success or error. Poll status with
nimble tasks get --task-id <id> until terminal, then fetch with
nimble tasks results --task-id <id> (see references/nimble-tasks/SKILL.md).
5. Run batch
Up to 1,000 items in one call — one shared template, per-item params:
nimble --client-source nimble-agent-skills extract:templates batch \
--template <template_name> \
--input '{"params": {"asin": "B0CHWRXH8B"}}' \
--input '{"params": {"asin": "B08N5WRWNW"}}'
Returns a batch_id. Poll with nimble batches progress --batch-id <id>, then
nimble batches get --batch-id <id> for task IDs and nimble tasks results --task-id <id>
for each. See references/nimble-tasks/SKILL.md.
Response shapes
The CLI response envelope is { url, task_id, status, data: { parsing }, metadata, status_code } — the parsed records live at data.parsing, so
--transform "data.parsing" extracts them in one shot:
nimble --client-source nimble-agent-skills --transform "data.parsing" \
extract:templates run --template amazon_pdp --params '{"asin": "B0CHWRXH8B"}'
The shape of data.parsing follows the template's output_schema — read it from get
before parsing:
output_schema.type | data.parsing shape | Examples |
|---|
array | list of record objects | list / SERP-style templates |
object | one flat record | detail / PDP-style templates |
object w/ entities | {"entities": {"OrganicResult": [...]}} | search/maps SERP templates |
If a run comes back empty or clearly wrong, say so plainly — a login wall, a changed page
structure, or malformed params are real outcomes. Re-check the input_schema, or route to a
Web Search Agent if the site simply isn't a good fit for a fixed template.
