Usage Endpoints

Usage Endpoints

These endpoints allow you to track your API usage, monitor quotas, and view historical usage data. All usage endpoints require authentication via the X-Fizzy-Token header.

Authentication

All usage endpoints require a valid Fizzy Personal Access Token:

curl -H "X-Fizzy-Token: fz_xxxxxxxxxxxxx" \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/me/usage

Caution

Without a valid token, these endpoints return a 401 Unauthorized error.

Endpoints

Method	Endpoint	Description
GET	/api/me/usage	Current usage statistics
GET	/api/me/usage/today	Today’s usage
GET	/api/me/history	Usage history

---

GET /api/me/usage Auth Required

Returns your current cumulative usage statistics including total reads, writes, and current limits based on your subscription tier.

Request

curl -H "X-Fizzy-Token: fz_xxxxxxxxxxxxx" \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/me/usage

Response

{
  "data": {
    "userId": "usr_abc123def456",
    "accountId": "acc_xyz789",
    "tier": "pro",
    "usage": {
      "totalReads": 15234,
      "totalWrites": 3421,
      "totalRequests": 18655
    },
    "limits": {
      "requestsPerMinute": 300,
      "dailyLimit": 10000,
      "monthlyLimit": 300000
    },
    "currentPeriod": {
      "start": "2024-01-01T00:00:00.000Z",
      "end": "2024-01-31T23:59:59.999Z",
      "requestsUsed": 18655,
      "requestsRemaining": 281345
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Response Fields

Data Object

Field	Type	Description
userId	string	Your unique user identifier
accountId	string	Associated account identifier
tier	string	Your subscription tier (free, pro, enterprise)

Usage Object

Field	Type	Description
totalReads	number	Total read operations (GET requests, list operations)
totalWrites	number	Total write operations (POST, PATCH, DELETE)
totalRequests	number	Sum of all requests

Limits Object

Field	Type	Description
requestsPerMinute	number	Maximum requests per minute
dailyLimit	number	Maximum requests per day
monthlyLimit	number	Maximum requests per billing period

Current Period Object

Field	Type	Description
start	string	Period start timestamp (ISO 8601)
end	string	Period end timestamp (ISO 8601)
requestsUsed	number	Requests used this period
requestsRemaining	number	Remaining requests (-1 for unlimited)

Example: Monitor Usage

curl

#!/bin/bash
TOKEN="fz_xxxxxxxxxxxxx"
BASE_URL="https://fizzy-mcp-hosted.ryanyogan.workers.dev"

# Get usage and check remaining quota

response=$(curl -s -H "X-Fizzy-Token: $TOKEN" "$BASE_URL/api/me/usage")

used=$(echo "$response" | jq '.data.currentPeriod.requestsUsed')
remaining=$(echo "$response" | jq '.data.currentPeriod.requestsRemaining')
tier=$(echo "$response" | jq -r '.data.tier')

echo "Tier: $tier"
echo "Used: $used requests"
echo "Remaining: $remaining requests"

# Warn if approaching limit

if [ "$remaining" != "-1" ] && [ "$remaining" -lt 1000 ]; then
echo "WARNING: Approaching usage limit!"
fi

JavaScript

const TOKEN = 'fz_xxxxxxxxxxxxx';
const BASE_URL = 'https://fizzy-mcp-hosted.ryanyogan.workers.dev';

async function checkUsage() {
  const response = await fetch(`${BASE_URL}/api/me/usage`, {
    headers: { 'X-Fizzy-Token': TOKEN }
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const { data } = await response.json();

  console.log(`=== Usage Report for ${data.tier} tier ===`);
  console.log(`Total Reads: ${data.usage.totalReads.toLocaleString()}`);
  console.log(`Total Writes: ${data.usage.totalWrites.toLocaleString()}`);
  console.log(`\nCurrent Period:`);
  console.log(`  Used: ${data.currentPeriod.requestsUsed.toLocaleString()}`);
  console.log(`  Remaining: ${data.currentPeriod.requestsRemaining.toLocaleString()}`);

  // Calculate percentage
  const total = data.currentPeriod.requestsUsed + data.currentPeriod.requestsRemaining;
  const percentUsed = ((data.currentPeriod.requestsUsed / total) * 100).toFixed(1);
  console.log(`  Usage: ${percentUsed}%`);

  return data;
}

checkUsage();

Python

import requests

TOKEN = 'fz_xxxxxxxxxxxxx'
BASE_URL = 'https://fizzy-mcp-hosted.ryanyogan.workers.dev'

def check_usage():
response = requests.get(
f'{BASE_URL}/api/me/usage',
headers={'X-Fizzy-Token': TOKEN}
)
response.raise_for_status()
data = response.json()['data']

    print(f"=== Usage Report for {data['tier']} tier ===")
    print(f"Total Reads: {data['usage']['totalReads']:,}")
    print(f"Total Writes: {data['usage']['totalWrites']:,}")
    print(f"\nCurrent Period:")
    print(f"  Used: {data['currentPeriod']['requestsUsed']:,}")
    print(f"  Remaining: {data['currentPeriod']['requestsRemaining']:,}")

    # Calculate percentage
    used = data['currentPeriod']['requestsUsed']
    remaining = data['currentPeriod']['requestsRemaining']
    if remaining > 0:
        percent = (used / (used + remaining)) * 100
        print(f"  Usage: {percent:.1f}%")

    return data

if **name** == '**main**':
check_usage()

---

GET /api/me/usage/today Auth Required

Returns your usage statistics for the current day (UTC). Useful for monitoring daily quotas and real-time usage.

Request

curl -H "X-Fizzy-Token: fz_xxxxxxxxxxxxx" \
  https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/me/usage/today

Response

{
  "data": {
    "date": "2024-01-15",
    "timezone": "UTC",
    "reads": {
      "count": 523,
      "limit": 5000
    },
    "writes": {
      "count": 127,
      "limit": 2500
    },
    "total": {
      "count": 650,
      "limit": 10000
    },
    "breakdown": {
      "byHour": [
        { "hour": 0, "reads": 12, "writes": 3 },
        { "hour": 1, "reads": 8, "writes": 1 },
        { "hour": 2, "reads": 5, "writes": 0 },
        { "hour": 9, "reads": 145, "writes": 32 },
        { "hour": 10, "reads": 178, "writes": 45 },
        { "hour": 11, "reads": 175, "writes": 46 }
      ],
      "byTool": {
        "fizzy_list_cards": 312,
        "fizzy_get_card": 156,
        "fizzy_create_card": 89,
        "fizzy_update_card": 38,
        "fizzy_list_boards": 45,
        "other": 10
      }
    },
    "peakHour": {
      "hour": 10,
      "requests": 223
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2024-01-15T11:45:00.000Z"
  }
}

Response Fields

Field	Type	Description
date	string	Current date in YYYY-MM-DD format
timezone	string	Timezone for the date (always UTC)
reads	object	Read operation count and limit
writes	object	Write operation count and limit
total	object	Total request count and limit
breakdown.byHour	array	Hourly usage breakdown
breakdown.byTool	object	Usage count per MCP tool
peakHour	object	Hour with highest traffic

Example: Daily Dashboard

curl

TOKEN="fz_xxxxxxxxxxxxx"

curl -s -H "X-Fizzy-Token: $TOKEN" \
 "https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/me/usage/today" | \
 jq '{
date: .data.date,
total: "\(.data.total.count) / \(.data.total.limit)",
reads: .data.reads.count,
writes: .data.writes.count,
topTools: [.data.breakdown.byTool | to_entries | sort_by(-.value) | .[0:3] | .[].key]
}'

JavaScript

async function getDailyUsage() {
  const response = await fetch(
    'https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/me/usage/today',
    { headers: { 'X-Fizzy-Token': 'fz_xxxxxxxxxxxxx' } }
  );

  const { data } = await response.json();

  // Create progress bar
  const used = data.total.count;
  const limit = data.total.limit;
  const percent = Math.round((used / limit) * 100);
  const bar = '='.repeat(Math.floor(percent / 5)) + '-'.repeat(20 - Math.floor(percent / 5));

  console.log(`=== Daily Usage for ${data.date} ===\n`);
  console.log(`Progress: [${bar}] ${percent}%`);
  console.log(`Requests: ${used.toLocaleString()} / ${limit.toLocaleString()}\n`);
  console.log(`Reads:  ${data.reads.count.toLocaleString()}`);
  console.log(`Writes: ${data.writes.count.toLocaleString()}\n`);

  // Top tools
  const tools = Object.entries(data.breakdown.byTool)
    .sort((a, b) => b[1] - a[1])
    .slice(0, 5);

  console.log('Top Tools:');
  tools.forEach(([tool, count]) => {
    console.log(`  ${tool}: ${count}`);
  });
}

getDailyUsage();

---

GET /api/me/history Auth Required

Returns historical usage data over a specified time period. Useful for analytics, billing reconciliation, and usage trends.

Request

curl -H "X-Fizzy-Token: fz_xxxxxxxxxxxxx" \
  "https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/me/history?days=30"

Query Parameters

Parameter	Type	Default	Description
days	number	30	Number of days of history to retrieve (1-90)

Response

{
  "data": {
    "period": {
      "start": "2023-12-16",
      "end": "2024-01-15",
      "days": 30
    },
    "summary": {
      "totalReads": 12450,
      "totalWrites": 3210,
      "totalRequests": 15660,
      "averageDaily": 522,
      "peakDay": {
        "date": "2024-01-10",
        "requests": 1245
      }
    },
    "history": [
      {
        "date": "2024-01-15",
        "reads": 523,
        "writes": 127,
        "total": 650,
        "errors": 2
      },
      {
        "date": "2024-01-14",
        "reads": 612,
        "writes": 98,
        "total": 710,
        "errors": 0
      },
      {
        "date": "2024-01-13",
        "reads": 234,
        "writes": 45,
        "total": 279,
        "errors": 1
      }
    ],
    "trends": {
      "weekOverWeek": "+12.5%",
      "monthOverMonth": "+8.3%",
      "direction": "increasing"
    }
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Response Fields

Summary Object

Field	Type	Description
totalReads	number	Total reads over the period
totalWrites	number	Total writes over the period
totalRequests	number	Total requests over the period
averageDaily	number	Average daily requests
peakDay	object	Day with highest usage

History Array

Each entry contains:

Field	Type	Description
date	string	Date in YYYY-MM-DD format
reads	number	Read operations that day
writes	number	Write operations that day
total	number	Total requests that day
errors	number	Error count that day

Trends Object

Field	Type	Description
weekOverWeek	string	Change vs previous week
monthOverMonth	string	Change vs previous month
direction	string	Trend direction (increasing, decreasing, stable)

Example: Usage Analytics

curl

# Get 7-day history
curl -s -H "X-Fizzy-Token: fz_xxxxxxxxxxxxx" \
  "https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/me/history?days=7" | \
  jq '.data.history[] | "\(.date): \(.total) requests (\(.reads) reads, \(.writes) writes)"'

JavaScript

async function analyzeUsageTrends(days = 30) {
  const response = await fetch(
    `https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/me/history?days=${days}`,
    { headers: { 'X-Fizzy-Token': 'fz_xxxxxxxxxxxxx' } }
  );

  const { data } = await response.json();

  console.log(`=== Usage History (${data.period.days} days) ===\n`);
  console.log(`Period: ${data.period.start} to ${data.period.end}\n`);

  console.log('Summary:');
  console.log(`  Total Requests: ${data.summary.totalRequests.toLocaleString()}`);
  console.log(`  Daily Average: ${data.summary.averageDaily.toLocaleString()}`);
  console.log(`  Peak Day: ${data.summary.peakDay.date} (${data.summary.peakDay.requests})\n`);

  console.log('Trends:');
  console.log(`  Week over Week: ${data.trends.weekOverWeek}`);
  console.log(`  Month over Month: ${data.trends.monthOverMonth}`);
  console.log(`  Direction: ${data.trends.direction}\n`);

  // ASCII chart
  console.log('Daily Usage (last 7 days):');
  const last7 = data.history.slice(0, 7).reverse();
  const max = Math.max(...last7.map(d => d.total));

  last7.forEach(day => {
    const barLen = Math.round((day.total / max) * 40);
    const bar = '#'.repeat(barLen);
    console.log(`  ${day.date.slice(5)}: ${bar} ${day.total}`);
  });
}

analyzeUsageTrends();

Python

import requests
from datetime import datetime

def analyze_usage(days=30):
    response = requests.get(
        f'https://fizzy-mcp-hosted.ryanyogan.workers.dev/api/me/history?days={days}',
        headers={'X-Fizzy-Token': 'fz_xxxxxxxxxxxxx'}
    )
    data = response.json()['data']

    print(f"=== Usage History ({data['period']['days']} days) ===\n")
    print(f"Period: {data['period']['start']} to {data['period']['end']}\n")

    print("Summary:")
    print(f"  Total Requests: {data['summary']['totalRequests']:,}")
    print(f"  Daily Average: {data['summary']['averageDaily']:,}")
    print(f"  Peak Day: {data['summary']['peakDay']['date']} "
          f"({data['summary']['peakDay']['requests']:,})\n")

    print("Trends:")
    print(f"  Week over Week: {data['trends']['weekOverWeek']}")
    print(f"  Month over Month: {data['trends']['monthOverMonth']}")
    print(f"  Direction: {data['trends']['direction']}\n")

    # Simple chart
    print("Daily Usage (last 7 days):")
    last_7 = list(reversed(data['history'][:7]))
    max_val = max(d['total'] for d in last_7)

    for day in last_7:
        bar_len = int((day['total'] / max_val) * 40)
        bar = '#' * bar_len
        print(f"  {day['date'][5:]}: {bar} {day['total']}")

if __name__ == '__main__':
    analyze_usage()

---

Error Responses

401 Unauthorized

Missing or invalid token:

{
  "error": "AUTH_ERROR",
  "message": "Invalid or missing X-Fizzy-Token header",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

429 Rate Limited

Too many requests:

{
  "error": "RATE_LIMIT_ERROR",
  "message": "Rate limit exceeded. Please try again in 60 seconds.",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "retryAfter": 60
}

Tip

Check the Retry-After header for the exact wait time in seconds.

---

Best Practices

1. Cache usage data

   Don’t check usage on every request. Cache the response for at least 5 minutes.

2. Set up alerts

   Monitor usage and set alerts at 75% and 90% of your limits.

3. Use history for planning

   Analyze usage trends to predict when you might need to upgrade your tier.

4. Track by tool

   Use the byTool breakdown to optimize your most-used operations.

Next Steps

• Health Endpoints - Monitor service status
• Admin Endpoints - Administrative functions
• Error Handling - Handle errors gracefully