ParrotRouter LogoParrotRouter
GET
/v1/credits

Get Credits Balance

Check your current credit balance, usage statistics, and rate limit information

Request

Example Requestbash
curl https://api.parrotrouter.com/v1/credits \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Successful Responsejson
{
  "object": "credit_balance",
  "balance": {
    "credits": 50.25,
    "currency": "USD"
  },
  "usage": {
    "daily": {
      "credits_used": 12.45,
      "requests": 156,
      "tokens": {
        "prompt": 45230,
        "completion": 12450,
        "total": 57680
      }
    },
    "monthly": {
      "credits_used": 245.80,
      "requests": 3421,
      "tokens": {
        "prompt": 892340,
        "completion": 321450,
        "total": 1213790
      }
    }
  },
  "limits": {
    "rate_limit": {
      "requests_per_minute": 100,
      "tokens_per_minute": 100000
    },
    "daily_limit": {
      "credits": 100,
      "remaining": 87.55
    }
  },
  "billing": {
    "plan": "pro",
    "auto_recharge": {
      "enabled": true,
      "threshold": 10,
      "amount": 50
    },
    "next_billing_date": "2024-02-01T00:00:00Z"
  }
}

Response Fields

balance

Current credit balance information

  • credits - Current credit balance (decimal)
  • currency - Currency code (always "USD")

usage

Usage statistics for different time periods

  • daily - Usage for the current day (UTC)
  • monthly - Usage for the current calendar month
  • Each period includes credits used, request count, and token breakdown

limits

Rate limiting and usage limit information

  • rate_limit - API rate limits for your plan
  • daily_limit - Daily credit limits (if applicable)

billing

Billing and subscription information

  • plan - Current subscription plan
  • auto_recharge - Automatic credit recharge settings
  • next_billing_date - Next billing cycle date

Simplified Response

For API keys with limited permissions, the response may be simplified:

Limited Responsejson
{
  "object": "credit_balance",
  "balance": {
    "credits": 50.25,
    "currency": "USD"
  }
}

Code Examples

Pythonpython
import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(
    "https://api.parrotrouter.com/v1/credits",
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    print(f"Current balance: $" + str(data['balance']['credits']))
    print(f"Daily usage: $" + str(data['usage']['daily']['credits_used']))
else:
    print(f"Error: {response.status_code}")
TypeScripttypescript
// Using fetch API
const response = await fetch('https://api.parrotrouter.com/v1/credits', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

if (response.ok) {
  const data = await response.json();
  console.log(`Current balance: $${data.balance.credits}`);
  console.log(`Daily usage: $${data.usage.daily.credits_used}`);
  
  // Check if low on credits
  if (data.balance.credits < 10) {
    console.warn('Low credit balance!');
  }
} else {
  console.error('Failed to fetch credits:', response.status);
}
Node.js with OpenAI SDKjavascript
// Note: The OpenAI SDK doesn't have a built-in method for credits
// You'll need to make a custom request

import OpenAI from 'openai';
import fetch from 'node-fetch';

const client = new OpenAI({
  baseURL: 'https://api.parrotrouter.com/v1',
  apiKey: 'YOUR_API_KEY',
});

async function getCredits() {
  const response = await fetch('https://api.parrotrouter.com/v1/credits', {
    headers: {
      'Authorization': `Bearer ${client.apiKey}`
    }
  });
  
  return response.json();
}

// Usage
const credits = await getCredits();
console.log('Balance:', credits.balance.credits);

Usage Monitoring

Best practices for monitoring your credit usage:

Set Up Alerts

Check your balance regularly and set up alerts when credits drop below a threshold:

async def check_credits_and_alert():
    response = await get_credits()
    balance = response['balance']['credits']
    
    if balance < 10:
        send_alert(f"Low credits: $" + str(balance) + " remaining")
    elif balance < 50:
        send_warning(f"Credits running low: $" + str(balance))
    
    return balance

Track Usage Trends

Monitor daily and monthly usage to optimize costs:

function analyzeUsage(data) {
  const daily = data.usage.daily;
  const monthly = data.usage.monthly;
  
  const avgCostPerRequest = daily.credits_used / daily.requests;
  const projectedMonthly = (daily.credits_used * 30);
  
  return {
    avgCostPerRequest,
    projectedMonthly,
    isOverBudget: projectedMonthly > 1000 // $1000 budget
  };
}

Error Responses

Authentication Errorjson
{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
Rate Limit Errorjson
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "param": null,
    "retry_after": 30
  }
}

Webhook Integration

You can also receive credit balance updates via webhooks:

Low Balance Webhookjson
{
  "type": "credit.low_balance",
  "created": 1699000000,
  "data": {
    "balance": {
      "credits": 5.50,
      "currency": "USD"
    },
    "threshold": 10,
    "api_key_id": "key_abc123",
    "account_id": "acc_xyz789"
  }
}

Best Practices

Related