tap_run
Run a pre-built tap to extract structured data from a site. Returns rows, columns, and timing; results are cached for 5 minutes to avoid redundant calls.
Instructions
Run a pre-built tap. Preferred over tap.* tools — deterministic, zero AI at runtime. Returns {columns, rows, count, timing, cache_hit}. Read-intent taps are memoized for 5 minutes per process; identical calls return cached data with cache_hit:true. Pass {fresh:true} to bypass cache. Write-intent taps are never cached. If rows contain login/error page content or are empty on a site that requires login → call tap.runtime(runtime:'chrome') first, then retry. If rows is empty on a public site, use tap.doctor(site, name) for structured diagnosis. On transient failure (timeout, connection), RETRY tap.run — do not fall back to manual tap.* operations.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Site name | |
| name | Yes | Tap name | |
| args | No | Tap arguments | |
| fresh | No | Bypass the 5-minute per-process result cache. Use when you need current data despite a recent identical call. | |
| envelope | No | Response shape. 'bare' (default) returns {rows, columns, count, elapsed_ms}; 'annotation' wraps the result in a W3C Web Annotation with target + body:tap:RunResult + prov:wasDerivedFrom — useful for provenance chains and signing. Does NOT affect sub-tap composition or pipe bindings (those read the internal flat shape). | bare |