𝐙𝐀𝐈

Usage API

Usage API

The Usage API provides live and historical usage for the current account, plus aggregate usage, details, and rankings for descendant accounts.

export BASE_URL="https://api.zairouter.com"
export API_KEY="sk-Xvs..."

Endpoints

Method and pathScopeDescription
GET /dashboard/liveCurrent accountLive totals for the day and month
GET /dashboard/billCurrent accountTrends and model details by date
GET /x-billDescendant accountsAggregate trends, model details, and account ranking

All endpoints require:

Authorization: Bearer sk-Xvs...

Current-account live usage

curl "$BASE_URL/dashboard/live" \
  -H "Authorization: Bearer $API_KEY"

In addition to account information, the response provides:

FieldDescription
daily_usageLive total for the current day
monthly_usageLive total for the current month
RequestsRequest count
PromptInput tokens
CompletionOutput tokens
ReasoningReasoning tokens
CreditUsedCredits used
ModelUsageRequests, tokens, and credits grouped by model

Use this endpoint for dashboard polling. Use /dashboard/bill for historical trends.

Current-account historical usage

GET /dashboard/bill
GET /dashboard/bill?date=2026-07-18
GET /dashboard/bill?start=2026-07-01&end=2026-07-18
GET /dashboard/bill?days=7

With no parameters, the endpoint returns usage for the current day.

ParameterDescription
dateOne day in YYYY-MM-DD format
start / endInclusive date range
daysA recent time window
curl "$BASE_URL/dashboard/bill?start=2026-07-01&end=2026-07-18" \
  -H "Authorization: Bearer $API_KEY"

Descendant-account usage

/x-bill reports descendants below the current account and does not include the current account itself. The caller must have account-management access.

GET /x-bill
GET /x-bill?date=2026-07-18
GET /x-bill?start=2026-07-01&end=2026-07-18
GET /x-bill?days=7
GET /x-bill?user=42&days=30

With no date parameters, the endpoint returns the current day. user accepts an account ID, name, or email. When omitted, usage is aggregated across all descendants.

curl "$BASE_URL/x-bill?start=2026-07-01&end=2026-07-18" \
  -H "Authorization: Bearer $API_KEY"

Aggregate response

/dashboard/bill and /x-bill share the same core usage structure:

FieldDescription
daily_costsDaily usage; line_items break each day down by model
usage_summaryPer-model totals across the full range
total_requestsTotal requests
total_promptTotal input tokens
total_completionTotal output tokens
total_reasoningTotal reasoning tokens
total_credit_usedTotal credits used
token_summaryCached, uncached input, and output token totals

Simplified response:

{
  "object": "bill_info",
  "daily_costs": [
    {
      "date": "2026-07-18",
      "total_requests": 24,
      "total_prompt": 18200,
      "total_completion": 3600,
      "total_credit_used": 1.42,
      "line_items": [
        {"name": "gpt-5-nano", "cost": 1.42, "usage": {}}
      ]
    }
  ],
  "usage_summary": {"gpt-5-nano": {}},
  "total_requests": 24,
  "total_prompt": 18200,
  "total_completion": 3600,
  "total_reasoning": 0,
  "total_credit_used": 1.42,
  "token_summary": {
    "input_total": 18200,
    "output_total": 3600,
    "processed_total": 21800
  }
}

Descendant ranking

/x-bill adds usage_users to the core statistics and sorts entries by credits used, descending:

FieldDescription
id, name, alias, emailAccount identity
top_cost_modelModel with the highest credit usage
top_request_modelModel with the most requests
total_requestsRequests made by this account
total_prompt, total_completion, total_reasoningToken usage for this account
total_credit_usedCredits used by this account
usage_analysis.request_percentageShare of all descendant requests
usage_analysis.cost_percentageShare of all descendant credit usage
{
  "usage_users": [
    {
      "id": 42,
      "name": "developer-a",
      "alias": "Engineering A",
      "email": "[email protected]",
      "top_cost_model": "gpt-5",
      "top_request_model": "gpt-5-nano",
      "total_requests": 50,
      "total_prompt": 42000,
      "total_completion": 8000,
      "total_reasoning": 0,
      "total_credit_used": 3.52,
      "usage_analysis": {
        "request_percentage": 62.5,
        "cost_percentage": 61.97
      }
    }
  ]
}

Accounts with no requests are omitted from usage_users.

Choose an endpoint

  • Current balance plus live daily and monthly totals: /dashboard/live
  • Current-account usage for a day, date range, or model breakdown: /dashboard/bill
  • Overall usage and ranking for all descendants: /x-bill
← Access Control (ACL)
ZAI Control →