Get Usage

Retrieves metered usage statistics for the current billing period, including API calls, storage, seats, and other billable metrics.

Endpoint

GET /api/billing/usage

Authentication

Required. Bearer token in Authorization header.

Request

Query Parameters

Parameter	Type	Description
`startDate`	string	Filter usage from this date (ISO 8601)
`endDate`	string	Filter usage until this date (ISO 8601)
`metrics`	string	Comma-separated list of specific metrics to return

Example Request

# Current period usage
curl -X GET https://api.example.com/api/billing/usage \
  -H "Authorization: Bearer <session_token>"

# Specific date range
curl -X GET "https://api.example.com/api/billing/usage?startDate=2024-01-01&endDate=2024-01-31" \
  -H "Authorization: Bearer <session_token>"

# Specific metrics only
curl -X GET "https://api.example.com/api/billing/usage?metrics=api_calls,storage" \
  -H "Authorization: Bearer <session_token>"

TypeScript Example

interface UsageParams {
  startDate?: string;
  endDate?: string;
  metrics?: string[];
}

async function getUsage(params?: UsageParams) {
  const query = new URLSearchParams();
  if (params?.startDate) query.set('startDate', params.startDate);
  if (params?.endDate) query.set('endDate', params.endDate);
  if (params?.metrics) query.set('metrics', params.metrics.join(','));

  const response = await fetch(`/api/billing/usage?${query}`, {
    headers: { 'Authorization': `Bearer ${sessionToken}` }
  });

  return response.json();
}

// Get current usage
const currentUsage = await getUsage();

// Get usage for specific period
const januaryUsage = await getUsage({
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Response

Success Response (200)

{
  "success": true,
  "data": {
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "metrics": {
      "apiCalls": {
        "name": "API Calls",
        "unit": "requests",
        "included": 100000,
        "used": 45230,
        "overage": 0,
        "percentage": 45.23
      },
      "storage": {
        "name": "Storage",
        "unit": "GB",
        "included": 100,
        "used": 67.5,
        "overage": 0,
        "percentage": 67.5
      },
      "seats": {
        "name": "Team Seats",
        "unit": "users",
        "included": 10,
        "used": 7,
        "overage": 0,
        "percentage": 70
      },
      "bandwidth": {
        "name": "Bandwidth",
        "unit": "GB",
        "included": 1000,
        "used": 234.8,
        "overage": 0,
        "percentage": 23.48
      }
    },
    "estimatedCost": {
      "base": 29.00,
      "overage": 0,
      "total": 29.00,
      "currency": "usd"
    },
    "projectedUsage": {
      "apiCalls": {
        "projected": 52000,
        "percentage": 52
      }
    }
  }
}

Response Fields

Field	Type	Description
`period`	object	The billing period for this usage data
`period.start`	string	ISO 8601 timestamp of period start
`period.end`	string	ISO 8601 timestamp of period end
`metrics`	object	Usage metrics keyed by metric ID
`metrics.*.name`	string	Human-readable metric name
`metrics.*.unit`	string	Unit of measurement
`metrics.*.included`	number	Amount included in plan
`metrics.*.used`	number	Current usage amount
`metrics.*.overage`	number	Overage amount (if any)
`metrics.*.percentage`	number	Usage as percentage of included amount
`estimatedCost`	object	Cost breakdown for current usage
`estimatedCost.base`	number	Base plan cost
`estimatedCost.overage`	number	Overage charges
`estimatedCost.total`	number	Total estimated cost
`projectedUsage`	object	Projected usage by end of period

Metric Types

Metric ID	Unit	Description
`apiCalls`	requests	Number of API requests made
`storage`	GB	Data storage used
`seats`	users	Number of team members
`bandwidth`	GB	Data transfer out
`emails`	emails	Emails sent
`webhooks`	events	Webhook events processed

Error Responses

Unauthorized (401)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Invalid Date Range (400)

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid date range: startDate must be before endDate"
  }
}

React Component Example

import { useEffect, useState } from 'react';

interface Metric {
  name: string;
  unit: string;
  included: number;
  used: number;
  percentage: number;
}

function UsageBar({ metric }: { metric: Metric }) {
  const color = metric.percentage > 90 ? 'red' : 
                metric.percentage > 75 ? 'yellow' : 'green';
  
  return (
    <div className="usage-metric">
      <div className="flex justify-between">
        <span>{metric.name}</span>
        <span>{metric.used.toLocaleString()} / {metric.included.toLocaleString()} {metric.unit}</span>
      </div>
      <div className="progress-bar">
        <div 
          className={`progress-fill bg-${color}-500`}
          style={{ width: `${Math.min(metric.percentage, 100)}%` }}
        />
      </div>
      <span className="text-sm text-gray-500">
        {metric.percentage.toFixed(1)}% used
      </span>
    </div>
  );
}

function UsageDashboard() {
  const [usage, setUsage] = useState<any>(null);
  
  useEffect(() => {
    fetch('/api/billing/usage', {
      headers: { 'Authorization': `Bearer ${getToken()}` }
    })
      .then(res => res.json())
      .then(({ data }) => setUsage(data));
  }, []);

  if (!usage) return <div>Loading...</div>;

  return (
    <div className="usage-dashboard">
      <h2>Usage for {usage.period.start} - {usage.period.end}</h2>
      
      {Object.entries(usage.metrics).map(([key, metric]) => (
        <UsageBar key={key} metric={metric as Metric} />
      ))}
      
      <div className="estimated-cost">
        Estimated cost: ${usage.estimatedCost.total.toFixed(2)}
        {usage.estimatedCost.overage > 0 && (
          <span className="text-red-500">
            (includes ${usage.estimatedCost.overage.toFixed(2)} overage)
          </span>
        )}
      </div>
    </div>
  );
}

Notes

Usage data is updated in near real-time (within 5 minutes)
Projected usage is calculated based on current consumption rate
Overage charges apply when usage exceeds included amounts
Historical usage data is retained for 12 months
Usage resets at the start of each billing period

Get Usage

On this page