Usage Statistics

Monitor your API usage, rate limits, and subscription status.

GET

/v1/usage

Get Usage Statistics

Retrieve detailed usage statistics for your account, including current period consumption, rate limiting status, and historical usage data.

Request

cURL Request

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

Response

Success Response

{
  "current_period": {
    "start_date": "2024-01-01T00:00:00.000Z",
    "end_date": "2024-02-01T00:00:00.000Z",
    "requests_made": 2847,
    "requests_limit": 25000,
    "requests_remaining": 22153,
    "usage_percentage": 11.39
  },
  "subscription": {
    "tier": "starter",
    "status": "active",
    "requests_per_month": 25000,
    "requests_per_minute": 60
  },
  "rate_limiting": {
    "requests_this_minute": 3,
    "minute_limit": 60,
    "minute_reset_time": "2024-01-15T10:31:00.000Z"
  },
  "daily_usage": [
    {
      "date": "2024-01-14",
      "requests": 145
    },
    {
      "date": "2024-01-13",
      "requests": 203
    },
    {
      "date": "2024-01-12",
      "requests": 167
    }
  ],
  "top_categories": {
    "hate": 234,
    "harassment": 189,
    "sexual": 156,
    "violence": 98,
    "self-harm": 12
  }
}

Response Fields

Current Period

start_date, end_date

ISO timestamps defining your current billing period

requests_made

Number of API requests made in current period

requests_limit

Maximum requests allowed for your subscription tier

requests_remaining

Requests remaining before hitting monthly limit

usage_percentage

Percentage of monthly quota consumed (0-100)

Subscription

tier

Current subscription tier: free, starter, growth, or business

status

Subscription status: active, canceled, past_due, etc.

requests_per_month, requests_per_minute

Rate limits for your subscription tier

Rate Limiting

requests_this_minute

Requests made in the current minute window

minute_limit

Maximum requests allowed per minute

minute_reset_time

When the current minute window resets

Historical Data

daily_usage

Array of daily request counts for the last 30 days

top_categories

Count of content flagged by category in current period

Code Examples

JavaScript/Node.js

// Node.js / JavaScript
const response = await fetch('https://api.moder8r.app/v1/usage', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer m8r_sk_your_key_here'
  }
});

const usage = await response.json();

// Check if approaching monthly limit
if (usage.current_period.usage_percentage > 80) {
  console.log('Warning: Approaching monthly request limit');
}

// Check current rate limit status
const remainingThisMinute = usage.subscription.requests_per_minute - usage.rate_limiting.requests_this_minute;
console.log(`Requests remaining this minute: ${remainingThisMinute}`);

Python

# Python
import requests
from datetime import datetime

url = 'https://api.moder8r.app/v1/usage'
headers = {
    'Authorization': 'Bearer m8r_sk_your_key_here'
}

response = requests.get(url, headers=headers)
usage = response.json()

# Monitor usage and plan accordingly
current = usage['current_period']
if current['usage_percentage'] > 90:
    print(f"Critical: {current['usage_percentage']:.1f}% of monthly limit used")
    print(f"Requests remaining: {current['requests_remaining']}")

# Daily usage tracking
for day in usage['daily_usage'][:7]:  # Last 7 days
    print(f"{day['date']}: {day['requests']} requests")

Usage Monitoring Best Practices

💡 Proactive Monitoring

Check usage regularly to avoid hitting rate limits. Consider implementing automatic usage monitoring in your application.

Rate Limit Management

• Monitor requests_this_minute
• Implement exponential backoff
• Respect minute_reset_time
• Queue requests during peak usage

Quota Management

• Set alerts at 80% usage
• Track daily_usage trends
• Plan for usage spikes
• Consider upgrading tiers early