Usage

Monitor your API usage and costs in detail.

Usage Overview

The Usage page shows comprehensive usage analytics:

Current Period Summary

• Total Tokens: Combined input + output
• Total Requests: API call count
• Total Cost: Running total
• Period: Current billing period dates

Each summary card also shows a trend indicator comparing the current period to the previous matching period (for example, this week vs. last week), so you can tell at a glance whether usage is up or down.

Cached Tokens and Cache Savings

Models that support automatic prefix caching reuse the computed prefix of a prompt across requests, and cached input tokens are billed at a reduced rate. When your usage includes cached tokens, two extra stat cards appear:

• Cached Tokens: How many of your input tokens were served from the cache.
• Cache Savings: How much less you paid because those tokens were billed at the cached rate instead of the full input price.

The savings are already included in Total Cost — the card just shows how much the cache reduced your bill. To make the most of caching, keep the shared/system portion of your prompts stable at the start of each request.

Usage Charts

Daily Usage

Interactive chart showing:

• Input tokens (blue)
• Output tokens (green)
• Requests (line)
• Cost (area)

Time range options:

• Today
• Yesterday
• Last 24 hours (rolling window, distinct from Today)
• Last 7 days
• Last 30 days
• Last 90 days
• Custom range (with hour and minute precision)

The 7, 30, and 90 day presets are exact calendar ranges aligned to your timezone, not approximate rolling windows, so repeated views of the same preset return the same period. The picker displays the active timezone it is resolving against — all presets and custom ranges send explicit ISO start/end timestamps plus that timezone, and the charts, tables, and exports all stay on one date contract.

Daily trend data is sourced from the canonical usage report endpoint, which combines historical aggregates with live current-period events. This means the chart, the summary cards above it and any Excel export agree on totals — there is no drift between views.

Custom range (split-panel picker)

Selecting Custom opens a split-panel popover so you can pick a window in whichever way is fastest:

• Quick ranges (left) — a "Last [N] ⟨unit⟩" builder (minutes, hours, days, weeks, months, years) plus one-click fixed ranges such as This week and This month. Choosing one fills the custom range on the right.
• Custom range (right) — a timezone badge, collapsed FROM and TO date-time fields, a live summary of the window, and Apply.

Each FROM/TO field opens a compact calendar for the date and an HH:mm field for the time (24-hour). This lets you narrow usage to an incident window — for example "between 14:30 and 16:00 today" — rather than only whole days.

• Time errors are shown on blur only, so you're not warned while you're still typing; an invalid time such as 25:70 is rejected.
• Nested popovers close innermost-first — Escape or an outside click closes the open calendar/time popover before the whole picker.
• Ranges are capped to the last 365 days; a longer quick range (e.g. "Last 2 years") is clamped and shows a "Limited to the last 365 days" note.

The outer preset buttons (Today/7D/30D/90D) remain date-only; the backend automatically includes the whole end-of-day.

Times use your local timezone

The Usage page shows dates and times — and aligns preset and custom day boundaries — to your browser's local timezone, and the picker displays the timezone it is resolving against. (Previously an untouched account could show everything in UTC.) If your account has an explicit, non-UTC timezone set, that takes precedence over the browser.

Model Breakdown

Pie chart showing usage distribution by model.

Detailed Tables

By Model

Column	Description
Model	Model identifier
Requests	Number of API calls
Input Tokens	Total input tokens
Output Tokens	Total output tokens
Cached	Input tokens served from the prefix cache (shown when the model has cached usage)
Cost	Total cost

By Day

Daily breakdown with same metrics.

By API Key

Usage per API key:

• Identify high-usage keys
• Track application-specific usage

Export

Export usage data to Excel from the Export menu on the Usage page:

• Quick Export — exports summary cards, daily trends and per-model breakdown for the selected date range. Reads from the canonical report, so totals match the on-screen chart exactly.
• Export With History — adds a per-request detail sheet covering the API calls in the selected range. For long ranges with many calls, the detail sheet is fetched in pages and stitched together, capped at the 5,000 most recent rows for the selected range.

The selected date range (including hour and minute when set via Custom) is preserved in the Excel file metadata.

File formats

The Export menu offers Excel and CSV:

• Excel (.xlsx) — a single styled workbook with one sheet per section (overview, daily trends, per-model breakdown, and the per-request detail sheet when you choose Export With History).
• CSV — a CSV file cannot hold multiple sheets, so the export downloads a .zip archive containing one CSV per sheet, named in order after the on-screen section titles (for example 01_overview.csv, 02_daily_trends.csv, 03_models.csv). Every sheet is preserved rather than collapsing to a single table. Each CSV keeps its own headers and UTF-8 encoding, so it opens cleanly in Excel or any spreadsheet tool, and values carry the same readable formatting as the Excel workbook — currency with the $ symbol, percentages as displayed percentages, and dates in ISO format.

Spending Alerts

When you have a daily cost limit configured, the platform sends informational email alerts at 80% and 90% of the limit. See Cost Limits for details.

Cost Analysis

Cost Breakdown

See cost composition:

• By model
• By token type (input vs. output)
• By time period

Real-Time vs. Aggregated

• Real-time: Usage updated within seconds
• Aggregated: Daily totals calculated at midnight UTC

Some displays show real-time, others aggregated. Check timestamps for clarity.

API Reference

Get Current Usage

curl "https://api.bulutistan.ai/api/v1/usage/current" \
  -H "Authorization: Bearer sk-proj-your-api-key"

Query Parameters

Scope Parameter

Control whose usage to retrieve:

Value	Description	Access
user	Your personal usage (default)	All users
tenant	Entire organization's usage	Admin or Owner

Team Usage in the UI

The Usage page has a My Usage / Team Usage toggle at the top. Switching to Team Usage calls scope=tenant under the hood. It's visible to both admins and owners (previously owners received a 403 and the page stayed on My Usage). When Team Usage is active, an Organization Users Usage table appears below the headline metrics, listing each team member with their request count, tokens, cost, share of the organization and status. Time-of-day custom ranges apply to this table too.

# Get organization-wide usage (admin only)
curl "https://api.bulutistan.ai/api/v1/usage/current?scope=tenant" \
  -H "Authorization: Bearer sk-proj-your-api-key"

Format Parameter

Control cost precision in response:

Value	Description	Use Case
display	User-friendly format (default)	UI display
detail	Full precision	Analytics
invoice	2 decimal places	Billing/accounting
raw	8 decimal precision	Internal calculations

# Get usage with invoice-ready cost format
curl "https://api.bulutistan.ai/api/v1/usage/current?format=invoice" \
  -H "Authorization: Bearer sk-proj-your-api-key"

Response Example

{
  "tenant_id": "c63f88b3-cb39-4f07-8353-4982557f7533",
  "period_start": "2024-01-01T00:00:00",
  "period_end": "2024-01-31T23:59:59",
  "total_requests": 1250,
  "successful_requests": 1200,
  "failed_requests": 50,
  "success_rate": 0.96,
  "total_input_tokens": 125000,
  "total_output_tokens": 85000,
  "total_tokens": 210000,
  "average_tokens_per_request": 168.0,
  "total_cost": "45.50000000",
  "average_cost_per_request": "0.036400",
  "average_cost_per_token": "0.000217",
  "total_cost_formatted": "$45.50",
  "average_cost_per_request_formatted": "$0.0364",
  "average_cost_per_token_formatted": "$0.000217",
  "currency": "USD",
  "average_duration_ms": 850.0,
  "models_used": [
    "meta-llama/Llama-3.1-8B-Instruct",
    "BAAI/bge-large-en-v1.5"
  ],
  "top_model": "meta-llama/Llama-3.1-8B-Instruct",
  "models_breakdown": [
    {
      "model_name": "meta-llama/Llama-3.1-8B-Instruct",
      "requests": 1000,
      "input_tokens": 100000,
      "output_tokens": 80000,
      "total_tokens": 180000,
      "total_cost": 35.0,
      "avg_duration_ms": 900.0
    },
    {
      "model_name": "BAAI/bge-large-en-v1.5",
      "requests": 250,
      "input_tokens": 25000,
      "output_tokens": 5000,
      "total_tokens": 30000,
      "total_cost": 10.5,
      "avg_duration_ms": 650.0
    }
  ]
}

Tenant Usage Breakdown (Admin Only)

Get per-user usage within your organization:

curl "https://api.bulutistan.ai/api/v1/usage/tenant-breakdown" \
  -H "Authorization: Bearer sk-proj-your-api-key"

Response:

{
  "tenant_id": "c63f88b3-cb39-4f07-8353-4982557f7533",
  "period": {
    "start_date": "2024-01-01T00:00:00",
    "end_date": "2024-01-31T23:59:59"
  },
  "users": [
    {
      "user_id": "uuid-1",
      "total_requests": 500,
      "input_tokens": 80000,
      "output_tokens": 20000,
      "total_tokens": 100000,
      "total_cost": 20.0,
      "successful_requests": 490,
      "failed_requests": 10
    },
    {
      "user_id": "uuid-2",
      "total_requests": 300,
      "input_tokens": 48000,
      "output_tokens": 12000,
      "total_tokens": 60000,
      "total_cost": 12.0,
      "successful_requests": 298,
      "failed_requests": 2
    }
  ],
  "tenant_total": {
    "total_requests": 800,
    "total_tokens": 160000,
    "total_cost": 32.0
  }
}

Python Example

import requests

api_key = "sk-proj-your-api-key"
base_url = "https://api.bulutistan.ai"

# Get personal usage
response = requests.get(
    f"{base_url}/api/v1/usage/current",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"format": "display"}
)
usage = response.json()
print(f"Total cost: {usage['total_cost_formatted']}")
print(f"Total tokens: {usage['total_tokens']}")
print(f"Top model: {usage['top_model']}")

# Get team breakdown (tenant admin only)
response = requests.get(
    f"{base_url}/api/v1/usage/tenant-breakdown",
    headers={"Authorization": f"Bearer {api_key}"}
)
if response.status_code == 200:
    breakdown = response.json()
    for user in breakdown["users"]:
        print(f"User {user['user_id']}: ${user['total_cost']}")