GET /v1/usage

Retrieve credit usage and request history for your API key.

Overview

This endpoint returns your total credit consumption, request count, and recent request history. Use it to monitor usage, track costs, and audit API activity.

Endpoint

GET https://api.nelliewriter.com/v1/usage

Authentication

Required. Include your API key in the X-API-Key header.

X-API-Key: nel_your_api_key_here

⚠️ Security Note: This endpoint is secured by your API key. Anyone with your key can view these statistics. Keep your key secure and avoid embedding it in client-side code.

Example Request

cURL

curl https://api.nelliewriter.com/v1/usage \
  -H "X-API-Key: nel_your_api_key"

Python SDK

from nellie_api import Nellie

client = Nellie(api_key="nel_your_api_key")
usage = client.get_usage()

print(f"Total requests: {usage.total_requests}")
print(f"Total credits used: {usage.total_credits_used}")

for req in usage.recent_requests:
    print(f"  {req.request_id}: {req.status} ({req.credits_used} credits)")

Python (requests)

import requests

response = requests.get(
    "https://api.nelliewriter.com/v1/usage",
    headers={"X-API-Key": "nel_your_api_key"}
)
data = response.json()

print(f"Total credits: {data['totalCreditsUsed']}")

JavaScript

const response = await fetch('https://api.nelliewriter.com/v1/usage', {
  headers: {
    'X-API-Key': 'nel_your_api_key'
  }
});
const data = await response.json();

console.log(`Total requests: ${data.totalRequests}`);
console.log(`Credits used: ${data.totalCreditsUsed}`);

Response

Success (200 OK)

{
  "success": true,
  "totalRequests": 42,
  "totalCreditsUsed": 8750,
  "recentRequests": [
    {
      "requestId": "abcd1234-ef56-7890-abcd-12ef34567890",
      "status": "completed",
      "createdAt": "2025-12-03T10:30:00Z",
      "completedAt": "2025-12-03T10:55:00Z",
      "creditsUsed": 250
    },
    {
      "requestId": "b2c3d4e5-f678-9012-bcde-f23456789012",
      "status": "completed",
      "createdAt": "2025-12-02T14:20:00Z",
      "completedAt": "2025-12-02T15:10:00Z",
      "creditsUsed": 500
    },
    {
      "requestId": "c3d4e5f6-7890-1234-cdef-345678901234",
      "status": "failed",
      "createdAt": "2025-12-01T09:15:00Z",
      "completedAt": "2025-12-01T09:16:00Z",
      "creditsUsed": 0
    }
  ]
}

Response Fields

Recent Request Fields

Error Responses

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized",
  "details": "Valid API key required",
  "errorCode": "AUTH_REQUIRED"
}

This occurs when:

• X-API-Key header is missing
• API key is invalid or revoked

Use Cases

Monitor Credit Balance

from nellie_api import Nellie

client = Nellie(api_key="nel_...")

CREDIT_LIMIT = 10000  # Your credit allocation

usage = client.get_usage()
remaining = CREDIT_LIMIT - usage.total_credits_used

print(f"Credits used: {usage.total_credits_used}")
print(f"Credits remaining: {remaining}")

if remaining < 500:
    print("⚠️ Warning: Low credit balance!")

Track Daily Usage

from datetime import datetime, timedelta
from nellie_api import Nellie

client = Nellie(api_key="nel_...")
usage = client.get_usage()

# Filter to today's requests
today = datetime.utcnow().date()
today_requests = [
    r for r in usage.recent_requests
    if r.created_at and datetime.fromisoformat(r.created_at.replace('Z', '+00:00')).date() == today
]

today_credits = sum(r.credits_used for r in today_requests)
print(f"Today's usage: {len(today_requests)} requests, {today_credits} credits")

Build a Usage Dashboard

async function displayUsageStats() {
  const response = await fetch('https://api.nelliewriter.com/v1/usage', {
    headers: { 'X-API-Key': apiKey }
  });
  const data = await response.json();
  
  // Update summary
  document.getElementById('total-requests').textContent = data.totalRequests;
  document.getElementById('total-credits').textContent = data.totalCreditsUsed.toLocaleString();
  
  // Populate request history table
  const tbody = document.getElementById('request-history');
  tbody.innerHTML = '';
  
  data.recentRequests.forEach(req => {
    const row = document.createElement('tr');
    row.innerHTML = `
      <td>${req.requestId.slice(0, 8)}...</td>
      <td><span class="status-${req.status}">${req.status}</span></td>
      <td>${new Date(req.createdAt).toLocaleString()}</td>
      <td>${req.creditsUsed}</td>
    `;
    tbody.appendChild(row);
  });
}

Audit API Activity

from nellie_api import Nellie

client = Nellie(api_key="nel_...")
usage = client.get_usage()

# Check for unexpected activity
print(f"Total requests: {usage.total_requests}")
print("\nRecent activity:")
for req in usage.recent_requests[:10]:
    status_icon = "✅" if req.status == "completed" else "❌"
    print(f"  {status_icon} {req.request_id[:8]}... - {req.status} ({req.credits_used} credits)")

# Alert on high usage
if usage.total_requests > 100:
    print("\n⚠️ High request volume detected - verify this is expected")

Pre-generation Credit Check

from nellie_api import Nellie

client = Nellie(api_key="nel_...")

CREDIT_LIMIT = 10000
MODEL_COSTS = {"2.0": 250, "3.0": 500}

def can_generate(model: str) -> bool:
    usage = client.get_usage()
    remaining = CREDIT_LIMIT - usage.total_credits_used
    return remaining >= MODEL_COSTS.get(model, 500)

if can_generate("3.0"):
    book = client.books.create(prompt="...", model="3.0")
else:
    print("Insufficient credits for Nellie 3.0")

Related Endpoints

• POST /v1/book: Create generation requests
• GET /v1/status/{requestId}: Check individual request status
• GET /v1/models: View model costs

See Also

• Authentication: Managing API keys
• Rate Limits & Credits: Understanding the credit system
• FAQ: Questions about billing