RevKeenDocs
StatusSupport
API Reference
📊 Usage BillingUsage Events

Query usage events

List usage events with optional filters. Returns up to 100 events per request.

GET/usage-events

List usage events with optional filters. Returns up to 100 events per request.

Related endpoints

  • POST /usage-events — Ingest usage events
  • GET /usage-events/{id} — Get a usage event

Common errors

  • 401 authentication_error — missing, invalid, expired, or revoked credential. Codes: authentication_failed, invalid_api_key, expired_api_key, api_key_revoked, session_invalid, merchant_required. Carries a WWW-Authenticate: Bearer challenge.

Pagination

Offset-based with limit (default 25, max 100) and offset. The response pagination block includes total and hasMore. See the pagination guide for SDK auto-paging helpers.

Authorization

apiKey
x-api-key<token>

Your RevKeen merchant API key. Create and manage keys in Dashboard → Settings → Developer. Use rk_sandbox_* for staging/test and rk_live_* for production. The same key may be sent as Authorization: Bearer <key> if that suits your HTTP client better. A missing, invalid, expired, or revoked key returns 401 with a WWW-Authenticate: Bearer challenge; a valid key without the required scope returns 403.

In: header

Query Parameters

meter_id?string

Filter by meter ID

customer_id?string

Filter by customer ID

external_customer_id?string

Filter by external customer ID

subscription_id?string

Filter by subscription ID

start_time?string

Start of time range (ISO 8601)

Formatdate-time
end_time?string

End of time range (ISO 8601)

Formatdate-time
limit?string

Max results (default 100, max 100)

Response Body

application/json

application/json

application/json

Stuck on an error response? Ask the RevKeen assistant to explain it.
curl -X GET "https://api.revkeen.com/v2/usage-events?meter_id=meter_xxx&customer_id=cus_1RxKm3ApBqCrDsEtFuGvHwJx" \
  -H "x-api-key: $REVKEEN_API_KEY"

Synthetic documentation data, validated against the response schema; not a live API result.

{  "object": "list",  "data": [    {      "id": "8d9e0f1a-2b3c-4641-9e5f-6a7b8c9d0e12",      "merchant_id": "8f14e45f-ceea-4e7a-9b4b-7c3f1a2d5e60",      "customer_id": "c2a1e7d4-5b3f-4a8e-9d21-6f0b3e4c7a11",      "subscription_id": "d4e6f8a1-2b3c-4d5e-9f60-7a8b9c0d1e24",      "meter_id": "7c8d9e0f-1a2b-4630-8d4e-5f6a7b8c9d01",      "name": "api_call",      "event_name": "api_call",      "quantity": 1,      "event_time": "2026-04-18T09:15:00.000Z",      "idempotency_key": "api_call_req_000123",      "external_id": null,      "source": "api",      "metadata": {},      "properties": {        "endpoint": "/engines/difference"      },      "ingestion_timestamp": "2026-04-18T09:15:01.000Z",      "created_at": "2026-04-18T09:15:01.000Z"    }  ],  "has_more": true}

Put this endpoint to work

Configure usage billing