> ## Documentation Index > Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt > Use this file to discover all available pages before exploring further. # Per-request usage event stream > Stream individual billed requests via GET /v1/usage/events — one row per billed call, the raw data underlying /v1/usage. `GET /v1/usage` returns aggregated buckets — `total_credits`, `total_input_tokens`, etc. summed over a window. When you need event-level granularity (one row per billed request, e.g. for FinOps reconciliation against per-call receipts), use `GET /v1/usage/events` instead. ## Shape ```bash theme={null} curl 'https://api.aurous-labs.com/v1/usage/events?start_time=2026-05-20T00:00:00Z&end_time=2026-05-20T10:00:00Z&limit=50' \ -H "X-Api-Key: $AUROUS_API_KEY" ``` ```json theme={null} { "object": "list", "data": [ { "id": "cmp_01HXMQ7Z3K8Y2ABCDEFGHJKM", "type": "chat", "model": "aurous-grow-2.0-pro", "status": "completed", "created_at": "2026-05-20T08:14:23.491Z", "completed_at": "2026-05-20T08:14:25.137Z", "duration_ms": 1646, "input_tokens": 247, "output_tokens": 103, "credits_charged": 0.0291, "api_key_id": "apikey_01HXMQ7Z3KCDEFGHJKM23ABCDEFGH", "user_id": "uuid-of-the-caller-user", "request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKMZQXVN" }, { "id": "emb_01HXMQ7Z3K8Y2ABCDEFGHJKM", "type": "embedding", "model": "aurous-embed-vision-1.0", "status": "completed", "created_at": "2026-05-20T08:13:50.221Z", "completed_at": "2026-05-20T08:13:50.987Z", "duration_ms": 766, "input_tokens": 412, "output_tokens": 0, "credits_charged": 0.00077, "api_key_id": "apikey_01HXMQ7Z3KCDEFGHJKM23ABCDEFGH", "user_id": "uuid-of-the-caller-user", "request_id": "req_01HXMQ7Z3K8YJKMZQXVNCDEFGHABC" } ], "has_more": true, "next_cursor": "MDFIWE1RN1ozSzhZMkFCQ0RFRkdISktN..." } ``` Each row has the `id` from the original resource (`cmp_*` for chat, `emb_*` for embedding, `img_*` for image, `vid_*` for video), the type, the token counts, the credit charge, and pointers back to the API key + user. ## Query parameters ### Required * **`start_time`** (RFC 3339) — inclusive lower bound. Maximum lookback: 730 days. * **`end_time`** (RFC 3339) — exclusive upper bound; defaults to `now`. ### Filters * **`type`** — `chat` / `embedding` / `image` / `video` (comma-separated for multi-value) * **`status`** — `completed` / `failed` / `cancelled` / `processing` / `pending` * **`model`** — slug or comma-separated multi-value * **`api_key_id`** — `apikey_` * **`user_id`** — uuid * **`lora_id`** — `lora_` (image/video rows only) ### Pagination * **`limit`** — rows per page (default 100, max 500) * **`cursor`** — opaque forward-only cursor The cursor is short-lived and event-stream-specific (different from the `/v1/usage` page\_token). It encodes a `(created_at, id)` tuple — rows are returned in descending `created_at` order, ties broken by `id` ascending. ## Use cases ### Per-call audit against your ledger ```python theme={null} import requests # Pull every billed call from the last hour, reconcile against your billing ledger events = requests.get( "https://api.aurous-labs.com/v1/usage/events", params={"start_time": "2026-05-20T09:00:00Z", "end_time": "2026-05-20T10:00:00Z", "limit": 500}, headers={"X-Api-Key": "al_live_xxxxxxxxxxxxxxxx"}, ).json() for e in events["data"]: expected = your_ledger.find_by_request_id(e["request_id"]) if expected and abs(expected.credits - e["credits_charged"]) > 0.0001: print(f"DRIFT on {e['id']}: ledger {expected.credits} vs platform {e['credits_charged']}") ``` The `request_id` on each event matches the `Aurous-Request-Id` header you got on the original response — that's the canonical identifier for cross-system reconciliation. ### FinOps cost attribution `api_key_id` lets you attribute spend to a particular integration or environment (mint a separate API key per workload), and `user_id` tracks which team member kicked off the call (when calls go via the dashboard or a per-user-token integration). ### Replaying a window into your own analytics For long windows (multiple days), iterate the cursor and stream rows into your warehouse: ```python theme={null} import requests cursor = None while True: params = {"start_time": "2026-05-01T00:00:00Z", "end_time": "2026-05-20T00:00:00Z", "limit": 500} if cursor: params["cursor"] = cursor res = requests.get( "https://api.aurous-labs.com/v1/usage/events", params=params, headers={"X-Api-Key": "al_live_xxxxxxxxxxxxxxxx"}, ).json() for row in res["data"]: warehouse.insert(row) # your sink if not res.get("has_more") or not res.get("next_cursor"): break cursor = res["next_cursor"] ``` For sustained ingest, prefer [webhooks](/webhooks) — we POST a signed event the moment each row reaches a terminal status, so you don't have to poll. ## `/v1/usage/events` vs `/v1/usage` — when to pick which | Question | `/v1/usage` | `/v1/usage/events` | | ------------------------------- | ---------------------------- | ----------------------------------------- | | Total spend on chat last week? | ✅ aggregate sum | ❌ would have to sum | | Which call cost \$50? | ❌ no per-call | ✅ per-row charge | | Daily chart for the dashboard? | ✅ pre-bucketed | ❌ aggregate client-side | | Reconcile to my billing ledger? | ⚠️ aggregate only | ✅ row-by-row | | Audit a specific request\_id? | ❌ | ✅ filter by request\_id (via cursor walk) | | Compute p95 latency last hour? | ✅ duration\_ms\_p95 baked in | ⚠️ compute client-side | In short: `/v1/usage` is the **dashboard** view; `/v1/usage/events` is the **ledger** view. ## Where to next? * [Usage overview](/api-reference/usage/overview) — aggregated usage queries * [Usage pagination](/api-reference/usage/pagination) — cursor walk pattern * [Cost transparency](/guides/cost-transparency) — receipt math reconciliation * [Webhooks](/webhooks) — push-based event ingest as an alternative to polling * [`GET /v1/usage/events`](/api-reference/openapi#tag/account) — endpoint reference