Usage & Billing API

Base URL: https://api.sparbz.cloud/api/v1

Overview

The Usage & Billing API allows you to track resource usage, monitor quotas, and access billing-related metrics. View current usage across all services, set and monitor quotas, and plan for capacity.

Sparbz Cloud uses per-second billing for all resources - you're charged for the exact seconds a resource is active with no minimum hour penalties. This means a 5-minute test costs approximately $0.003 for a database, making experimentation affordable.

All endpoints require authentication via Bearer token or API key.

---

Current Usage

GET /usage

Get current usage summary for your organization.

Headers:

Authorization: Bearer <token>

Response (200 OK):

{
  "organization_id": "uuid",
  "period_start": "2024-11-01T00:00:00Z",
  "period_end": "2024-11-29T23:59:59Z",
  "databases": {
    "used": 5,
    "limit": 10,
    "percentage": 50
  },
  "namespaces": {
    "used": 3,
    "limit": 5,
    "percentage": 60
  },
  "storage_gb": {
    "used": 256,
    "limit": 1000,
    "percentage": 25.6
  },
  "bandwidth_gb": {
    "used": 450,
    "limit": 2000,
    "percentage": 22.5
  },
  "nfs_shares": {
    "used": 2,
    "limit": 10,
    "percentage": 20
  },
  "kafka_clusters": {
    "used": 1,
    "limit": 5,
    "percentage": 20
  },
  "api_requests": {
    "used": 1250000,
    "limit": 10000000,
    "percentage": 12.5
  },
  "seats": {
    "used": 8,
    "limit": 10,
    "percentage": 80
  }
}

---

Usage by Resource

GET /usage/:resource_type

Get detailed usage for a specific resource type.

Resource Types:

• databases
• namespaces
• storage
• nfs
• kafka
• vault
• vpc
• backups

Query Parameters:

Parameter	Type	Description
period	string	current, last-month, last-quarter, custom
from	timestamp	Start date (for custom period)
to	timestamp	End date (for custom period)

Response (200 OK):

{
  "resource_type": "databases",
  "period": "current",
  "period_start": "2024-11-01T00:00:00Z",
  "period_end": "2024-11-29T23:59:59Z",
  "resources": [
    {
      "id": "uuid",
      "name": "prod-postgres",
      "type": "postgres",
      "tier": "pro",
      "status": "running",
      "storage_gb": 50,
      "storage_limit_gb": 100,
      "connections_used": 45,
      "connections_limit": 100,
      "cpu_percent_avg": 35.2,
      "memory_percent_avg": 62.1,
      "cost": 99.00,
      "daily_usage": [
        {
          "date": "2024-11-29",
          "storage_gb": 50,
          "connections_peak": 50,
          "cpu_percent": 40.2
        }
      ]
    }
  ],
  "total_used": 5,
  "total_limit": 10,
  "total_cost": 495.00,
  "estimated_monthly_cost": 495.00
}

---

Usage History

GET /usage/history

Get usage history over time.

Query Parameters:

Parameter	Type	Description
granularity	string	daily, weekly, monthly
resource_type	string	Filter by resource type
months	integer	Number of months to retrieve (default: 1, max: 24)

Response (200 OK):

[
  {
    "date": "2024-11-29",
    "databases": {
      "used": 5,
      "limit": 10,
      "cost": 99.00
    },
    "namespaces": {
      "used": 3,
      "limit": 5,
      "cost": 50.00
    },
    "storage_gb": {
      "used": 256,
      "limit": 1000,
      "cost": 12.80
    },
    "bandwidth_gb": {
      "used": 25,
      "cost": 1.25
    },
    "total_cost": 163.05
  }
]

---

Quotas

GET /usage/quotas

Get quota limits and current usage.

Response (200 OK):

{
  "organization_id": "uuid",
  "quotas": [
    {
      "resource": "databases",
      "soft_limit": 10,
      "hard_limit": 20,
      "current_usage": 5,
      "warning_threshold": 80,
      "alert_at_percent": 90,
      "alert_enabled": true
    },
    {
      "resource": "api_requests",
      "soft_limit": 10000000,
      "hard_limit": 50000000,
      "current_usage": 1250000,
      "warning_threshold": 80,
      "alert_at_percent": 90,
      "alert_enabled": true
    },
    {
      "resource": "storage_gb",
      "soft_limit": 1000,
      "hard_limit": 5000,
      "current_usage": 256,
      "warning_threshold": 80,
      "alert_at_percent": 90,
      "alert_enabled": true
    }
  ]
}

---

POST /usage/quotas/:resource

Set quota limits for a resource.

Request Body:

{
  "soft_limit": 10,
  "hard_limit": 20,
  "alert_at_percent": 90
}

Response (200 OK):

{
  "resource": "databases",
  "soft_limit": 10,
  "hard_limit": 20,
  "alert_at_percent": 90,
  "updated_at": "2024-11-29T15:45:00Z"
}

---

Quota Alerts

GET /usage/quota-alerts

Get active quota alerts.

Query Parameters:

Parameter	Type	Description
status	string	Filter by status: warning, critical, resolved
resource	string	Filter by resource type

Response (200 OK):

[
  {
    "id": "uuid",
    "resource": "storage_gb",
    "current_usage": 800,
    "quota_limit": 1000,
    "usage_percent": 80,
    "severity": "warning",
    "triggered_at": "2024-11-29T15:30:00Z",
    "message": "Storage usage reached 80% of quota (800 GB of 1000 GB)"
  },
  {
    "id": "uuid",
    "resource": "seats",
    "current_usage": 9,
    "quota_limit": 10,
    "usage_percent": 90,
    "severity": "critical",
    "triggered_at": "2024-11-29T14:15:00Z",
    "message": "Seats usage reached 90% of quota (9 of 10 seats)"
  }
]

---

Projections

GET /usage/projections

Get projected usage for the current billing period.

Query Parameters:

Parameter	Type	Description
resource_type	string	Project specific resource or all if omitted

Response (200 OK):

{
  "projection_date": "2024-11-29",
  "period_end": "2024-12-01T00:00:00Z",
  "days_remaining": 2,
  "projections": [
    {
      "resource": "storage_gb",
      "current_usage": 256,
      "daily_growth_gb": 5,
      "projected_month_end": 266,
      "quota_limit": 1000,
      "will_exceed_quota": false
    },
    {
      "resource": "bandwidth_gb",
      "current_usage": 450,
      "daily_growth_gb": 25,
      "projected_month_end": 500,
      "quota_limit": 2000,
      "will_exceed_quota": false
    }
  ]
}

---

Cost Analysis

GET /usage/costs

Get detailed cost breakdown by resource.

Query Parameters:

Parameter	Type	Description
period	string	current, last-month, last-quarter
resource_type	string	Filter by resource
granularity	string	daily, weekly, monthly

Response (200 OK):

{
  "period": "current",
  "period_start": "2024-11-01T00:00:00Z",
  "period_end": "2024-11-29T23:59:59Z",
  "total_cost": 1234.56,
  "breakdown": [
    {
      "resource": "databases",
      "count": 5,
      "unit_cost_monthly": 99.00,
      "total_cost": 495.00,
      "percentage": 40.1
    },
    {
      "resource": "namespaces",
      "count": 3,
      "unit_cost_monthly": 50.00,
      "total_cost": 150.00,
      "percentage": 12.2
    },
    {
      "resource": "storage_gb",
      "usage": 256,
      "unit_cost_per_gb": 0.05,
      "total_cost": 12.80,
      "percentage": 1.0
    },
    {
      "resource": "bandwidth_gb",
      "usage": 450,
      "unit_cost_per_gb": 0.1,
      "total_cost": 45.00,
      "percentage": 3.6
    },
    {
      "resource": "nfs_gb",
      "usage": 500,
      "unit_cost_per_gb": 0.06,
      "total_cost": 30.00,
      "percentage": 2.4
    }
  ],
  "estimated_monthly_total": 1234.56,
  "daily_average": 42.57
}

---

Optimization Recommendations

GET /usage/recommendations

Get optimization recommendations based on usage patterns.

Response (200 OK):

[
  {
    "id": "rec-001",
    "priority": "high",
    "category": "performance",
    "resource": "databases",
    "title": "Right-size database tier",
    "description": "Database 'prod-postgres' is using only 35% CPU on average. Consider downgrading to a smaller tier.",
    "current_cost": 99.00,
    "projected_savings": 33.00,
    "savings_percent": 33.3,
    "implementation_effort": "low"
  },
  {
    "id": "rec-002",
    "priority": "medium",
    "category": "efficiency",
    "resource": "storage",
    "title": "Clean up old backups",
    "description": "You have 125 GB of backups older than 90 days that could be deleted.",
    "current_cost": 6.25,
    "projected_savings": 6.25,
    "savings_percent": 100,
    "implementation_effort": "low"
  },
  {
    "id": "rec-003",
    "priority": "medium",
    "category": "utilization",
    "resource": "namespaces",
    "title": "Consolidate underutilized namespaces",
    "description": "3 namespaces are using less than 10% of their allocated resources.",
    "current_cost": 150.00,
    "projected_savings": 50.00,
    "savings_percent": 33.3,
    "implementation_effort": "medium"
  }
]

---

Export Usage Data

POST /usage/export

Export usage data in CSV or JSON format.

Request Body:

{
  "format": "csv | json",
  "resource_types": ["databases", "namespaces", "storage"],
  "period": {
    "from": "2024-11-01T00:00:00Z",
    "to": "2024-11-29T23:59:59Z"
  }
}

Response (202 Accepted):

{
  "export_id": "export-xxx",
  "status": "processing",
  "format": "csv",
  "download_url": null,
  "expires_at": "2024-12-06T15:45:00Z",
  "created_at": "2024-11-29T15:45:00Z"
}

---

GET /usage/export/:export_id

Get status and download link for an export.

Response (200 OK):

{
  "export_id": "export-xxx",
  "status": "completed",
  "format": "csv",
  "file_size_bytes": 1048576,
  "download_url": "https://downloads.sparbz.cloud/export-xxx.csv",
  "expires_at": "2024-12-06T15:45:00Z",
  "created_at": "2024-11-29T15:45:00Z"
}

---

Error Responses

Code	Description
400	Bad Request - Invalid period, resource type, or parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Export or quota doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

---

Common Use Cases

Monitoring Current Usage

GET /usage

Setting Quota Alerts

POST /usage/quotas/storage_gb
{
  "soft_limit": 1000,
  "hard_limit": 5000,
  "alert_at_percent": 80
}

Analyzing Costs by Resource

GET /usage/costs?period=current&granularity=daily

Getting Optimization Recommendations

GET /usage/recommendations

Exporting Usage Data for Reporting

POST /usage/export
{
  "format": "csv",
  "resource_types": ["databases", "storage", "bandwidth"],
  "period": {
    "from": "2024-11-01T00:00:00Z",
    "to": "2024-11-29T23:59:59Z"
  }
}

---

Per-Second Billing Model

Sparbz Cloud charges for resources based on exact usage duration with no minimum hour penalties.

How It Works

1. Usage Recording - When a resource is created, usage is recorded per second
2. Hourly Aggregation - At :05 past each hour, usage is aggregated into summaries
3. Daily Billing - At 2 AM UTC each day, aggregated usage is synced to Stripe
4. Accurate Charging - Stripe invoices based on the exact hours of usage at the resource's hourly rate

Cost Calculation

Costs are calculated as:

Cost = (Duration in Seconds ÷ 3600) × Hourly Rate

Pricing Examples

Databases (Postgres Pro = $29/month ≈ $0.0397/hour)

Duration	Cost
5 minutes	$0.0033
1 hour	$0.0397
1 day (24 hours)	$0.952
30 days	$29.00

Storage (Per GB = $0.10/month ≈ $0.000137/hour)

Duration	Cost
1 hour	$0.00014
1 day (24 hours)	$0.0033
30 days	$0.10

Compute Namespaces (Pro Tier = $29/month ≈ $0.0397/hour)

Same as database pricing above.

Resource Pricing Tiers

Databases:

• Postgres Starter: $9/month ($0.0123/hour)
• Postgres Pro: $29/month ($0.0397/hour)
• Postgres Scale: $99/month ($0.1355/hour)

Compute (Namespaces):

• Starter: $0/month (Free)
• Pro: $29/month ($0.0397/hour)
• Scale: $99/month ($0.1355/hour)

Storage:

• Per GB: $0.10/month ($0.000137/hour)

Bandwidth:

• Per GB: $0.10/month

Container Registry:

• Per GB: $0.10/month

Prorated Billing

Resources created or deleted mid-hour are billed proportionally. For example:

• Created a database at 13:30, deleted at 14:15 = 45 minutes of usage
• Cost = (45 minutes ÷ 60) × hourly rate = 0.75 × hourly rate

Billing Cycle

• Charges are accumulated daily
• Billed at the end of your monthly billing cycle
• Appears on your invoice from Stripe as usage-based charges
• Can monitor accumulated costs via the /usage/costs endpoint

GET /billing/subscription

Get current subscription and billing information.

Response (200 OK):

{
  "organization_id": "uuid",
  "stripe_customer_id": "cus_xxx",
  "subscription_id": "sub_xxx",
  "plan": "pro",
  "status": "active",
  "billing_cycle": {
    "current_period_start": "2024-12-01T00:00:00Z",
    "current_period_end": "2025-01-01T00:00:00Z"
  },
  "usage_based_metrics": [
    {
      "name": "database_hours",
      "display_name": "Database Hours",
      "usage": 168.5,
      "unit": "hours",
      "price_per_unit": 0.0397
    },
    {
      "name": "storage_gb",
      "display_name": "Storage GB",
      "usage": 256.0,
      "unit": "gb-month",
      "price_per_unit": 0.10
    }
  ],
  "estimated_total_cost": 1234.56,
  "next_billing_date": "2025-01-01T00:00:00Z"
}

---