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

# Credits System

> Understanding how credits work and tracking usage

## Overview

Mavera uses a credit-based billing system. Each API call consumes credits based on the complexity of the request and the resources used. Your subscription includes a monthly credit allocation.

## Credit Allocation by Plan

| Plan         | Monthly Credits |
| ------------ | --------------- |
| Starter      | 500             |
| Basic        | 2,000           |
| Professional | 5,000           |
| Enterprise   | Custom          |

<Info>
  Credits reset at the start of each billing cycle. Unused credits do not roll over.
</Info>

## Estimating Cost Before Calling

Before running expensive operations (e.g. focus groups, video analyses), estimate the cost to avoid 402 mid-run. Use the ranges below as upper bounds; actual cost may be lower.

| Operation                | How to Estimate                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| **Focus group**          | \~50–75 credits for 10–25 respondents + \~2 per question. 50 respondents + 5 questions ≈ 100–125 credits. |
| **Video analysis**       | \~100–150 for \<30s, \~200–350 for 1–3 min. Longer videos cost more.                                      |
| **Mave query**           | \~10–15 (simple) to \~40–75 (complex/strategic). Specific questions use fewer credits than broad ones.    |
| **Response**             | \~1–5 per message. Long conversations use more.                                                           |
| **Content generation**   | \~10–30. Depends on template and output length.                                                           |
| **Brand voice creation** | 50 credits (one-time).                                                                                    |

For pre-flight checks, see [Credits and Budget Alerts](/cookbooks/credits-budget-alerts).

## Credit Costs by Endpoint

| Endpoint                     | Typical Cost    | Notes                                    |
| ---------------------------- | --------------- | ---------------------------------------- |
| `/responses`                 | 1-5 credits     | Based on tokens used                     |
| `/mave/chat`                 | 10-50 credits   | Includes research, multi-source analysis |
| `/personas` (GET)            | 0 credits       | Free to list/retrieve                    |
| `/personas` (POST)           | 300 credits     | Creating custom personas                 |
| `/focus-groups`              | 50-200 credits  | Based on sample size and questions       |
| `/video-analyses`            | 100-500 credits | Based on video length                    |
| `/news/stories/{id}/analyze` | 5-20 credits    | Based on analysis depth                  |
| `/generations`               | 10-30 credits   | Based on content length                  |
| `/brand-voices` (POST)       | 50 credits      | Creating brand voice profiles            |

## Tracking Usage

### In API Responses

Every API response includes credit usage in the `usage` object:

```json theme={"dark"}
{
  "id": "resp_abc123",
  "object": "response",
  "output": [...],
  "usage": {
    "credits_used": 3,
    "input_tokens": 150,
    "output_tokens": 200,
    "total_tokens": 350
  }
}
```

### Via Dashboard

Monitor your usage at [app.mavera.io/settings/usage](https://app.mavera.io/settings/usage):

* Current period usage
* Usage by endpoint
* Daily breakdown
* Historical trends

## Handling Insufficient Credits

When you run out of credits, API calls return a 402 error:

```json theme={"dark"}
{
  "error": {
    "message": "Insufficient credits. Please upgrade your subscription or wait for your next billing cycle.",
    "type": "insufficient_credits",
    "code": "credits_exhausted",
    "param": null
  }
}
```

## Auto-Recharge

Enable auto-recharge to automatically purchase additional credits when you run low:

<Steps>
  <Step title="Go to Billing Settings">
    Navigate to [app.mavera.io/settings/billing](https://app.mavera.io/settings/billing)
  </Step>

  <Step title="Enable Auto-Recharge">
    Toggle on "Auto-recharge credits"
  </Step>

  <Step title="Set Threshold">
    Choose when to trigger a recharge (e.g., when credits fall below 100)
  </Step>

  <Step title="Set Recharge Amount">
    Choose how many credits to purchase (e.g., 500 credits)
  </Step>
</Steps>

## Best Practices

### Monitor Usage Proactively

Track credits in your application:

```python theme={"dark"}
def make_api_call_with_tracking(client, messages, persona_id):
    response = client.responses.create(
        model="mavera-1",
        input=messages,
        extra_body={"persona_id": persona_id},
    )

    credits_used = response.usage.credits_used
    log_credit_usage(credits_used)

    # Alert if usage is high
    if credits_used > 10:
        alert_high_usage(credits_used)

    return response
```

### Set Budget Alerts

Configure alerts in the dashboard to notify you when:

* You've used 50%, 75%, 90% of monthly credits
* A single request exceeds a threshold
* Daily usage exceeds normal patterns

### Optimize Credit Usage

<AccordionGroup>
  <Accordion title="Use appropriate endpoints">
    * Use `/responses` for simple questions (1-5 credits)
    * Reserve `/mave/chat` for complex research (10-50 credits)
  </Accordion>

  <Accordion title="Cache responses when possible">
    Store frequently-requested data to avoid redundant API calls
  </Accordion>

  <Accordion title="Batch operations">
    Combine multiple questions into single conversations rather than separate requests
  </Accordion>

  <Accordion title="Use streaming efficiently">
    Streaming doesn't cost extra, but allows you to cancel early if needed
  </Accordion>
</AccordionGroup>

## Workspace & Project Budgets

For team accounts, you can set budgets at workspace and project levels:

| Setting       | Description                                  |
| ------------- | -------------------------------------------- |
| Budget Alert  | Notification when spending reaches threshold |
| Usage Limit   | Hard cap that blocks requests when reached   |
| Billing Email | Separate email for budget notifications      |

Configure these at:

* Workspace level: [Workspace Settings > Budget](https://app.mavera.io/settings/workspace)
* Project level: Project Settings > Budget

## Credit Purchase

Need more credits mid-cycle?

1. **Upgrade plan** - Move to a higher tier for more monthly credits
2. **Purchase credits** - Buy additional credits à la carte
3. **Enable auto-recharge** - Automatically purchase when low

<CardGroup cols={2}>
  <Card title="Credits & Budget Alerts" icon="coins" href="/cookbooks/credits-budget-alerts">
    Pre-flight checks, usage tracking, graceful degradation
  </Card>

  <Card title="Error Handling" icon="exclamation-triangle" href="/guides/errors">
    Handle 402 credits\_exhausted
  </Card>

  <Card title="View Pricing" icon="dollar-sign" href="https://mavera.io/pricing">
    Credit packages and subscriptions
  </Card>

  <Card title="Usage Dashboard" icon="chart-bar" href="https://app.mavera.io/settings/usage">
    Monitor usage in real time
  </Card>
</CardGroup>