> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlaud.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage & invoicing

> How qlaud records every request, surfaces it per-key, and lets you bill end-users at month-end.

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`.

```bash theme={null}
curl https://api.qlaud.ai/v1/usage -H "x-api-key: $QLAUD_MASTER_KEY"
```

```json theme={null}
{
  "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.

```bash theme={null}
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](https://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`:

<CodeGroup>
  ```python Python theme={null}
  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",
      )
  ```

  ```typescript TypeScript theme={null}
  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`,
    });
  }
  ```
</CodeGroup>

Stripe rolls all open `InvoiceItem`s 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](/per-user-billing).