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

# Credits and Usage

> How credits work, what they cost, and how to track your usage.

Brainstormer uses a credit-based billing system that converts all platform usage into a single, transparent unit. Every AI call, embedding generation, vector operation, and file storage action is tracked and charged in credits.

## How Credits Work

### Credit Value

By default, **1 credit = \$0.50 USD**. This value is configurable by platform administrators.

### Margin Multiplier

The platform applies a **margin multiplier** (default: 2x) to the raw provider cost before converting to credits. This covers platform overhead and infrastructure.

### Credit Calculation

For every billable operation:

1. **Raw cost** — The actual cost from the AI provider (e.g., \$0.01 for a chat completion)
2. **Charged cost** — Raw cost multiplied by the margin (e.g., $0.01 x 2.0 = $0.02)
3. **Credits burned** — Charged cost divided by credit value (e.g., $0.02 / $0.50 = 0.04 credits)

<Info>
  The margin multiplier and credit value are platform-wide settings configured by superadmins. All organizations use the same rates.
</Info>

## What Consumes Credits

Credits are consumed by various operations across the platform:

| Operation                      | Provider        | What It Covers                                             |
| ------------------------------ | --------------- | ---------------------------------------------------------- |
| **Chat completions**           | OpenRouter      | Every message your agent generates                         |
| **Welcome message generation** | OpenRouter      | Generated-mode welcome messages (fixed mode is free)       |
| **Document embeddings**        | Gemini / OpenAI | Converting content to vectors when processing KB documents |
| **Vector operations**          | Pinecone        | Upsert, query, delete operations on vector storage         |
| **File storage**               | AWS S3          | Upload, download, delete, and egress of stored files       |
| **Voice synthesis**            | ElevenLabs      | Text-to-speech generation and voice cloning                |
| **Transcription**              | OpenAI Whisper  | Audio and video transcription                              |

<Note>
  Fixed-mode prompts (welcome messages, system prompts) do not consume credits because they do not call an AI model. Only generated-mode prompts that trigger an LLM call are billed.
</Note>

<Frame caption="The credits and billing page showing your organization's credit balance">
  <img src="https://mintcdn.com/brainstormerinnovationsinc/W4SthX7HiYMp2Bca/images/screenshots/credits.png?fit=max&auto=format&n=W4SthX7HiYMp2Bca&q=85&s=b557785295a74e255fb75ada3d5e2dc1" alt="Credits and billing overview page" width="1440" height="900" data-path="images/screenshots/credits.png" />
</Frame>

## Credit Wallet

Each organization has a **credit wallet** that tracks:

* **Current balance** — How many credits are available
* **Total credits purchased** — Lifetime credits added to the wallet
* **Total credits used** — Lifetime credits consumed

The wallet is debited atomically with every billable operation — the credit deduction happens in the same database transaction as the cost event recording, ensuring accurate tracking.

## Tracking Usage

### Usage Dashboard

Navigate to **Billing** in the sidebar to see your organization's usage:

<Frame caption="The analytics dashboard showing usage trends and breakdowns">
  <img src="https://mintcdn.com/brainstormerinnovationsinc/W4SthX7HiYMp2Bca/images/screenshots/analytics.png?fit=max&auto=format&n=W4SthX7HiYMp2Bca&q=85&s=ae58c5c7867b27a9a475fc3c0547bdff" alt="Analytics dashboard with usage charts" width="1440" height="900" data-path="images/screenshots/analytics.png" />
</Frame>

* **Credit balance** with progress bar showing usage against your plan allocation
* **Usage breakdown** by operation type (chat, embeddings, vector ops, storage)
* **Daily usage trend** — See how your usage patterns over time
* **Per-agent breakdown** — Which agents consume the most credits

### Per-Conversation Cost

Each conversation tracks token usage and cost:

* Input tokens and output tokens per message
* Cost per message based on the model's pricing
* Total conversation cost

You can see this in the conversation details view.

## Credit Ledger

Every credit transaction is recorded in an **immutable credit ledger**. Each entry includes:

* **Transaction type** — Debit (usage) or credit (purchase, refund)
* **Amount** — Credits consumed or added
* **Balance before and after** — Running balance at the time of transaction
* **Reference** — Link to the specific operation (chat message, embedding batch, etc.)
* **Timestamp** — When the transaction occurred

The ledger is append-only — entries are never modified or deleted, providing a complete audit trail.

<Tip>
  If you notice unexpected credit consumption, check the credit ledger for detailed transaction history. Each entry links back to the specific operation that triggered the charge.
</Tip>

## Cost Optimization Tips

<AccordionGroup>
  <Accordion title="Choose cost-effective models">
    Model pricing varies dramatically. GPT-3.5 Turbo or Gemini Flash can be 10-50x cheaper than GPT-4 Turbo for simple use cases. Match your model to the complexity of the task.
  </Accordion>

  <Accordion title="Use fixed-mode prompts where possible">
    Fixed welcome messages and static system prompts do not call the AI model and cost nothing. Only use generated mode when you genuinely need dynamic, context-aware content.
  </Accordion>

  <Accordion title="Optimize knowledge base content">
    Well-organized, relevant content reduces the number of search queries needed and improves hit rates. Remove outdated or duplicate content that wastes embedding and storage credits.
  </Accordion>

  <Accordion title="Monitor per-agent usage">
    Some agents may consume far more credits than others. Use the per-agent breakdown to identify high-cost agents and optimize their model selection or prompt length.
  </Accordion>
</AccordionGroup>

## Superadmin Billing Dashboard

Platform superadmins have access to an additional billing dashboard at **Admin > Billing** that shows:

* **Raw cost vs. charged revenue** — Platform margin visibility
* **Provider breakdown** — Costs by provider (OpenRouter, Pinecone, S3, etc.)
* **Daily trend** — Revenue and cost over time
* **Top organizations** — Which orgs consume the most
* **Plan mix** — Distribution of organizations across plans

This dashboard is only visible to users with the superadmin platform role.