Getting Started

How Credits Work

The metering gate, what gets charged, and the lifecycle of a paid request.

GTM Tools meters every paid tool in credits. The unit decouples price from raw infrastructure cost: billing happens in dollars, but a tool may run multiple SMTP probes or LinkedIn scrapes per call, so a flat credit price keeps the agent’s reasoning simple.

The basics

Value
Exchange rate$1 = 100 credits
Minimum top-up$5 (500 credits)
Free starter balance100 credits

The lifecycle of a paid call

When your agent calls a paid tool:

  1. Authorize. The auth layer resolves the bearer token to an org.
  2. Validate. Arguments are checked against the tool’s schema.
  3. Meter. The tool’s cost is looked up and debited from the wallet in one step. If the balance doesn’t cover it, the call stops here with 402 and nothing is charged. Concurrent calls see the reduced balance.
  4. Execute. The tool runs. This is where most of the time is spent.

The debit happens before the work, not after, and there is no automatic refund. That single fact tells you what any given error cost you:

OutcomeCharged?
400 invalid arguments, 401 unauthorized, 404 unknown toolNo: rejected before the metering gate
402 insufficient creditsNo: that is the gate declining
Session-required errors (no connected extension session)No: gated ahead of metering
200 with status: "not_found"Yes: the tool did the work and there was nothing to return
429 with status: "try_again_later"Yes: the provider was busy after the gate. Each retry charges again
5xx upstream provider error or timeoutYes

If a tool charged you for something broken on our side, contact support with the tool name and arguments and we’ll credit the balance manually.

What “0 credits” means

Some tools cost 0, every Billing tool plus a handful elsewhere:

ToolWhy it’s free
list_connected_linkedin_accounts / list_connected_reddit_accountsLocal state read
detect_signalDispatcher; only the detectors it runs are charged
set_signals_order / get_signals_orderLocal config
All Billing tools (get_api_key, get_credit_balance, buy_credits, set_auto_reload, get_billing_portal, list_invoices, list_api_keys, revoke_api_key)Wallet operations

These are intentional; they let your agent orient itself without spending credits.

Keeping the bill down

Since a call that reaches a provider is charged whether or not the answer is useful, the savings come from calling less, not from recovering charges after the fact:

  • Filter before you hydrate. Narrow the list with a cheap tool, then spend the expensive per-record call only on what survives.
  • Respect retry_after_seconds. A tight retry loop on try_again_later multiplies the cost of one busy provider.
  • Cache what doesn’t change. Company IDs, profile URLs, and verified emails are stable for weeks.

See Credit Efficiency for the full set of patterns.

Balance changes show up in get_credit_balance immediately. list_invoices covers purchases (one-off top-ups and auto-reload charges), not per-call debits.

When you run out

The next paid tool call returns 402 Insufficient Credits with no work done. Two options:

  • One-off top-up. Call buy_credits ({"amount": 25} for 2,500 credits).
  • Auto-reload. Call set_auto_reload once with a threshold and a top-up amount; the saved card is charged automatically when the balance drops.
$curl -X POST https://api.gtm-tools.sh/api/v0/set_auto_reload \
>  -H "Authorization: Bearer $GTM_TOOLS_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{"enabled": true, "threshold": 200, "reload_to": 5000}'