Subscriber Telemetry API

Subscriber Counts

GET

/v1/subscribers/count

(subscriber)

Subscriber Current Total Count

Service
subscriber

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber View

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)

Response Status Codes

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

Response Properties

Name	In	Type	Description
count	body	integer	Total current subscribers in domain.

Response Example

{
    "count": 9999
}

Data Usage

The following API definitions describe how to perform data usage queries. These queries are restricted. Please refer to Subscriber Telemetry documentation for more information relating their use.

Query Restrictions:

Resolution / Aggregation.	Max time range.	Available Data.
Hourly	128 days.	5 years.
Daily	128 days.	5 years.
Weekly	114 weeks.	5 years.
Monthly	60 months.	5 years.
Yearly	5 years.	5 years.

All data usage records are available in all timezones.

POST

/v1/subscriber/{subscriber_id}/data/{aggregation}

(telemetry)

Subscriber Account data usage.

Service
telemetry

Accepted Roles (RBAC)

AdministratorCustomerNetwork OperationsStaff MemberSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber ViewSupport

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
aggregation	url	string	hourly, daily, weekly, monthly or yearly.	X
subscriber_id	url	string	Unique Subscriber ID.	X
end	body	string	End Report Date Time in ISO 8601.	X
pretty_date	body	boolean	The default time format in response is ISO 8601. Setting this to true will format it as a user-friendly format that can be used for graphs, for example.
start	body	string	Start Report Date Time in ISO 8601.	X

Request Example

{
    "start": "2024-05-01T00:00:00+02:00",
    "end": "2024-08-13T12:16:43+02:00",
    "pretty_date": true
}

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
combined_kb	body	decimal	Download + Upload.
download_kb	body	decimal	Downloaded in Kilobytes.
download_kbps	body	decimal	Average Download Speed for specified aggregation in Kilobits Per Second.
max_download_kbps	body	decimal	Maximum Download Speed for specified aggregation in Kilobits Per Second.
max_upload_kbps	body	decimal	Maximum Upload Speed for specified aggregation in Kilobits Per Second.
min_download_kbps	body	decimal	Minimum Download Speed for specified aggregation in Kilobits Per Second.
min_upload_kbps	body	decimal	Minimum Upload Speed for specified aggregation in Kilobits Per Second.
time	body	string	User friendly formatted time.
upload_kb	body	decimal	Uploaded in Kilobytes.
upload_kbps	body	decimal	Average Upload Speed for specified aggregation in Kilobits Per Second.

Response Example

[
    {
        "download_kb": 0.0,
        "upload_kb": 0.0,
        "combined_kb": 0.0,
        "upload_kbps": 0.0,
        "download_kbps": 0.0,
        "min_download_kbps": 0.0,
        "min_upload_kbps": 0.0,
        "max_download_kbps": 0.0,
        "max_upload_kbps": 0.0,
        "time": "2024-05 (May)"
    },
    {
        "download_kb": 0.0,
        "upload_kb": 0.0,
        "combined_kb": 0.0,
        "upload_kbps": 0.0,
        "download_kbps": 0.0,
        "min_download_kbps": 0.0,
        "min_upload_kbps": 0.0,
        "max_download_kbps": 0.0,
        "max_upload_kbps": 0.0,
        "time": "2024-06 (June)"
    },
    {
        "download_kb": 0.0,
        "upload_kb": 0.0,
        "combined_kb": 0.0,
        "upload_kbps": 0.0,
        "download_kbps": 0.0,
        "min_download_kbps": 0.0,
        "min_upload_kbps": 0.0,
        "max_download_kbps": 0.0,
        "max_upload_kbps": 0.0,
        "time": "2024-07 (July)"
    },
    {
        "download_kb": 0.0,
        "upload_kb": 0.0,
        "combined_kb": 0.0,
        "upload_kbps": 0.0,
        "download_kbps": 0.0,
        "min_download_kbps": 0.0,
        "min_upload_kbps": 0.0,
        "max_download_kbps": 0.0,
        "max_upload_kbps": 0.0,
        "time": "2024-08 (August)"
    }
]

POST

/v1/subscriber/virtual/{virtual_id}/data/{aggregation}

(telemetry)

Virtual Server data usage.

Service
telemetry

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AdministratorSubscriber Telemetry

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
aggregation	url	string	hourly, daily, weekly, monthly or yearly.	X
virtual_id	url	string	Unique Virtual ID.	X
end	body	string	End Report Date Time in ISO 8601.	X
pretty_date	body	boolean	The default time format in response is ISO 8601. Setting this to true will format it as a user-friendly format that can be used for graphs, for example.
start	body	string	Start Report Date Time in ISO 8601.	X

Request Example

{
    "start": "2024-05-01T00:00:00+02:00",
    "end": "2024-08-13T12:16:43+02:00",
    "pretty_date": true
}

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
data	body	object	An array of data usage entries for the requested period.
data.combined_kb	body	decimal	Download + Upload.
data.download_kb	body	decimal	Downloaded in Kilobytes.
data.download_kbps	body	decimal	Average Download Speed for specified aggregation in Kilobits Per Second.
data.max_download_kbps	body	decimal	Maximum Download Speed for specified aggregation in Kilobits Per Second.
data.max_upload_kbps	body	decimal	Maximum Upload Speed for specified aggregation in Kilobits Per Second.
data.min_download_kbps	body	decimal	Minimum Download Speed for specified aggregation in Kilobits Per Second.
data.min_upload_kbps	body	decimal	Minimum Upload Speed for specified aggregation in Kilobits Per Second.
data.time	body	string	User friendly formatted time.
data.upload_kb	body	decimal	Uploaded in Kilobytes.
data.upload_kbps	body	decimal	Average Upload Speed for specified aggregation in Kilobits Per Second.
metadata	body	object	Metadata about the returned data.
metadata.interpolate_interval	body	integer	The intervals (in seconds) over which the original usage was stored, the returned usage data is interpolated from these intervals. Will be NULL if interpolation did not take place.
metadata.per_second_avg_interval	body	integer	The interval (in seconds) by which the data was divided to calculate the returned per-second values.

Response Example

{
    "data": [
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-05 (May)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-06 (June)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-07 (July)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-08 (August)"
        }
    ],
    "metadata": {
        "interpolate_interval": null,
        "per_second_avg_interval": 3600
    }
}

POST

/v1/subscriber/client/{client_id}/data/{aggregation}

(telemetry)

Virtual Server Client data usage.

Service
telemetry

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AdministratorSubscriber Telemetry

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
aggregation	url	string	hourly, daily, weekly, monthly or yearly.	X
client_id	url	string	Unique Virtual Client ID.	X
end	body	string	End Report Date Time in ISO 8601.	X
pretty_date	body	boolean	The default time format in response is ISO 8601. Setting this to true will format it as a user-friendly format that can be used for graphs, for example.
start	body	string	Start Report Date Time in ISO 8601.	X

Request Example

{
    "start": "2024-05-01T00:00:00+02:00",
    "end": "2024-08-13T12:16:43+02:00",
    "pretty_date": true
}

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
data	body	object	An array of data usage entries for the requested period.
data.combined_kb	body	decimal	Download + Upload.
data.download_kb	body	decimal	Downloaded in Kilobytes.
data.download_kbps	body	decimal	Average Download Speed for specified aggregation in Kilobits Per Second.
data.max_download_kbps	body	decimal	Maximum Download Speed for specified aggregation in Kilobits Per Second.
data.max_upload_kbps	body	decimal	Maximum Upload Speed for specified aggregation in Kilobits Per Second.
data.min_download_kbps	body	decimal	Minimum Download Speed for specified aggregation in Kilobits Per Second.
data.min_upload_kbps	body	decimal	Minimum Upload Speed for specified aggregation in Kilobits Per Second.
data.time	body	string	User friendly formatted time.
data.upload_kb	body	decimal	Uploaded in Kilobytes.
data.upload_kbps	body	decimal	Average Upload Speed for specified aggregation in Kilobits Per Second.
metadata	body	object	Metadata about the returned data.
metadata.interpolate_interval	body	integer	The intervals (in seconds) over which the original usage was stored, the returned usage data is interpolated from these intervals. Will be NULL if interpolation did not take place.
metadata.per_second_avg_interval	body	integer	The interval (in seconds) by which the data was divided to calculate the returned per-second values.

Response Example

{
    "data": [
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-05 (May)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-06 (June)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-07 (July)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-08 (August)"
        }
    ],
    "metadata": {
        "interpolate_interval": null,
        "per_second_avg_interval": 3600
    }
}

POST

/v1/subscriber/service/{service_id}/data/{aggregation}

(telemetry)

Service Profile data usage.

Service
telemetry

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AdministratorSubscriber Telemetry

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
aggregation	url	string	hourly, daily, weekly, monthly or yearly.	X
service_id	url	string	Unique Service ID.	X
end	body	string	End Report Date Time in ISO 8601.	X
pretty_date	body	boolean	The default time format in response is ISO 8601. Setting this to true will format it as a user-friendly format that can be used for graphs, for example.
start	body	string	Start Report Date Time in ISO 8601.	X

Request Example

{
    "start": "2024-05-01T00:00:00+02:00",
    "end": "2024-08-13T12:16:43+02:00",
    "pretty_date": true
}

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
data	body	object	An array of data usage entries for the requested period.
data.combined_kb	body	decimal	Download + Upload.
data.download_kb	body	decimal	Downloaded in Kilobytes.
data.download_kbps	body	decimal	Average Download Speed for specified aggregation in Kilobits Per Second.
data.max_download_kbps	body	decimal	Maximum Download Speed for specified aggregation in Kilobits Per Second.
data.max_upload_kbps	body	decimal	Maximum Upload Speed for specified aggregation in Kilobits Per Second.
data.min_download_kbps	body	decimal	Minimum Download Speed for specified aggregation in Kilobits Per Second.
data.min_upload_kbps	body	decimal	Minimum Upload Speed for specified aggregation in Kilobits Per Second.
data.time	body	string	User friendly formatted time.
data.upload_kb	body	decimal	Uploaded in Kilobytes.
data.upload_kbps	body	decimal	Average Upload Speed for specified aggregation in Kilobits Per Second.
metadata	body	object	Metadata about the returned data.
metadata.interpolate_interval	body	integer	The intervals (in seconds) over which the original usage was stored, the returned usage data is interpolated from these intervals. Will be NULL if interpolation did not take place.
metadata.per_second_avg_interval	body	integer	The interval (in seconds) by which the data was divided to calculate the returned per-second values.

Response Example

{
    "data": [
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-05 (May)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-06 (June)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-07 (July)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-08 (August)"
        }
    ],
    "metadata": {
        "interpolate_interval": null,
        "per_second_avg_interval": 3600
    }
}

POST

/v1/subscriber/profile/{profile_id}/data/{aggregation}

(telemetry)

Subscriber Profile data usage.

Service
telemetry

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AdministratorSubscriber Telemetry

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
aggregation	url	string	hourly, daily, weekly, monthly or yearly.	X
profile_id	url	string	Unique Subscriber Profile ID.	X
end	body	string	End Report Date Time in ISO 8601.	X
pretty_date	body	boolean	The default time format in response is ISO 8601. Setting this to true will format it as a user-friendly format that can be used for graphs, for example.
start	body	string	Start Report Date Time in ISO 8601.	X

Request Example

{
    "start": "2024-05-01T00:00:00+02:00",
    "end": "2024-08-13T12:16:43+02:00",
    "pretty_date": true
}

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
data	body	object	An array of data usage entries for the requested period.
data.combined_kb	body	decimal	Download + Upload.
data.download_kb	body	decimal	Downloaded in Kilobytes.
data.download_kbps	body	decimal	Average Download Speed for specified aggregation in Kilobits Per Second.
data.max_download_kbps	body	decimal	Maximum Download Speed for specified aggregation in Kilobits Per Second.
data.max_upload_kbps	body	decimal	Maximum Upload Speed for specified aggregation in Kilobits Per Second.
data.min_download_kbps	body	decimal	Minimum Download Speed for specified aggregation in Kilobits Per Second.
data.min_upload_kbps	body	decimal	Minimum Upload Speed for specified aggregation in Kilobits Per Second.
data.time	body	string	User friendly formatted time.
data.upload_kb	body	decimal	Uploaded in Kilobytes.
data.upload_kbps	body	decimal	Average Upload Speed for specified aggregation in Kilobits Per Second.
metadata	body	object	Metadata about the returned data.
metadata.interpolate_interval	body	integer	The intervals (in seconds) over which the original usage was stored, the returned usage data is interpolated from these intervals. Will be NULL if interpolation did not take place.
metadata.per_second_avg_interval	body	integer	The interval (in seconds) by which the data was divided to calculate the returned per-second values.

Response Example

{
    "data": [
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-05 (May)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-06 (June)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-07 (July)"
        },
        {
            "download_kb": 0.0,
            "upload_kb": 0.0,
            "combined_kb": 0.0,
            "download_kbps": 0.0,
            "upload_kbps": 0.0,
            "min_download_kbps": 0.0,
            "min_upload_kbps": 0.0,
            "max_download_kbps": 0.0,
            "max_upload_kbps": 0.0,
            "time": "2024-08 (August)"
        }
    ],
    "metadata": {
        "interpolate_interval": null,
        "per_second_avg_interval": 3600
    }
}

Top Subscribers by Data Usage

POST

/v1/subscriber/topusers

(telemetry)

List Top Subscribers by Usage

Service
telemetry

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AdministratorSubscriber Telemetry

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
end	body	string	Report End datetime
start	body	string	Report Start datetime
timezone	body	string	Timezone.

Request Example

{
    "timezone":"Africa/Johannesburg",
    "start":"2025-01-01 00:00",
    "end":"2025-02-01 00:00"
}

Response Status Codes

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

Response Properties

Name	In	Type	Description
name	body	string	Subscriber name.
profile	body	string	Name of Subscriber Profile.
service	body	string	Name of Service Profile.
subscriber_id	body	string	Unique Subscriber ID.
usage_kb	body	integer	The total number of kilobytes of usage for the subscriber.
usage_pretty	body	string	The human-readable volume of usage for the subscriber.
username	body	string	Subscriber username.
virtual	body	string	Name of Virtual Server.

Response Example

[
    {
        "subscriber_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "usage_kb": "2168513382",
        "usage_pretty": "2.17TB",
        "username": "XXXXXXXXXXXXXXXXX",
        "name": "XXXXX",
        "virtual": "XXX",
        "service": "XXX",
        "profile": "XXX"
    },
    {
        "subscriber_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "usage_kb": "2148323355",
        "usage_pretty": "2.15TB",
        "username": "XXXXXXXXXXXXXXXXX",
        "name": "XXXXX",
        "virtual": "XXX",
        "service": "XXX",
        "profile": "XXX"
    },
    {
        "subscriber_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "usage_kb": "1577329845",
        "usage_pretty": "1.58TB",
        "username": "XXXXXXXXXXXXXXXXX",
        "name": "XXXXX",
        "virtual": "XXX",
        "service": "XXX",
        "profile": "XXX"
    }
]

Credit Usage

GET

/v1/subscriber/{subscriber_id}/credit/status

(telemetry)

Subscriber Current Credits Usage

Service
telemetry

Accepted Roles (RBAC)

AdministratorCustomerNetwork OperationsStaff MemberSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber ViewSupport

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
subscriber_id	url	string	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
credit_name	body	integer	Credit Name.
free	body	integer	Free in Kilobytes.
rollover	body	integer	Rollover in Kilobytes.
total_credit	body	integer	Credit in Kilobytes.
total_used	body	integer	Used in Kilobytes.

Response Example

[
    {
        "credit_name": "Monthly Anytime",
        "total_credit": 10000000,
        "total_used": 10000000,
        "rollover": 0,
        "free": 0
    }
]

Active/Inactive Subscriber Counts

POST

/v1/subscriber/count

(telemetry)

Subscriber Active/Inactive Count

Service
telemetry

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber View

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)

Response Status Codes

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

Response Properties

Name	In	Type	Description
active	body	integer	Active subscribers for aggregation period.
inactive	body	integer	Inactive subscribers for aggregation period.
time	body	string	Human-readable representation of aggregation period.
total	body	integer	Total subscribers for aggregation period.

Response Example

[
    {
        "active": 100,
        "total": 150,
        "inactive": 50,
        "time": "2025-01 (January)"
    },
    {
        "active": 100,
        "total": 150,
        "inactive": 50,
        "time": "2025-02 (February)"
    },
    {
        "active": 100,
        "total": 150,
        "inactive": 50,
        "time": "2025-03 (March)"
    }
]

Event Logs

The following API definitions describe how to query subscriber event logs. Please refer to Subscriber Telemetry - Event Logs documentation for more information relating their use.

Events are only retained for up to 2 weeks.

GET

/v1/subscriber/{subscriber_id}/events

(telemetry)

List of Events.

Service
telemetry

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber View

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
subscriber_id	url	string	Unique Subscriber ID.	X
facility	query	string	Match facility. Authentication, Accounting and more.
severity	query	string	Match severity precisely. (info, warning, error, critical)

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
event_id	body	string	Unique Event ID.
facility	body	string	Authentication, Accounting and more.
message	body	string	Short version of message.
severity	body	string	The severity level of the message. (info, warning, error, critical)
time	body	string	ISO 8601 Event Time.

Response Example

[
    {
        "time": "2024-08-07T11:33:17+00:00",
        "facility": "authentication",
        "severity": "info",
        "message": "Authentication: Authentication login success",
        "event_id": "1723028400::d7268c5d-54b0-11ef-aefc-174adb24f2cd"
    },
    {
        "time": "2024-08-05T12:46:32+00:00",
        "facility": "authentication",
        "severity": "info",
        "message": "Authentication: Authentication login success",
        "event_id": "1722859200::bd44210d-5328-11ef-bf64-cfca366fc35d"
    },
    {
        "time": "2024-07-31T05:57:34+00:00",
        "facility": "authentication",
        "severity": "info",
        "message": "Authentication: Authentication login success",
        "event_id": "1722402000::c85b25d4-4f01-11ef-9648-cfca366fc35d"
    },
    {
        "time": "2024-07-30T16:26:59+00:00",
        "facility": "authentication",
        "severity": "info",
        "message": "Authentication: Authentication login success",
        "event_id": "1722355200::8bcf84f0-4e90-11ef-b265-aff022b163c4"
    },
    {
        "time": "2024-07-29T07:06:02+00:00",
        "facility": "authentication",
        "severity": "info",
        "message": "Authentication: Authentication login success",
        "event_id": "1722236400::03d9363a-4d79-11ef-80c4-174adb24f2cd"
    },
    {
        "time": "2024-07-29T07:05:56+00:00",
        "facility": "disconnect",
        "severity": "error",
        "message": "disconnect: Error (server http://10.0.0.33)",
        "event_id": "1722236400::0020393a-4d79-11ef-8c67-cfca366fc35d"
    }
]

GET

/v1/subscriber/{subscriber_id}/event/{event_id}

(telemetry)

Get Event.

Service
telemetry

Accepted Roles (RBAC)

AdministratorNetwork OperationsSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber View

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
event_id	url	string	Unique Event ID.	X
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
domain	body	string	NebularStack Domain
event_id	body	string	Unique Event ID.
facility	body	string	Authentication, Accounting and more.
message	body	string	Event message.
region	body	string	Region associated with the event.
severity	body	string	The severity level of the message. (info, warning, error, critical)
subscriber_id	body	string	Unique Subscriber ID.
time	body	string	ISO 8601 Event Time.
username	body	string	Subscriber username.
virtual_id	body	string	Unique Virtual ID that triggered event.

Response Example

{
    "time": "2024-08-05T12:46:32+00:00",
    "domain": "isp.com",
    "subscriber_id": "00034ae6-4d79-11ef-80c4-174adb24f2cd",
    "virtual_id": "465be807-54f1-4bf6-b940-398ed95cdbe7",
    "username": "test@isp.com",
    "facility": "Authentication",
    "severity": "info",
    "message": "Authentication: Authentication login success\nUsername: test@isp.com\nVirtual-Router-ID: 465be807-54f1-4bf6-b940-398ed95cdbe7\nRequest:\nuser-name: test@isp.com\nchap-password: 0x661112163bf93a571d5f924c7ef868aba9\nnas-ip-address: 172.16.123.5\nnas-port: 100\nservice-type: Framed-User\nframed-protocol: PPP\nnas-identifier: mx204\nchap-challenge: 0xdf206be846a226de8b61b741f2d703606499b1db80\nnas-port-type: Ethernet\nacct-session-id: 89195146\nnas-port-id: ae2:114-100\nchargeable-user-identity: 0x00\nerx-pppoe-description: pppoe 70:a7:41:38:ed:f9\nerx-dhcp-mac-addr: 70a7.4138.edf9\nerx-qos-set-name: ae2-114\nerx-client-profile-name: PPPOE:\ncalabiyau-client-ip-address: 172.16.123.5\ncalabiyau-nas-profile: JUNIPER\ncalabiyau-nas-id: 19b88f68-0e9b-423f-82c8-2d4a5f83d4e3\ncalabiyau-user-id: 00034ae6-4d79-11ef-80c4-174adb24f2cd",
    "region": "South Africa",
    "event_id": "1722859200::bd44210d-5328-11ef-bf64-cfca366fc35d"
}

Caller Data Records (CDR)

The following API definitions describe how to query subscriber CDR logs. Please refer to Subscriber Telemetry - Caller Data Records documentation for more information relating their use.

The CDR list endpoint supports both GET and POST:

GET returns the CDRs for the last 5 days. It takes no date parameters; any that are supplied are ignored.
POST returns the CDRs for an explicit date range, supplied in the request body as start_time and end_time (both required). end_time must be after start_time and the range must not exceed 32 days.

Data is retained for 5 years.

GET

/v1/subscriber/{subscriber_id}/cdr/records

(telemetry)

CDR List for one subscriber (last 5 days).

Service
telemetry

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
subscriber_id	url	string	Unique ID of subscriber for which CDR records are to be retrieved	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
acct_unique_id	body	string	Unique ID
called_station_id	body	string	Called station ID
calling_station_id	body	string	Calling station ID
client_ip_address	body	string	Client IP Address
duration	body	integer	Duration of record
id	body	string	Unique ID of cdr record
nas_ip_address	body	string	Nas IP Address
start_time	body	string	Timestamp when record was initiated
terminate_cause	body	integer	Termination Cause
update_time	body	string	Timestamp when record was updated
username	body	string	Username of subscriber to which this record belongs

Response Example

[
    {
        "id": "89e88982-cc01-11ee-9127-a5b2efd1bd16::2024-02-01",
        "start_time": "2024-02-15T12:55:47+00:00",
        "update_time": "2024-02-15T12:55:47+00:00",
        "acct_unique_id": "89e88982-cc01-11ee-9127-a5b2efd1bd16",
        "username": "user@example.com",
        "calling_station_id": "00:11:22:33:44:55",
        "called_station_id": "PPPOE SERVER",
        "nas_ip_address": "192.0.2.20",
        "client_ip_address": "198.51.100.10",
        "duration": 0,
        "terminate_cause": null
    },
    {
        "id": "36d81884-cc01-11ee-9127-a5b2efd1bd16::2024-02-01",
        "start_time": "2024-02-15T12:53:28+00:00",
        "update_time": "2024-02-15T12:53:29+00:00",
        "acct_unique_id": "36d81884-cc01-11ee-9127-a5b2efd1bd16",
        "username": "user@example.com",
        "calling_station_id": "00:11:22:33:44:66",
        "called_station_id": "PPPOE SERVER",
        "nas_ip_address": "192.0.2.20",
        "client_ip_address": "198.51.100.11",
        "duration": 0,
        "terminate_cause": "User-Request"
    }
]

POST

/v1/subscriber/{subscriber_id}/cdr/records

(telemetry)

CDR List for one subscriber (date range).

Service
telemetry

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
subscriber_id	url	string	Unique ID of subscriber for which CDR records are to be retrieved.	X
end_time	body	string	End of the range, as an ISO-8601 datetime. Must be after start_time, and the range must not exceed 32 days. Required.	X
start_time	body	string	Start of the range, as an ISO-8601 datetime. Required.	X

Request Example

{
    "start_time": "2024-02-01T00:00:00+00:00",
    "end_time": "2024-02-15T00:00:00+00:00"
}

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
acct_unique_id	body	string	Unique ID
called_station_id	body	string	Called station ID
calling_station_id	body	string	Calling station ID
client_ip_address	body	string	Client IP Address
duration	body	integer	Duration of record
id	body	string	Unique ID of cdr record
nas_ip_address	body	string	Nas IP Address
start_time	body	string	Timestamp when record was initiated
terminate_cause	body	integer	Termination Cause
update_time	body	string	Timestamp when record was updated
username	body	string	Username of subscriber to which this record belongs

Response Example

[
    {
        "id": "89e88982-cc01-11ee-9127-a5b2efd1bd16::2024-02-01",
        "start_time": "2024-02-15T12:55:47+00:00",
        "update_time": "2024-02-15T12:55:47+00:00",
        "acct_unique_id": "89e88982-cc01-11ee-9127-a5b2efd1bd16",
        "username": "user@example.com",
        "calling_station_id": "00:11:22:33:44:55",
        "called_station_id": "PPPOE SERVER",
        "nas_ip_address": "192.0.2.20",
        "client_ip_address": "198.51.100.10",
        "duration": 0,
        "terminate_cause": null
    }
]

GET

/v1/subscriber/cdr/record/{cdr_id}

(telemetry)

CDR record.

Service
telemetry

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
cdr_id	url	string	Unique ID of the CDR record, in the form "acct_unique_id::month" (e.g. as returned by the IP Query endpoint).	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
acct_session_id	body	string	Accounting session ID.
acct_unique_id	body	string	Accounting unique ID.
called_station_id	body	string	Called station ID.
calling_station_id	body	string	Calling station ID.
charging_id	body	string	Charging ID.
client_ip_address	body	string	Client IP address.
client_mac_address	body	string	Client MAC address.
download	body	integer	GB downloaded during record.
duration	body	integer	Duration of record.
framed_protocol	body	string	Framed protocol.
ggsn_address	body	string	GGSN address.
id	body	string	Unique ID of the CDR record.
imsi	body	string	IMSI.
iplog	body	array	IP addresses (prefixes) used during the record.
msisdn	body	string	MSISDN.
name	body	string	Subscriber name.
nas_identifier	body	string	NAS identifier.
nas_ip_address	body	string	NAS IP address.
nas_port	body	string	NAS port.
nas_port_id	body	string	NAS port ID.
nas_port_type	body	string	NAS port type.
policy_in	body	string	Ingress policy.
policy_out	body	string	Egress policy.
profile	body	string	Profile.
realm	body	string	Realm.
realm_id	body	string	Realm ID.
service	body	string	Service name.
sgsn_address	body	string	SGSN address.
start_time	body	string	Timestamp when record was initiated.
terminate_cause	body	string	Termination cause.
update_time	body	string	Timestamp when record was updated.
upload	body	integer	GB uploaded during record.
username	body	string	Username of subscriber to which this record belongs.
virtual	body	string	Virtual AAA name.
vrf	body	string	VRF.

Response Example

{
    "id": "89e88982-cc01-11ee-9127-a5b2efd1bd16::2024-02-01",
    "start_time": "2024-02-15T12:55:47+00:00",
    "update_time": "2024-02-15T12:55:47+00:00",
    "acct_session_id": "9f2c1a10",
    "acct_unique_id": "89e88982-cc01-11ee-9127-a5b2efd1bd16",
    "name": "Example Subscriber",
    "username": "user@example.com",
    "calling_station_id": "00:11:22:33:44:55",
    "called_station_id": "PPPOE SERVER",
    "nas_ip_address": "192.0.2.20",
    "nas_identifier": "NAS-1",
    "nas_port": "0",
    "nas_port_type": "Ethernet",
    "nas_port_id": "eth0",
    "client_ip_address": "198.51.100.10",
    "realm": "example.com",
    "realm_id": null,
    "duration": 3600,
    "upload": 1,
    "download": 5,
    "framed_protocol": "PPP",
    "vrf": null,
    "client_mac_address": "00:11:22:33:44:55",
    "policy_in": null,
    "policy_out": null,
    "imsi": null,
    "msisdn": null,
    "charging_id": null,
    "sgsn_address": null,
    "ggsn_address": null,
    "terminate_cause": "User-Request",
    "profile": "Premium-100",
    "service": "subscriber_cdr",
    "virtual": "ExampleAAA",
    "iplog": [
        {
            "prefix_type": "framed-ip-address",
            "prefix": "198.51.100.10"
        }
    ]
}

Subscriber Reports

A subscriber report contains information about all subscribers within a the provided domain context. The available report types are: Subscriber Usage; Subscriber Credit Usage; and Active/Inactive Subscribers.

The following API definitions describe how to query subscriber reports.

POST

/v1/subscriber/report

(telemetry)

Subscriber Report.

Service
telemetry

Accepted Roles (RBAC)

AdministratorCustomerNetwork OperationsStaff MemberSubscriber AccountsSubscriber AdministratorSubscriber SupportSubscriber TelemetrySubscriber ViewSupport

Request Parameters

Name	In	Type	Description	MUST include
X-Auth-Token	header	string	Valid Authentication Token. Please see developers documentation/identity.	X
X-Domain	header	string	Optional domain context for the request. (default: the token domain)
X-Timezone	header	string	Timezone for response datetime property values. (default UTC)
format	header	string	The format in which to report the report. Accepted values - "csv", "json"
month	body	string	The month for which the report is generated (in the form "YYYY-MM")
timezone	body	string	The timezone string representing the timezone in which the report is generated
type	body	string	The report type. Accepted values - "USAGE", "CREDIT", "ACTIVE_INACTIVE"

Request Example

{
    "type": "USAGE",
    "timezone": "Africa/Johannesburg",
    "month": "2024-11"
}

Response Status Codes

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

Response Properties

Name	In	Type	Description
combined_gb	body	decimal	Combined upload and download for the period in gigabytes.
combined_kb	body	integer	Combined upload and download for the period in kilobytes.
download_gb	body	decimal	Total download for the period in gigabytes.
download_kb	body	integer	Total download for the period in kilobytes.
subscriber_id	body	string	Unique Subscriber ID.
subscriber_name	body	string	Subscriber name.
subscriber_package	body	string	Subscriber package.
subscriber_service	body	string	Subscriber service.
subscriber_username	body	string	Subscriber username.
upload_gb	body	decimal	Total upload for the period in gigabytes.
upload_kb	body	integer	Total upload for the period in kilobytes.

Response Example

{
    "subscriber_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "subscriber_name": "XXX",
    "subscriber_username": "user@domain.co.za",
    "subscriber_service": "XXX",
    "subscriber_package": "XXX",
    "download_gb": 999.99,
    "upload_gb": 999.99,
    "combined_gb": 999.99,
    "download_kb": 9999999,
    "upload_kb": 9999999,
    "combined_kb": 9999999
}