Estimating a Batch Cost Before Running It with the Clay CLI

A routine's estimatedCreditCost.perRun multiplied by the number of rows in a JSONL file gives a cost estimate before any credits are spent. In the runs measured here, the 3-row estimate matched the 3 credits actually spent.

What you will build

An estimate_batch function that prints the row count, the per-run estimate, and the estimated total for a routine and a JSONL file.

clay routines get <routine>  ->  estimatedCreditCost.perRun
rows.jsonl                   ->  row count
    ↓
estimated_credits = rows * per_run

AI Prompt

Using the Clay CLI, estimate the credit cost of a bulk run before starting it.

Requirements:
- `clay routines get <routineId>` returns `estimatedCreditCost.perRun`, the estimated credits for one row.
- A bulk file has one JSON object per line, so the row count is the number of non-empty lines. Use `grep -c .` to count them.
- Multiply with `bc`, because per-run estimates can be decimals such as 3.3 or 18.2.
- `containsVariablePricing: true` on a routine means the final charge can differ from the estimate. Treat the number as a planning figure.
- The estimate does not account for runs that return nothing. For `Work Email`, a run with an empty result was not charged in one measurement.
- Run the verification step below before finishing.

Prerequisites

• The clay CLI on PATH, authenticated via clay login
• jq and bc
• A JSONL file such as rows.jsonl

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Define the function

estimate_batch() {
  local routine="$1" file="$2" per rows
  per=$(clay routines get "$routine" | jq .estimatedCreditCost.perRun)
  rows=$(grep -c . "$file")
  echo "rows=$rows per_run=$per estimated_credits=$(echo "$rows * $per" | bc)"
}

2. Estimate the same 3 rows for three routines

cat rows.jsonl
estimate_batch function:t_0tjqm9rUjfGY4MunGDM rows.jsonl
estimate_batch function:t_0tjqmaaroo9mQFCBA5C rows.jsonl
estimate_batch function:t_0tjqm9wYmmfbigtrMKs rows.jsonl

Real output:

{"id":"a","inputs":{"Company Name":"Notion"}}
{"id":"b","inputs":{"Company Name":"Figma"}}
{"id":"c","inputs":{"Company Name":"Linear"}}
rows=3 per_run=1 estimated_credits=3
rows=3 per_run=3 estimated_credits=9
rows=3 per_run=18.2 estimated_credits=54.6

The three estimates are for Company Domain, Work Email, and Enrich Person and Find Contact Details. Only the first routine accepts this file's input. The other two are estimated to show how the figure changes with the routine, and no runs were started for them.

3. Compare the estimate with a real run

estimate_batch function:t_0tjqm9rUjfGY4MunGDM rows.jsonl

The estimate was 3. The bulk run in Running a Bulk Routine Batch from a JSONL File spent credits_spent=3, the same number.

Verify the result

estimate_batch function:t_0tjqm9rUjfGY4MunGDM rows.jsonl

Expected: rows=3 per_run=1 estimated_credits=3 for the 3-row file.

How it works

Pricing is attached to the routine definition, and row count comes from the file. Multiplying them gives the cost the run would have if every row were charged the perRun amount. Each of the three routines above has a different perRun, so the same 3 rows are estimated at 3, 9, and 54.6 credits.

Common issues

A run that returns nothing can be charged less than the estimate

In the measurements here, a run that returned a value was charged the estimate, and one Work Email run with an empty result was charged 0. Another Work Email run for a made-up person returned an address and was charged 3. See Comparing What a Run Costs When It Finds Nothing.

Variable-priced routines

Company Latest Funding reports containsVariablePricing: true. A multiplication by perRun is a starting figure for that routine, and a small test run shows what a real charge looks like.

Blank lines change the row count

grep -c . counts lines with at least one character. Appending an empty line to the 3-row file still gave rows=3, while appending a line of three spaces gave rows=4. Remove whitespace-only lines before estimating.

Next steps

• Guarding a Script with a Credit Balance Check with the Clay CLI
• Running a Bulk Routine Batch from a JSONL File with the Clay CLI

verification:
  status: verified
  tested_at: "2026-10-09"
  product_version: "clay CLI 1.9.1"
  command: "estimate_batch function:t_0tjqm9rUjfGY4MunGDM rows.jsonl"
  expected_result: "rows=3 per_run=1 estimated_credits=3 for the 3-row file."