RevKeen Docs
Api reference

Ingest usage events

Send usage events for billing. Accepts a single event or a batch of up to 1000 events.

Single event: Send the event object directly in the request body. Batch: Wrap events in an events array.

Events are matched to meters by name (event name) or meter_id. At least one of customer_id, external_customer_id, or subscription_id is required.

Related endpoints

  • GET /usage-events — Query usage events
  • POST /usage-events/dry-run — Dry-run usage events
  • GET /usage-events/aggregate/{meterId} — Get aggregated usage

Common errors

  • 400 invalid_request — malformed payload or failed validation.
  • 401 unauthenticated — missing, malformed, or revoked API key.

Idempotency

Pass an Idempotency-Key header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see the idempotency guide.

POST
/usage-events

Authorization

apiKey
x-api-key<token>

Your RevKeen API key (powered by Unkey). Get it from Dashboard > Settings > API Keys. Use rk_sandbox_* for test mode and rk_live_* for production.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.revkeen.com/v2/usage-events" \  -H "x-api-key: $REVKEEN_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "name": null,        "customer_id": null,        "external_customer_id": null,        "subscription_id": null,        "meter_id": null,        "quantity": null,        "timestamp": null,        "idempotency_key": null,        "metadata": null      }    ]  }'
{
  "object": "usage_event_batch_result",
  "summary": {
    "ingested": 0,
    "duplicate": 0,
    "skipped": 0,
    "failed": 0
  },
  "data": [
    {
      "index": 0,
      "status": "ingested",
      "id": "string",
      "reason": "string"
    }
  ]
}
{
  "object": "usage_event_batch_result",
  "summary": {
    "ingested": 0,
    "duplicate": 0,
    "skipped": 0,
    "failed": 0
  },
  "data": [
    {
      "index": 0,
      "status": "ingested",
      "id": "string",
      "reason": "string"
    }
  ]
}
{
  "object": "usage_event_batch_result",
  "summary": {
    "ingested": 0,
    "duplicate": 0,
    "skipped": 0,
    "failed": 0
  },
  "data": [
    {
      "index": 0,
      "status": "ingested",
      "id": "string",
      "reason": "string"
    }
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
Edit on GitHub