Usage
CmdCal meters usage by counting successful render operations against your plan's monthly document limit. The dashboard shows real-time usage for the current billing period.
What is Metered
Each successful call to /api/v2/render that produces output counts as one document toward your monthly limit. Specifically:
- Counted: renders with
status: "success"in the usage log - Not counted: preflight-only calls, failed renders, and playground requests
Each usage log entry records:
org_id-- the organization that owns the renderapi_key_id-- which key was used (if API-authenticated)status--success,error, ortimeoutrender_time_ms-- server-side render latencyerror_message-- populated on failures
Viewing Usage in the Dashboard
The dashboard overview at /dashboard shows a usage bar for the current billing period:
- Documents used / Monthly limit (e.g. "142 / 2,000 documents")
- Percentage used with color coding: green (under 80%), amber (80-99%), red (limit reached)
- Overage count and per-document cost on paid plans
Usage API
The usage endpoint returns the full summary:
curl https://api.paperjsx.com/api/dashboard/usage \
-H "Cookie: <session>"
Response fields:
| Field | Type | Description |
|---|---|---|
totalRenders | number | Total renders this period |
successCount | number | Successful renders |
errorCount | number | Failed renders |
avgRenderTimeMs | number | Average render latency (ms) |
monthlyRenderLimit | number | Plan document cap |
overagePerDoc | number or null | Overage cost in cents, null for hard cap |
overageCount | number | Documents beyond the limit |
limitReached | boolean | True when free-tier hard cap is hit |
tier | string | Current plan tier |
dailyBreakdown | array | Per-day breakdown with date, renders, errors, avgLatency |
Usage Alerts
The dashboard shows inline warnings as you approach your limit:
- At 80% usage on the free tier, a prompt suggests upgrading to Pro.
- When the free-tier limit is reached, the usage bar turns red and the API returns
429withERR_USAGE_LIMIT_EXCEEDEDfor new render requests.
Overage Behavior
| Tier | Monthly Limit | At Limit |
|---|---|---|
| Free | 5 docs | Hard cap -- renders blocked until next period |
| Pro | 2,000 docs | Overage at $0.03/doc |
| Business | 10,000 docs | Overage at $0.02/doc |
On paid plans, rendering continues past the limit and overage charges appear on your next invoice.
Activation Tracking
The first successful render sets activated_at on your organization record. This timestamp is used internally to track when an organization moves from sign-up to first real usage.