clay.com

Command Palette

Search for a command to run...

Measuring the Real Cost of a Routine Run with the Clay CLI

Last updated: 10/10/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.

Measuring the Real Cost of a Routine Run with the Clay CLI

clay credits balance before and after a run gives the exact credits a run spent. A small shell function wraps that into one command that starts a run, waits for it, and prints the delta.

What you will build

A run_cost function that runs one routine and prints its status, its result, and the credit delta.

balance before  ->  clay routines runs start  ->  poll until not in_progress  ->  balance after
                                                                                   ↓
                                                                             delta = before - after

AI Prompt

Using the Clay CLI, run one routine and report how many credits it spent.

Requirements:
- `clay credits balance` returns `{ "balance": <number> }` and does not spend credits.
- `clay routines runs start <routineId> --input <file>` returns `{ routineRunId, mode: "inline", status: "in_progress" }` immediately and does not wait.
- Poll `clay routines runs get <routineRunId>` until `status` is no longer `in_progress`. The final status in the example below is `complete`.
- The input body is `{ "items": [ { "id": "<string>", "inputs": { ... } } ] }`.
- Read the balance again a few seconds after completion, because the new balance can lag the status.
- The balance is workspace wide. Other activity in the workspace during the run changes the delta.
- Run the verification step below before finishing.

Prerequisites

  • The clay CLI on PATH, authenticated via clay login
  • jq
  • A workspace with credits. This example spends 1 credit.

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

run_cost() {
  local routine="$1" body="$2" b0 rid s
  b0=$(clay credits balance | jq .balance)
  rid=$(clay routines runs start "$routine" --input "$body" | jq -r .routineRunId)
  for _ in $(seq 1 30); do
    sleep 4
    s=$(clay routines runs get "$rid" | tee /tmp/run.json | jq -r .status)
    [ "$s" != "in_progress" ] && break
  done
  sleep 5
  echo "status=$s credits_spent=$(( b0 - $(clay credits balance | jq .balance) ))"
  jq -c '.data' /tmp/run.json
}

2. Run it

echo '{"items":[{"id":"r1","inputs":{"Company Name":"Stripe"}}]}' > in.json
run_cost function:t_0tjqm9rUjfGY4MunGDM in.json

Real output:

status=complete credits_spent=1
[{"id":"r1","status":"complete","result":{"Domain":"stripe.com"}}]

The balance went from 393076 to 393075. Running the same function a second time reported credits_spent=1 again.

3. Run it for a routine that costs more

echo '{"items":[{"id":"r1","inputs":{"Full Name":"<known public person>","Company Domain":"stripe.com","Company Name":"Stripe"}}]}' > in-email.json
run_cost function:t_0tjqmaaroo9mQFCBA5C in-email.json

Real output, with the address replaced by a placeholder:

status=complete credits_spent=3
[{"id":"r1","status":"complete","result":{"Work Email":"<address>"}}]

The balance went from 393074 to 393071, which is 3 credits and matches the perRun: 3 estimate for Work Email.

Verify the result

run_cost function:t_0tjqm9rUjfGY4MunGDM in.json | head -1

Expected: a line of the form status=complete credits_spent=<n>, where n is 1 for Company Domain when nothing else in the workspace is spending credits.

How it works

The routine runs asynchronously. runs start returns a run id, runs get reports in_progress until the run is done, and the workspace balance reflects the charge shortly afterward. The difference between two credits balance reads is the charge, as long as nothing else spends credits in between.

Common issues

The delta can be wrong in a busy workspace

The balance is shared by every run, signal, and table in the workspace. A delta is exact only when nothing else is spending during the measurement. Repeat the measurement on a quiet workspace if the number looks off.

The balance can lag the run status

For a run started over REST, a balance read taken right after the run was accepted still showed the previous value, and the charge appeared a few seconds later. The sleep 5 before the second balance read covers this.

A run can take longer than 30 seconds

A Work Email run for a person with no findable address stayed in_progress for a little over a minute before completing with an empty result. The run_cost function polls for up to 120 seconds (30 polls, 4 seconds apart); raise the limit for routines that search several providers.

Next steps

verification:
  status: verified
  tested_at: "2026-10-09"
  product_version: "clay CLI 1.9.1"
  command: "run_cost function:t_0tjqm9rUjfGY4MunGDM in.json | head -1"
  expected_result: "status=complete credits_spent=1 for Company Domain when nothing else in the workspace is spending credits."