> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://gtm-tools.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://gtm-tools.sh/_mcp/server.

# How Credits Work

> How GTM Tools meters paid calls: the metering gate, which failures charge credits, and what to do when you run out

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 balance | 100 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:

| Outcome                                                         | Charged?                                                            |
| --------------------------------------------------------------- | ------------------------------------------------------------------- |
| `400` invalid arguments, `401` unauthorized, `404` unknown tool | No: rejected before the metering gate                               |
| `402` insufficient credits                                      | No: 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 timeout                        | Yes                                                                 |

If a tool charged you for something broken on our side, [contact support](/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:

| Tool                                                                                                                                                                | Why it's free                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `list_connected_linkedin_accounts` / `list_connected_reddit_accounts`                                                                                               | Local state read                                   |
| `detect_signal`                                                                                                                                                     | Dispatcher; only the detectors it runs are charged |
| `set_signals_order` / `get_signals_order`                                                                                                                           | Local 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](/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.

```bash
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}'
```