Skip to main content
ModuleX charges for managed usage in credits. A credit is a small, fixed unit of value: **100 credits = 1.00∗∗,soonecreditisworth1.00**, so one credit is worth 0.01. Your plan includes a monthly credit allowance, and managed work — running a workflow, chatting with the Assistant, retrieving from managed knowledge, calling a tool — draws down that allowance as you go. This page is the mental model: where credits come from, what spends them, what is free, and what happens when the allowance runs out. For the exact metering rules and the wallet mechanics, follow the links to Credits & metering and the Billing & credits overview.

​
Credits in one minute

What a credit is

The unit ModuleX uses to meter managed usage. **100 credits = 1.00∗∗(1credit=1.00** (1 credit = 0.01). Allowances and the wallet are both counted in credits.

Where credits come from

Your plan grants a monthly credit allowance. When that runs out, a paid organization with overage turned on can keep going using a prepaid wallet.

What spends them

Managed work: a workflow run, an Assistant turn, a tool call, and managed-knowledge retrieval and ingest. See what costs credits.

What does not

Bring-your-own-key (BYOK) usage is not charged in credits — your own provider bills you directly.
The credit value is fixed. 100 credits always equal 1.00.Eachpaidplanincludesamonthlycreditallowance—forexample,the1.00. Each paid plan includes a monthly credit allowance — for example, the 25/month plan includes 5,000 credits (50ofmanagedusage),andthe50 of managed usage), and the 100/month plan includes 20,000 credits ($200). See Plans & pricing for current figures.

​
What costs credits

Credits are spent on managed actions — work ModuleX runs for you on ModuleX-provisioned providers. The table below is the plain-language summary; Credits & metering has the exact per-action numbers.
Resuming does not double-charge. Each turn is charged exactly once. When the Assistant or a workflow pauses for human-in-the-loop approval and then continues, resuming the same turn is not charged a second time.

​
What does not cost credits

Bring-your-own-key usage

Model and tool calls made on your own provider accounts are tracked for analytics only — never billed in credits. See managed versus BYOK.

BYOK knowledge stores

Retrieval and ingest on a knowledge base backed by your own vector store (Qdrant, Pinecone, MongoDB Atlas, or Weaviate) are not charged by ModuleX.

Reading and managing

Browsing workflows, editing the canvas, viewing runs, and managing settings are not metered in credits.

Building before you run

Designing a workflow does not spend credits. Credits apply when managed work actually executes.

​
Managed versus BYOK usage

Every model, tool, and knowledge action runs in one of two modes. The mode decides whether ModuleX meters it in credits.

Managed usage

ModuleX provides the model, tool, or vector store on your behalf — the managed providers are modulexai (models and tools) and modulexdb (knowledge). Managed usage is billed in credits.

Bring your own key (BYOK)

You connect your own provider accounts and ModuleX uses your keys. BYOK usage is not charged in credits — your provider bills you directly, with no ModuleX markup.
The rule in one line. Managed (modulexai / modulexdb) usage spends credits. BYOK usage is uncosted by ModuleX and tracked for analytics only. For how to connect your own providers, see LLM providers and external knowledge providers.

​
When the allowance runs out

Credits are drawn first from your plan’s monthly allowance. What happens next depends on your plan and settings.
1

Plan allowance is spent first

Managed usage draws down your monthly credit allowance until it reaches zero.
2

A paid plan can switch to the wallet

If you are on a paid plan and have overage turned on, further managed usage is funded by your prepaid wallet. You can top the wallet up manually, or set auto top-up to refill it before it runs dry.
3

Otherwise, managed usage pauses

Without an allowance or a funded wallet, the next managed action is declined rather than billed silently. See the usage gate.
For the full mechanics — how the wallet works, overage, top-ups, and auto top-up — see Wallet & top-ups and Credits & metering.

​
The usage gate: when a run is paused

ModuleX checks your credit and limit status before it starts a piece of managed work. This check is the usage gate, and it is live today. If you do not have the budget or are over a limit, the gate declines the action up front — so you are never charged for work that could not run. The gate applies on the managed-usage surfaces: starting a workflow run, using the AI Composer, taking an Assistant turn, and managed-knowledge retrieval and ingest. Plain read-and-manage actions — listing workflows, editing settings, viewing runs — do not go through this gate.
Where the gate does and does not apply. A billing denial can appear on the managed-run surfaces above. It does not appear on ordinary list/create/update/delete and organization-settings requests, which use a different, plain error shape. See Errors & status codes for the exact shapes.
When the gate declines an action, ModuleX returns a structured billing denial. The gate itself emits two of these — 402 (out of credits) and 429 (rate limited). A related 403 can also stop you, but it comes from a plan-limit check on the resource route rather than from the gate, so it carries a plainer error shape:

402 — out of credits

Your plan allowance is used up and the wallet cannot cover the action (no overage, or an empty or insufficient balance). Top up the wallet or upgrade your plan. Emitted by the gate as a structured billing denial.

403 — quota reached

You have hit a plan limit on a resource, such as the number of knowledge bases. Upgrade or free up the resource. This comes from the resource route’s own limit check — a plain detail error, not the gate’s structured denial.

429 — rate limited

You are sending managed requests faster than your plan’s per-minute rate. Slow down and retry; the response tells you how long to wait. Emitted by the gate as a structured billing denial.
The gate’s denials (402 and 429) are structured responses that tell you exactly what was hit — the kind of limit, the value, and the cap — so you can react automatically. The plan-limit 403 uses the plainer detail shape instead. The full response shapes and how to handle them in code live on Usage gating & limits and Errors & status codes.

​
How it fits together

Billing & credits overview

The whole billing picture: plans, credits, the wallet, and the gate.

Plans & pricing

Free, Pro, Max, and Enterprise — allowances, limits, and pricing.

Credits & metering

The exact rules for what a credit is and what each action costs.

Usage gating & limits

The admission gate and its 402 / 403 / 429 responses, in detail.