REST Services Manager API for Billing and Revenue Management

Get Usage

get

/usage

Gets the usage resource that matches the specified query criteria.

Request

Query Parameters

@type: string

The type of object to return.

Example:

Use @type=Usage for a base object, or @type=UsageOracle for an extended object.

description: string
Retrieves the usage whose description matches the specified description.
Example:
```
description=Cycle Forward Fees (srvc):Standard GSM Telephony
```
description.like: string
Retrieves the usage whose description is similar to the specified description.
Example:
```
description.like=Cycle Forward Fees (srvc):Standard GSM Telephony
```
fields: string
The list of fields to return in the response.
Example:
```
fields=type,status
```

id: string

The ID of the usage to get.

Example:

id=0.0.0.1+-event-billing-product-fee-cycle-cycle_forward_monthly+32341474824064940

limit: integer
The maximum number of results to return.
Example:
```
Use limit=10 to return the first 10 results only.
```
offset: integer
The number of results to offset the response by.
Example:
```
Use offset=10 to return results 10 and higher.
```
usageDate: string
Retrieves the usage with a date that is equal to the specified dateTime.
Example:
```
usageDate=2020-01-01T04:00:27-08:00
```
usageDate.gt: string
Retrieves the usage with a date that is greater than the specified dateTime.
Example:
```
usageDate.gt=2020-01-01T04:00:27-08:00
```
usageDate.gte: string
Retrieves the usage with a date that is greater than or equal to the specified dateTime.
Example:
```
usageDate.gte=2020-01-01T04:00:27-08:00
```
usageDate.lt: string
Retrieves the usage whose date is less than the specified dateTime.
Example:
```
usageDate.lt=2020-01-01T04:00:27-08:00
```
usageDate.lte: string
Retrieves the usage with a date that is less than or equal to the specified dateTime.
Example:
```
usageDate.lte=2020-01-01T04:00:27-08:00
```

There's no request body for this operation.

Response

Supported Media Types

application/json

200 Response

The usage was returned successfully.

Root Schema : schema

Type: array

Show Source

Array of: object Usage

Title: Usage

A instance of usage.

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/Usage"
    }
}

Nested Schema : Usage

Type: object

Title: Usage

A instance of usage.

Show Source

@baseType: string

The object's superclass.
@schemaLocation: string (uri)

A URI to a JSON schema file that defines additional attributes and relationships.
@type: string

The object's subclass.
description: string

Title: Usage Description

The usage's description
href: string (uri)

Title: Usage Href

The usage's href.
id: string

Title: Usage ID

The usage's ID.
ratedProductUsage: array ratedProductUsage

The usage's rating details.
relatedParty: array relatedParty

The parties related to the usage.
status: string

Title: Usage Status

Allowed Values: [ "received", "rejected", "recycled", "guided", "rated", "rerated", "billed" ]

The usage's status.
usageCharacteristic: array usageCharacteristic

The usage's characteristics.
usageDate: string (date-time)

Title: Usage Date

The usage's date.
usageSpecification: object Usage Specification Ref

Title: Usage Specification Ref

A usage specification reference.
usageType: string

Title: Usage Type

The usage's type.

{
    "type":"object",
    "title":"Usage",
    "description":"A instance of usage.",
    "properties":{
        "id":{
            "type":"string",
            "title":"Usage ID",
            "description":"The usage's ID."
        },
        "href":{
            "type":"string",
            "format":"uri",
            "title":"Usage Href",
            "description":"The usage's href."
        },
        "usageDate":{
            "type":"string",
            "title":"Usage Date",
            "description":"The usage's date.",
            "format":"date-time"
        },
        "usageType":{
            "type":"string",
            "title":"Usage Type",
            "description":"The usage's type."
        },
        "description":{
            "type":"string",
            "title":"Usage Description",
            "description":"The usage's description"
        },
        "status":{
            "description":"The usage's status.",
            "$ref":"#/components/schemas/UsageStatusType"
        },
        "usageSpecification":{
            "description":"The usage's specification.",
            "$ref":"#/components/schemas/UsageSpecificationRef"
        },
        "usageCharacteristic":{
            "type":"array",
            "description":"The usage's characteristics.",
            "items":{
                "$ref":"#/components/schemas/UsageCharacteristic"
            }
        },
        "relatedParty":{
            "type":"array",
            "description":"The parties related to the usage.",
            "items":{
                "$ref":"#/components/schemas/RelatedParty"
            }
        },
        "ratedProductUsage":{
            "type":"array",
            "description":"The usage's rating details.",
            "items":{
                "$ref":"#/components/schemas/RatedProductUsage"
            }
        },
        "@baseType":{
            "type":"string",
            "description":"The object's superclass."
        },
        "@schemaLocation":{
            "type":"string",
            "format":"uri",
            "description":"A URI to a JSON schema file that defines additional attributes and relationships."
        },
        "@type":{
            "type":"string",
            "description":"The object's subclass."
        }
    }
}

Nested Schema : ratedProductUsage

Type: array

The usage's rating details.

Show Source

Array of: object Rated Product Usage

Title: Rated Product Usage

An instance of rated usage.

{
    "type":"array",
    "description":"The usage's rating details.",
    "items":{
        "$ref":"#/components/schemas/RatedProductUsage"
    }
}

Nested Schema : relatedParty

Type: array

The parties related to the usage.

Show Source

Array of: object Related Party

Title: Related Party

A party related to another object.

{
    "type":"array",
    "description":"The parties related to the usage.",
    "items":{
        "$ref":"#/components/schemas/RelatedParty"
    }
}

Nested Schema : usageCharacteristic

Type: array

The usage's characteristics.

Show Source

Array of: object Usage Characteristic

Title: Usage Characteristic

A characteristic of usage.

{
    "type":"array",
    "description":"The usage's characteristics.",
    "items":{
        "$ref":"#/components/schemas/UsageCharacteristic"
    }
}

Nested Schema : Usage Specification Ref

Type: object

Title: Usage Specification Ref

A usage specification reference.

Show Source

@baseType: string

Title: Base Type

The object's superclass.
@referredType: string

Title: Referred Type

The object's type in the target system, if baseType and type need further disambiguation.
@schemaLocation: string (uri)

Title: Schema Location

A URI to a JSON-Schema file that defines additional attributes and relationships.
@type: string

Title: Type

The object's subclass.
href: string (uri)

Title: Usage Specification Href

The usage specification's href.
id(required): string

Title: Usage Specification ID

The usage specification's ID.
name: string

Title: Usage Specification Name

The usage specification's name.

{
    "type":"object",
    "title":"Usage Specification Ref",
    "description":"A usage specification reference.",
    "properties":{
        "id":{
            "type":"string",
            "title":"Usage Specification ID",
            "description":"The usage specification's ID."
        },
        "href":{
            "type":"string",
            "format":"uri",
            "title":"Usage Specification Href",
            "description":"The usage specification's href."
        },
        "name":{
            "type":"string",
            "title":"Usage Specification Name",
            "description":"The usage specification's name."
        },
        "@baseType":{
            "type":"string",
            "title":"Base Type",
            "description":"The object's superclass."
        },
        "@schemaLocation":{
            "type":"string",
            "format":"uri",
            "title":"Schema Location",
            "description":"A URI to a JSON-Schema file that defines additional attributes and relationships."
        },
        "@type":{
            "type":"string",
            "title":"Type",
            "description":"The object's subclass."
        },
        "@referredType":{
            "type":"string",
            "title":"Referred Type",
            "description":"The object's type in the target system, if <b>baseType</b> and <b>type</b> need further disambiguation."
        }
    },
    "required":[
        "id"
    ]
}

Nested Schema : Rated Product Usage

Type: object

Title: Rated Product Usage

An instance of rated usage.

Show Source

@baseType: string

Title: Base Type

The object's superclass.
@schemaLocation: string (uri)

Title: Schema Location

A URI to a JSON-Schema file that defines additional attributes and relationships.
@type: string

Title: Type

The object's subclass.
bucketValueConvertedInAmount: object Money

The base / value business entity used to represent money.
isBilled: boolean

Title: Is Billed

Whether the usage has been billed (true) or not (false).
isTaxExempt: boolean

Title: Is Tax Exempt

Whether the usage is tax exempt (true) or not (false).
offerTariffType: string

Title: Offer Tariff Type

The tariff's type.
productRef: object Product Ref

Title: Product Ref

A reference to a product.
ratingAmountType: string

Title: Rating Amount Type

The rating amount's type.
ratingDate: string (date-time)

Title: Rating Date

The date the usage was rated.
taxExcludedRatingAmount: object Money

The base / value business entity used to represent money.
taxIncludedRatingAmount: object Money

The base / value business entity used to represent money.
taxRate: number (float)

Title: Tax Rate

The tax rate.
usageRatingTag: string

Title: Usage Rating Tag

The usage rating's tag.

{
    "type":"object",
    "title":"Rated Product Usage",
    "description":"An instance of rated usage.",
    "properties":{
        "ratingDate":{
            "type":"string",
            "format":"date-time",
            "title":"Rating Date",
            "description":"The date the usage was rated."
        },
        "usageRatingTag":{
            "type":"string",
            "title":"Usage Rating Tag",
            "description":"The usage rating's tag."
        },
        "isBilled":{
            "type":"boolean",
            "title":"Is Billed",
            "description":"Whether the usage has been billed (<b>true</b>) or not (<b>false</b>)."
        },
        "ratingAmountType":{
            "type":"string",
            "title":"Rating Amount Type",
            "description":"The rating amount's type."
        },
        "taxRate":{
            "type":"number",
            "format":"float",
            "title":"Tax Rate",
            "description":"The tax rate."
        },
        "isTaxExempt":{
            "type":"boolean",
            "description":"Whether the usage is tax exempt (<b>true</b>) or not (<b>false</b>).",
            "title":"Is Tax Exempt"
        },
        "offerTariffType":{
            "type":"string",
            "title":"Offer Tariff Type",
            "description":"The tariff's type."
        },
        "bucketValueConvertedInAmount":{
            "title":"Bucket Value Converted In Amount",
            "description":"The rating amount, converted from a bucket value.",
            "$ref":"#/components/schemas/Money"
        },
        "productRef":{
            "title":"Product Ref",
            "description":"The product related to the rated product.",
            "$ref":"#/components/schemas/ProductRef"
        },
        "taxExcludedRatingAmount":{
            "title":"Tax Excluded Rating Amount",
            "description":"The rating amount, with tax excluded.",
            "$ref":"#/components/schemas/Money"
        },
        "taxIncludedRatingAmount":{
            "title":"Tax Included Rating Amount",
            "description":"The rating amount, with tax included.",
            "$ref":"#/components/schemas/Money"
        },
        "@baseType":{
            "type":"string",
            "title":"Base Type",
            "description":"The object's superclass."
        },
        "@schemaLocation":{
            "type":"string",
            "format":"uri",
            "title":"Schema Location",
            "description":"A URI to a JSON-Schema file that defines additional attributes and relationships."
        },
        "@type":{
            "type":"string",
            "title":"Type",
            "description":"The object's subclass."
        }
    }
}

Nested Schema : Money

Type: object

The base / value business entity used to represent money.

Show Source

unit: string

The currency (ISO4217 norm uses 3 letters to define the currency).
value: number (float)

The signed floating point number, the meaning of the sign is according to the context of the API that uses this Data type

{
    "type":"object",
    "description":"The base / value business entity used to represent money.",
    "properties":{
        "unit":{
            "type":"string",
            "description":"The currency (ISO4217 norm uses 3 letters to define the currency)."
        },
        "value":{
            "type":"number",
            "format":"float",
            "description":"The signed floating point number, the meaning of the sign is according to the context of the API that uses this Data type"
        }
    }
}

Nested Schema : Product Ref

Type: object

Title: Product Ref

A reference to a product.

Show Source

@baseType: string

Title: Base Type

The object's superclass.
@referredType: string

Title: Referred Type

The object's type in the target system, if baseType and type need further disambiguation.
@schemaLocation: string (uri)

Title: Schema Location

A URI to a JSON schema file that defines additional attributes and relationships.
@type: string

Title: Type

The object's subclass.
href: string

Title: Product Href

The product's href.
id(required): string

Title: Product ID

The product's ID.
name: string

Title: Product Name

The product's name.

{
    "required":[
        "id"
    ],
    "type":"object",
    "title":"Product Ref",
    "description":"A reference to a product.",
    "properties":{
        "@baseType":{
            "type":"string",
            "title":"Base Type",
            "description":"The object's superclass."
        },
        "@referredType":{
            "type":"string",
            "title":"Referred Type",
            "description":"The object's type in the target system, if <b>baseType</b> and <b>type</b> need further disambiguation."
        },
        "@schemaLocation":{
            "type":"string",
            "title":"Schema Location",
            "description":"A URI to a JSON schema file that defines additional attributes and relationships.",
            "format":"uri"
        },
        "@type":{
            "type":"string",
            "title":"Type",
            "description":"The object's subclass."
        },
        "href":{
            "type":"string",
            "title":"Product Href",
            "description":"The product's href."
        },
        "id":{
            "type":"string",
            "title":"Product ID",
            "description":"The product's ID."
        },
        "name":{
            "type":"string",
            "title":"Product Name",
            "description":"The product's name."
        }
    }
}

Nested Schema : Related Party

Type: object

Title: Related Party

A party related to another object.

Show Source

@baseType: string

Title: Base Type

The object's superclass.
@referredType(required): string

Title: Referred Type

The object's type in the target system, if baseType and type need further disambiguation.
@schemaLocation: string (uri)

Title: Schema Location

A URI to a JSON schema file that defines additional attributes and relationships.
@type: string

Title: Type

The object's subclass.
href: string (uri)

Title: Href

The party's href.
id(required): string

Title: Party ID

The party's ID.
name: string

Title: Party Name

The party's name.
role: string

Title: Party Role

The party's role.

{
    "required":[
        "@referredType",
        "id"
    ],
    "type":"object",
    "title":"Related Party",
    "properties":{
        "@baseType":{
            "type":"string",
            "title":"Base Type",
            "description":"The object's superclass."
        },
        "@referredType":{
            "type":"string",
            "title":"Referred Type",
            "description":"The object's type in the target system, if <b>baseType</b> and <b>type</b> need further disambiguation."
        },
        "@schemaLocation":{
            "type":"string",
            "title":"Schema Location",
            "description":"A URI to a JSON schema file that defines additional attributes and relationships.",
            "format":"uri"
        },
        "@type":{
            "type":"string",
            "title":"Type",
            "description":"The object's subclass."
        },
        "href":{
            "type":"string",
            "title":"Href",
            "description":"The party's href.",
            "format":"uri"
        },
        "id":{
            "type":"string",
            "title":"Party ID",
            "description":"The party's ID."
        },
        "name":{
            "type":"string",
            "title":"Party Name",
            "description":"The party's name."
        },
        "role":{
            "type":"string",
            "title":"Party Role",
            "description":"The party's role."
        }
    },
    "description":"A party related to another object."
}

Nested Schema : Usage Characteristic

Type: object

Title: Usage Characteristic

A characteristic of usage.

Show Source

@baseType: string

The object's superclass.
@schemaLocation: string (uri)

A URI to a JSON schema file that defines additional attributes and relationships.
@type: string

The object's subclass.
characteristicRelationship: array characteristicRelationship

The characteristic's relationships.
id: string

The usage characteristic's ID.
name(required): string

Title: Usage Characteristic Name

The characteristic's name.
value(required): object Any
valueType: string

The type of the characteristic's value.

{
    "type":"object",
    "title":"Usage Characteristic",
    "description":"A characteristic of usage.",
    "properties":{
        "id":{
            "type":"string",
            "description":"The usage characteristic's ID."
        },
        "name":{
            "type":"string",
            "title":"Usage Characteristic Name",
            "description":"The characteristic's name."
        },
        "valueType":{
            "type":"string",
            "description":"The type of the characteristic's value."
        },
        "characteristicRelationship":{
            "type":"array",
            "description":"The characteristic's relationships.",
            "items":{
                "$ref":"#/components/schemas/CharacteristicRelationship"
            }
        },
        "value":{
            "description":"The characteristic's value.",
            "$ref":"#/components/schemas/Any"
        },
        "@baseType":{
            "type":"string",
            "description":"The object's superclass."
        },
        "@schemaLocation":{
            "type":"string",
            "format":"uri",
            "description":"A URI to a JSON schema file that defines additional attributes and relationships."
        },
        "@type":{
            "type":"string",
            "description":"The object's subclass."
        }
    },
    "required":[
        "name",
        "value"
    ]
}

Nested Schema : characteristicRelationship

Type: array

The characteristic's relationships.

Show Source

Array of: CharacteristicRelationship

{
    "type":"array",
    "description":"The characteristic's relationships.",
    "items":{
        "$ref":"#/components/schemas/CharacteristicRelationship"
    }
}

Nested Schema : Any

Type: object

Nested Schema : CharacteristicRelationship

Match All

The characteristic that is related to the current Characteristic.

Show Source

object Extensible

The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
object CharacteristicRelationship-allOf[1]

The characteristic that is related to the current Characteristic.

{
    "allOf":[
        {
            "$ref":"#/components/schemas/Extensible"
        },
        {
            "type":"object",
            "description":"The characteristic that is related to the current Characteristic.",
            "properties":{
                "id":{
                    "type":"string",
                    "description":"The unique identifier of the characteristic."
                },
                "relationshipType":{
                    "type":"string",
                    "description":"The type of relationship."
                }
            }
        }
    ]
}

Nested Schema : Extensible

Type: object

The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type

Show Source

@baseType: string

The defines the super-class when sub-classing.
@schemaLocation: string

The URI to a JSON-Schema file that defines additional attributes and relationships
@type(required): string

The definition of the sub-class extensible name, when sub-classing.

{
    "type":"object",
    "description":"The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema  MUST be extended with the @type",
    "properties":{
        "@type":{
            "type":"string",
            "description":"The definition of the sub-class extensible name, when sub-classing."
        },
        "@baseType":{
            "type":"string",
            "description":"The defines the super-class when sub-classing."
        },
        "@schemaLocation":{
            "type":"string",
            "description":"The URI to a JSON-Schema file that defines additional attributes and relationships"
        }
    },
    "required":[
        "@type"
    ]
}

Nested Schema : CharacteristicRelationship-allOf[1]

Type: object

The characteristic that is related to the current Characteristic.

Show Source

id: string

The unique identifier of the characteristic.
relationshipType: string

The type of relationship.

{
    "type":"object",
    "description":"The characteristic that is related to the current Characteristic.",
    "properties":{
        "id":{
            "type":"string",
            "description":"The unique identifier of the characteristic."
        },
        "relationshipType":{
            "type":"string",
            "description":"The type of relationship."
        }
    }
}

400 Response

Request error

500 Response

Unexpected server error

Examples

The following example shows how to get usage data by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.

The request uses the limit query parameter to limit the results.

curl -X GET 'http://host:port/brm/usageManagement/version/usage?limit=2'

Example of the Response Body

The following example shows the contents of the response body in JSON format.

[
    {
        "@baseType": "Usage",
        "@schemaLocation": null,
        "@type": "Usage",
        "id": "0.0.0.1+-event-billing-product-fee-cycle-cycle_forward_monthly+326088760519522593",
        "href": "http://host:port/brm/usageManagement/version/usage/0.0.0.1+-event-billing-product-fee-cycle-cycle_forward_monthly+326088760519522593",
        "date": "2025-08-14T00:00:00-07:00",
        "type": "EventBillingProductFeeCycleCycle_forward_monthly",
        "status": "Rated",
        "usageSpecification": null,
        "usageCharacteristic": null,
        "relatedParty": null,
        "ratedProductUsage": [
            {
                "@baseType": null,
                "@schemaLocation": null,
                "@type": null,
                "ratingDate": "2025-08-14T00:00:00-07:00",
                "usageRatingTag": "Rate 1",
                "isBilled": null,
                "ratingAmountType": null,
                "taxExcludedAmount": {
                    "unit": "USD",
                    "value": 20.0
                },
                "taxIncludedAmount": {
                    "unit": "USD",
                    "value": 20.0
                },
                "taxRate": 0.0,
                "isTaxExempt": null,
                "offerTariffType": null,
                "bucketValueConvertedInAmount": null,
                "productRef": null
            }
        ]
    },
    {
        "@baseType": "Usage",
        "@schemaLocation": null,
        "@type": "Usage",
        "id": "0.0.0.1+-event-billing-product-fee-cycle-cycle_forward_monthly+326088760519524129",
        "href": "http://host:port/brm/usageManagement/version/usage/0.0.0.1+-event-billing-product-fee-cycle-cycle_forward_monthly+326088760519524129",
        "date": "2025-09-14T00:00:00-07:00",
        "type": "EventBillingProductFeeCycleCycle_forward_monthly",
        "status": "Rated",
        "usageSpecification": null,
        "usageCharacteristic": null,
        "relatedParty": null,
        "ratedProductUsage": [
            {
                "ratingDate": "2025-09-14T00:00:00-07:00",
                "usageRatingTag": "Rate 1",
                "isBilled": null,
                "ratingAmountType": null,
                "taxExcludedAmount": {
                    "unit": "USD",
                    "value": 40.0
                },
                "taxIncludedAmount": {
                    "unit": "USD",
                    "value": 40.0
                },
                "taxRate": 0.0,
                "isTaxExempt": null,
                "offerTariffType": null,
                "bucketValueConvertedInAmount": null,
                "productRef": null
            }
        ]
    }
]