---
title: "AI credits and your own key"
description: "How AI is paid for: prepaid credits, or your own provider key with credits as a safety net. Plus budget caps and what visitors see when AI is unavailable."
canonical: "https://undocsend.com/docs/ai/credits-and-your-own-key"
last_updated: "2026-11-19"
---

# AI credits and your own key

How AI is paid for: prepaid credits, or your own provider key with credits as a safety net. Plus budget caps and what visitors see when AI is unavailable.

Everything on this page lives on the **Agent** console, in the sidebar under AI Analyst. Only owners and admins can open it.

## How credits work

- 1,000 credits = $1.
- Each AI call uses credits at the provider’s list price plus 15%. A typical assistant answer uses about 5 to 30 credits, depending on its length and the model.
- A new trial workspace starts with 2,000 credits ($2), once.
- Plans don’t include a monthly credit allowance. If your workspace has one, the balance shows “Your plan adds … of credits each month”. Unused allowance lapses when the next one arrives.
- Credits you buy don’t expire while your workspace is active.

To buy credits, click **Buy credits** on the Agent console. To refill automatically, use **Auto top-up** next to it. Amounts, payment and auto top-up settings are covered in [Billing](https://undocsend.com/docs/billing).

## What uses credits

Any AI call that isn’t paid for by your own key:

- Room assistant answers, including the quick check that screens each question first.
- AI drafts of answers to visitor questions.
- Document summaries, gap detection, predicted questions, the question dictionary and visitor enrichment.
- Setting up a room with AI.
- Improving scanned text with AI, and AI redaction suggestions.

You can switch most of these off under **AI features**. See [Summaries, gaps and other AI features](https://undocsend.com/docs/ai/other-ai-features). Visitors’ own AI tools reading your room don’t use your credits.

## Your balance and history

The top of **How your agent is powered** shows your **Credit balance** in dollars and credits. Further down, **AI credits** shows a chart of the last 30 days of spend and your most recent credit activity, each row labelled:

- **Usage**: An AI call, listed in credits with the model that served it.
- **Top-up**: Credits you bought, with the amount paid.
- **Trial credits**: The one-time trial grant.
- **Monthly grant**: A monthly allowance, if your workspace has one.
- **Refund**: Credits taken back when a purchase was refunded.
- **Adjustment**: A manual change, or an unused monthly allowance lapsing.

## Running low or out

When your balance drops below $1, the dashboard shows an **AI credits running low** banner with a **Manage credits** button, and owners get an email titled “AI credits running low for *workspace*”. The email is sent once, then again only after you add credits and run low again.

When credits run out, the assistant and other AI features stop unless one of your own keys can serve them. Visitors see a short note that the assistant isn’t available right now, that their access is unaffected, and that they can reply to whoever shared the room. They are never told it is about credits.

## The fallback order

Under **How your agent is powered**, the **Fallback order** lists the steps the assistant tries, top to bottom. It uses the first step that is working and within its cap. **undocsend credits** is always the last step and can’t be moved or removed, so answers never stop while you have credits.

Each step has:

- **Answer model**: The model that writes the replies people see in your room.
- **Screening model**: A fast, low-cost model that checks each question first (is it on-topic, does it need an answer).
- **Monthly cap**: The most this step may spend this month. When reached, the next step takes over. On the last step, the assistant pauses until next month. Leave blank for no cap.

Use the arrows to reorder your own-key steps, then click **Save order**, or **Discard changes** to undo. A room can choose different models on its [Agent tab](https://undocsend.com/docs/ai/room-assistant#room-overrides).

## Use your own key

With your own key from a supported AI provider, calls on that key are billed by your provider and use no credits. Click **Add your own key** under the fallback order. Setup has three steps, each unlocked by the one before.

### 1. Safety net

If your key ever fails, undocsend finishes the answer on credits so visitors never see an error. So own-key steps need either **$5 of credits** or **auto top-up turned on** (which needs a saved card). Without a card, you’ll see “Add a card to use your own API keys.” Use **Buy credits**, **Turn on auto top-up** or **Add a card** to continue.

### 2. Add your key

1. Choose the **Provider**. The menu lists the supported providers.
2. Optionally give it a **Nickname** so you can tell keys apart. Only your team sees it.
3. Paste the **API key** and click **Check and save key**. undocsend checks the key works before saving it, stores it encrypted, and never shows it again.

If you already added a key for a provider, you can pick it under “Or use a key you’ve added”.

### 3. Pick this step’s models

Choose the **Answer model** and **Screening model** from that provider, then click **Add to fallback order**. The step goes directly above undocsend credits.

### Your keys

**Your keys** lists every key by provider, showing only its nickname and last four characters. When a provider has more than one key, its step tries them top to bottom; use the arrows to reorder them. For each key you can:

- **Rotate**: paste a new key from the same provider and click **Save new key**. It replaces the old one straight away.
- **Remove**: confirm with **Remove key**. Steps for that provider stop using it straight away.

> If your credits fall below $5 and auto top-up isn’t on (or is paused), your own-key steps pause and answers come from credits until you add credits or fix auto top-up. The console tells you which.

## When your key fails

If a call on your key fails, for example because your provider rejected the key:

1. The answer is finished on credits, charged like any credit call. Visitors don’t see an error.
2. The key is marked **Failing since** a date, and undocsend skips it, using your next key or step.
3. Owners get one email per failure, titled “Your *provider* key failed for *workspace*”, with a link to rotate the key.
4. The usage row in your history reads **BYOK failover**.

undocsend re-checks failing keys every hour and starts using a key again once it works. To check straight away, click **Re-check now**. If it still fails, rotate it with a new key from your provider.

## Budget caps

Under **Budget & limits** you can set optional caps on AI spend. Leave a field blank for no cap.

- **Monthly budget cap**: A ceiling on AI spend across all your rooms this month.
- **Per-visitor cap**: The most one visitor’s questions may spend this month, so one person can’t use up your budget.
- **When a cap is hit**: What the assistant does instead of showing an error: **Switch to the cheaper model**, **Answer from documents only (no tools)**, **Serve cached answers only (no new spend)**, **Show your FAQ instead (no spend)**, or **Pause the agent for the rest of the cycle** (the default).

Click **Save budget**. These are separate from each fallback step’s monthly cap.

## Privacy

- Requests paid for with credits are sent with zero data retention required on every request.
- Requests on your own key are governed by your agreement with that provider.
- A request finished on credits after your key failed is not routed under zero data retention.

The details and the provider list are in the [privacy policy](https://undocsend.com/privacy) and the [sub-processor list](https://undocsend.com/subprocessors).

---

Section: AI. HTML: https://undocsend.com/docs/ai/credits-and-your-own-key · Docs index: https://undocsend.com/docs.md
