Skip to main content

​
Credit model

a21e uses a simple credit system: 1 credit = 1 enhancement (one prompt compilation and execution). Your balance is split into two buckets:
TypeSourceBehavior
SubscriptionMonthly planResets on your renewal date
Add-onCredit packs, admin grantsNever expires, never resets
Credits are consumed subscription-first. Add-on credits are only used once subscription credits are exhausted.

​
Checking your balance

curl https://api.a21e.com/v1/credits/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "balance": 550,
  "plan": "pro",
  "mode": "managed"
}
The balance field is your total available credits (subscription + add-on). mode indicates whether you’re on managed (a21e-hosted LLM) or BYOK (your own provider key).

​
Managed vs. BYOK

ManagedBYOK
Credit cost1 credit per enhancement1 credit per enhancement
LLM costIncluded in creditBilled by your provider
SetupNothing extraAdd provider key in settings
Credits are always required — they cover prompt engineering, context assembly, and orchestration. In BYOK mode, your provider handles the LLM inference cost separately. See BYOK guide for setup instructions.

​
Usage tracking

​
Summary

Get a high-level overview of your usage over a time period: 
curl "https://api.a21e.com/v1/usage/summary?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Daily breakdown

curl "https://api.a21e.com/v1/usage/by-day?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Run history

List individual runs with pagination: 
curl "https://api.a21e.com/v1/usage/runs?days=30&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
Each run includes the prompt title, credits used, model, provider, status, and duration.

​
CSV export

Export your run history as a CSV file for accounting or analysis: 
curl "https://api.a21e.com/v1/usage/runs/export?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o runs.csv

​
Credit ledger

The ledger provides a full audit trail of every credit transaction.

​
List transactions

curl "https://api.a21e.com/v1/credits/ledger?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
Each entry includes a entry_type field:
Entry typeMeaning
debitCredit consumed by an enhancement
refundCredits returned (e.g. failed execution)
grantCredits added by admin or credit pack
pinned_hitPrompt pinning cache hit (no credit charged)
dedup_hitDeduplication cache hit (no credit charged)

​
Period summary

Get aggregated credit activity over a time window (up to 90 days): 
curl "https://api.a21e.com/v1/credits/ledger/summary?days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "total_debits": 142,
  "total_refunds": 3,
  "total_grants": 0,
  "cache_hits": 28,
  "net_change": -139,
  "period_days": 30,
  "since": "2026-02-06T00:00:00.000Z"
}

​
Insufficient credits

When your balance reaches zero, API requests return a 402 error: 
{
  "error": "INSUFFICIENT_CREDITS",
  "message": "Your credit balance is 0. Purchase additional credits or upgrade your plan.",
  "balance": 0
}
This applies to both managed and BYOK modes — credits are always required for prompt engineering.

​
Organization credits

Organizations have a separate credit pool shared across all members:
  • Org admins can purchase credits and set per-member spending limits
  • Member usage is tracked individually within the org pool
  • When a member’s personal credits are exhausted, org credits are used (if allowed by policy)
See Organizations for more on team billing.