Quotas and Overage

Every FileSafety plan includes a monthly scan quota. This page explains how quotas are consumed, when they reset, and how overage works on paid plans.

Monthly quotas

Plan	Monthly quota
Free	10 scans
Starter	1,000 scans
Growth	4,000 scans
Pro	10,000 scans

What counts as a scan

Each call to POST /v1/scan consumes one scan from your quota, regardless of:

The number of scan types requested (virus + NSFW both run by default)
Whether the result was served from the deduplication cache
Whether the scan succeeds or fails
Whether you use direct upload or the presigned URL flow

A scan is counted at submission time, not at completion time.

Free plan: hard limit

The free plan enforces a hard quota limit. When your 10 monthly scans are exhausted:

POST /v1/scan returns 429 Quota Exceeded
No further scans can be submitted until the quota resets
Existing scan results remain accessible via GET /v1/scan/{id}
The usage endpoint continues to work

{
  "error": "Quota exceeded"
}

To continue scanning before the reset date, upgrade to a paid plan.

Paid plans: soft limit with overage

Paid plans (Starter, Growth, Pro) use a soft quota limit. When you exceed your quota:

Scanning continues without interruption
Each additional scan is billed as overage at $0.01 per scan
Overage is metered and reported on your next invoice
There is no maximum overage cap — you can scan as much as you need

How overage appears on your invoice

Overage charges are calculated when your billing period ends. Your Stripe invoice will include:

Your plan’s base subscription fee
An overage line item for any scans beyond the quota

For example, a Starter plan customer who used 1,350 scans in a month:

Line item	Amount
Starter plan	$19.00
Overage: 350 scans x $0.01	$3.50
Total	$22.50

Quota reset timing

Free plan

Quotas reset on the first of each month at midnight UTC.

Paid plans

Quotas reset on your billing date — the day you originally subscribed. For example, if you signed up on March 15, your quota resets on the 15th of each month.

The reset date is reflected in the period_ends field of the usage API:

{
  "plan": "starter",
  "scans_used": 342,
  "scans_quota": 1000,
  "overage_scans": 0,
  "period_ends": "2026-04-15"
}

When the period ends:

scans_used resets to 0
overage_scans resets to 0
A new billing period begins
If you had overage, it is finalized on the invoice for the ended period

Checking your usage

Via the API

curl https://api.filesafety.dev/v1/usage \
  -H "x-api-key: $FILESAFETY_API_KEY"

{
  "plan": "growth",
  "scans_used": 3847,
  "scans_quota": 4000,
  "overage_scans": 0,
  "period_ends": "2026-04-01"
}

Via the dashboard

The dashboard displays your current usage, including a visual progress bar showing quota consumption.

Proactive usage monitoring

Build alerts into your integration to avoid unexpected overage charges:

const res = await fetch("https://api.filesafety.dev/v1/usage", {
  headers: { "x-api-key": process.env.FILESAFETY_API_KEY },
});
const usage = await res.json();

const usagePercent = (usage.scans_used / usage.scans_quota) * 100;

if (usagePercent >= 80) {
  console.warn(`FileSafety usage at ${usagePercent.toFixed(0)}%`);
}

if (usagePercent >= 100) {
  console.warn(`FileSafety quota exceeded — overage billing active`);
}

Quota behavior during plan changes

Action	Quota behavior
Upgrade	New (higher) quota takes effect immediately. `scans_used` carries over.
Downgrade	Current quota remains until the period ends. New (lower) quota applies on the next period.
Cancel	Current quota remains until the period ends. After that, the account reverts to the free plan.

Example: mid-cycle upgrade

You are on Starter (1,000 scans) and have used 800 scans this period. You upgrade to Growth (4,000 scans).

Your quota immediately becomes 4,000
scans_used remains at 800
You have 3,200 scans remaining for the rest of the period