get_usage_history_m Sample Call and Response
This example retrieves individual usage history records for an account, filtered by a master plan instance, a specific usage type, and a date range, based on the method definition in plsql_m_r73.yml.
This example includes every required field and a representative set of commonly used optional fields, not every field the method accepts.
Sample call
{
"rest_call": "get_usage_history_m",
"output_format": "json",
"client_no": 10023,
"auth_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"acct_no": 3300481,
"master_plan_instance_no": 20200456,
"specified_usage_type_no": 4021,
"date_range_start": "2026-06-01 00:00:00",
"date_range_end": "2026-06-30 23:59:59",
"usage_qualifier_1": ["CALL-INTL"],
"limit": 50,
"offset": 0,
"retrieve_excluded_usage": "false",
"billed_filter": 0
}
The envelope fields rest_call and output_format are added by the REST layer and are not part of the method’s own documented arguments. The account is identified with acct_no rather than its alternative, client_acct_id. The master plan instance is identified with master_plan_instance_no rather than its alternative, client_master_plan_instance_id, and the usage type is identified with specified_usage_type_no rather than its alternative, specified_usage_type_code. The usage_qualifier_1 field is represented as an array because its description names it as a list of filters; this example passes only one filter value, but you may pass more than one. The billed_filter value of zero means the call returns both billed and unbilled usage records; values one and two restrict the results to billed-only or unbilled-only records. The retrieve_excluded_usage value of false means usage records that were permanently excluded from billing are not returned.
Sample response
{
"error_code": 0,
"error_msg": "OK",
"error_details": "",
"usage_history_recs": [
{
"billable_acct_no": 3300481,
"incurring_acct_no": 3300481,
"client_billable_acct_id": "ACME-3300481",
"client_incurring_acct_id": "ACME-3300481",
"plan_instance_id": 20200456,
"client_plan_instance_id": "ACME-PLAN-55019",
"usage_type_no": 4021,
"usage_type_description": "International Call Minutes",
"usage_date": "2026-06-14",
"usage_time": "14:32:07",
"units": 12.5,
"units_description": "minutes",
"invoice_no": 8820044,
"is_excluded": "false",
"qualifier_1": "CALL-INTL",
"recorded_units": 12.5,
"usage_rec_no": 990144221,
"usage_type_code": "INTL_MIN",
"usage_record_pre_taxed_ind": 2,
"usage_record_tax_inclusive_ind": 0
},
{
"billable_acct_no": 3300481,
"incurring_acct_no": 3300481,
"client_billable_acct_id": "ACME-3300481",
"client_incurring_acct_id": "ACME-3300481",
"plan_instance_id": 20200456,
"client_plan_instance_id": "ACME-PLAN-55019",
"usage_type_no": 4021,
"usage_type_description": "International Call Minutes",
"usage_date": "2026-06-18",
"usage_time": "09:11:52",
"units": 4.0,
"units_description": "minutes",
"invoice_no": 8820044,
"is_excluded": "false",
"qualifier_1": "CALL-INTL",
"recorded_units": 4.0,
"usage_rec_no": 990144399,
"usage_type_code": "INTL_MIN",
"usage_record_pre_taxed_ind": 2,
"usage_record_tax_inclusive_ind": 0
}
],
"filtered_usage_count": 2
}
An error_code of zero and an error_msg of OK indicate that the call succeeded. The usage_history_recs array holds one entry per usage record that matches the filters; this example shows two entries for clarity, and a real account could return many more. This example leaves out the invoice_no and invoice_line_item filters (used instead of a date range), the usage_qualifier_2 through usage_qualifier_4 filters, client_record_id, locale_no and locale_name (and the corresponding acct_locale_no and acct_locale_name response fields), the usage_field response field, and the usage_record_tax_details response array. The usage_field response field is left out because the yml marks it usage: unused, meaning the system never actually populates it, and the include_usage_fields input field that appears to control it is itself marked nonpublic and usage: unused, so it has no real effect and is left out of the call as well.