Credits System

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

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

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.

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:

{
  "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:

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:

{
  "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:

Go to Billing Settings

Navigate to app.mavera.io/settings/billing

Enable Auto-Recharge

Toggle on “Auto-recharge credits”

Set Threshold

Choose when to trigger a recharge (e.g., when credits fall below 100)

Set Recharge Amount

Choose how many credits to purchase (e.g., 500 credits)

Best Practices

Monitor Usage Proactively

Track credits in your application:

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

Use appropriate endpoints

Use /responses for simple questions (1-5 credits)
Reserve /mave/chat for complex research (10-50 credits)

Cache responses when possible

Store frequently-requested data to avoid redundant API calls

Batch operations

Combine multiple questions into single conversations rather than separate requests

Use streaming efficiently

Streaming doesn’t cost extra, but allows you to cancel early if needed

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
Project level: Project Settings > Budget

Credit Purchase

Need more credits mid-cycle?

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

Credits & Budget Alerts

Pre-flight checks, usage tracking, graceful degradation

Error Handling

Handle 402 credits_exhausted

View Pricing

Credit packages and subscriptions

Usage Dashboard

Monitor usage in real time

Getting Started

Core Concepts

Features

SDKs & Libraries

Credits System

Overview

Credit Allocation by Plan

Estimating Cost Before Calling

Credit Costs by Endpoint

Tracking Usage

In API Responses

Via Dashboard

Handling Insufficient Credits

Auto-Recharge

Best Practices

Monitor Usage Proactively

Set Budget Alerts

Optimize Credit Usage

Workspace & Project Budgets

Credit Purchase

Credits & Budget Alerts

Error Handling

View Pricing

Usage Dashboard

​Overview

​Credit Allocation by Plan

​Estimating Cost Before Calling

​Credit Costs by Endpoint

​Tracking Usage

​In API Responses

​Via Dashboard

​Handling Insufficient Credits

​Auto-Recharge

​Best Practices

​Monitor Usage Proactively

​Set Budget Alerts

​Optimize Credit Usage

​Workspace & Project Budgets

​Credit Purchase

Credits & Budget Alerts

Error Handling

View Pricing

Usage Dashboard

Overview

Credit Allocation by Plan

Estimating Cost Before Calling

Credit Costs by Endpoint

Tracking Usage

In API Responses

Via Dashboard

Handling Insufficient Credits

Auto-Recharge

Best Practices

Monitor Usage Proactively

Set Budget Alerts

Optimize Credit Usage

Workspace & Project Budgets

Credit Purchase