nimble-extract-templates-reference

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
• 2. Inspect a template (schema)
• 3. Run a template (realtime)
• 4. Run async
• 5. Run batch
• Response shapes

---

1. Discover templates

# List templates (paginated). No server-side search — filter client-side by
# display_name / name / metadata.domain for the target site.
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.