API Endpoints

Usage & Billing

Usage & Billing

Overview

The AI Magicx API provides comprehensive usage tracking and flexible billing options including pay-as-you-go overage to ensure uninterrupted service. Monitor consumption in real-time, manage costs effectively, and scale seamlessly with your needs.

Usage Analytics API

Get Usage Statistics

Code
 
GET /api/v1/usage

Retrieve detailed usage analytics with filtering and aggregation options.

Query Parameters

Parameter	Type	Required	Description
start_date	ISO 8601	No	Start of date range (default: current period start)
end_date	ISO 8601	No	End of date range (default: now)
api_key_id	string	No	Filter by specific API key
model	string	No	Filter by AI model
endpoint	string	No	Filter by API endpoint
aggregation	string	No	Group by: hour, day, week, month
timezone	string	No	Timezone for aggregation (default: UTC)
limit	integer	No	Results per page (max: 1000)
offset	integer	No	Pagination offset

Response

Code(json)
 
{
  "success": true,
  "data": {
    "summary": {
      "total_requests": 15750,
      "total_credits": 18500,
      "success_rate": 99.8,
      "average_latency": 234,
      "period": {
        "start": "2025-01-01T00:00:00Z",
        "end": "2025-01-10T23:59:59Z"
      }
    },
    "current_usage": {
      "requests": 15750,
      "credits_used": 18500,
      "credits_included": 5000,
      "credits_overage": 13500,
      "overage_cost": 135.00
    },
    "details": [
      {
        "timestamp": "2025-01-10T14:30:00Z",
        "request_id": "req_abc123",
        "endpoint": "/api/v1/chat",
        "method": "POST",
        "model": "4o-mini",
        "credits": 2,
        "latency": 215,
        "status": "success",
        "metadata": {
          "tools_used": ["web_search"],
          "tokens": {
            "prompt": 150,
            "completion": 450,
            "total": 600
          }
        }
      }
    ],
    "aggregations": {
      "by_model": {
        "4o-mini": { "requests": 8500, "credits": 9200 },
        "claude-4-sonnet": { "requests": 4200, "credits": 5100 },
        "dall-e-3": { "requests": 3050, "credits": 4200 }
      },
      "by_endpoint": {
        "/api/v1/chat": { "requests": 12700, "credits": 14300 },
        "/api/v1/ai-image/generate": { "requests": 3050, "credits": 4200 }
      }
    }
  },
  "meta": {
    "pagination": {
      "limit": 100,
      "offset": 0,
      "total": 15750,
      "has_more": true
    }
  }
}

Usage Aggregation Examples

Daily Usage Chart

Code(bash)
 
curl -X GET "https://beta.aimagicx.com/api/v1/usage?aggregation=day&start_date=2025-01-01" \
  -H "Authorization: Bearer mgx-sk-your-api-key"

Model Performance Analysis

Code(bash)
 
curl -X GET "https://beta.aimagicx.com/api/v1/usage?model=4o-mini&aggregation=hour" \
  -H "Authorization: Bearer mgx-sk-your-api-key"

Account Management API

Get Account Information

Code
 
GET /api/v1/account

Retrieve comprehensive account details including plan information and limits.

Response

Code(json)
 
{
  "success": true,
  "data": {
    "account": {
      "id": "acc_123456789",
      "name": "Acme Corporation",
      "email": "api@acme.com",
      "created_at": "2024-06-15T10:00:00Z",
      "status": "active"
    },
    "subscription": {
      "plan": "api-professional",
      "status": "active",
      "current_period": {
        "start": "2025-01-01T00:00:00Z",
        "end": "2025-01-31T23:59:59Z"
      },
      "features": {
        "included_credits": 5000,
        "overage_enabled": true,
        "overage_rate": 0.01,
        "rate_limit": 120,
        "concurrent_requests": 20,
        "available_models": ["all"],
        "api_features": [
          "chat:completions",
          "image:generation",
          "logo:generation",
          "tools:all",
          "streaming:enabled"
        ]
      }
    },
    "billing": {
      "payment_method": "card",
      "next_billing_date": "2025-02-01T00:00:00Z",
      "auto_renew": true,
      "overage_settings": {
        "enabled": true,
        "soft_limit": 10000,
        "hard_limit": 50000,
        "notification_thresholds": [50, 80, 100]
      }
    }
  }
}

Credit Management API

Get Credit Balance

Code
 
GET /api/v1/credits

Monitor credit balance and transaction history in real-time.

Query Parameters

Parameter	Type	Required	Description
type	string	No	Filter: allocation, consumption, purchase, overage
start_date	ISO 8601	No	Transaction history start date
end_date	ISO 8601	No	Transaction history end date
limit	integer	No	Results per page (default: 50)
offset	integer	No	Pagination offset

Response

Code(json)
 
{
  "success": true,
  "data": {
    "balance": {
      "total_available": 1500,
      "included_remaining": 1500,
      "purchased": 0,
      "overage_used": 13500,
      "overage_cost": 135.00
    },
    "current_period": {
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-01-31T23:59:59Z",
      "included_credits": 5000,
      "credits_used": 18500,
      "overage_active": true
    },
    "transactions": [
      {
        "id": "txn_789012",
        "type": "overage",
        "amount": -500,
        "balance_after": 0,
        "created_at": "2025-01-10T15:00:00Z",
        "description": "Overage usage - 500 credits",
        "metadata": {
          "rate": 0.01,
          "cost": 5.00,
          "billing_status": "pending"
        }
      },
      {
        "id": "txn_789011",
        "type": "consumption",
        "amount": -2,
        "balance_after": 0,
        "created_at": "2025-01-10T14:30:00Z",
        "description": "Chat completion - 4o-mini",
        "metadata": {
          "request_id": "req_abc123",
          "model": "4o-mini",
          "endpoint": "/api/v1/chat"
        }
      },
      {
        "id": "txn_789010",
        "type": "allocation",
        "amount": 5000,
        "balance_after": 5000,
        "created_at": "2025-01-01T00:00:00Z",
        "description": "Monthly credit allocation",
        "metadata": {
          "plan": "api-professional",
          "period": "2025-01"
        }
      }
    ]
  }
}

Pay-As-You-Go Overage

How Overage Works

Our pay-as-you-go overage system ensures your applications never experience interruptions due to credit limits:

1. Automatic Activation: When monthly credits are exhausted, overage billing activates automatically
2. Transparent Pricing: Pay only for additional credits used at your plan's overage rate
3. Real-time Tracking: Monitor overage usage through API headers and dedicated endpoints
4. Monthly Billing: Overage charges are consolidated and billed at the end of each billing period
5. No Prepayment Required: Use now, pay later - no need to pre-purchase credit packages

Overage Configuration

Code
 
GET /api/v1/overage/status

Check current overage configuration and usage.

Response

Code(json)
 
{
  "success": true,
  "data": {
    "enabled": true,
    "rate_per_credit": 0.01,
    "current_usage": {
      "credits": 13500,
      "cost": 135.00,
      "billing_period": "2025-01"
    },
    "limits": {
      "soft_limit": 10000,
      "soft_limit_reached": true,
      "hard_limit": 50000,
      "hard_limit_reached": false
    },
    "notifications": {
      "email_alerts": true,
      "webhook_enabled": false,
      "thresholds": [50, 80, 100],
      "last_notification": "2025-01-10T12:00:00Z"
    }
  }
}

Overage Management

Enable/Disable Overage

Code
 
POST /api/v1/overage/configure

Code(json)
 
{
  "enabled": true,
  "soft_limit": 10000,
  "hard_limit": 50000,
  "notification_email": "billing@acme.com"
}

Set Overage Limits

Protect against unexpected charges by setting limits:

• Soft Limit: Triggers notifications but allows continued usage
• Hard Limit: Stops API access when reached (optional)

Overage Response Headers

Every API response includes overage information when active:

Code
 
X-Credits-Used: 2
X-Credits-Remaining: 0
X-Overage-Active: true
X-Overage-Credits: 13500
X-Overage-Cost: 135.00
X-Overage-Rate: 0.01

Cost Optimization

Best Practices

1. Model Selection

   • Use efficient models for simple tasks (e.g., 4o-mini for basic queries)
   • Reserve advanced models for complex operations
   • Benchmark performance vs. cost trade-offs

2. Request Optimization

   Code(javascript)
    
   // Batch multiple operations when possible
   const batchRequest = {
     operations: [
       { type: "chat", model: "4o-mini", message: "Query 1" },
       { type: "chat", model: "4o-mini", message: "Query 2" }
     ]
   };

3. Caching Strategy

   • Cache frequently requested data
   • Implement response deduplication
   • Use conditional requests where applicable

4. Usage Monitoring

   Code(javascript)
    
   // Set up usage alerts
   async function checkUsage() {
     const response = await fetch('/api/v1/credits');
     const { data } = await response.json();
     
     const usagePercent = (data.balance.included_remaining / 5000) * 100;
     if (usagePercent < 20) {
       console.warn(`Low credits: ${usagePercent}% remaining`);
     }
   }

Cost Analysis Tools

Usage Breakdown

Code(bash)
 
# Get cost breakdown by model
curl -X GET "https://beta.aimagicx.com/api/v1/usage?aggregation=model&start_date=2025-01-01" \
  -H "Authorization: Bearer mgx-sk-your-api-key"

Export Usage Data

Code(bash)
 
# Export detailed usage for analysis
curl -X GET "https://beta.aimagicx.com/api/v1/usage?format=csv&start_date=2025-01-01" \
  -H "Authorization: Bearer mgx-sk-your-api-key" \
  -o usage_report.csv

Billing FAQ

When are overage charges billed?

Overage charges are accumulated throughout the billing period and charged at the end of each month along with your regular subscription.

Can I set spending limits?

Yes, configure soft and hard limits through the overage configuration API to control spending.

How quickly do credits refresh?

Credits refresh at the start of each billing period (monthly). Unused credits do not roll over.

What happens if payment fails for overage?

Your account remains active, but overage is disabled until payment is resolved. You can still use included credits.

Can I purchase credits in advance?

Currently, we operate on a pay-as-you-go model. Pre-purchased credit packages are coming soon.

Next Steps

• API Overview: Understand the API architecture
• Authentication: Set up secure access
• Error Handling: Handle billing-related errors
• Code Examples: Implementation samples

---

For billing support, contact contact@aimagicx.com