- Core Concepts
- Billing & Usage
Core Concepts
Billing & Usage
Monitor your credit balance and API usage
The Billing API lets you check your account balance and track API usage. All billing endpoints are read-only.
Get Balance
import requests
headers = {"X-API-Key": "YOUR_API_KEY"}
balance = requests.get(
"https://app.backboard.io/api/billing/balance",
headers=headers
).json()
print(f"Balance: ${balance['balance_usd']:.2f}")
Response fields: balance_usd, auto_reload_enabled, auto_reload_threshold_usd, auto_reload_amount_usd, created_at, updated_at.
Recent Usage
Paginated list of individual usage events with full filtering and sorting.
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number (1-indexed) |
page_size | integer | 20 | Items per page (1–100) |
start | string | — | Start date YYYY-MM-DD (inclusive) |
end | string | — | End date YYYY-MM-DD (inclusive) |
model | string | — | Filter by model name (substring match) |
credit_type | string | — | Filter: subscription, regular, mixed, none |
sort_by | string | date | Sort field: date, amount, total_tokens |
sort_order | string | desc | asc or desc |
usage = requests.get(
"https://app.backboard.io/api/billing/usage/recent",
headers=headers,
params={"page": 1, "page_size": 20, "start": "2025-12-01", "sort_by": "amount", "sort_order": "desc"}
).json()
for event in usage["data"]:
print(f"{event['date']} | {event.get('model')} | "
f"{event['input_tokens']}→{event['output_tokens']} tokens | "
f"${event['amount_deducted_usd']:.4f}")
Usage Event Fields
| Field | Type | Description |
|---|---|---|
date | datetime | Timestamp of the event |
model | string | Model used (can be null) |
input_tokens | integer | Input tokens consumed |
output_tokens | integer | Output tokens generated |
vector_reads | integer | Vector DB reads |
vector_cost_usd | number | Vector operation cost |
memory_write_cost_usd | number | Memory write cost |
credit_type | string | subscription, regular, mixed, or none |
amount_deducted_usd | number | Total cost for this event |
Usage Summary
Aggregated totals for a time window.
| Parameter | Type | Default | Description |
|---|---|---|---|
range | string | period | period (current billing period), 7d, 30d, or all |
summary = requests.get(
"https://app.backboard.io/api/billing/usage/summary",
headers=headers,
params={"range": "30d"}
).json()
print(f"Total: ${summary['total_spending_usd']:.4f}")
print(f"Tokens: ${summary['token_usage_usd']:.4f} ({summary['token_input_tokens']} in / {summary['token_output_tokens']} out)")
print(f"Reads: {summary['reads_count']} (${summary['reads_cost_usd']:.4f})")
print(f"Writes: {summary['writes_count']} (${summary['writes_cost_usd']:.4f})")
New accounts include $5 in free credits (valid for 30 days). Purchase additional credits or subscribe from the Backboard dashboard.