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

Description and use

A spend‑gate system for AI agents using Apify’s metered API enforces three steps: a free count, a reproducible random sample, and user approval before a full paid run, preventing accidental costs.

Problem

AI agents need a disciplined way to interact with metered data APIs so they do not incur unexpected costs.

Outcome

The spend‑gate prevented a costly full run by enforcing a free count, a reproducible random sample, and user approval before the paid run.

Workflow

• 1. Agent requests a count (mode=count) to get the total number of matching rows – free.
• 2. Agent requests a random sample (mode=people, maxResults=100, sampleSeed set) to estimate data quality and cost – charged only for the sample.
• 3. Agent requests the full run (mode=people, maxResults=desired) after approval – charged for the full set.
• 4. A PreToolUse hook checks the tool name, mode, and maxResults; it blocks or allows the call based on the spend‑gate rules.

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 sample is the step the agent is allowed to pay for without asking. Its job is to turn the count into an expected delivery: of the 22,370, how many will arrive with a work email on record, how many with a personal one, what the employer sizes look like.

Source

A hook is a script that runs before the tool call, outside the model. It does not forget, and it does not read the data.

Source

The matcher is a regular expression because of the .*; a plain string would have to match the tool name exactly.

Source