Live end-to-end demo
Every request and response on this page was run against the live API (https://usage-lab.marc-cf2.workers.dev) on October 13, 2026 with a demo account. Nothing is mocked. The API key is shown as $USAGE_LAB_KEY.
What it shows: 1,250 + 830 tokens recorded, a retry that is not counted twice ("duplicate": true), a monthly total of 2,080 tokens, and 3 active-user events that count as 2 unique users.
0. Get an API key
Keys are issued by us during early access (no self-serve signup yet). The admin call returned:
{
"tenant": {
"id": "ten_77c7c7f736ba40f5bc5cb3b2a4f3c41e",
"name": "demo"
},
"api_key": {
"id": "key_6f342fcaf44e4870adb9a32bb0452a59",
"secret": "$USAGE_LAB_KEY",
"note": "Shown once. Store it now."
}
}The flow
1. Create the sum meter
curl -X POST https://usage-lab.marc-cf2.workers.dev/api/v1/meters \
-H "Authorization: Bearer $USAGE_LAB_KEY" -H "Content-Type: application/json" \
-d '{"key":"llm_tokens","name":"LLM tokens","aggregation":"sum","stripe_event_name":"llm_tokens"}'Response: HTTP 201
{
"meter": {
"id": "mtr_87b152c48fbc416eb2e2305708a4fcf9",
"key": "llm_tokens",
"name": "LLM tokens",
"aggregation": "sum",
"stripe_event_name": "llm_tokens",
"created_at": "2026-10-14T02:27:28.171Z"
}
}2. Create the unique-count meter
curl -X POST https://usage-lab.marc-cf2.workers.dev/api/v1/meters \
-H "Authorization: Bearer $USAGE_LAB_KEY" -H "Content-Type: application/json" \
-d '{"key":"active_users","name":"Active users","aggregation":"unique_count"}'Response: HTTP 201
{
"meter": {
"id": "mtr_2013e897a663487f8afde89e300f6c5a",
"key": "active_users",
"name": "Active users",
"aggregation": "unique_count",
"stripe_event_name": null,
"created_at": "2026-10-14T02:27:28.335Z"
}
}3. Record one event (1,250 tokens)
curl -X POST https://usage-lab.marc-cf2.workers.dev/api/v1/usage \
-H "Authorization: Bearer $USAGE_LAB_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: chatcmpl-demo-001" \
-d '{"meter":"llm_tokens","subscription":"cus_demo_acme","value":1250}'Response: HTTP 201
{
"event": {
"status": "created",
"id": "evt_7588d40f45fd4df193fe091d4b883b91",
"idempotency_key": "chatcmpl-demo-001",
"meter": "llm_tokens",
"month": "2026-10"
},
"duplicate": false
}4. Retry the exact same request (network blip)
# identical request, same Idempotency-Key
curl -X POST https://usage-lab.marc-cf2.workers.dev/api/v1/usage \
-H "Authorization: Bearer $USAGE_LAB_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: chatcmpl-demo-001" \
-d '{"meter":"llm_tokens","subscription":"cus_demo_acme","value":1250}'Response: HTTP 200
{
"event": {
"status": "duplicate",
"id": "evt_7588d40f45fd4df193fe091d4b883b91",
"idempotency_key": "chatcmpl-demo-001",
"meter": "llm_tokens",
"month": "2026-10"
},
"duplicate": true
}5. Post a batch: 830 more tokens, plus user_42, user_7 and user_42 again
curl -X POST https://usage-lab.marc-cf2.workers.dev/api/v1/usage \
-H "Authorization: Bearer $USAGE_LAB_KEY" -H "Content-Type: application/json" \
-d '{"events":[
{"meter":"llm_tokens","subscription":"cus_demo_acme","value":830,"idempotency_key":"chatcmpl-demo-002"},
{"meter":"active_users","subscription":"cus_demo_acme","unique_value":"user_42","idempotency_key":"au-demo-user_42"},
{"meter":"active_users","subscription":"cus_demo_acme","unique_value":"user_7","idempotency_key":"au-demo-user_7"},
{"meter":"active_users","subscription":"cus_demo_acme","unique_value":"user_42","idempotency_key":"au-demo-user_42-b"}]}'Response: HTTP 200
{
"results": [
{
"status": "created",
"id": "evt_f8a12423a25742df80f05a295f946a29",
"idempotency_key": "chatcmpl-demo-002",
"meter": "llm_tokens",
"month": "2026-10"
},
{
"status": "created",
"id": "evt_536297ab120749c69ba91f3632cccf82",
"idempotency_key": "au-demo-user_42",
"meter": "active_users",
"month": "2026-10"
},
{
"status": "created",
"id": "evt_e3e162bab54646d7a062d69850c53808",
"idempotency_key": "au-demo-user_7",
"meter": "active_users",
"month": "2026-10"
},
{
"status": "created",
"id": "evt_b5c869f2d37b4f3fbaecd69a55ec70f0",
"idempotency_key": "au-demo-user_42-b",
"meter": "active_users",
"month": "2026-10"
}
],
"summary": {
"created": 4,
"duplicate": 0,
"conflict": 0
}
}6. Monthly rollup: llm_tokens
curl "https://usage-lab.marc-cf2.workers.dev/api/v1/meters/llm_tokens/rollups?month=2026-10" \
-H "Authorization: Bearer $USAGE_LAB_KEY"Response: HTTP 200
{
"meter": {
"id": "mtr_87b152c48fbc416eb2e2305708a4fcf9",
"key": "llm_tokens",
"name": "LLM tokens",
"aggregation": "sum",
"stripe_event_name": "llm_tokens",
"created_at": "2026-10-14T02:27:28.171Z"
},
"month": "2026-10",
"computed_at": "2026-10-14T02:27:29.231Z",
"total_quantity": 2080,
"rollups": [
{
"subscription": "cus_demo_acme",
"quantity": 2080,
"event_count": 2,
"exported_quantity": 0,
"pending_export_quantity": 2080,
"exported_at": null
}
]
}7. Monthly rollup: active_users
curl "https://usage-lab.marc-cf2.workers.dev/api/v1/meters/active_users/rollups?month=2026-10" \
-H "Authorization: Bearer $USAGE_LAB_KEY"Response: HTTP 200
{
"meter": {
"id": "mtr_2013e897a663487f8afde89e300f6c5a",
"key": "active_users",
"name": "Active users",
"aggregation": "unique_count",
"stripe_event_name": null,
"created_at": "2026-10-14T02:27:28.335Z"
},
"month": "2026-10",
"computed_at": "2026-10-14T02:27:29.498Z",
"total_quantity": 2,
"rollups": [
{
"subscription": "cus_demo_acme",
"quantity": 2,
"event_count": 3,
"exported_quantity": 0,
"pending_export_quantity": 2,
"exported_at": null
}
]
}8. Stripe export (dry run)
curl -X POST "https://usage-lab.marc-cf2.workers.dev/api/v1/meters/llm_tokens/rollups/export?month=2026-10" \
-H "Authorization: Bearer $USAGE_LAB_KEY"Response: HTTP 200
{
"meter": "llm_tokens",
"month": "2026-10",
"mode": "dry_run",
"planned": [
{
"subscription": "cus_demo_acme",
"delta": 2080,
"request": {
"method": "POST",
"url": "https://api.stripe.com/v1/billing/meter_events",
"form": {
"event_name": "llm_tokens",
"payload[stripe_customer_id]": "cus_demo_acme",
"payload[value]": "2080",
"identifier": "ul:mtr_87b152c48fbc416eb2e2305708a4fcf9:cus_demo_acme:2026-10:0-2080",
"timestamp": "1791944849"
}
}
}
],
"pushed": []
}Stripe invoice step is dry-run until the test Billing Meter is connected; this is the exact quantity it will send.
The export above made no call to Stripe. It shows the planned Stripe Billing Meter event: event_name=llm_tokens, payload[value]=2080 for cus_demo_acme, with a deterministic identifier so a repeated push is deduped. pushed is empty and exported_quantity stays 0 until a real push succeeds. No Stripe invoice has been created by this demo.