> ## Documentation Index
> Fetch the complete documentation index at: https://superthread.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# AI credits
> Learn how AI credits are spent, how to see your workspace's usage broken down by agent, model, or person, and how to buy more
AI credits are what your workspace spends when it uses AI. Every time an [agent](/docs/help/agents) runs — whether you chatted with it, mentioned it in a comment, or it fired on a trigger — the run draws down a single workspace-wide balance. That balance is shown to you in dollars, so there's no separate credit figure to keep track of.
Workspace owners and admins manage credits in [*Settings > AI credits*](https://app.superthread.com/settings/ai-credits). That page holds three things: your balance, a usage and cost breakdown, and your credit history.
AI credits are owner and admin only. Other members can use agents normally, but won't see the balance or the spend breakdown.
## What uses credits
Credits are consumed by agent runs. That covers every way an agent can start:
* Chatting with an agent, including the built-in Superthread Agent.
* `@` mentioning an agent in a comment.
* An agent firing on a schedule or on a workspace event.
* The AI chat in the [forms portal](/docs/help/forms#forms-portal), which is itself a built-in agent.
How much a run costs depends on how much work it does. Credits are metered on the tokens each run actually uses, so the main drivers are the amount of context the agent reads, the length of what it writes, the model it runs on, and its [effort level](/docs/help/agents#model-and-effort). A cheap model doing a short summary costs a fraction of a top-tier model reasoning at high effort across several boards.
## Your balance
The balance card shows what your workspace has left to spend, in dollars, alongside how much has been spent so far this calendar month.
Credit comes from two places:
* **Credits you buy**, which never expire and stay on your balance until they're spent.
* **Credits you're given** — your workspace's welcome credit, and any promotional credit. Some of these carry an expiry date, and you'll be warned in advance if any is about to expire.
There's no automatic monthly top-up, so the balance only goes up when you buy more or when credit is granted to you. As it runs down you'll see a **Low credits** warning, and then **Out of credits** when it's empty.
### Running out
If your workspace runs out of credits, **agents pause**. They can't be chatted with, mentioned, or triggered until the balance is topped up. Any run already in progress stops, and you'll get a notification telling you why.
The rest of Superthread is unaffected. Boards, pages, notes, and everything else keep working exactly as normal — only AI features stop.
Each individual run also has its own credit ceiling. This is a safety net rather than a budget: it means a single agent that gets stuck repeating itself can't quietly drain the whole balance before anyone notices.
## Buying more credits
Click **Buy credits** on the balance card. Pick one of the preset dollar amounts, or choose **Custom** and enter your own — there's a minimum, shown next to the field. What you buy is added to your balance immediately and never expires.
## Viewing your usage
The **AI usage & cost** dashboard on the same page shows where your AI spend is actually going.
Two totals sit at the top for whichever window you're looking at:
* **Total spend** – the cost of every metered AI call in the period, in dollars.
* **AI calls** – how many calls were made.
Below them, a chart plots spend per day so you can see trends and spot the day a new trigger started costing real money.
### Group by agent, model, or person
The real value of the dashboard is the grouping dropdown, which pivots the whole breakdown three ways:
* **Agent** – which agents are spending your credits. This is the default, and usually the first question worth asking. It's how you find the scheduled agent that's running more often than it needs to, or confirm that the expensive agent is the one actually earning its keep.
* **Model** – how spend splits across the models your agents run on. Useful when deciding whether an agent really needs a top-tier model, or whether the same job would be fine on a cheaper one.
* **User** – who in the workspace is driving the spend. Useful for understanding adoption as much as cost: it shows who has actually built agents into their day.
Switching between the three is instant — it re-cuts the data you're already looking at rather than reloading it.
### Choosing a period
The date range dropdown offers **Last 7 days** (the default), **Last 30 days**, **Last 90 days**, and **This month**. 90 days is as far back as the dashboard goes.
If you've just started using agents, the dashboard will be empty. Spend appears here once your agents have actually run.
## Credit history
The credit history table below records everything that has ever been *added* to your balance — as opposed to the usage dashboard, which shows what's been spent from it.
Each row shows the date, the amount, and:
* **Type** – whether the credits came from a **Purchase**, **Promo credits**, or a **Credit grant**.
* **Expiry** – the date the credits expire, or **Never** for anything you've bought.
* **Status** – whether that batch of credits is still **Active** or has **Expired**.
If you have credits due to expire soon, Superthread will warn you before they go.
## Keeping costs down
* **Check the breakdown by agent first.** Spend is rarely spread evenly — it's usually one or two agents, and often one trigger firing more often than anyone expected.
* **Match the model and effort to the job.** Deep reasoning on a top-tier model is worth paying for on genuinely complex work, and wasted on a daily summary.
* **Narrow your triggers.** A trigger set to fire on any card property change in a whole space will run far more often than one watching a single status on a single board.
* **Keep instructions focused.** An agent told exactly what to do reads less and writes less than one that has to work out what you meant.
## Related
* [Agents](/docs/help/agents) – how agents work, and the settings that affect what a run costs
* [Plans and billing](/docs/help/plans-billing) – workspace plans, seats, and invoices
* [Forms](/docs/help/forms#forms-portal) – the forms portal and its AI chat