Usage Endpoint

The usage endpoint returns real-time information about your API consumption, remaining quota, rate limits, and plan details.

Endpoint

GET /api/usage

Request

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key

curl -X GET https://api.spamidate.com/api/usage \
  -H "X-API-Key: spm_live_..."

const response = await fetch('https://api.spamidate.com/api/usage', {
  headers: {
    'X-API-Key': process.env.SPAMIDATE_API_KEY,
  },
});

const usage = await response.json();

const usage = await client.getUsage();
console.log(`${usage.quota.percentage}% used`);

Response

{
  "period": {
    "start": "2024-01-01T00:00:00.000Z",
    "end": "2024-01-31T23:59:59.999Z",
    "daysRemaining": 16
  },
  "quota": {
    "limit": 10000,
    "used": 4523,
    "remaining": 5477,
    "percentage": 45.23,
    "inGracePeriod": false,
    "hardLimit": 12000
  },
  "rateLimit": {
    "limitPerMinute": 100,
    "limitPerDay": 10000,
    "usedThisMinute": 12,
    "usedToday": 1547,
    "remainingThisMinute": 88,
    "remainingToday": 8453,
    "minuteResetsAt": "2024-01-15T10:31:00.000Z",
    "dayResetsAt": "2024-01-16T00:00:00.000Z"
  },
  "recentErrors": {
    "unauthorized": 0,
    "rateLimited": 2,
    "badRequest": 5,
    "serverError": 0,
    "lastErrorAt": "2024-01-15T09:45:00.000Z"
  },
  "plan": {
    "tier": "growth",
    "name": "Growth",
    "features": [
      "syntax",
      "domain",
      "mxRecords",
      "disposable",
      "roleBased",
      "catchAll",
      "typoSuggestion",
      "freeEmail",
      "corporateEmail",
      "mailboxProvider"
    ]
  }
}

Response Fields

Period

Field	Type	Description
`start`	string	Billing period start (ISO 8601)
`end`	string	Billing period end (ISO 8601)
`daysRemaining`	number	Days until quota resets

Quota

Field	Type	Description
`limit`	number	Monthly quota limit
`used`	number	Validations used this period
`remaining`	number	Validations remaining
`percentage`	number	Percentage of quota used
`inGracePeriod`	boolean	Whether in 100-120% grace period
`hardLimit`	number	Absolute limit (120% for Growth+)

Rate Limit

Field	Type	Description
`limitPerMinute`	number	Max requests per minute
`limitPerDay`	number	Max requests per day
`usedThisMinute`	number	Requests made this minute
`usedToday`	number	Requests made today
`remainingThisMinute`	number	Requests left this minute
`remainingToday`	number	Requests left today
`minuteResetsAt`	string	When minute limit resets
`dayResetsAt`	string	When daily limit resets

Recent Errors

Field	Type	Description
`unauthorized`	number	401 errors (last 24h)
`rateLimited`	number	429 errors (last 24h)
`badRequest`	number	400 errors (last 24h)
`serverError`	number	5xx errors (last 24h)
`lastErrorAt`	string	Most recent error timestamp

Plan

Field	Type	Description
`tier`	string	Plan tier identifier
`name`	string	Human-readable plan name
`features`	string[]	Available validation checks

Monitoring Examples

Check Quota Status

const usage = await client.getUsage();

if (usage.quota.percentage > 80) {
  console.warn(`Warning: ${usage.quota.percentage}% of quota used`);
}

if (usage.quota.inGracePeriod) {
  console.error('In grace period - upgrade plan to avoid service interruption');
}

if (usage.quota.remaining < 100) {
  console.error(`Only ${usage.quota.remaining} validations remaining`);
}

Rate Limit Awareness

const usage = await client.getUsage();

// Check if we're approaching per-minute limit
if (usage.rateLimit.remainingThisMinute < 10) {
  const waitMs = new Date(usage.rateLimit.minuteResetsAt).getTime() - Date.now();
  console.log(`Rate limited - wait ${Math.ceil(waitMs / 1000)}s`);
}

// Check daily limit
if (usage.rateLimit.remainingToday < 100) {
  console.warn('Approaching daily limit');
}

Dashboard Display

function displayUsage(usage: UsageResponse) {
  return {
    quota: `${usage.quota.used.toLocaleString()} / ${usage.quota.limit.toLocaleString()}`,
    percentage: `${usage.quota.percentage.toFixed(1)}%`,
    remaining: usage.quota.remaining.toLocaleString(),
    daysLeft: usage.period.daysRemaining,
    plan: usage.plan.name,
  };
}

Error Tracking

const usage = await client.getUsage();

if (usage.recentErrors.rateLimited > 10) {
  console.warn('High rate limit errors - consider batching requests');
}

if (usage.recentErrors.badRequest > 0) {
  console.warn('Bad request errors - check input validation');
}

if (usage.recentErrors.serverError > 0) {
  console.error('Server errors detected - contact support if persistent');
}

Automated Monitoring

Slack Notification Example

async function checkAndNotify() {
  const usage = await client.getUsage();

  if (usage.quota.percentage >= 80) {
    await fetch(process.env.SLACK_WEBHOOK, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        text: `Spamidate quota alert: ${usage.quota.percentage}% used (${usage.quota.remaining} remaining)`,
      }),
    });
  }
}

// Run every hour
setInterval(checkAndNotify, 60 * 60 * 1000);

Cron Job Script

#!/bin/bash
USAGE=$(curl -s https://api.spamidate.com/api/usage \
  -H "X-API-Key: $SPAMIDATE_API_KEY")

PERCENTAGE=$(echo $USAGE | jq '.quota.percentage')

if (( $(echo "$PERCENTAGE > 80" | bc -l) )); then
  echo "Warning: Spamidate quota at $PERCENTAGE%"
  # Send alert
fi

Grace Period Behavior

For Growth tier and above:

Quota Usage	Status
0-80%	Normal
80-100%	Warning headers sent
100-120%	Grace period (requests still work)
>120%	Hard stop until next period

const usage = await client.getUsage();

if (usage.quota.inGracePeriod) {
  // Using grace period buffer
  const graceUsed = usage.quota.used - usage.quota.limit;
  const graceRemaining = usage.quota.hardLimit - usage.quota.used;

  console.warn(`Grace period: ${graceUsed} used, ${graceRemaining} remaining`);
}