Billing

info

Billing information is accessed through the Usage & Billing section in the sidebar. There is no separate Billing page in the portal — billing data is integrated into the Usage view at /usage.

View billing cycles, usage totals, and invoice records.

How billing works

The platform tracks usage at the request level. Each inference request is metered by the gateway, priced by the model's per-token rate, and recorded as a usage event by the usage service.

At the end of each calendar month a billing cycle is generated for your organization. A cycle aggregates the month's totals: requests, input tokens, output tokens, total cost. Cycles are issued by your platform administrator; they are not generated automatically by the portal.

The portal exposes billing data read-only:

• Current cycle — month-to-date totals for the open period.
• Cycle history — all closed cycles for your tenant.
• Summary — multi-month aggregate with monthly breakdown.
• Invoices — invoice records derived from finalized cycles.

There is no in-product payment flow. Settlement is handled outside the platform by your administrator. The status field on a cycle reflects its lifecycle in the platform's records (e.g. draft); the payment_status field is a bookkeeping field that defaults to pending.

Cost controls

The platform enforces two spend caps. Both are optional — when set, requests that would exceed the cap are rejected at the gateway with a rate-limit error.

• Daily cost cap (cost_per_day) — resets at midnight UTC. Self-service: tenant owners and admins can set their own daily cap from the portal. See Cost Limits.
• Monthly cost cap (cost_per_month) — resets at the start of each calendar month. Configured by your platform administrator on the tenant or per-user via the admin API; not exposed in the portal UI.

API Reference

All four endpoints below are read-only and require JWT authentication.

Get Current Billing Cycle

curl https://api.bulutistan.ai/api/v1/billing/current \
  -H "Authorization: Bearer <your-jwt-token>"

Response:

{
  "id": "ca597376-b8d7-4f95-9bb7-d2c9153239bf",
  "tenant_id": "c63f88b3-cb39-4f07-8353-4982557f7533",
  "period_start": "2024-02-01T00:00:00Z",
  "period_end": "2024-02-28T23:59:59Z",
  "billing_month": "2024-02",
  "status": "draft",
  "total_requests": 1250,
  "total_input_tokens": 125000,
  "total_output_tokens": 85000,
  "total_tokens": 210000,
  "total_cost": "45.50",
  "currency": "USD",
  "discount_amount": "0",
  "adjustment_amount": "0",
  "final_amount": "45.50",
  "invoice_number": null,
  "invoice_generated_at": null,
  "invoice_due_date": null,
  "invoice_paid_at": null,
  "payment_status": "pending",
  "average_cost_per_token": null
}

List Billing Cycles

curl https://api.bulutistan.ai/api/v1/billing/cycles \
  -H "Authorization: Bearer <your-jwt-token>"

Returns an array of billing cycle objects (same shape as above).

Get Billing Summary

curl https://api.bulutistan.ai/api/v1/billing/summary \
  -H "Authorization: Bearer <your-jwt-token>"

Response:

{
  "tenant_id": "c63f88b3-cb39-4f07-8353-4982557f7533",
  "period_months": 6,
  "summary": {
    "total_cost": 250.75,
    "total_requests": 15000,
    "total_tokens": 3500000,
    "average_monthly_cost": 41.79,
    "average_cost_per_token": 0.0
  },
  "monthly_breakdown": [
    {
      "month": "2024-02",
      "cost": 45.50,
      "requests": 1250,
      "tokens": 210000,
      "status": "draft",
      "invoice_number": null,
      "payment_status": "pending"
    }
  ]
}

List Invoices

curl https://api.bulutistan.ai/api/v1/billing/invoices \
  -H "Authorization: Bearer <your-jwt-token>"

Returns an array of invoice objects for finalized billing cycles.

Python Example

import requests

jwt_token = "<your-jwt-token>"
base_url = "https://api.bulutistan.ai"
headers = {"Authorization": f"Bearer {jwt_token}"}

# Get current billing cycle
response = requests.get(f"{base_url}/api/v1/billing/current", headers=headers)
current = response.json()
print(f"Current period: {current['billing_month']}")
print(f"Total cost: {current['total_cost']} {current['currency']}")

# Get billing summary
response = requests.get(f"{base_url}/api/v1/billing/summary", headers=headers)
summary = response.json()
print(f"Average monthly cost: ${summary['summary']['average_monthly_cost']}")