Quickstart: Report Usage (5 minutes)

Last updated: Phase 8.5

Prerequisites

• A ValidonX API key
• A valid license key
• A metric name (entitlement code)

Step 1: Record a Usage Event

curl -X POST https://api.validonx.com/api/v1/integration/usage/record \
  -H "X-API-Key: vx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "license_key": "YOUR-LICENSE-KEY",
    "metric": "api.calls",
    "quantity": 100,
    "metadata": {"endpoint": "/v1/search"}
  }'

Step 2: Confirm the Response

Success (202 Accepted):

{
  "data": {
    "recorded": true,
    "usage_event": {
      "id": 1,
      "entitlement_code": "api.calls",
      "quantity": 100,
      "recorded_at": "2026-03-30T10:30:00.000000Z"
    }
  },
  "meta": { "request_id": "uuid", "api_version": "1" }
}

Step 3: Batch Your Reports

For efficiency, batch usage reports rather than sending one per API call:

// Instead of reporting every call individually:
await reportUsage({ metric: 'api.calls', quantity: 1 })  // Don't do this

// Batch and report periodically:
let callCount = 0
setInterval(async () => {
  if (callCount > 0) {
    await reportUsage({ metric: 'api.calls', quantity: callCount })
    callCount = 0
  }
}, 60_000)  // Every 60 seconds

Common Errors

Code	Meaning	Fix
LICENSE.NOT_FOUND	Bad license key	Verify the key
AUTH.INVALID_API_KEY	Bad API key	Check header
RATE_LIMIT.EXCEEDED	Too many requests	Batch your reports