Get summary reports

The summary reports add up the call records of a period: one row per account, per sub-customer or per vendor, optionally split further by prefix, country, remote IP or price. They count calls the way the Summary Reports and Vendor Summary Reports screens do and read the call records themselves, so they are exact but cover only the period for which CDRs are kept. For months and years, use Get statistics.

All three methods support trusted mode with i_customer, the customer the report is built for. They read from the database replica, so the newest calls can be missing for a few seconds.

Common parameters

These parameters work the same way in all three methods.

Name	Type	Required	Description
start_date	string	no	Start of the period, UTC, for example 2026-05-20 00:00:00. Also accepted: 2026-05-20T00:00:00, 2026-05-20T00:00:00Z, 20260520T00:00:00 and 00:00:00.000 GMT Wed May 20 2026. Send it as a string, not as a dateTime value. Default: one hour ago
end_date	string	no	End of the period, UTC, same formats. The end is included: a call set up exactly at end_date counts. Default: now
group_by	int	no	Split of the rows, see the values of group_by. Default: 0
cdr_currency	string	no	ISO 4217 code of the currency of all amounts, for example USD. Amounts are converted with your current exchange rates. Default: your base currency
type	string	no	non_zero leaves out calls with zero duration. Default: all
limit	int	no	Return at most this many rows. Default: 0, all rows
offset	int	no	Skip this many rows. Default: 0

Calls are selected by their setup time.

Values of group_by

Every row is first grouped by the account, sub-customer or vendor; group_by adds a second dimension.

Code	Name	Adds to the row
0	name	Nothing: one row per account, sub-customer or vendor (default)
1	prefix	The prefix the call was rated by
2	country	The country of the called number (CLD)
3	remote_ip	The IP address the call came from; for vendors, the destination host
4	prefix_price	The prefix and its prices price_1 and price_n
5	country_description	The country and the destination description of the called number
6	result	getVendorSummaryReport only: the call result code
7	connection	getVendorSummaryReport only: the connection

getAccountSummaryReport accepts the code or the name, and also the short names ip, price and description; any other value is refused. getCustomerSummaryReport and getVendorSummaryReport take the code only, as an int: they do not check the value, and a name such as country gives the plain report without the second dimension.

Report rows

report_data is an array of rows. The fields that identify the row depend on the method and on group_by; the figures are the same in every row.

Name	Type	Description
name	string	The account’s username, the sub-customer’s name or the vendor’s name
i_account, i_customer, i_vendor	int	ID of the account, sub-customer or vendor, depending on the method
prefix	string	group_by 1 and 4
price_1, price_n	double	group_by 4: price of the first and of the next billing intervals, in cdr_currency
remote_ip	string	group_by 3
country	string	The destination country for group_by 1, 2, 4 and 5. Unknown for the other groupings and when no destination matches
description	string	The destination description for group_by 1, 4 and 5; the account’s or sub-customer’s own description for group_by 0; otherwise empty
number_of_calls	int	Number of calls
billable_calls	int	Calls with a duration above zero
duration	double	Total duration, seconds
billed_duration	double	Total billed duration, seconds
revenue	double	What the calls were charged, in cdr_currency. Not in vendor rows
cost	double	What the calls cost, in cdr_currency

The response also carries currency, start_date and end_date as sent, group_by and the totals total_number_of_calls, total_billable_calls, total_duration, total_billed_duration, total_revenue and total_cost.

Caution

The totals are the sums of the rows returned. With a limit they cover only that page. Leave limit at 0 when you need the totals of the whole period.

getAccountSummaryReport

Returns one row per account of the authenticated customer. Accounts of your sub-customers are not included; use getCustomerSummaryReport for them. Any customer may call it.

revenue is what the accounts were charged. cost is what the same calls cost you: what the vendors charged for the root customer, summed over every vendor attempt of a call, and what your wholesaler charged for a reseller.

Parameters

The common parameters, plus:

Name	Type	Required	Description
i_account	int	no	Report only this account
only_connected_calls	boolean	no	True counts only calls that reached at least one vendor; False also counts calls that were refused before routing. Default: True

Returns

Name	Type	Description
result	string	OK
report_data	array	Report rows with name (the username) and i_account
currency, start_date, end_date, group_by, total_*		See Report rows

Example

request

call("getAccountSummaryReport", {
    "start_date": "2026-05-20 00:00:00",
    "end_date": "2026-05-20 23:59:59",
    "group_by": "country",
    "cdr_currency": "USD",
})

response

{
    "result": "OK",
    "report_data": [
        {
            "name": "1001",
            "i_account": 3092,
            "country": "Ukraine",
            "description": "",
            "number_of_calls": 17,
            "billable_calls": 15,
            "duration": 583.0,
            "billed_duration": 600.0,
            "revenue": 12.34,
            "cost": 4.56,
        },
    ],
    "currency": "USD",
    "start_date": "2026-05-20 00:00:00",
    "end_date": "2026-05-20 23:59:59",
    "group_by": 2,
    "total_number_of_calls": 17,
    "total_billable_calls": 15,
    "total_duration": 583.0,
    "total_billed_duration": 600.0,
    "total_revenue": 12.34,
    "total_cost": 4.56,
}

getCustomerSummaryReport

Returns one row per direct sub-customer of the authenticated customer. Any customer may call it; a customer without sub-customers gets an empty report.

revenue is what you charged the sub-customer for its calls. cost is what the same calls cost you: what the vendors charged for the root customer, what your wholesaler charged for a reseller.

Parameters

The common parameters, plus:

Name	Type	Required	Description
i_customer_filter	int	no	Report only this sub-customer

Send group_by as an int, see the values of group_by.

Returns

Name	Type	Description
result	string	OK
report_data	array	Report rows with name and i_customer of the sub-customer
currency, start_date, end_date, group_by, total_*		See Report rows

Example

request

call("getCustomerSummaryReport", {
    "start_date": "2026-05-01 00:00:00",
    "end_date": "2026-05-31 23:59:59",
    "group_by": 1,
    "i_customer_filter": 7,
})

response

{
    "result": "OK",
    "report_data": [
        {
            "name": "Sub-reseller LLC",
            "i_customer": 7,
            "prefix": "380",
            "country": "Ukraine",
            "description": "Fixed",
            "number_of_calls": 124,
            "billable_calls": 98,
            "duration": 4231.0,
            "billed_duration": 4500.0,
            "revenue": 89.1,
            "cost": 41.2,
        },
    ],
    "currency": "USD",
    "start_date": "2026-05-01 00:00:00",
    "end_date": "2026-05-31 23:59:59",
    "group_by": 1,
    "total_number_of_calls": 124,
    # … the other totals
}

getVendorSummaryReport

Returns one row per vendor with what the vendor charged. Only the root customer may call it.

Every vendor attempt counts as a call: a call that failed over from one vendor to another appears once at each vendor. Rows have no revenue, and total_revenue is always 0.

Parameters

The common parameters, plus:

Name	Type	Required	Description
i_vendor	int	no	Report only this vendor

Send group_by as an int, see the values of group_by.

Returns

Name	Type	Description
result	string	OK
report_data	array	Report rows with name and i_vendor of the vendor. group_by 6 adds result; group_by 7 adds connection_name and connection_id. With group_by 2 and 5 the country also comes as c_name and the description as descr
i_vendor	int	The i_vendor sent, or None
currency, start_date, end_date, group_by, total_*		See Report rows

Example

request

call("getVendorSummaryReport", {
    "start_date": "2026-05-20 00:00:00",
    "end_date": "2026-05-20 23:59:59",
    "group_by": 7,
})

response

{
    "result": "OK",
    "report_data": [
        {
            "name": "Carrier A",
            "i_vendor": 11,
            "connection_name": "carrier-a-main",
            "connection_id": 23,
            "country": "Unknown",
            "description": "",
            "number_of_calls": 92,
            "billable_calls": 71,
            "duration": 3120.0,
            "billed_duration": 3300.0,
            "cost": 28.74,
        },
    ],
    "currency": "USD",
    "start_date": "2026-05-20 00:00:00",
    "end_date": "2026-05-20 23:59:59",
    "group_by": 7,
    "i_vendor": None,
    "total_number_of_calls": 92,
    "total_revenue": 0,
    "total_cost": 28.74,
    # … the other totals
}

Errors

faultCode	faultString	Cause
401	You do not have permissions to use this API call.	getVendorSummaryReport was called by a customer other than the root customer
402	Unrecognized date format in start_date.	start_date or end_date is in none of the accepted formats
402	Unknown group_by code: 9. or Unknown group_by value: 'city'.	getAccountSummaryReport only: group_by is not one of the listed values
404	Customer not found	The customer named by i_customer in trusted mode does not exist

Related

• Reports: the Summary Reports and Vendor Summary Reports screens
• Get statistics: the same kind of summary for long periods, from pre-aggregated data
• Get the DID summary report
• Get CDRs of an account: the calls behind the figures
• Call records (CDRs)
• Exchange rates