Skip to main content
View Categories

GET /v1/usage

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 #

Field Type Description
success boolean Always true for successful requests
totalRequests integer Total number of requests made with this key
totalCreditsUsed integer Cumulative credits consumed
recentRequests array Recent request history (most recent first)

Recent Request Fields #

Field Type Description
requestId string Unique request identifier
status string Final status (completed, failed, processing)
createdAt string ISO 8601 timestamp when request was made
completedAt string null ISO 8601 timestamp when request finished
creditsUsed integer Credits consumed (0 for failed jobs)

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 = `
      ${req.requestId.slice(0, 8)}...
      ${req.status}
      ${new Date(req.createdAt).toLocaleString()}
      ${req.creditsUsed}
    `;
    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 #