Skip to main content
Aria Knowledge Central

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.

TOP
  • Was this article helpful?