Quotas

Understand per-channel monthly quotas for the ScamVerify™ API, including how quota is tracked, grace buffers, and tips for managing usage.

The ScamVerify™ API uses per-channel monthly quotas to manage usage. Each channel (phone, URL, text, email) has its own independent quota that resets at the start of each billing period.

Monthly Quotas by Plan

Plan	Phone	URL	Text	Email	Price
Free	50	50	25	25	$0/mo
Starter	1,000	1,000	500	500	$149/mo
Professional	3,000	3,000	1,500	1,500	$499/mo
Business	10,000	10,000	5,000	5,000	$1,499/mo
Scale	25,000	25,000	12,500	12,500	$2,999/mo

Quota Headers

Every API response includes headers showing your current quota usage for the channel you called:

Header	Description	Example
`X-Quota-Phone-Used`	Phone lookups consumed this period	`142`
`X-Quota-Phone-Limit`	Phone lookup quota for your plan	`1000`
`X-Quota-Url-Used`	URL verifications consumed this period	`87`
`X-Quota-Url-Limit`	URL verification quota for your plan	`1000`
`X-Quota-Text-Used`	Text analyses consumed this period	`23`
`X-Quota-Text-Limit`	Text analysis quota for your plan	`500`
`X-Quota-Email-Used`	Email analyses consumed this period	`11`
`X-Quota-Email-Limit`	Email analysis quota for your plan	`500`

Only the headers relevant to the channel you called are included in the response. A phone lookup response will include X-Quota-Phone-Used and X-Quota-Phone-Limit.

Quota Exhausted (402 Response)

When your quota is exhausted for a channel, the API returns a 402 Payment Required response:

{
  "error": {
    "code": "quota_exhausted",
    "message": "Phone lookup quota exhausted. 1,000 of 1,000 used this period.",
    "details": {
      "channel": "phone",
      "used": 1000,
      "limit": 1000,
      "resets_at": "2026-04-01T00:00:00Z"
    },
    "upgrade_url": "https://scamverify.ai/pricing"
  }
}

Do not retry 402 responses. They will not succeed until your quota resets or you upgrade your plan.

Grace Buffer

Paid plans include a 10% grace buffer above the stated quota. This allows your integration to complete in-flight requests when you are near the limit, rather than failing abruptly.

Plan	Phone Quota	With Grace Buffer
Free	50	50 (no buffer)
Starter	1,000	1,100
Professional	3,000	3,300
Business	10,000	11,000
Scale	25,000	27,500

The grace buffer applies to all channels. Free tier does not receive a grace buffer.

Cached Lookups Do Not Consume Quota

When the API returns a cached result (indicated by "cached": true in the response), no quota is consumed. This is an important cost optimization: if you look up the same phone number or URL multiple times within the 24-hour cache window, only the first lookup counts against your quota.

Quota Reset

Quotas reset at the start of each billing period. For paid plans, this aligns with your Stripe billing cycle. For free plans, quotas reset on the 1st of each month at midnight UTC.

Checking Remaining Quota

You can check your current quota usage across all channels at any time using the usage endpoint:

curl https://scamverify.ai/api/v1/usage \
  -H "Authorization: Bearer sv_live_abc123..."

Response:

{
  "plan": "professional",
  "billing_period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-04-01T00:00:00Z"
  },
  "quotas": {
    "phone": { "used": 142, "limit": 3000 },
    "url": { "used": 87, "limit": 3000 },
    "text": { "used": 23, "limit": 1500 },
    "email": { "used": 11, "limit": 1500 }
  }
}

Tips for Managing Quota

Monitor usage proactively - Call the /usage endpoint periodically and set up internal alerts when you reach 80% of your quota.
Let caching work for you - Avoid using force_refresh unless you specifically need fresh data. Cached lookups are free and do not count against quota.
Use batch endpoints wisely - A batch request with 50 items consumes 50 quota (one per item), not 1. Batch endpoints save on rate limits, not quota.
Separate test and live traffic - Use sv_test_ keys during development so you do not burn through your production quota.
Upgrade before hitting limits - The grace buffer is a safety net, not extra capacity. If you consistently need more lookups, upgrade your plan.

On this page