Skip to main content
POST
/
report
/
usage
Report pre-aggregated usage
curl --request POST \
  --url https://api.kelviq.com/api/v1/report/usage/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "value": 150,
  "customerId": "customer_001",
  "featureId": "seats",
  "behaviour": "SET"
}
'
{
  "value": 150,
  "customerId": "customer_001",
  "featureId": "seats",
  "behaviour": "SET",
  "orgId": "1",
  "eventName": "aggregated.usage",
  "idempotencyKey": "597ee95063c744ed9bcc9b1cf5676a8a",
  "timestamp": "2025-05-22 08:27:45.430732"
}

Authorizations

​
Authorization
string
header
required

The Server API Key obtained from the kelviq application. Pass as a Bearer token in the Authorization header. Example: 'Authorization: Bearer YOUR_API_KEY'

Body

application/json
​
value
integer
required

The usage value being reported.

Example:

150

​
customerId
string
required

Unique identifier for the customer associated with this usage.

Example:

"customer_001"

​
featureId
string
required

Unique identifier for the feature for which usage is being reported.

Example:

"seats"

​
behaviour
enum<string>
required

Dictates how the usage is updated. SET replaces, DELTA increments.

Available options:
SET,
DELTA
Example:

"SET"

Response

200 - application/json

Usage reported successfully.

​
value
integer
Example:

150

​
customerId
string
Example:

"customer_001"

​
featureId
string
Example:

"seats"

​
behaviour
enum<string>
Available options:
SET,
DELTA
Example:

"SET"

​
orgId
string
Example:

"1"

​
eventName
string

Internal event name (e.g., "aggregated.usage").

Example:

"aggregated.usage"

​
idempotencyKey
string

Server-generated unique idempotency key for this usage report instance.

Example:

"597ee95063c744ed9bcc9b1cf5676a8a"

​
timestamp
string

Server-generated UTC timestamp (e.g., yyyy-MM-dd HH:mm:ss.ffffff) when the report was processed.

Example:

"2025-05-22 08:27:45.430732"