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	cheap only	Trying Oculum
Starter	$9/mo	100	cheap, validated	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 (cheap)	Yes	Yes	Yes	Yes
AI validation (validated)	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

Scan Depth and Credits

All scan depths consume the same number of credits:

cheap scan = 1 credit
validated scan = 1 credit
deep scan = 1 credit

The difference is in what you get: validated and deep scans include AI analysis for better accuracy.

Tracking Usage

CLI

Check your current usage:

oculum usage

Output:

Plan: Pro
Credits: 45 / 250 (18%)

Recent Scans:
  my-project    validated   2 min ago
  api-service   cheap       1 hour ago
  web-app       deep        3 hours ago

Reset Date: February 1, 2026

For JSON output (useful for scripting):

oculum usage --json

Dashboard

View your usage at /dashboard/usage:

Visual usage meter
Scan history
Plan details
Upgrade options

Managing Usage

Tips for Efficient Usage

Use cheap scans for quick checks
```
oculum scan --depth cheap
```
Fast feedback during development, save validated scans for important commits.
Use incremental scans in CI
```
oculum scan --incremental
```
Only scans changed files, reducing noise and focusing on new code.

Set up profiles

{
  "profiles": {
    "quick": { "depth": "cheap" },
    "ci": { "depth": "validated", "incremental": true }
  }
}

Reserve deep scans for audits Deep scans are most valuable for initial setup and periodic security reviews.

Quota Warnings

At 80% usage, you'll see upgrade prompts in the CLI and dashboard
At 100% usage, scans will fail until your quota resets

Upgrading Your Plan

From CLI

oculum upgrade

Opens upgrade information and pricing options.

From Dashboard

Visit /pricing to compare plans and upgrade.

Mid-Cycle Upgrades

If you upgrade mid-cycle:

Your new quota is available immediately
Previous usage counts against the new quota
Billing is prorated

API Rate Limits

In addition to credit-based quotas, API requests have rate limits:

Plan	Requests/minute
Free	10
Starter	30
Pro	60
Max	120

Rate limit headers are included in API responses:

X-RateLimit-Limit — requests allowed per minute
X-RateLimit-Remaining — requests remaining
X-RateLimit-Reset — timestamp when limit resets

Enterprise

For organizations with larger needs:

Custom credit quotas
Volume discounts
Self-hosted deployment options
Dedicated support

Contact enterprise@oculum.dev for details.

Scan Depths — Understand cheap, validated, and deep scans
CLI Reference — Usage command and other CLI features
API Reference — Rate limits and API usage