Usage & invoicing

Every request through qlaud lands one row in our usage_events table:

Column	What
`id`	Unique request ID (UUID, propagated to upstream)
`key_id`	Which `qlk_live_…` was used
`user_id`	The qlaud account (you)
`model_slug`	Customer-facing model id (e.g. `claude-sonnet-4-6`)
`provider_slug`	Where it actually routed (e.g. `anthropic`)
`input_tokens`, `output_tokens`	From upstream `usage` field
`cost_micros`	What we charged you (input × in_price + output × out_price, with 7% markup)
`latency_ms`	End-to-end including upstream
`status`	HTTP status code
`created_at`	Server 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",
    )

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

for (const k of usage.by_key) {
  const user = await lookupByKeyId(k.key_id);
  await stripe.invoiceItems.create({
    customer: user.stripeCustomerId,
    amount: Math.round(k.cost_micros / 100),    // micro-dollars → cents
    currency: 'usd',
    description: `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.

Get started

Tutorials

Concepts

Integrations

Usage & invoicing

`GET /v1/usage` — rollup

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

Pricing & markup

Invoicing pattern (Stripe)

​GET /v1/usage — rollup

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

​Pricing & markup

​Invoicing pattern (Stripe)

`GET /v1/usage` — rollup

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

Pricing & markup

Invoicing pattern (Stripe)