API docs by Redocly

Usage Engine Cloud Edition API

Download OpenAPI specification:Download

Usage Engine offers several different APIs for performing various tasks using external systems.

HTTP error response codes

Describes the standard HTTP error codes returned by the API, including their meanings and typical scenarios.

The following error response codes are used in the system:

Error code Explanation
400 Bad request
401 Unauthorized
404 Not found
405 Method not allowed
409 Conflict
413 Request body too large
429 Too many requests
500 An unexpected internal error occurred even though the request was valid
503 Service unavailable

Authentication

Endpoints for obtaining OAuth 2.0 tokens to securely access the API.

Create access token

Generates a bearer access token for authenticating OAuth clients with the Usage Engine REST API. Requires an Application Access client ID and secret. See Application Access for setup instructions.

Rate Limits
Each client can make up to 10 request(s) every 1s. The burst capacity is 5 request(s).

header Parameters
Content-Type
string
Authorization
string
Request Body schema: application/json

Credentials used for authenticating the client to the authorization server.

audience
required
string

The intended recipients which should accept and process the token. Use the base URL for the environment you are accessing.

client_id
required
string

The client ID generated when creating the Application Access in Usage Engine CE.

client_secret
required
string

The client secret generated when creating the Application Access in Usage Engine CE.

grant_type
required
string

The OAuth grant type that will be used to generate the token. The value of this parameter must be client_credentials.

Responses

Request samples

Content type
application/json
{
  • "audience": "https://api.digitalroute.io/",
  • "client_id": "u4grtTy18E2DYANsv0G174aSxR3EeOiA",
  • "client_secret": "U6qN9NTgis3MLeleRXtLgIxtRE-qhpZcPJ_5eoNtNQYcodiY9q0Abs3afgpbX3M6",
  • "grant_type": "client_credentials"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImZUYU5saGpnclFERE0xYkdVZG1WeiJ9.eyJhY2NvdW50SWQiOiJhZDZmZWM5NS1lMDYzLTQ5MmItOTJjYy01MmJiNjJjMGU3NTAiLCJpc3MiOiJodHRwczovL2F1dGguZGlnaXRhbHJvdXRlLmlvLyIsInN1YiI6IjhtMUhUMHA2SkdMOVJjbzhWNEZjWGZ2Y2dHejcwcms4QGNsaWVudHMiLCJhdWQiOiJodHRwczovL2FwaS5kaWdpdGFscm91dGUuaW8vIiwiaWF0IjoxNzEyMTQ0OTQzLCJleHAiOjE3MTIxNDg1NDMsInNjb3BlIjoiY3JlYXRlOm1ldGVyX3R5cGVzIGNyZWF0ZTptZXRlcnMgZGVsZXRlOm1ldGVyX3R5cGVzIGRlbGV0ZTptZXRlcnMgcmVhZDptZXRlcl90eXBlcyByZWFkOm1ldGVycyB1cGRhdGU6bWV0ZXJfdHlwZXMiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMiLCJhenAiOiI4bTFIVDBwNkpHTDlSY284VjRGY1hmdmNnR3o3MHJrOCJ9.VS8Ti1zTK4b8qGRKXJg8b0-aMpNpTTL1_nwsPbCeM7CFlUYu45ZUQGWvUqC6XGK-Xl3j9k5Tkth8TtFbbXNEW4mEV0e1qQbDu_ZlvH-bH2nCNJhk-7mFriGYfTF0U-erqNiMsk4Tbrmm2Voy9CJ4_WyVrCjTLBqRBKb_bU4KHFJtgadlqwaTVNZUiI-sIV3Y2V_gid_4qPTO1Vr01ybID_F8uNII9goDqPJBRh6hmcKHqt65U5n2xzbmBcNqRPoXqxh1g9OaYEPDjojp2lHttqs2EkGG9KxzTFqhdX4lcrjfHGgzNk7LD7S7mGJTO0V-n57geptxM7gFGr-hAQ4Ikg",
  • "expires_in": 3600,
  • "scope": "usage-metering:create:meter_types usage-metering:create:meters usage-metering:delete:meter_types usage-metering:delete:meters usage-metering:read:meter_types usage-metering:read:meters usage-metering:update:meter_types usage-metering:update:meters",
  • "token_type": "Bearer"
}

Meter type

Defines categories for usage-based billing, representing products or services available to customers.

Create meter type

Creates a new meter type definition in the account. Meter types define the structure and behavior of usage meters, including what is being measured, how it is counted, and any associated metadata or external system references. Once created, the meter type can be used to instantiate individual meters for tracking user consumption. Meter types must have a unique name and optional external reference within the account.

Rate Limits
Each client can make up to 20 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires at least one of the following scopes: usage-metering:create:meter_types, create:meter_types.

Authorizations:
OAuth 2.0 Bearer Token
header Parameters
Authorization
required
string

Bearer token for authentication

Request Body schema: application/json
activeFrom
string

Determines from which date and time the meter type will be active, with the time based on UTC. The date and time cannot be in the past, and if this parameter is left undefined, the current date and time will be picked.

activeTo
string

Determines to which date and time the meter type will be active, with the time based on UTC. The date and time cannot be in the past, and if this parameter is left undefined, it will be active indefinitely.

required
object

Choose the aggregation type for aggregating data within a defined interval.

  • Sum: Summarize all values.
  • Increment: Count the number of occurrences.
  • Max: Highest value received.
  • Min: Lowest value received.

The aggregation type cannot be updated.

capacity
number >= 0

The total capacity allocated for meters of this meter type. This value serves as a reference of upper limit for each meter of this type.

category
string <= 50 characters

Specify the category to which the meter type should be assigned. By using the category when configuring the Meter processor, meter types can be added, edited, or deleted without necessarily affecting the Meter processor configuration. If no category is specified, the meter type will be assigned to the DEFAULT category.

description
string <= 200 characters

You can add a more detailed description for the meter type with this parameter.

externalRef
string <= 100 characters

If the meter type is registered as a product in an external system, you can add the external ID to reference it.

name
required
string <= 80 characters ^[\w\s().-]+$

Name of the meter type. Only alphanumeric characters, spaces, and the following special characters are supported - _ . ( )

required
object

Determines how often the usage counting data should be reset and sent to downstream systems defined in crontab format.

Array of Using absolute value (object) or Using percentage of capacity (object) <= 5 items

A list of one or more thresholds that define usage checkpoints for meters of this meter type. When meter value reaches the defined threshold, a signal or action can be triggered.

timezone
required
string

The canonical timezone that should be applied for reset time. See IANA time zones for the complete available list.

unit
required
string <= 50 characters

Specify the unit which the meters should be measuring, such as MB, minutes, etc.

Responses

Request samples

Content type
application/json
{
  • "activeFrom": "2023-07-26T09:00:15.690+00:00",
  • "activeTo": "2024-11-22T00:00:00.000+00:00",
  • "aggregation": {
    },
  • "capacity": 1000,
  • "category": "API Counts",
  • "description": "Meter definition to count the number of API requests per customer",
  • "externalRef": "878752b4-4ddf",
  • "name": "Usage based API counter",
  • "resetSchedule": {
    },
  • "thresholds": [
    ],
  • "timezone": "Etc/UTC",
  • "unit": "requests"
}

Response samples

Content type
application/json
{
  • "accountId": "4d6548c8-1793-498f-9306-9ec101cb9bf8",
  • "activeFrom": "2023-07-26T09:00:15.690+00:00",
  • "activeTo": "2024-11-22T00:00:00.000+00:00",
  • "aggregation": {
    },
  • "capacity": 1000,
  • "category": "API Counts",
  • "createdAt": "2023-07-26T09:00:15.690+00:00",
  • "description": "Meter definition to count the number of API requests per customer",
  • "externalRef": "878752b4-4ddf",
  • "id": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "name": "Usage based API counter",
  • "numberOfMeters": 0,
  • "resetSchedule": {
    },
  • "thresholds": [
    ],
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-26T09:00:15.690+00:00"
}

Delete meter type

Permanently removes the specified meter type definition from the account. A meter type can only be deleted if no active meters are instantiated from it. Before deleting a meter type, you must first delete all associated meters to ensure data integrity and prevent orphaned meter instances. This action cannot be undone and will remove the meter type definition permanently.

Rate Limits
Each client can make up to 20 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires at least one of the following scopes: usage-metering:delete:meter_types, delete:meter_types.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter type.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "deletedCount": 1
}

Get meter type

Retrieves the complete definition and configuration of a specific meter type by its unique identifier. Returns the meter type's name, description, external references, and any associated metadata that defines how meters of this type will track and count usage.

Rate Limits
Each client can make up to 20 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires at least one of the following scopes: usage-metering:read:meter_types, read:meter_types.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter type.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "accountId": "4d6548c8-1793-498f-9306-9ec101cb9bf8",
  • "activeFrom": "2023-07-26T09:00:15.690+00:00",
  • "activeTo": "2024-11-22T00:00:00.000+00:00",
  • "aggregation": {
    },
  • "capacity": 1000,
  • "category": "API Counts",
  • "createdAt": "2023-07-26T09:00:15.690+00:00",
  • "description": "Meter definition to count the number of API requests per customer",
  • "externalRef": "878752b4-4ddf",
  • "id": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "name": "Usage based API counter",
  • "numberOfMeters": 0,
  • "resetSchedule": {
    },
  • "thresholds": [
    ],
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-26T09:00:15.690+00:00"
}

List meter types

Retrieves a paginated and sortable list of meter types configured for the account. Meter types define the structure and behavior of usage meters, including what is being measured and how it is counted. This endpoint supports filtering by name (full or partial match) and sorting by various fields to help locate specific meter type definitions.

Rate Limits
Each client can make up to 20 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires at least one of the following scopes: usage-metering:read:meter_types, read:meter_types.

Authorizations:
OAuth 2.0 Bearer Token
query Parameters
limit
integer

Defines the number of meter types to be returned. A maximum of 100 items can be returned.

skip
integer

Defines an offset for the meter types to be returned. If you set skip to 10, the first 10 meter types will be skipped in the returned list.

sortOrder
string
Enum: "ASC" "DESC"

Determines the sort order of the returned list; ASC for ascending or DESC for descending.

sortBy
string

Determines the field in the meter type by which the returned list will be sorted.

name
string

Defines the name for which meter type should be returned. You may provide full or partial name.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "meterTypes": [
    ]
}

Update meter type

Updates the configurable properties of a specified meter type definition. Allows modification of the meter type's name, description, and metadata while maintaining its unique identifier. Changes to the meter type affect the definition but do not retroactively modify existing meters instantiated from this type. The updated name and external reference must remain unique within the account.

Rate Limits
Each client can make up to 20 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires at least one of the following scopes: usage-metering:update:meter_types, update:meter_types.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter type.

header Parameters
Authorization
required
string

Bearer token for authentication

Request Body schema: application/json
string or null

The new active from date you want the meter type to use.

string or null

The new active to date you want the meter type to use.

capacity
number >= 0

A new total capacity allocated for meters of this meter type.

string or null <= 50 characters

The new category you want the meter type to use. You may need to revise the configuration in the Meter processor following the category update.

description
string <= 200 characters

The updated description you want the meter type to have.

string or null <= 100 characters

The new external ID you want to associate with the meter type.

name
string <= 80 characters ^[\w\s().-]+$

The new name you want the meter type to have. Only alphanumeric characters, spaces, and the following special characters are supported - _ . ( ).

object

The new reset schedule you want the meter type to use. The new reset schedule takes effect after the current period has ended and meters have been reset.

Array of Using absolute value (object) or Using percentage of capacity (object) <= 5 items

A new list of threshold objects, each of which can specify either an absolute value or a percentage of capacity.

timezone
string

The new canonical timezone you want the meter type to use. See IANA time zones for the complete available list.

unit
string <= 50 characters

Specify the unit which the meters should be measuring, such as MB, minutes, etc.

Responses

Request samples

Content type
application/json
{
  • "activeFrom": "2023-07-26T09:00:15.690+00:00",
  • "activeTo": "2024-11-22T00:00:00.000+00:00",
  • "capacity": 1000,
  • "category": "API Counts",
  • "description": "Meter definition to count the number of API requests per customer",
  • "externalRef": "878752b4-4ddf",
  • "name": "Usage based API counter",
  • "resetSchedule": {
    },
  • "thresholds": [
    ],
  • "timezone": "Etc/UTC",
  • "unit": "requests"
}

Response samples

Content type
application/json
{
  • "accountId": "4d6548c8-1793-498f-9306-9ec101cb9bf8",
  • "activeFrom": "2023-07-26T09:00:15.690+00:00",
  • "activeTo": "2024-11-22T00:00:00.000+00:00",
  • "aggregation": {
    },
  • "capacity": 1000,
  • "category": "API Counts",
  • "createdAt": "2023-07-26T09:00:15.690+00:00",
  • "description": "Meter definition to count the number of API requests per customer",
  • "externalRef": "878752b4-4ddf",
  • "id": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "name": "Usage based API counter",
  • "numberOfMeters": 0,
  • "resetSchedule": {
    },
  • "thresholds": [
    ],
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-26T09:00:15.690+00:00"
}

Meter

Represents a customer-specific usage counter, mapping usage events to one or more meter types.

Create meter

Creates a new meter to track usage consumption for a specific user and meter type. Meters continuously count usage events based on their associated meter type definition and meter key. Each meter is uniquely identified by the combination of meter type ID (or external reference), meter key, and user ID. Custom fields can be added to enrich the metered output with additional metadata.

Rate Limits
Each client can make up to 50 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires at least one of the following scopes: usage-metering:create:meters, create:meters.

Authorizations:
OAuth 2.0 Bearer Token
header Parameters
Authorization
required
string

Bearer token for authentication

Request Body schema: application/json
One of
object

Custom fields to enrich the metered output.

meterKey
required
string <= 36 characters

The meter key for the Meter processor counting the usage for the meter.

meterTypeId
required
string <= 36 characters

The unique ID of the meter type that the meter should count usage for.

userId
required
string <= 320 characters

Unique ID of the user the meter belongs to, for example an email address, user name or MSISDN number.

Responses

Request samples

Content type
application/json
Example
{
  • "customFields": {
    },
  • "meterKey": "a1f8797b-c827-4483-b6cf-6d3d3baa18a7",
  • "meterTypeId": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "userId": "user0@example.com"
}

Response samples

Content type
application/json
{
  • "capacity": 1000,
  • "carryFirst": {
    },
  • "carryLast": {
    },
  • "createdAt": "2023-07-01T00:00:00.000Z",
  • "customFields": {
    },
  • "deleteOnReset": false,
  • "groupBreakdowns": [
    ],
  • "groups": [
    ],
  • "id": "8a76066d-ff29-417c-a18e-abde22e44310",
  • "meterKey": "a1f8797b-c827-4483-b6cf-6d3d3baa18a7",
  • "meterMetaData": {
    },
  • "meterTypeId": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "meterTypeName": "Usage based API counter",
  • "periodEnd": "2023-08-01T00:00:00.000Z",
  • "periodStart": "2023-07-01T00:00:00.000Z",
  • "thresholds": [
    ],
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-05T22:01:04.431Z",
  • "userId": "user0@example.com",
  • "value": 25
}

Delete meter

Permanently removes the specified meter from the account. After deletion, usage tracking for the associated user and meter type combination will cease. This action cannot be undone.

Rate Limits
Each client can make up to 50 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires at least one of the following scopes: usage-metering:delete:meters, delete:meters.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "deletedCount": 1
}

Get meter

Retrieves the configuration and current state of a specific meter by its unique identifier. Returns the meter's associated meter type, meter key, user ID, custom fields, and timestamps. Use this endpoint to verify meter configuration or retrieve meter details for usage analysis.

Rate Limits
Each client can make up to 50 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires at least one of the following scopes: usage-metering:read:meters, read:meters.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "capacity": 1000,
  • "carryFirst": {
    },
  • "carryLast": {
    },
  • "createdAt": "2023-07-01T00:00:00.000Z",
  • "customFields": {
    },
  • "deleteOnReset": false,
  • "groupBreakdowns": [
    ],
  • "groups": [
    ],
  • "id": "8a76066d-ff29-417c-a18e-abde22e44310",
  • "meterKey": "a1f8797b-c827-4483-b6cf-6d3d3baa18a7",
  • "meterMetaData": {
    },
  • "meterTypeId": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "meterTypeName": "Usage based API counter",
  • "periodEnd": "2023-08-01T00:00:00.000Z",
  • "periodStart": "2023-07-01T00:00:00.000Z",
  • "thresholds": [
    ],
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-05T22:01:04.431Z",
  • "userId": "user0@example.com",
  • "value": 25
}

List meters

Retrieves a paginated list of meters configured for the account. Meters track usage consumption for specific users and meter types. This endpoint supports filtering by meter key, meter type ID, and user ID to locate specific meter instances. Use pagination with limit and skip parameters to navigate large meter collections efficiently.

Rate Limits
Each client can make up to 50 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires at least one of the following scopes: usage-metering:read:meters, read:meters.

Authorizations:
OAuth 2.0 Bearer Token
query Parameters
limit
integer

Defines the number of meters to be returned. A maximum of 100 items can be returned.

skip
integer

Defines an offset for the meters to be returned. If you set skip to 10, the first 10 meters will be skipped in the returned list.

meterKey
string

Defines the meter key for which meters should be returned.

meterTypeId
string

Defines the meter type ID for which meters should be returned.

userId
string

Defines the user ID for which meters should be returned.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "meters": [
    ]
}

Update meter

Updates the mutable properties of a specified meter. Allows modification of custom fields and other configurable attributes while preserving the meter's core identity (meter type, meter key, and user ID). Use this endpoint to enrich meters with updated metadata or adjust operational parameters without recreating the meter.

Rate Limits
Each client can make up to 50 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires at least one of the following scopes: usage-metering:update:meters, update:meters.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of meter.

header Parameters
Authorization
required
string

Bearer token for authentication

Request Body schema: application/json
capacity
number >= 0

The new total capacity allocated to this meter after the update, representing reference of usage limit. This value is used as the reference for evaluating capacityPercentage thresholds for this meter.

object

Custom fields to enrich the metered output.

deleteOnReset
boolean

Determine whether the meter should be deleted after the next reset.

Array of Using absolute value (object) or Using percentage of capacity (object) <= 5 items

A new list of threshold objects, each of which can specify either an absolute value or a percentage of capacity.

Responses

Request samples

Content type
application/json
{
  • "capacity": 1000,
  • "customFields": {
    },
  • "deleteOnReset": true,
  • "thresholds": [
    ]
}

Response samples

Content type
application/json
{
  • "capacity": 1000,
  • "carryFirst": {
    },
  • "carryLast": {
    },
  • "createdAt": "2023-07-01T00:00:00.000Z",
  • "customFields": {
    },
  • "deleteOnReset": false,
  • "groupBreakdowns": [
    ],
  • "groups": [
    ],
  • "id": "8a76066d-ff29-417c-a18e-abde22e44310",
  • "meterKey": "a1f8797b-c827-4483-b6cf-6d3d3baa18a7",
  • "meterMetaData": {
    },
  • "meterTypeId": "645ed240-02b5-400c-9a3c-21857e8f2ac4",
  • "meterTypeName": "Usage based API counter",
  • "periodEnd": "2023-08-01T00:00:00.000Z",
  • "periodStart": "2023-07-01T00:00:00.000Z",
  • "thresholds": [
    ],
  • "timezone": "Etc/UTC",
  • "unit": "requests",
  • "updatedAt": "2023-07-05T22:01:04.431Z",
  • "userId": "user0@example.com",
  • "value": 25
}

Online collection management

Endpoints for managing collectors in online collection.

Create collector

Creates a new online collection collector to ingest usage data from external sources. Collectors define the ingestion endpoint and configuration for receiving usage records. Once created, the collector provides a unique ID that is used in the ingestion API to submit data. Each account is limited to a maximum of five collectors.

Rate Limits
Each client can make up to 1 request(s) every 1s. The burst capacity is 1 request(s).

Authorization scopes
Requires the scope online-collection:create:collectors.

Authorizations:
OAuth 2.0 Bearer Token
header Parameters
Authorization
required
string

Bearer token for authentication

Request Body schema: application/json
name
required
string [ 1 .. 80 ] characters ^[\w\s().-]+$

The name of the collector. Only alphanumeric characters, spaces, and the following special characters are supported - _ . ( )

Responses

Request samples

Content type
application/json
{
  • "name": "Collector Name"
}

Response samples

Content type
application/json
{
  • "createdAt": "2023-07-01T00:00:00.000Z",
  • "id": "8a76066d-ff29-417c-a18e-abde22e44310",
  • "name": "Collector Name",
  • "status": "CREATING",
  • "updatedAt": "2023-07-05T22:01:04.431Z"
}

Delete collector

Permanently removes the specified online collection collector from the account. After deletion, the collector's ingestion endpoint will no longer accept data, and any streams or configurations referencing this collector will need to be updated. This action cannot be undone.

Rate Limits
Each client can make up to 1 request(s) every 1s. The burst capacity is 1 request(s).

Authorization scopes
Requires the scope online-collection:delete:collectors.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of the collector.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "deletedCount": 1
}

Get collector

Retrieves the complete configuration and status details for a specific online collection collector by its unique identifier. Returns the collector's name, operational status, creation and update timestamps, and any associated configuration metadata.

Rate Limits
Each client can make up to 5 request(s) every 1m. The burst capacity is 5 request(s).

Authorization scopes
Requires the scope online-collection:read:collectors.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of the collector.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2023-07-01T00:00:00.000Z",
  • "id": "8a76066d-ff29-417c-a18e-abde22e44310",
  • "name": "Collector Name",
  • "status": "ACTIVE",
  • "updatedAt": "2023-07-05T22:01:04.431Z"
}

List collectors

Retrieves a paginated and sortable list of online collection collectors configured for the account. Collectors define how usage data is ingested from external sources into the system. This endpoint supports sorting by name, status, and timestamps, and returns collectors with their current configuration and operational status. Use pagination to manage large collector deployments.

Rate Limits
Each client can make up to 5 request(s) every 1m. The burst capacity is 5 request(s).

Authorization scopes
Requires the scope online-collection:read:collectors.

Authorizations:
OAuth 2.0 Bearer Token
query Parameters
limit
integer

Defines the number of collectors to be returned. A maximum of 100 items can be returned.

skip
integer

Defines an offset for the collectors to be returned. If you set skip to 10, the first 10 collectors will be skipped in the returned list.

sortOrder
string
Enum: "ASC" "DESC"

Determines the sort order of the returned list.

sortBy
string
Enum: "name" "status" "createdAt" "updatedAt"

Determines the field in the collector by which the returned list will be sorted.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "collectors": [
    ]
}

Update collector

Updates the specified online collection collector's properties. Currently, only the collector's name field can be modified. The collector's unique identifier and operational status remain unchanged. The updated name must be unique within the account.

Rate Limits
Each client can make up to 1 request(s) every 1s. The burst capacity is 1 request(s).

Authorization scopes
Requires the scope online-collection:update:collectors.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of the collector.

header Parameters
Authorization
required
string

Bearer token for authentication

Request Body schema: application/json
non-empty
name
string [ 1 .. 80 ] characters ^[\w\s().-]+$

The name of the collector. Only alphanumeric characters, spaces, and the following special characters are supported - _ . ( )

Responses

Request samples

Content type
application/json
{
  • "name": "Collector Name"
}

Response samples

Content type
application/json
{
  • "createdAt": "2023-07-01T00:00:00.000Z",
  • "id": "8a76066d-ff29-417c-a18e-abde22e44310",
  • "name": "Collector Name",
  • "status": "ACTIVE",
  • "updatedAt": "2023-07-05T22:01:04.431Z"
}

Online collection ingestion

Endpoints for submitting usage data to online storage.

Send data

Submits usage records to the online collection storage for the specified collector.

Rate Limits
Each client can make up to 2000 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires the scope online-collection:ingest:collectors.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string

The unique ID of the collector.

header Parameters
Authorization
required
string

Bearer token for authentication

Request Body schema: application/json
required
string or object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "ingestionId": "645ed240-02b5-400c-9a3c-21857e8f2ac4"
}

Stream management

Endpoints for managing and exporting stream configurations.

Export stream

Exports the full configuration of a stream in a format designed for seamless import into another solution or environment. This enables easy backup, migration, or duplication of stream configurations across environments.

Rate Limits
Each client can make up to 20 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires the scope stream-management:read:streams.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string
Example: 514c23cd-301d-4922-bc9d-d8a3dcb11819

The unique identifier of the stream to export.

query Parameters
tag
string
Example: tag=v1.0.1

A version tag that identifies which version of the stream configuration to export. If not provided, the latest version will be returned.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "annotation": {
    },
  • "description": "Initial draft version",
  • "edges": [
    ],
  • "name": "My Stream",
  • "nodeGroups": [
    ],
  • "nodes": [
    ],
  • "tag": "v1.0"
}

Get stream

Retrieve the full configuration and metadata for a specific stream by its unique ID. Allows clients to specify which fields to include in the response for efficiency.

Rate Limits
Each client can make up to 20 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires the scope stream-management:read:streams.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string
Example: 514c23cd-301d-4922-bc9d-d8a3dcb11819

The unique ID of the stream to fetch.

query Parameters
fields
string
Example: fields=name,nodes.name

A comma-separated list of fields to include in each stream object in the response. Only the specified fields will be included. If omitted, all fields will be returned. Supports dot notation for nested fields (e.g., nodes.name).

tag
string
Example: tag=v1.0.1

A version tag that identifies which version of the stream to fetch. If not provided, the latest version will be returned.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "cas": 7,
  • "createdAt": "2025-10-21T14:52:54.232Z",
  • "createdBy": {
    },
  • "description": "Initial draft version",
  • "edges": [
    ],
  • "id": "239268d1-f26f-434c-9365-0625027a8ea3",
  • "ingress": {},
  • "name": "My Stream",
  • "nodeGroups": [
    ],
  • "nodes": [
    ],
  • "processingType": "batch",
  • "schemaVersion": 1,
  • "solutionId": "73253be8-0c7c-4670-9631-5a29fe59b4d2",
  • "tag": "v1.0",
  • "updatedAt": "2025-10-21T14:53:25.828Z",
  • "updatedBy": {
    }
}

Import stream

Imports a stream configuration into the specified solution. This endpoint allows clients to create a new stream or update an existing one by providing a complete stream definition. When a tag is not provided in the stream configuration, the import overwrites the latest autosaved version of the stream. When a tag is provided, the import saves both the autosaved version and a tagged version, enabling version control and tracking of stream changes. The endpoint supports flexible conflict resolution strategies for handling name collisions and can optionally allow node deletions when overwriting existing streams.

Rate Limits
Each client can make up to 20 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires the scope stream-management:write:streams.

Authorizations:
OAuth 2.0 Bearer Token
header Parameters
Authorization
required
string

Bearer token for authentication

Request Body schema: application/json
allowNodeDeletion
boolean

If set to true, allows the import to overwrite an existing stream even if the imported configuration omits nodes that are present in the target stream (permitting node deletions). By default (false), the API will return an error if the import would result in the removal of any existing nodes.

onNameConflict
string
Enum: "overwrite" "create-new" "skip"

Specifies how to handle name conflicts during import: overwrite replaces an existing stream, create-new creates a new stream with the provided name if there is no conflict or with the name <name> (Copy) if a conflict exists, and skip skips the import if a stream with the same name exists, returning the existing stream in the response.

solutionId
required
string <= 36 characters

The ID of the solution to which the stream will be imported.

required
object

Defines a complete stream configuration, composed of nodes (instantiated functions) and edges that describe the data flow between them.

Responses

Request samples

Content type
application/json
{
  • "allowNodeDeletion": true,
  • "onNameConflict": "overwrite",
  • "solutionId": "73253be8-0c7c-4670-9631-5a29fe59b4d2",
  • "streamConfig": {
    }
}

Response samples

Content type
application/json
{
  • "importAction": "created",
  • "stream": {
    },
  • "tag": "v1.0"
}

List stream versions

Retrieves a paginated list of all available versions for a specific stream. Each stream version represents a tagged snapshot of the stream configuration, enabling version control, rollback capabilities, and tracking of configuration changes over time. This endpoint supports filtering by resource references to identify versions that use specific collectors, meter keys, or storage resources. Use pagination to navigate through the version history efficiently.

Rate Limits
Each client can make up to 20 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires the scope stream-management:read:streams.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string
Example: 514c23cd-301d-4922-bc9d-d8a3dcb11819

The unique identifier of the stream.

query Parameters
skip
integer

The number of stream versions to skip before starting to return results. Use for pagination.

limit
integer
Example: limit=50

The maximum number of stream versions to return. Use for pagination. The maximum allowed value is 100.

resourceRefs
Array of arrays
Example: resourceRefs=onlineCollector:8a76066d-ff29-417c-a18e-abde22e44310&resourceRefs=meterKey:*

Filter streams versions by associated resource references. Accepts an array of resource references; the response will include versions that reference any of the specified resources (logical OR relationship). Each resource reference must be in the format <resourceType>:<resourceId>. Supported resource types: meterKey, onlineCollector, scriptAggregationStore, dataAggregationStore. Use * as the resourceId to filter by resource type only (e.g., onlineCollector:*).

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "total": 3,
  • "versions": [
    ]
}

List streams

Retrieves a paginated list of streams. Supports filtering by stream name, associated resources, and solution ID. Allows clients to specify which fields to include in the response for efficiency. Results are sorted by createdAt in ascending order (oldest first, newest last), ensuring stable cursor-based pagination where newly created streams appear at the end of the list without interfering with existing pages.

Rate Limits
Each client can make up to 20 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires the scope stream-management:read:streams.

Authorizations:
OAuth 2.0 Bearer Token
query Parameters
solutionId
string
Example: solutionId=73253be8-0c7c-4670-9631-5a29fe59b4d2

Filter streams belonging to a specific solution by its unique solution ID.

fields
string
Example: fields=name,updatedAt

A comma-separated list of fields to include in each stream object in the response. Only the specified fields will be included. If omitted, all fields will be returned.

name
string
Example: name=My Stream

Filter results to streams whose name exactly matches the specified value. Matching is case-sensitive. Wildcards and partial matches are not supported.

resourceRefs
Array of arrays
Example: resourceRefs=onlineCollector:8a76066d-ff29-417c-a18e-abde22e44310&resourceRefs=meterKey:*

Filter streams by associated resource references. Accepts an array of resource references; the response will include streams that reference any of the specified resources (logical OR relationship). Each resource reference must be in the format <resourceType>:<resourceId>. Supported resource types: meterKey, onlineCollector, scriptAggregationStore, dataAggregationStore. Use * as the resourceId to filter by resource type only (e.g., onlineCollector:*).

cursor
string
Example: cursor=eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTAxVDAwOjAwOjAwLjAwMFoiLCJpZCI6IjNmZGVmYTc5LWZlNjMtNDQzNS05ODQ2LTkzNjgyNTkxMjE3MSJ9

To paginate results, use the nextCursor value from the previous response as the cursor parameter in your next request. If nextCursor is not present, there are no more results to fetch.

limit
integer
Example: limit=50

Defines the number of streams to be returned per page. A maximum of 100 items can be returned.

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTAxVDAwOjAwOjAwLjAwMFoiLCJpZCI6IjNmZGVmYTc5LWZlNjMtNDQzNS05ODQ2LTkzNjgyNTkxMjE3MSJ9",
  • "streams": [
    ]
}

Aggregation

Endpoints for managing aggregation sessions.

Lookup script aggregation session

Retrieves a session by calculating its session key from the provided fieldValues, which must be in the same order as the fields defined in your Script aggregator configuration. This endpoint enables direct lookup of a session in the specified aggregation store without pagination.

How it works:
The API uses the values you provide (in the correct order) to generate a unique session key, just like your script aggregation function does. It then looks up and returns the session that matches this key.

Tip: Before using this endpoint, make sure your values match the field order in your Script aggregator function configuration.

Rate Limits
Each client can make up to 50 request(s) every 1s. The burst capacity is 5 request(s).

Authorization scopes
Requires the scope aggregation:read:sessions.

Authorizations:
OAuth 2.0 Bearer Token
path Parameters
id
required
string
Example: 514c23cd-301d-4922-bc9d-d8a3dcb11819

The unique identifier of the aggregation store in which to search for the session. Required to scope the lookup to the correct store.

query Parameters
fieldValues
required
string
Example: fieldValues=customer123&fieldValues=order456

Array of values, in the same order as the fields defined in your script aggregation function configuration, used to generate the session key. Example: fieldValues=customer123&fieldValues=order456

header Parameters
Authorization
required
string

Bearer token for authentication

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2025-10-27T14:04:31.648Z",
  • "data": {
    },
  • "meta": {
    },
  • "timeoutAt": "2025-10-28T16:00:17.645Z",
  • "updatedAt": "2025-10-27T16:00:17.809Z"
}

Global parameters

Create parameter

Use POST /parameters to create a new parameter. Each account is limited to a maximum of 100 parameters.

Rate Limits
Each client can make up to 2 request(s) every 1s. The burst capacity is 4 request(s).

Authorization scopes
Requires the scope global-parameters:create:parameters.

Authorizations:
OAuth 2.0 Bearer Token
header Parameters
Authorization
required
string

Bearer token for authentication.

Request Body schema: application/json
description
string <= 1024 characters

The description of the parameter.

name
required
string [ 1 .. 900 ] characters ^[\w.-]+(?:/[\w.-]+)*$

Must contain only alphanumeric characters, underscores (_), hyphens (-), periods (.), and forward slashes (/). Forward slashes create a hierarchy (e.g., group/subgroup/name). Maximum hierarchy depth: 10 levels. Length: 1-900 characters.

type
required
string
Enum: "standard" "sensitive"

Choose the type on how the data is stored. This is case-sensitive.

  • sensitive: Stores sensitive information which will be encrypted.
  • standard: Stores data as plain text.

The parameter type cannot be updated.

value
required
string [ 1 .. 8192 ] characters

The value of the parameter.

Responses

Request samples

Content type
application/json
{
  • "description": "API key for third-party payment gateway",
  • "name": "credentials/payment-gateway/api-key",
  • "type": "standard",
  • "value": "sk_val_51H8KJ8eXAMPLEKEY1234567890"
}

Response samples

Content type
application/json
{
  • "name": "credentials/payment-gateway/api-key"
}

Delete parameters

Use DELETE /parameters to delete one or more parameters.

Rate Limits
Each client can make up to 1 request(s) every 1s. The burst capacity is 2 request(s).

Authorization scopes
Requires the scope global-parameters:delete:parameters.

Authorizations:
OAuth 2.0 Bearer Token
header Parameters
Authorization
required
string

Bearer token for authentication.

Request Body schema: application/json

A list of parameters that are to be deleted.

parameters
required
Array of strings

An array of unique parameter names to be deleted.

Responses

Request samples

Content type
application/json
{
  • "parameters": [
    ]
}

Response samples

Content type
application/json
{
  • "deletedCount": 1,
  • "deletedParameters": [
    ],
  • "invalidParameters": [
    ]
}

Get parameter

Use GET /parameters/{parameter-name} to retrieve information about a specified parameter.

Rate Limits
Each client can make up to 2 request(s) every 1s. The burst capacity is 4 request(s).

Authorization scopes
Requires the scope global-parameters:read:parameters.

Authorizations:
OAuth 2.0 Bearer Token
header Parameters
Authorization
required
string

Bearer token for authentication.

Responses

Response samples

Content type
application/json
{
  • "description": "API gateway key for external integrations",
  • "name": "credentials/payment-gateway/api-key",
  • "type": "standard",
  • "updatedAt": "2025-01-01T00:00:00.000Z",
  • "value": "sk_val_51H8KJ8eXAMPLEKEY1234567890"
}

List parameters

Use GET /parameters to get a list of parameters.

Rate Limits
Each client can make up to 2 request(s) every 1s. The burst capacity is 4 request(s).

Authorization scopes
Requires the scope global-parameters:read:parameters.

Authorizations:
OAuth 2.0 Bearer Token
query Parameters
limit
string

Defines the number of parameters to be returned. A maximum of 100 items can be returned.

skip
string

Defines an offset for the parameters to be returned. If you set skip to 10, the first 10 parameters will be skipped in the returned list.

sortBy
string
Enum: "name" "description" "updatedAt"

Determines the field in the parameter by which the returned list will be sorted.

sortOrder
string

Determines the sort order of the returned list; ASC for ascending or DESC for descending.

name
string

Defines the name for which parameter should be returned. You may provide full or partial name.

header Parameters
Authorization
required
string

Bearer token for authentication.

Responses

Response samples

Content type
application/json
{
  • "parameters": [
    ]
}

Update parameter

Use PATCH /parameters/{parameter-name} to update the description, the value, or both for a parameter. At least one field (description or value) must be provided.

Rate Limits
Each client can make up to 2 request(s) every 1s. The burst capacity is 4 request(s).

Authorization scopes
Requires the scope global-parameters:update:parameters.

Authorizations:
OAuth 2.0 Bearer Token
header Parameters
Authorization
required
string

Bearer token for authentication.

Request Body schema: application/json
non-empty
description
string <= 1024 characters

The description of the parameter.

value
string [ 1 .. 8192 ] characters

The value of the parameter.

Responses

Request samples

Content type
application/json
{
  • "description": "Updated API gateway key for external integrations",
  • "value": "sk_val_1He58KJ81XAMPLEKEY78956210"
}

Response samples

Content type
application/json
{
  • "name": "credentials/payment-gateway/api-key"
}