Usage & Quota Status

Check your API key's tier, rate limit, and monthly quota usage.

GET

/v1/moderate

Get Key Status

Returns the calling API key's tier and per-minute rate limit, plus monthly quota usage. This call doesn't count toward your monthly quota or your per-minute rate limit.

Request

cURL Request

curl -X GET https://api.moder8r.app/v1/moderate \
  -H "Authorization: Bearer m8r_sk_your_key_here"

Response

200 OK

{
  "api_key": {
    "id": "6b1f2c9e-3a7d-4e8b-9f21-0c5d8a4e7b13",
    "name": "Production Key",
    "tier": "starter",
    "rate_limit_per_minute": 60
  },
  "quota": {
    "usage": 2847,
    "limit": 25000,
    "remaining": 22153,
    "percentage": 11
  },
  "timestamp": "2026-10-11T14:30:45.123Z"
}

Response Fields

api_key

id, name

The key's ID and the name you gave it in the dashboard

tier

Plan tier: free, starter, growth, or business

rate_limit_per_minute

Per-minute request limit for this key

quota

usage

Requests made by your account (all of its API keys combined) in the current calendar month (UTC)

limit

Your plan's monthly request limit

remaining

limit - usage, never below 0

percentage

Share of the monthly limit used, as a whole number (can exceed 100)

timestamp

Server time when the status was generated (ISO 8601)

Usage on Every Moderation Response

You often don't need a separate status call. Every successful POST /v1/moderate/text response includes a usage block with counts that include that request:

usage block

{
  "request_id": "mod_3f2b8c1e-9a4d-4c7e-b1f0-6d2a5e8c9b13",
  "flagged": false,
  "categories": { ... },
  "action": "allow",
  "usage": {
    "daily": 145,
    "monthly": 2848,
    "limit": 25000,
    "remaining": 22152
  }
}

Rate-limit status is in the X-RateLimit-* response headers. See Rate Limits.

Note: GET /v1/usage is reserved and currently returns 501 Not Implemented. Use GET /v1/moderate or the usage block instead. For daily history and charts, see the dashboard.

Errors

401: missing_api_key, invalid_auth_format, or invalid_api_key (same as every authenticated endpoint)
500: { "error": "Failed to get status" }. Note that error is a plain string here, not an object.

Code Examples

JavaScript/Node.js

// Node.js / JavaScript
const response = await fetch('https://api.moder8r.app/v1/moderate', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.MODER8R_API_KEY}`,
  },
});

const status = await response.json();

if (status.quota.percentage >= 80) {
  console.warn(`Warning: ${status.quota.percentage}% of monthly quota used`);
}
console.log(`Tier: ${status.api_key.tier}, ${status.api_key.rate_limit_per_minute} requests/minute`);

Python

# Python
import os
import requests

response = requests.get(
    'https://api.moder8r.app/v1/moderate',
    headers={'Authorization': f"Bearer {os.environ['MODER8R_API_KEY']}"},
)
status = response.json()

quota = status['quota']
if quota['percentage'] >= 90:
    print(f"Critical: {quota['percentage']}% of monthly limit used")
    print(f"Requests remaining: {quota['remaining']}")

API Documentation