Planning a credit budget

Every call's price is known before it runs. Price the job, pick the cheap form of each call, cap what an agent may spend, and read what each call actually cost.

Price it before you run it

estimate=true on any endpoint — "estimate": true on any tool — returns the call's credit range and a breakdown, and whether it would run now. It costs nothing and runs nothing.

curl -s -G "https://api.unzoi.com/graph/network" -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "entity_id=organization:asml" \
  --data-urlencode "compare_from=2026-07-01" --data-urlencode "compare_to=2026-07-31" \
  --data-urlencode "estimate=true" | jq '{credits, breakdown}'

{
  "credits": { "min": 2, "max": 19 },
  "breakdown": [
    { "item": "graph_queries", "min": 2, "max": 16 },
    { "item": "network_compare", "min": 0, "max": 3 }
  ]
}

For a job of many similar calls, price one of each kind and multiply by the maximum. The maximum is what a key that stops at its allocation is checked against, and a call is never charged more.

Cap what a call may spend

max_credits refuses a call whose worst case costs more, before it runs and at no cost (credit_budget_exceeded). Pass it on every call an agent makes, and a model that reaches for a deep relationship traversal when a search would do is stopped at the call rather than at the invoice.

The cheap form of each call

Instead of	Use, when it answers	Saves
`mode=hybrid` (3)	`mode=keyword` (1) for a name, a ticker or an exact phrase	2 credits a search
A relevance-ranked `/stories` page with `q`	`sort=recency` when you want what is newest	Up to 2 credits a page
A relationship call with evidence	`evidence=0` when you only need who is connected	Up to 12 credits a call
Walking deep offsets	A cursor, or a narrower time window	+1 per 1,000 rows of offset, and `/stories` stops at 1,000
An `entity_id` resolved on every call	Resolving it once with `/entities`, then filtering on the exact field it names	1–2 credits a call
Many small pages	`limit=100`	Nine calls in ten

What a watch spends

A watch costs its /stories query each run, plus 1 credit for every webhook delivery attempt. A plain watch on the Build plan's shortest interval of 15 minutes runs about 2,880 times a month, so about that many credits before any webhooks; the same watch with an entity_id costs up to three times as much. A longer interval is the lever: an hourly watch runs 720 times a month.

Preview a create with estimate=true: the answer adds per_run, runs_per_month and webhook_attempts_per_event_max, so the monthly cost is on the screen before the watch exists. A webhook endpoint that fails costs up to 4 credits an event in retries; fix it rather than letting it fail.

Read what it cost

Every priced answer carries credits_charged, and every REST response x-credits-charged. Sum them per job, or read /account (free) before and after. The console breaks the month down by operation — calls and credits side by side — which is where to look when a bill is larger than expected.

A job that must not overshoot belongs on a key that stops at its allocation: a call the credits left cannot cover is refused before it runs (insufficient_credits), never charged part-way. Credits and overage has the full table.