Credits

Credits belong to the workspace: every member, API key, the app, the browser extension and the Claude connector draw from one shared balance.

What v1 calls cost

For every other CluGTM price, see Pricing and credits.

The 402 pre-check

CluGTM checks your balance before a bulk run starts. The balance must cover the worst case: the number of contacts (after duplicates are removed) times the full price of the enrichment_type.

If it doesn’t, the request fails with 402 and nothing is queued:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Required: 2750.0 for 250 prospects, Available: 1200. Please purchase more credits to continue."
  }
}

When the run finishes, you’re charged only for what was found, so the final cost is usually lower than the pre-check amount.

Handling 402

import requests
 
def enrich(payload, api_key):
    r = requests.post(
        "https://api.cleanlist.ai/api/v1/public/enrich/bulk",
        headers={"Authorization": f"Bearer {api_key}"},
        json=payload,
    )
    if r.status_code == 402:
        # Not enough credits for the worst case. Top up, or send fewer
        # contacts or a cheaper enrichment_type.
        raise RuntimeError(r.json()["error"]["message"])
    r.raise_for_status()
    return r.json()

Nothing is queued or charged on a 402, so you can resend the same payload after topping up.

Checking your balance

The legacy v1 API has no balance endpoint. Use the v2 endpoint with the same key (scope credits:read, no credit cost):

curl https://api.cleanlist.ai/api/v2/credits/balance \
  -H "Authorization: Bearer clapi_your_api_key"

import requests
 
r = requests.get(
    "https://api.cleanlist.ai/api/v2/credits/balance",
    headers={"Authorization": "Bearer clapi_your_api_key"},
)
r.raise_for_status()
print(r.json()["credits"])

const r = await fetch("https://api.cleanlist.ai/api/v2/credits/balance", {
  headers: { Authorization: "Bearer clapi_your_api_key" },
});
if (!r.ok) throw new Error(`HTTP ${r.status}`);
console.log((await r.json()).credits);

{
  "organization_id": "org_2abcRevenueLabs",
  "credits": 4820
}

The live response also carries v2 envelope fields such as task_id and timestamp_ms. See v2 credits.

Pre-flight check for large batches

balance = requests.get(
    "https://api.cleanlist.ai/api/v2/credits/balance",
    headers={"Authorization": f"Bearer {api_key}"},
).json()["credits"]
 
PRICE = {"partial": 1, "phone_only": 10, "full": 11}
required = len(contacts) * PRICE[enrichment_type]
if balance < required:
    raise RuntimeError(f"Need {required} credits for the pre-check, have {balance}.")

Topping up

• Self-serve plans: go to Settings → Plans & billing → Buy more credits, or click Add next to your credits in the sidebar. Purchased credits are added to the workspace balance right away and never expire. Top-ups aren’t available during the Pro trial.
• AppSumo workspaces: card top-ups aren’t offered. Use the AppSumo one-time credits add-on or add a paid CluGTM plan; see AppSumo credits.

You can also see your balance at any time in the credits row at the bottom of the app sidebar.

Related

• Pricing and credits
• Enrichment
• Errors and rate limits
• v2 credits and quotes