> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits & the billing model

> How ModuleX meters managed usage in credits, what spends them, the difference between managed and bring-your-own-key usage, and where the billing gate can pause a run.

export const MediaEmbed = ({id, type = 'screenshot', caption = '', ext, ratio = '16 / 9'}) => {
  const isVideo = type === 'video' || type === 'app_video';
  const resolvedExt = ext || (isVideo ? 'mp4' : type === 'screenshot' ? 'webp' : 'svg');
  const src = 'https://media.modulex.dev/' + id + '.' + resolvedExt;
  const [status, setStatus] = useState('loading');
  const [isDev, setIsDev] = useState(false);
  const [inView, setInView] = useState(false);
  const boxRef = useRef(null);
  useEffect(() => {
    if (typeof window === 'undefined') return;
    const h = window.location.hostname;
    setIsDev(h === 'localhost' || h === '127.0.0.1' || h.endsWith('.mintlify.app'));
  }, []);
  useEffect(() => {
    if (inView) return;
    if (typeof IntersectionObserver === 'undefined') {
      setInView(true);
      return;
    }
    const el = boxRef.current;
    if (!el) return;
    const io = new IntersectionObserver(entries => {
      if (entries.some(e => e.isIntersecting)) {
        setInView(true);
        io.disconnect();
      }
    }, {
      rootMargin: '300px'
    });
    io.observe(el);
    return () => io.disconnect();
  }, [inView]);
  if (status === 'missing') {
    if (!isDev) return null;
    return <div style={{
      display: 'flex',
      flexDirection: 'column',
      justifyContent: 'center',
      gap: '0.4rem',
      padding: '1rem 1.25rem',
      margin: '1.25rem 0',
      width: '100%',
      aspectRatio: ratio,
      boxSizing: 'border-box',
      border: '1px dashed rgba(128,128,128,0.45)',
      borderRadius: '0.75rem',
      background: 'rgba(128,128,128,0.06)',
      color: 'currentColor',
      fontSize: '0.85rem',
      lineHeight: 1.45
    }}>
        <div style={{
      display: 'flex',
      alignItems: 'center',
      gap: '0.5rem',
      opacity: 0.75
    }}>
          <span aria-hidden="true">🎬</span>
          <code style={{
      fontSize: '0.75rem'
    }}>{id}</code>
          <span style={{
      fontSize: '0.65rem',
      textTransform: 'uppercase',
      letterSpacing: '0.04em',
      padding: '0.1rem 0.4rem',
      borderRadius: '0.4rem',
      background: 'rgba(128,128,128,0.18)'
    }}>
            {type}
          </span>
        </div>
        <div style={{
      opacity: 0.9
    }}>{caption || 'Media not uploaded yet.'}</div>
        <div style={{
      fontSize: '0.7rem',
      opacity: 0.5
    }}>
          Upload to R2 as <code>{id}.{resolvedExt}</code> — preview only, hidden in production.
        </div>
      </div>;
  }
  const mediaStyle = {
    display: status === 'loaded' ? 'block' : 'none',
    width: '100%',
    height: 'auto',
    borderRadius: '0.75rem'
  };
  const media = isVideo ? <video src={inView ? src : undefined} autoPlay loop muted playsInline preload="metadata" onLoadedData={() => setStatus('loaded')} onError={() => setStatus('missing')} style={mediaStyle} /> : <img src={inView ? src : undefined} alt={caption} onLoad={() => setStatus('loaded')} onError={() => setStatus('missing')} style={mediaStyle} />;
  return <figure style={{
    margin: '1.25rem 0'
  }}>
      <div ref={boxRef} style={status === 'loaded' ? {
    width: '100%'
  } : {
    width: '100%',
    aspectRatio: ratio,
    borderRadius: '0.75rem',
    background: 'rgba(128,128,128,0.06)'
  }}>
        {media}
      </div>
      {status === 'loaded' && caption ? <figcaption style={{
    marginTop: '0.5rem',
    textAlign: 'center',
    fontSize: '0.85rem',
    opacity: 0.7
  }}>
          {caption}
        </figcaption> : null}
    </figure>;
};

ModuleX charges for **managed usage** in **credits**. A credit is a small, fixed
unit of value: \*\*100 credits = $1.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](/concepts/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](/billing/credits) and the
[Billing & credits overview](/billing/overview).

<MediaEmbed id="MX-MEDIA-1160" type="image" caption={"A single flow diagram showing where credits come from and where they go."} />

## Credits in one minute

<CardGroup cols={2}>
  <Card title="What a credit is" icon="coins">
    The unit ModuleX uses to meter managed usage. \*\*100 credits = $1.00**
            (1 credit = $0.01). Allowances and the wallet are both counted in credits.
  </Card>

  <Card title="Where credits come from" icon="wallet">
    Your [plan](/billing/plans) grants a monthly credit allowance. When that runs
    out, a paid organization with overage turned on can keep going using a prepaid
    [wallet](/billing/wallet).
  </Card>

  <Card title="What spends them" icon="bolt">
    Managed work: a workflow [run](/concepts/workflows-and-runs), an Assistant
    turn, a tool call, and managed-knowledge retrieval and ingest. See
    [what costs credits](#what-costs-credits).
  </Card>

  <Card title="What does not" icon="key">
    [Bring-your-own-key (BYOK)](#managed-versus-byok-usage) usage is not charged in
    credits — your own provider bills you directly.
  </Card>
</CardGroup>

<Info>
  **The credit value is fixed.** 100 credits always equal $1.00. Each paid plan
    includes a monthly credit allowance — for example, the $25/month plan includes 5,000
  credits ($50 of managed usage), and the $100/month plan includes 20,000 credits
  (\$200). See [Plans & pricing](/billing/plans) for current figures.
</Info>

## 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](/billing/credits) has the exact per-action numbers.

| Managed action                                                                             | What it costs                                                                                                                                |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Run a workflow, or take one Assistant turn                                                 | A flat base charge per run or turn, plus the cost of any model usage inside it. A turn is one message you send and the response it produces. |
| Use a language model on managed credentials                                                | Metered by tokens — input and output — at the model's rate, with a small system margin applied.                                              |
| Call an integration [tool](/workflow-builder/nodes/tool)                                   | A flat base charge per tool call.                                                                                                            |
| Retrieve from managed ([modulexdb](/integrations/knowledge-providers/modulexdb)) knowledge | A flat base charge per search, plus the cost of embedding your query.                                                                        |
| Ingest a document into managed knowledge                                                   | A flat base charge per document, plus the cost of embedding its text. Retrying an unchanged document does not charge again.                  |

<Tip>
  **Resuming does not double-charge.** Each turn is charged exactly once. When the
  Assistant or a workflow pauses for [human-in-the-loop](/realtime/hitl) approval and
  then continues, resuming the same turn is not charged a second time.
</Tip>

### What does not cost credits

<CardGroup cols={2}>
  <Card title="Bring-your-own-key usage" icon="plug">
    Model and tool calls made on **your own** provider accounts are tracked for
    analytics only — never billed in credits. See
    [managed versus BYOK](#managed-versus-byok-usage).
  </Card>

  <Card title="BYOK knowledge stores" icon="database">
    Retrieval and ingest on a knowledge base backed by **your own** vector store
    (Qdrant, Pinecone, MongoDB Atlas, or Weaviate) are not charged by ModuleX.
  </Card>

  <Card title="Reading and managing" icon="list">
    Browsing workflows, editing the canvas, viewing runs, and managing settings
    are not metered in credits.
  </Card>

  <Card title="Building before you run" icon="pen-ruler">
    Designing a workflow does not spend credits. Credits apply when managed work
    actually executes.
  </Card>
</CardGroup>

## 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.

<CardGroup cols={2}>
  <Card title="Managed usage" icon="cloud" href="/integrations/llm-providers/modulexai">
    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.**
  </Card>

  <Card title="Bring your own key (BYOK)" icon="key" href="/integrations/llm-providers/overview">
    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.
  </Card>
</CardGroup>

<Info>
  **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](/integrations/llm-providers/overview)
  and [external knowledge providers](/platform/knowledge/external-providers).
</Info>

## When the allowance runs out

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

<Steps>
  <Step title="Plan allowance is spent first">
    Managed usage draws down your monthly credit allowance until it reaches zero.
  </Step>

  <Step title="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](/billing/wallet). You can top the wallet up
    manually, or set auto top-up to refill it before it runs dry.
  </Step>

  <Step title="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](#the-usage-gate-when-a-run-is-paused).
  </Step>
</Steps>

For the full mechanics — how the wallet works, overage, top-ups, and auto top-up —
see [Wallet & top-ups](/billing/wallet) and [Credits & metering](/billing/credits).

## 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](/concepts/workflows-and-runs), using the [AI Composer](/concepts/ai-composer),
taking an [Assistant](/concepts/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.

<Warning>
  **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](/api-reference/errors) for the exact shapes.
</Warning>

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:

<CardGroup cols={3}>
  <Card title="402 — out of credits" icon="circle-dollar-sign">
    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](/billing/wallet) or [upgrade your plan](/billing/plans). Emitted by
    the gate as a structured billing denial.
  </Card>

  <Card title="403 — quota reached" icon="ban">
    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.
  </Card>

  <Card title="429 — rate limited" icon="gauge">
    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.
  </Card>
</CardGroup>

<Note>
  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](/billing/usage-gating) and
  [Errors & status codes](/api-reference/errors).
</Note>

<MediaEmbed id="MX-MEDIA-1161" type="screenshot" caption={"The in-app message a user sees when the usage gate declines a managed action."} />

## How it fits together

<CardGroup cols={2}>
  <Card title="Billing & credits overview" icon="receipt" href="/billing/overview">
    The whole billing picture: plans, credits, the wallet, and the gate.
  </Card>

  <Card title="Plans & pricing" icon="layers" href="/billing/plans">
    Free, Pro, Max, and Enterprise — allowances, limits, and pricing.
  </Card>

  <Card title="Credits & metering" icon="calculator" href="/billing/credits">
    The exact rules for what a credit is and what each action costs.
  </Card>

  <Card title="Usage gating & limits" icon="shield" href="/billing/usage-gating">
    The admission gate and its 402 / 403 / 429 responses, in detail.
  </Card>
</CardGroup>