Report Usage

Last updated: Phase 8.5

Record a usage event for a metered entitlement.

Endpoint

POST /api/v1/integration/usage/record

Headers

Header	Required	Value
X-API-Key	Yes	Your API key
Content-Type	Yes	application/json

Request Body

{
  "license_key": "VX-ACME-abc123def456",
  "metric": "api.calls",
  "quantity": 150,
  "metadata": {
    "endpoint": "/v1/search",
    "period": "hourly"
  }
}

Field	Required	Type	Description
license_key	Yes	string	The license key
metric	Yes	string	Entitlement code / metric name
quantity	Yes	integer	Usage amount (min: 1)
metadata	No	object	Additional context

Response (202 Accepted)

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

Note: HTTP 202 indicates the event was accepted. The recorded: true field confirms persistence.

Error Responses

Code	HTTP	Description
LICENSE.NOT_FOUND	404	License key not found
AUTH.INVALID_API_KEY	401	Invalid API key
RATE_LIMIT.EXCEEDED	429	Rate limit exceeded

Notes

• Usage events are stored in the tenant's isolated database
• Metadata includes license_key_id and source: "integration_api" automatically
• Usage events are immutable — they cannot be edited or deleted
• Use the Tenant Dashboard to view usage snapshots and reports