Credits & Usage
Oculum uses a credit-based system to track scan usage. This page explains how credits work and how to manage your quota.
How Credits Work
- 1 credit = 1 scan operation
- Credits are consumed when you run scans via CLI, API, or GitHub Action
- Your monthly quota resets on your billing date
- Unused credits do not roll over
Plan Comparison
| Plan | Price | Credits/month | Scan Depths | Best For |
|---|---|---|---|---|
| Free | $0 | 5 | local only | Trying Oculum |
| Starter | $9/mo | 100 | local, verified | Solo developers |
| Pro | $19/mo | 250 | all depths | Small teams |
| Max | $60/mo | 1,000 | all depths | Active development |
Feature Comparison
| Feature | Free | Starter | Pro | Max |
|---|---|---|---|---|
| Pattern matching (local) | Yes | Yes | Yes | Yes |
| AI validation (verified) | No | Yes | Yes | Yes |
| Deep analysis (deep) | No | No | Yes | Yes |
| Dashboard access | Yes | Yes | Yes | Yes |
| API access | No | Yes | Yes | Yes |
| GitHub Action | Yes | Yes | Yes | Yes |
| Priority support | No | No | Yes | Yes |
What Uses Credits
Scans That Use Credits
| Action | Credits |
|---|---|
CLI scan (oculum scan) | 1 |
API scan (POST /scan) | 1 |
| GitHub Action run | 1 |
| VS Code extension scan | 1 |
Free Operations
These actions do not consume credits:
- Checking your usage (
oculum usage) - Viewing scan history (
oculum history) - Authentication (
oculum login) - Verifying API keys
All Depths = Same Credits
All scan depths consume the same number of credits:
- Local scan = 1 credit
- Verified scan = 1 credit
- Deep scan = 1 credit
The difference is in what you get: verified and deep scans include AI analysis.
Tracking Usage
CLI
oculum usage
Output:
Plan: Pro
Credits: 45 / 250 (18%)
Recent Scans:
my-project verified 2 min ago
api-service local 1 hour ago
web-app deep 3 hours ago
Reset Date: February 1, 2026
JSON Output
oculum usage --json
{
"plan": "pro",
"creditsUsed": 45,
"creditsTotal": 250,
"creditsPercent": 18,
"resetDate": "2026-02-01T00:00:00Z",
"recentScans": [...]
}
Dashboard
View your usage at /dashboard/usage.
Managing Usage
Tips for Efficient Usage
-
Use local scans for quick checks
oculum scan --depth local -
Use incremental scans in CI
oculum scan --incremental -
Set up profiles
profiles: quick: depth: local ci: depth: verified incremental: true -
Reserve deep scans for audits
Quota Warnings
- At 80% usage, you'll see upgrade prompts
- At 100% usage, scans fail until reset
Upgrading
From CLI
oculum upgrade
From Dashboard
Visit /pricing to compare plans.
Mid-Cycle Upgrades
- New quota available immediately
- Previous usage counts against new quota
- Billing is prorated
API Rate Limits
In addition to credits, API requests have rate limits:
| Plan | Requests/minute |
|---|---|
| Free | 10 |
| Starter | 30 |
| Pro | 60 |
| Max | 120 |
Enterprise
For organizations with larger needs:
- Custom credit quotas
- Volume discounts
- Self-hosted deployment options
- Dedicated support
Contact enterprise@oculum.dev.
Related
- Authentication — Login methods
- Scan Depths — Understanding scan modes
- API Reference — API usage