Skip to main content
Every request through qlaud lands one row in our usage_events table:
ColumnWhat
idUnique request ID (UUID, propagated to upstream)
key_idWhich qlk_live_… was used
user_idThe qlaud account (you)
model_slugCustomer-facing model id (e.g. claude-sonnet-4-6)
provider_slugWhere it actually routed (e.g. anthropic)
input_tokens, output_tokensFrom upstream usage field
cost_microsWhat we charged you (input × in_price + output × out_price, with 7% markup)
latency_msEnd-to-end including upstream
statusHTTP status code
created_atServer time
You read this back via two endpoints.

​
GET /v1/usage — rollup

Default window: month-to-date. Override with from_ms / to_ms. 
curl https://api.qlaud.ai/v1/usage -H "x-api-key: $QLAUD_MASTER_KEY"

{
  "from_ms": 1746124800000,
  "to_ms": 1746518400000,
  "total_cost_micros": 7340000,
  "total_input_tokens": 142000,
  "total_output_tokens": 68000,
  "request_count": 312,
  "by_key": [
    {
      "key_id": "0e2c3a91-...",
      "key_name": "user_42",
      "key_prefix": "qlk_live_abcd…wxyz",
      "cost_micros": 2347000,
      "request_count": 84,
      ...
    },
    ...
  ],
  "by_model": [
    { "model_slug": "claude-sonnet-4-6", "cost_micros": 4900000, ... },
    ...
  ]
}

​
GET /v1/keys/:keyId/usage — drilldown

Single key. Includes the 100 most recent events. 
curl https://api.qlaud.ai/v1/keys/<key_id>/usage \
  -H "x-api-key: $QLAUD_MASTER_KEY"
Use this for a per-user usage page in your app — show the user their last N requests, current spend, cap.

​
Pricing & markup

The catalog has the customer-facing price for every model (qlaud.ai/models). Those prices already include our flat 7% markup on top of upstream cost. So cost_micros is what you owe us. Bill your end-users anything you want on top — the difference is your margin.

​
Invoicing pattern (Stripe)

End of month, pull /v1/usage, fold each by_key row into a Stripe InvoiceItem: 
for k in usage["by_key"]:
    user = lookup_by_key_id(k["key_id"])
    stripe.InvoiceItem.create(
        customer=user.stripe_customer_id,
        amount=int(k["cost_micros"] / 100),  # micro-dollars → cents
        currency="usd",
        description=f"AI usage — {k['request_count']} requests",
    )
Stripe rolls all open InvoiceItems into the customer’s next invoice. Set their subscription’s billing cycle to monthly and you’re done. See the full walkthrough in Per-user billing.