Subscriber Usage Meter API

Reference material for managing subscriber usage meter thresholds and monitoring monthly combined data usage.

Overview

The Usage Meter API allows administrators to:

Set a monthly combined usage trigger threshold (KB) for a subscriber
Monitor when subscribers reach their configured threshold
Trigger webhooks when threshold is exceeded
Reset usage meter trigger state for a subscriber

Usage meters track monthly combined data usage (downloads + uploads in KB) on a per-subscriber basis. When a subscriber's monthly usage reaches or exceeds the configured trigger threshold, a subscriber-usage-meter-triggered webhook is fired once per monthly cycle.

Monthly cycles reset automatically on the first day of each month (based on the subscriber's timezone).

API Endpoints

GET

/v1/usage-meter/{subscriber_id}

(subscriber)

Get Current Usage Meter.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
subscriber_id	url	string	Unique subscriber ID.	X

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
monthly_combined_kb	body	integer	Current monthly combined usage in kilobytes (downloads + uploads).
monthly_combined_trigger_kb	body	integer	Configured trigger threshold in kilobytes.
monthly_combined_triggered	body	boolean	Flag indicating whether the threshold has been triggered this month.
monthly_month	body	string	Current month in YYYY-MM format (e.g., 2025-01).
subscriber_id	body	string	Unique subscriber ID.

Response Example

{
    "subscriber_id": "00034ae6-4d79-11ef-80c4-174adb24f2cd",
    "monthly_combined_kb": 524288,
    "monthly_month": "2025-01",
    "monthly_combined_trigger_kb": 1048576,
    "monthly_combined_triggered": false
}

POST

/v1/usage-meter/{subscriber_id}

(subscriber)

Set Usage Meter Threshold.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
subscriber_id	url	string	Unique subscriber ID.	X
monthly_combined_trigger_kb	body	integer	Monthly combined usage trigger threshold in kilobytes. Must be a non-negative integer. Set to 0 to stop receiving usage-meter threshold webhooks.	X

Request Example

{
    "monthly_combined_trigger_kb": 1048576
}

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Response Properties

Name	In	Type	Description
monthly_combined_kb	body	integer	Current monthly combined usage in kilobytes (downloads + uploads).
monthly_combined_trigger_kb	body	integer	Configured trigger threshold in kilobytes.
monthly_combined_triggered	body	boolean	Flag indicating whether the threshold has been triggered this month.
monthly_month	body	string	Current month in YYYY-MM format (e.g., 2025-01).
subscriber_id	body	string	Unique subscriber ID.

Response Example

{
    "subscriber_id": "00034ae6-4d79-11ef-80c4-174adb24f2cd",
    "monthly_combined_kb": 524288,
    "monthly_month": "2025-01",
    "monthly_combined_trigger_kb": 1048576,
    "monthly_combined_triggered": false
}

DELETE

/v1/usage-meter/{subscriber_id}

(subscriber)

Reset Usage Meter Trigger State.

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber Administrator

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Tenant-ID	header	string	Request Tenant Context.
subscriber_id	url	string	Unique subscriber ID.	X

Response Status Codes

Code	Meaning
200	OK
400	Bad Request
401	Unauthorized / Require Authentication
403	Forbidden / Access Denied
404	Not Found
409	Conflict
429	Too Many Requests / Your Rate Limited
500, 501, 502, 503, 504	Service Unavailable

Request/Response Examples

See usage_meter.api.yaml for complete request/response examples for all endpoints.

How It Works

Setting a Threshold: Use POST to /v1/usage-meter/{subscriber_id} to set monthly_combined_trigger_kb (in kilobytes). When a subscriber's monthly usage reaches this value, the trigger is activated.

To stop receiving usage-meter threshold webhooks, set monthly_combined_trigger_kb to 0 using POST.
Monthly Cycle: Each month (based on subscriber timezone), the usage counters reset automatically and the trigger flag resets to allow retrieval on first threshold breach.
Webhook Trigger: When monthly_combined_kb >= monthly_combined_trigger_kb, the system fires a subscriber-usage-meter-triggered webhook containing: - Subscriber details - monthly_combined_kb: Total usage in KB for the current month - monthly_month: The current billing month (YYYY-MM) - monthly_combined_trigger_kb: The configured threshold in KB
Resetting Trigger State: Use DELETE to reset usage-meter trigger state for the subscriber.