# AI credits
> How AI credits work in AY Inbox, what each AI action costs, the monthly allowance and reset rules, and how to buy top-up packs.
Source: https://docs.ayinbox.com/guides/ai-credits/
AI features run on credits, and they need a paid plan. Your plan grants a monthly allowance that refreshes each billing cycle, and top-up packs you buy never expire.
Check and top up credits [#check-and-top-up-credits]
Open the **AI & credits** tab of **Settings > Billing** (it needs the **Manage billing** permission).
Check your balance and the reset date beside it.
Buy a top-up pack of **500**, **2,000** or **10,000** credits through Stripe Checkout.
Good to know [#good-to-know]
* Unused monthly credits do not roll over. Purchased credits survive every reset.
* Spending draws the monthly allowance first, then purchased credits.
* Each action reserves a small minimum up front, then settles against real usage. A provider error refunds it.
* Running out stops work before it starts, so you are never half-charged.
* You can set daily, weekly and monthly spend limits for the workspace and for each member.
What credits are and who manages them [#what-credits-are-and-who-manages-them]
AI features run on credits, and they are paid-only: a free trial carries no allowance and the AI surfaces stay locked until the workspace is on a paid plan. Your plan grants a monthly allowance that refreshes each billing cycle, and top-up packs never expire.
Everything here lives on the **AI & credits** tab of **Settings > Billing** and needs the **Manage billing** permission. Other members do not see it.
The two pools [#the-two-pools]
A dedicated reviewer workspace starts with 100 test credits. Its header gauge and popover label them **Test credits** rather than plan credits. These use the normal credit ledger and spend rules, and do not keep paid features unlocked after the reviewer grant expires. Joining an existing workspace as a tester does not add credits. See [reviewer accounts](/development/accounts-and-access/#which-workspace-a-tester-lands-in).
| Pool | Refresh | Rollover |
| --------------------- | ------------------------------------------- | -------------------------------------------------- |
| **Monthly allowance** | Reset to the plan amount each billing cycle | No, unused credits are replaced by the fresh grant |
| **Purchased credits** | Bought as top-up packs | Yes, they never expire and survive every reset |
Spending draws the monthly pool first and only touches purchased credits once it is empty, holding your top-ups in reserve for heavy months.
What each action costs [#what-each-action-costs]
Each action reserves a flat **minimum** up front (which also gates an empty balance before work starts), then settles against real token usage after the call.
| Action | Minimum |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Writing assistant draft, selection edit ("Edit with AI") | 1 |
| Aya step | 1 per turn |
| Reply draft, compose draft, contact research run | 2 |
| One contact's line in a [first-line job](/guides/ai-contact-research/#write-first-lines-in-bulk) | 1 |
| AI spam analysis of a campaign step, and each Re-check | 2 |
| Single-shot automation AI step (classify, extract, generate) | 1 |
| Automation AI agent step | 1 per step |
| AI switch or campaign switch step, AI decider (value decider is free) | 1 |
| Ask AI branch | 1 per evaluation |
| Per-recipient AI variable, instant / research mode | 1 / 2 per recipient |
| Web search by an AI step (only when results are found) | 1 |
| Inbox agent handled thread | 5 |
| [Calendar booking](/guides/booking/#limits-and-costs) follow-up written by the model (`booking_chase`) | 2 |
| [Calendar booking](/guides/booking/#limits-and-costs) typed reading of a pick, or one proposed-time extraction (`booking_pick`, `booking_time`) | 1 |
| [Auto-reply](/guides/auto-reply/#credits) handled reply, charged once when an answer is sent or left as a draft (`auto_reply`) | 5 |
| [Campaign brain](/guides/campaign-brain/) sample reply (`brain_sample`) | 2 |
| [Campaign brain](/guides/campaign-brain/#pages) organize material into pages (`brain_organize`), refunded when no page is written | 3 |
Five rules govern the settle:
* One credit buys a fixed token budget on the serving model: light models (mini and haiku class) at 1,500 tokens per credit, standard models at 400. The exact model and token count appear in the transaction log.
* **Overage can never fail a result you already received**; at worst it drains the balance to zero.
* A provider error refunds the reserved minimum automatically, so you are never charged for output you did not get.
* A contact research run that finds nothing still costs its credits. You are paying for the search, not the result.
* Running out returns "insufficient credits" **before** any work starts, so a depleted balance never leaves you half-charged.
A longer prompt settles higher. A [campaign brain](/guides/campaign-brain/) adds its facts and the material that fits to every reply and compose draft: a typical 2,000 character brain adds 0 to 2 credits a draft, a full one about 5. Every reply to a campaign also reads the step the prospect answered, which adds 0 to 1 credit, with or without a brain. Pages a reply reads count toward the same budget as material. Writing a brain, adding material or pages and previewing what a reply reads cost nothing.
Placement tests [#placement-tests]
Credits also pay for [inbox placement tests](/guides/placement-tests/#free-tests-and-credits) once a paid workspace has used its free tests for the month. A test is a flat `25` credits (the operator can change the price), with no AI involved and no settle afterwards. Nothing is charged without you agreeing to it: the new-test dialog shows the price and your balance, and you tick to pay before the test can start. A test that delivers no copy is refunded to the pools it came from. Placement charges count toward your spend limits (a refunded one no longer does) and appear in the usage breakdown as **Placement tests**; they are not held to the AI generation caps. Tests on your own seed inboxes are always free.
Looot verification, lead search and research [#looot-verification-lead-search-and-research]
When the operator turns on Looot, credits also pay for what Looot spends for your workspace. None of these is an AI call, so none is held to the AI generation caps, but all count toward your spend limits and appear in the usage breakdown and the transaction log.
| Activity | Shown as | Price |
| ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| An address checked through the instance's Looot balance | **Email verification** | `1` credit a check (the operator can change it). A check Looot did not bill is given back as **Email verification refund** |
| One domain of a [Looot lead job](/guides/looot-leads/#credits) | **Looot lead search** | The domain's settled Looot spend at one credit per $0.01, rounded up (the operator can change it) |
| One [signal lookup](/guides/signals/#credits) for a watched company (hiring, funding or news) | **Looot company signals** | The lookup's settled Looot spend at one credit per $0.01, rounded up. A lookup Looot has not reported a cost for is held at its cap, and the cap comes back as **Looot company signals refund** once the cost arrives |
| One company's lookups in a [first-line job](/guides/ai-contact-research/#what-a-job-costs) | **First lines company research** | The company's Looot spend at the same price, rounded up, charged once per job and company. A lookup whose cost Looot does not report is charged at its cap |
| One [company lookup](/guides/ai-contact-research/#company-website-news-and-linkedin-posts) made by research or the assistant | **Looot company research** | The lookup's settled Looot spend at the same price, rounded up. While Looot has not reported the cost, the lookup's cap is held, and it is given back as **Looot company research refund** once the cost settles |
| One company of a [lead scoring enrichment run](/guides/lead-scoring/#credits) | **Looot company enrichment** | The company's settled Looot spend at one credit per $0.01, rounded up (the operator can change it). A cost Looot has not settled is held by the run and not billed |
A workspace that connected its own verification service pays that service directly and is never charged credits for it. When credits run out or a spend limit is reached, [address verification](/guides/deliverability/#address-verification) falls back to the built-in check for your workspace, a lead job, an enrichment run or a first-line job stops with an error, and signal checks wait until credits are added. A member who reaches their own limit only stops their own checks, lead jobs and enrichment runs. Before a lead job's domain or a company lookup runs, AY Inbox checks that the workspace could pay for it at its most (its cost cap in credits) without going past the balance, a spend limit or the member's own limit; when it could not, the domain or lookup is refused before Looot is called, so nothing is spent or charged. A company lookup is charged once it settles, and a lookup your workspace already made today is reused at no charge. A self-hosted instance that does not bill with credits charges none of these.
Usage and spend controls [#usage-and-spend-controls]
The **AI usage & spend controls** card shows today, this week, and this month spend, a graph over the last 7, 30, or 90 days, and breakdowns by feature and model (credits, tokens, call counts). Each limit is set by slider or exact number and shows current spend against it; changes collect into a save bar.
| Control | Behavior |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Spend limits** | Optional hard caps per calendar day, ISO week, and calendar month. At the limit, AI pauses with a clear message until the window rolls over |
| **Per-member limits** | The same three windows per teammate, counting only charges they triggered. Workspace-level work (automations, inbox agent) is attributed to nobody |
| **Low-credit reminder** | Below your threshold, everyone with Manage billing gets an in-app alert, at most once a day |
| **Auto top-up** | Buys your chosen pack automatically when the balance dips below a threshold, bounded by a monthly purchase maximum. Needs the saved subscription card |
Who can use AI at all is separate: the **Use AI** role permission (see [Team and roles](/guides/team-roles/)).
Allowances and top-ups [#allowances-and-top-ups]
| Plan | Monthly credits |
| ---------- | -------------------------- |
| Free trial | none, AI is a paid feature |
| Starter | 250 |
| Grow | 2,000 |
| Business | 25,000 |
Paid workspaces get a fresh grant each cycle, with the reset date shown beside your balance. Top-up packs come in **500**, **2,000**, and **10,000** credits, paid through Stripe Checkout with the card on file, landing in the purchased pool as soon as payment settles. Top-ups require an active paid plan.
Credits arrive only after Stripe confirms payment, not when you click. Closing the checkout tab charges nothing. A completed purchase is applied exactly once even if Stripe retries.
The transaction log [#the-transaction-log]
Every grant, purchase, and spend, newest first, with the activity, model and token count, signed credit change, resulting balance, and time. Each spend records exactly what ran it: campaign, step, and contact for a switch step; automation, node, and run for an automation step (including what an Ask AI branch asked); the thread for inbox drafts; and the teammate behind manual features.
Reading credits with a key [#reading-credits-with-a-key]
A key with `READ_WORKSPACE`, whose member holds **Manage billing**, reads the balance, the usage overview, the transaction log and the spend settings (`GET /subscription/credits` and the routes under it), and so do the `get_credit_balance`, `get_credit_usage` and `list_credit_transactions` [agent tools](/api/mcp/). Buying credits and changing spend controls stay with a signed-in person. `generate_reply_draft` charges what the dashboard reply draft charges, within the same caps and spend limits. See [workspace, plan and credits](/api/endpoints/#workspace-plan-and-credits).
FAQ [#faq]
**Do unused monthly credits roll over?** No. Buy a top-up pack for credits that carry over.
**Do purchased credits expire?** No, through any number of resets.
**What happens when I change plans?** Your allowance follows the new plan from the next cycle. Purchased credits are unaffected.
**What happens if I cancel?** Monthly grants stop; any purchased balance stays until spent.
**Do credits apply when self-hosting?** Not when billing is off, which is the self-host default (`BILLING_PROVIDER=none`). You pay your AI provider directly, so the credit ledger is bypassed: nothing is debited, there is no plan allowance, the header shows no credit gauge, and per-action cost hints are hidden. A self-hosted install that runs Stripe (`BILLING_PROVIDER=stripe`) is metered exactly like the hosted product. Separately, a free or local model (`AI_PROVIDER=ollama`, or any provider with `AI_FREE=true`) is never charged and shows a "free model" notice. See the [self-hosting guide](/development/deployment-guide/).