How will credits work for the MCP Server & API?

One credit pool per workspace. Resets monthly. Credits are spent the moment a visitor on your site is identified.

What charges: 1 credit when the company is identified, 1 credit when the contact is identified, maximum 2 credits per unique visitor per month.

What doesn't charge: list_warm_visitors reads, list_warm_accounts reads, get_credits_remaining, and the same visitor being identified again within the same calendar month (per-month dedupe).

The dedupe matters more than people expect. Once Jane from Acme is identified on day 5, every subsequent session of hers this month is free. Credits work less like a meter and more like a library card. You're paying for the universe of accounts you've unlocked, not for every read.

Rate limits: 60 requests per minute on free tier, 120 per minute on paid. The server returns HTTP 429 when you exceed; back off about 60 seconds and retry.

list_third_party_signals

Read this part carefully because third-party signals is the only Warmly tool that draws credits per row. Reads of warm visitors and warm accounts stay free.

What charges:

• 1 credit per new company on a row. Dedupe key: the company's primary domain. First time you pull acme.com this month: 1 credit. Every subsequent row that resolves to acme.com: free.

• 1 credit per new contact on a row, when a contact resolves. Dedupe key: the contact's email. First time [email protected] resolves this month: 1 credit. Same email pulled again later: free.

• 2 credits per row maximum (1 company + 1 contact), even if a row carries five signal types.

• Both dedupe ledgers reset at midnight EST on the 1st of each month, in lockstep with the credit quota refresh.

What doesn't charge:

• preview: true calls. Always free.

• by_company calls that return zero matching signals. No row, no credit.

• Re-pulls of any company or contact you've already paid for in the current dedupe window.

• The other Warmly MCP tools: list_warm_visitors, list_warm_accounts, get_credits_remaining all free.

When the dedupe window resets. The dedupe ledger and the credit pool refresh together at the start of each calendar month. Whatever you paid for in June is free to re-pull until 11:59 PM on June 30. At midnight on July 1, the credit pool refills and the dedupe ledger clears — anything you pull on July 1 charges fresh, even if you pulled the same company in June. Your in-app credit meter shows the next reset date so you can plan large pulls accordingly.

Cap your spend in the prompt. Claude honors natural-language credit limits. Add a sentence like "don't use more than 100 credits" or "keep this under 500 credits total" to any query and the agent will preview first, narrow filters, and cut off the pull when the cap is approached. Pair with preview: true for a free dry-run before committing.

Worked example. Monday you pull 10 companies with hiring-velocity signals: 10 credits. Tuesday you pull 4 LinkedIn-comment signals where the contacts work at companies you already pulled Monday: 4 credits for the new contacts, zero for the companies. Run the same queries again Wednesday: zero credits. The dedupe matters more than people expect. You can run an agent loop daily across overlapping signal types without burning credits on stable accounts.

Over-charge gate. If a call would charge more credits than you have left in your monthly pool, the whole call is rejected with a structured error rather than partially charging. Drop the take size and retry, or upgrade.

When You Run Out of Credits

The MCP returns a structured error your agent can relay verbatim. Reads from list_warm_visitors and list_warm_accounts keep working on everyone already identified. Re-pulling anyone you've already paid for this month keeps working. New visitor identifications get paused until either the calendar month resets or you upgrade.

Heads-up: the credit pool is shared across the whole Warmly product. Running out also pauses visitor identifications and orchestrations in the app itself. The MCP isn't on its own meter.

Upgrades are self-serve via HubSpot payment links. Pick your tier, pay, use the same email as your Warmly account. We bump your tier within one business day. Webhook automation lands later this quarter.