A spend gate for AI agents on metered data APIs: count, random sample, approved run, enforced by one Claude Code hook

Description and use

An automation recipe that enables AI agents to safely use metered data APIs by implementing a three‑step spend gate: count, seeded random sample, and approved full run.

Problem

AI agents can unintentionally incur high costs when calling metered data APIs due to default parameters and lack of pre‑execution checks.

Outcome

The spend gate reduced accidental high‑cost runs by ensuring agents first obtain a free count, then a representative sample, and only proceed to a full run after explicit approval. Sample runs showed realistic cost estimates and data quality metrics.

Workflow

• 1. Agent requests a count (mode: "count") to get total rows and confirm no charge per row.
• 2. Agent requests a random sample (mode: "people", maxResults <= 100, sampleSeed set) to estimate cost and data quality.
• 3. Agent requests full run (mode: "people", maxResults > 100) only after receiving approval from the hook.
• 4. The PreToolUse hook checks mode and maxResults, allows free modes, permits capped samples, and blocks or approves full runs based on user approval.

Evidence

The filter is the one from the job‑change part of the series: sales and revenue leaders at director level and above, employers of 50 to 5,000 people, US, UK and Germany, current role started in the last twelve months.

Source

The same filter counted 21,834 on 10 October. Four days, 536 more people, because start dates reach the database as people update their profiles.

Source

Run log: 12.6 seconds, charged events person-row: 100, apify-actor-start: 1, nothing on the profile or contacts tiers.

Source

The hook that enforces it: Claude Code runs PreToolUse hooks before every tool call that matches a pattern, and an exit code of 2 blocks the call and hands the script's stderr back to the agent as the reason.

Source