# Billing and Usage

## What this is

This page explains how billing, credits, and usage tracking work in your Hookshot™ workspace.

For current pricing and plan details, visit the [Protege AI website](https://protegeai.com).

## When to use it

Use this page when you need to:

* Understand how credits are consumed
* Review your credit balance and usage history
* Configure auto top-up
* Purchase credit packs or change your plan

## What you need first

* Workspace owner or admin role (for billing management)
* Access to **Settings**

## Steps

### 1. Understand key concepts

#### Credits

Credits are the unit of consumption for Protege runs. Each time a Protege runs, the AI model usage (tokens in, tokens out, cached tokens) is converted into credits and deducted from your workspace balance.

#### Credit grants

Credits are added to your workspace through grants. Grant types include:

| Type                  | How it works                                 |
| --------------------- | -------------------------------------------- |
| **Included monthly**  | Renewed with each subscription billing cycle |
| **Trial credit**      | Provided during a free trial period          |
| **Pack purchase**     | One-time credit pack purchase                |
| **Bonus**             | Added by Protege AI                          |
| **Manual adjustment** | Admin adjustments                            |

#### Credit consumption order

When a Protege runs, credits are consumed from grants that expire soonest first. This ensures you use time-limited credits before they expire.

#### Usage ledger

Every billable event is recorded in the usage ledger with:

* The source (dispatcher decision or Protege run)
* The AI model used
* Token counts (input, output, cached)
* Credits charged

Each billable event is recorded exactly once — you will never be charged twice for the same run.

### 2. Manage credits

#### Credit balance

View your current credit balance in **Settings → Plan**. The balance reflects all grants minus all consumptions.

#### Credit packs

Credit packs are one-time purchases that add credits to your balance. Packs do not expire, though the credits they provide are consumed in the standard depletion order alongside other grants.

Visit the [Protege AI website](https://protegeai.com) for current pack options.

#### Auto top-up

Auto top-up automatically purchases a credit pack when your balance falls below a threshold you set.

To configure auto top-up:

1. Go to **Settings → Plan**
2. Enable auto top-up
3. Choose the threshold (when to trigger a purchase)
4. Choose the pack size to purchase
5. Optionally set a monthly spending cap

Auto top-up behavior:

* Triggers when available credits fall at or below the threshold
* Respects a monthly spending cap
* Has a 6-hour cooldown after a failed purchase attempt
* Sends an email notification if a purchase fails

{% hint style="info" %}
Auto top-up is not available for enterprise plans. Enterprise workspaces track overage separately and continue running even when the included credits are consumed.
{% endhint %}

#### Plan changes

Plan changes are handled through the billing portal. Go to **Settings → Plan** to access it.

Visit the [Protege AI website](https://protegeai.com) for plan comparison and upgrade options.

### 3. Understand what happens when credits run out

| Plan type                        | Behavior                                                                                                                     |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Self-serve** (Starter, Growth) | New Protege runs are blocked. Existing runs in progress will finish. A credit pack purchase or plan upgrade restores access. |
| **Enterprise**                   | Runs continue. Overage is tracked separately and invoiced according to your enterprise agreement.                            |

When credits run out on a self-serve plan, a reversal (debt) grant is created for each run that cannot be covered. Future credit pack purchases offset this debt before adding new available credits.

### 4. Review usage

**Settings → Usage** shows:

* Credit consumption over time
* Per-run usage details with token counts and credits charged
* Payment activity and billing history

### 5. Check seat limits

Each plan includes a set number of team seats. When you invite a new member, Hookshot™ checks the seat count against your plan limit. If the limit is reached, you need to upgrade the plan or remove existing members before sending new invites.

## How to verify

* Your credit balance reflects expected usage
* Auto top-up triggers correctly when the threshold is reached
* Usage history matches the Protege runs you observed in Audit
* Plan changes take effect on the next billing cycle

## Common failures

* Expanding a high-volume Protege without monitoring credit consumption
* Disabling auto top-up and running out of credits unexpectedly
* Assuming enterprise overage is free rather than tracked
* Inviting team members without checking the seat limit
* Purchasing a pack without confirming whether outstanding debt will be offset first

## Next step

* [Workspace Settings](/workspace-settings.md)
* [Teams and People](/workspace-settings/teams-and-people.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.tryprotege.com/workspace-settings/billing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.