Skip to main content
Most TAMTAM API endpoints consume credits from your account balance. Your account has separate credit lines depending on your subscription plan — each credit line covers a specific category of actions.

​
Credit lines

Depending on your plan, credits are organized into the following credit types: Read-only endpoints (list personas, get contacts, get research answers, workflow runs, search companies) do not consume credits.

​
Cost per endpoint

Research is billed in two separate ways, and they are easy to confuse. Unlocking a company (adding it to Key Accounts) is billed on its own credit line. It buys the bundle: your account’s standing research questions then run for that company, and neither those runs nor reading their answers costs anything further. Asking a question is billed per company, or per contact, on the same line as a custom AI column on a companies list — because it is the same thing. The company does not need to be unlocked; the credit is the payment. Asking a question you have already asked is free, since the same question about the same company returns the existing answer. Reading answers is always free, on any company, unlocked or not.

​
Engagement watches

Billed per person collected, not per sweep and not per post looked at. Creating, updating and listing watches is free, and so is reading the feed however often you poll it. That means you pay for what a watch delivers rather than for what it had to look through. Two consequences follow, and both are deliberate:
  • A quiet week is cheap. A sweep that finds nobody costs nothing, so watching a niche topic is not penalised for being niche.
  • The same person is charged once per watch. Sweeps re-read an overlapping window by design, and someone already collected is recognised rather than collected again. Two different watches finding the same person is two people collected, because you asked two different questions.
Your ceiling is exactly max_posts_per_sweep × max_engagers_per_post per sweep, per watch — the two caps you set when creating it. Set is_enabled: false to stop a watch spending without losing anything it has already collected. People who match none of the watch’s personas are still collected, and still cost a credit. That is the trade for being able to widen a persona later and find the people already waiting, and for being able to tell “nobody relevant engaged” from “my personas are too narrow” — narrow the caps, not the collection, if you want to spend less.

​
How credits are consumed

For search endpoints, credits are deducted after the results are returned — you are charged per result, not per request. For enrichment endpoints, credits are reserved when you submit the request and confirmed once enrichment completes. If enrichment fails for a contact, the reserved credits are released back to your balance.

​
Checking your balance

Use the GET /api/v2/credits endpoint to check your remaining credits across all active credit lines:

​
Running out of credits

When a credit line is exhausted, requests to endpoints consuming that credit type will return a 402 response. Contact your TAMTAM account manager to top up your credits.