GET /v1/usage

Retrieve your current plan details, quota consumption, and billing period information.

GET https://api.filesafety.dev/v1/usage

Authentication

Requires x-api-key header. See Authentication.

Example request

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

Response — 200 OK

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

Response schema

Field	Type	Description
plan	string	Your current plan: free, starter, growth, or pro.
scans_used	integer	Number of scans consumed in the current billing period (includes deduplicated scans).
scans_quota	integer	Total scans included in your plan for this period.
overage_scans	integer	Number of scans beyond the quota. Always 0 on the free plan (overages are blocked).
period_ends	string	Date when the current billing period ends (ISO 8601 date format, YYYY-MM-DD).

Field details

plan

Reflects your active plan. If you have a pending downgrade, this still shows your current (higher) plan until the period ends.

scans_used

The total number of scans submitted in the current billing period. This includes:

• Successful scans (any verdict)
• Failed scans
• Deduplicated scans (files matched by SHA-256 hash)

scans_quota

The number of scans included in your plan for this billing period:

Plan	Quota
free	10
starter	1,000
growth	4,000
pro	10,000

overage_scans

The number of scans beyond your quota. Behavior differs by plan:

• Free plan: Overages are blocked. When scans_used reaches scans_quota, further scan requests return 429 Quota Exceeded. overage_scans is always 0.
• Paid plans: Overages are allowed at $0.01 per additional scan. overage_scans tracks how many scans exceed the quota.

period_ends

The date when usage resets. For paid plans, this aligns with your Stripe billing cycle. For the free plan, it resets on the first of each month.

Error responses

Status	Error	Cause
401	"Invalid or missing API key"	Missing or invalid x-api-key header.

Use cases

Display remaining scans to users

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 remaining = usage.scans_quota - usage.scans_used;
console.log(`${remaining} scans remaining this period`);

Alert on high usage

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

if (usagePercent >= 90) {
  console.warn(`Warning: ${usagePercent.toFixed(0)}% of scan quota used`);
}

Check before scanning

if (usage.plan === "free" && usage.scans_used >= usage.scans_quota) {
  throw new Error("Free plan quota exhausted. Upgrade to continue scanning.");
}