Skip to main content

AI Credits

Audience: Sales · Management · QA · Support · Engineering · Where in app: Packages → AI Credits (usage); Packages (purchase add-ons) · Plan availability: All plans include a monthly allotment; add-ons top up any plan

AI Credits are the metered currency for AI usage. Every LLM call, embedding call, and voice-minute consumes credits. Each plan includes a monthly allotment; add-on packs top up. Think of credits like minutes on a phone plan — a monthly allowance, drawn down by each interaction, with the option to buy more.

What it does​

  • Meters and caps all AI activity across chat, voice, embeddings, fact extraction, and Nox.
  • Gives management a real-time view of consumption (donut gauge, per-source breakdown) so they can tune spend.
  • Logs every credit movement for chargebacks, debugging, and "why is my balance lower than expected?" support questions.
  • Degrades AI features gracefully when the balance hits zero (fallbacks rather than hard errors).

How it works​

Where balances live. On SubscriptionModel:

FieldWhat
remaining_ai_creditsCredits from the base plan (reset monthly). AI-only — telephony never touches them.
remaining_purchased_ai_creditsCredits bought via add-ons (carry over, don't reset). Doubles as the telephony wallet.
remaining_lead_intelligenceSeparate budget for B2B enrichment lookups.
remaining_live_session_viewsSeparate budget for watching live recordings.

Draw-down order. AI usage spends plan credits first, then falls back to purchased credits (AITokensCreditJob). Telephony (number rental, per-call cost) debits only the purchased/wallet balance and may drive it negative — see Wallet. Gate flags: ai_available: plan > 0 || wallet > 0, has_telephony: wallet > 0.

How a charge is computed. ms-ai's cost-tracking/ module books a usage_event with one or more usage_charge rows per AI action. Charges are measured in BillingUnits — input_token / output_token / cached_*_token / minute / second / character / message / request / credit — and priced from the model-pricing catalog (GET /ai-model-pricing). Providers tracked: openai, anthropic, elevenlabs, google, scrapingbee, baseten, plus flat-USD providers (Agent K's Apollo/PredictLeads/Unipile, telephony). CREDITS_PER_USD (100 — 1 credit = $0.01) converts provider cost to credits. Baseten GLM-4.7 is priced at 0 credits (platform-absorbed).

Flat-USD charges. recordFlatUsdCharge (cost-tracker.service.ts) is the generic path for non-token costs: the backend emits Agent K provider usage to POST /api/cost-tracking/internal/provider-usage (hourly AgentKUsageEmitJob, idempotent on agentk:<co>:<provider>:<day>), and ms-ai telephony crons record number rental / Twilio call costs the same way. Those credits flow into the same token-usage sum that AITokensCreditJob deducts.

Charge sources (ChargeSource):

SourceWhat
platformDirect provider cost (ElevenLabs voice/TTS, OpenAI/Anthropic LLM).
llm_passthroughThe inner LLM cost layered on top of an ElevenLabs voice call.
embeddingNew-document ingestion embeddings.
toolTool/function-call cost.
scrapingScrapingBee credits consumed crawling a site.

Configuration & options — what consumes credits​

UsageApprox costTracked as
Chat agent replyA few credits per turn (model + tokens)chat
Voice call (inbound)Per-minute (voice) + per-token (inner LLM)voice_inbound
Voice call (outbound)Per-minute, often higher (premium voices)voice_outbound
Voice call (web/browser)Per-minutevoice_web
Auto-Connect / auto-triggerPer generated messageauto_trigger
Embedding (doc ingestion)Small per chunkembedding
Fact extractionSmall per chat—
Nox queryCounted, but on a separate super-admin policy budgetknox

Voice is tracked by where the call happened so management can compare browser voice vs. phone calls. Chat bills per AI reply; voice bills per call event reflecting length/complexity.

Viewing usage — Packages → AI Credits:

  • Donut gauge — % of credits used this cycle at a glance.
  • Credit stats — Package Credits (plan total), Consumed, Remaining, Purchased.
  • Breakdown — daily/weekly/monthly chart by source (chat / voice / outbound / embedding) + recent log rows with model + tokens.

Useful for tuning: if 80% of credits go to outbound voice, that's where to economize.

Behaviors & edge cases​

When credits run out:

FeatureFallback
Chat agentSwitches to queue-for-human (or offline fallback message).
Call agentFalls back to human if available, otherwise missed-call.
Outbound campaignsPause until refilled.
Fact extractionSkipped — fact_extraction_state: skipped.
Knowledge ingestionPending until refilled.
  • Low-credit notifications fire at configurable thresholds (default 20% remaining).
  • No reply, no charge. If the AI doesn't actually reply (e.g. instant handoff), no credits are consumed for that interaction.
  • Audit log — AICreditLogModel records every movement:
{
  subscription_id, company_id,
  source: ai_tokens_credit_job | manual_ai_credits_job | addon | buy_addon
        | balance_auto_recharge | telephony_debit | telephony_rental | telephony_call | ...,
  action: consume | refill | reset | set,
  idempotency_key,   // unique index — telephony debits reserve it before the $inc
  before_credits, after_credits, delta,
  token_usage: { input_tokens, output_tokens, model, provider },
  metadata, created_at,
  expires_at   // 180 days
}

Wallet-facing rows (top-ups, auto-recharge, rental, calls) are what the tenant sees on Packages → Wallet (GET /subscription/wallet-transactions).

Refills:

  • Monthly reset — on the subscription anniversary, remaining_ai_credits returns to the plan allotment.
  • Add-ons — top up remaining_purchased_ai_credits; carry over until used.
  • Manual — super-admin can credit/debit (logged with source: manual_ai_credits_job).

Plan & limits​

  • Every plan includes a monthly AI-credit allotment (amount per tier — verify under billing/plans).
  • Lead intelligence is a separate budget — lead_intelligence_allowed (default 40 lookups) for B2B enrichment (RB2B, Snitcher, Clearbit). Independent of AI credits.
  • Live session views — remaining_live_session_views limits recording replays per period; higher tiers get unlimited.
  • Add-on packs are available on all plans to extend AI credits.

What Nox can tell you​

  • Current balance (SubscriptionModel.remaining_*_credits).
  • This month's consumption pattern and top consumers (which agents/campaigns).
  • Whether the company is on track to run out before period end (linear extrapolation).
  • When the last refill happened (AICreditLogModel query).

Tools: knox-stats for balance, knox-aggregate(metric=credit_consumption) for breakdown.

Technical implementation​

  • Service: ms-ai, module cost-tracking/ (entities usage_event / usage_charge, enums in cost-tracking.enums.ts: ProviderKind, ModelKind, BillingUnit, ChargeSource, EventStatus, CallType, EstimateBasis).
  • Pricing catalog: POST/GET/PATCH/DELETE /ai-model-pricing, GET /ai-model-pricing/estimates/:companyId, POST /ai-model-pricing/estimates/embeddings; providers via /ai-model-provider. GET /token-usage/:company_id for raw usage. See ms-ai/API_ENDPOINTS.md.
  • Model→agent bindings: cost-tracking/agent-model-bindings.ts (config-time wiring of catalog models to agent labels chat / auto_trigger / training / etc.; ElevenLabs voice is priced per-credit, not per-model).
  • Conversion: CREDITS_PER_USD (default 100) in constants.ts.
  • Schedulers: cost-tracking/schedulers/ — daily cost-estimate refresh, daily ElevenLabs catch-up, weekly cost-table prune (see ms-ai).
  • Balance store: SubscriptionModel and the AICreditLogModel audit log live in the backend (Mongo); ms-ai reports usage that the backend's credit jobs (ai_tokens_credit_job) consume to draw down balances.