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

# AI Usage

> Token balance, spend over time, request history and top-ups.

<Info>
  **Black tier only.** One shared budget covers [AI Auto-Moderation](/en/moderation/ai-auto-mod) and [AI Server Control](/en/moderation/ai-server-control) — there is no separate allowance per feature.
</Info>

## Two pools

Your balance is the sum of two pools, spent in this order:

<CardGroup cols={2}>
  <Card title="Monthly grant" icon="calendar">
    **10,000,000 tokens**, refilled on a 30-day cycle. Unused tokens do **not** roll over.
  </Card>

  <Card title="Top-up" icon="plus">
    Tokens you have purchased. **Never expire**, and survive renewals and plan changes.
  </Card>
</CardGroup>

The grant is always consumed first, so a top-up is a genuine reserve rather than something that quietly burns down each month.

<Warning>
  **The "Resets in" figure follows your billing date, not the grant cycle.** On a yearly Black subscription it can read several hundred days while the grant is actually refilling every 30 days.

  Watch the **Monthly grant** number itself — when it returns to 10,000,000, the cycle has rolled.
</Warning>

## Overview

| Tile                       | What it counts                                  |
| -------------------------- | ----------------------------------------------- |
| **Token Balance**          | Grant plus top-up — what you can actually spend |
| **Tokens Used Today**      | Today so far, in UTC                            |
| **Tokens Used This Month** | Calendar month to date                          |
| **Requests Today**         | Number of AI calls, not tokens                  |
| **Input / output tokens**  | Broken out for today and this month             |

<Note>
  Days roll over at **UTC midnight**, not your server's timezone.
</Note>

<Note>
  The monthly figures are cached for up to five minutes. Immediately after heavy activity the daily tiles update before the monthly ones — they are not disagreeing, just refreshing at different rates.
</Note>

The **Token Usage** chart plots input and output as a stacked area over 7, 14 or 30 days. Days with no activity show as zero rather than gaps.

**Top Token Consumers** lists the ten members whose activity cost the most **today**, with their request count and average cost per request. It only appears once there is something to show.

<Tip>
  A member sitting at the top of that list day after day is usually posting a lot of images. Auto-Mod scans up to four images per message, and images cost far more than text.
</Tip>

## Activity

Every AI request, newest first, 20 per page.

| Column      | Notes                                                          |
| ----------- | -------------------------------------------------------------- |
| **Content** | The message, truncated. Auto-Mod scans show as "Auto-Mod scan" |
| **Tokens**  | Total, split into input and output                             |
| **Source**  | "Auto-Mod", "AI Server Control", or the member who asked       |
| **Status**  | Completed, Failed, Blocked, Rate limited, and others           |
| **Time**    | Relative for recent entries, dated beyond a day                |

AI Server Control rows expand to show each action it ran — a tick for success, a shield for a refused action, a cross for an error — and how long each took.

<Note>
  Request history is kept for **30 days**. The chart and export reach back up to 90 days, so older spend still appears in the totals after the individual rows have gone.
</Note>

<Warning>
  A Server Control run that times out or errors is billed and counted in the totals but does not produce an Activity row. If your daily total looks higher than the visible rows explain, that is why.
</Warning>

## Export

**Export CSV** downloads the last **30 days** — one row per day with input, output and total tokens, request count and action count. The chart's period selector does not change the export window.

## Topping up

**\$1 per 500,000 tokens**, in blocks of 1, 5, 10, 25, 50 or 100 units.

<Steps>
  <Step title="Choose an amount">
    The dialog shows the token total and price as you select.
  </Step>

  <Step title="Complete checkout">
    You are sent to Paddle to pay.
  </Step>

  <Step title="Tokens are credited">
    The purchase is added to your top-up pool once payment confirms.
  </Step>
</Steps>

<Note>
  The **Top Up Tokens** button only appears if the server has an active Black subscription billed through Paddle. Servers on a granted or complimentary Black tier have no payment method on file and cannot top up.
</Note>

<Warning>
  **The balance does not update the instant you pay.** Refresh the page after a minute, and allow a little longer before AI features resume if they had already paused.
</Warning>

<Note>
  Every purchase is credited exactly once, even if the payment provider sends the confirmation more than once. Refunds debit the tokens back.
</Note>

## When the budget runs out

The two features stop at different points, because a Server Control run needs far more headroom than a single message scan.

| Remaining     | Effect                                                          |
| ------------- | --------------------------------------------------------------- |
| Below 100,000 | Auto-Mod posts a one-time "running low" notice                  |
| Below 30,000  | **AI Server Control declines new requests**                     |
| Below 3,000   | **AI Auto-Moderation stops scanning** and posts a paused notice |

<Warning>
  Auto-Mod is **fail-closed**. If it cannot confirm there is budget it does not scan — your server has no AI moderation until the balance recovers.
</Warning>

Notices are posted to your Auto-Mod alert channel, falling back to the log channel.

## Keeping spend down

<AccordionGroup>
  <Accordion title="Turn off image scanning">
    The single biggest saving. One message with four images costs five AI calls instead of one.
  </Accordion>

  <Accordion title="Enable Trust Tiers">
    Long-standing clean members get sampled rather than scanned every time — while invites, mass mentions and links are still always checked.
  </Accordion>

  <Accordion title="Exempt busy low-risk channels">
    A bot-command channel, or a memes channel among trusted regulars, rarely needs paid scanning.
  </Accordion>

  <Accordion title="Disable categories you do not enforce">
    A category that is off is never evaluated.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The balance shows zero on an active Black plan">
    Reload the page. If it persists, the subscription record for this specific server may not be resolving — check the server appears under your subscription on the Premium page.
  </Accordion>

  <Accordion title="I paid but the balance has not moved">
    Give it a minute and reload. If AI had already paused it can take a little longer to resume than the dashboard takes to show the new figure.
  </Accordion>

  <Accordion title="Export opens raw text instead of downloading">
    That is a sign-in failure on the download. Reload the dashboard so your session refreshes, then try again.
  </Accordion>

  <Accordion title="Today's tokens are high but the Activity list looks short">
    Auto-Mod bills one call per message plus one per image, so image-heavy activity multiplies quickly. Failed Server Control runs are also billed without leaving a row.
  </Accordion>

  <Accordion title="Can I split the budget between the two features?">
    No — there is one shared pool. If Auto-Mod is consuming it, tighten its exemptions or Trust Tiers rather than looking for a per-feature cap.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="AI Auto-Moderation" icon="sparkles" href="/en/moderation/ai-auto-mod">
    Where most token spend comes from.
  </Card>

  <Card title="AI and tokens" icon="crown" href="/en/premium/ai">
    How the Black-tier AI allowance works.
  </Card>
</CardGroup>