Get the DID summary report

getDidSummaryReport adds up the calls that arrived on your DIDs over a period: one row per DID, per account or sub-customer the DID is assigned to, per charging group, per country of the caller or per call result, with revenue, cost and profit in one currency. It returns the same figures as the DID Summary Reports screen.

Any customer with the DID Pool right may call it, the root customer included. The report covers the DID calls of your own accounts and of your direct sub-customers, the same calls the DIDs Call Records screen shows you. The method supports trusted mode with i_customer and reads from the database replica, so the newest calls can be missing for a few seconds.

Parameters

Name	Type	Required	Description
start_date	string	no	Start of the period, UTC, for example 2026-09-01 00:00:00. The formats of the summary reports are also accepted. Default: today 00:00 UTC
end_date	string	no	End of the period, UTC, included. Default: now
group_by	string	no	What one row stands for, see the values of group_by. Default: did
scope	string	no	all (default), accounts for the DIDs of your own accounts only, customers for the DIDs of your sub-customers only
i_account	int	no	Report only this account of yours. Sets scope to accounts
i_sub_customer	int	no	Report only this sub-customer. Sets scope to customers. Do not send it together with i_account
i_did	int	no	Report only this DID
did	string	no	Report only DIDs that match this pattern. With did_clause 0 and 1 use % for any characters and _ for one; separate several patterns with commas or spaces, up to 50
did_clause	int	no	How did is applied: 0 matches (default), 1 does not match, 2 matches the regular expression (SQL SIMILAR TO), 3 does not match it
result	string	no	Which calls count, see the values of result. Default: all
cdr_currency	string	no	ISO 4217 code of the currency of all amounts. Amounts are converted with your current exchange rates. Default: your base currency
sort_by	string	no	name (the grouping columns), number_of_calls, connected_calls, duration, billed_duration, revenue, cost or profit. Default: duration
sort_dir	string	no	asc or desc (default)
limit	int	no	Return at most this many rows. Default: 0, all rows
offset	int	no	Skip this many rows. Default: 0

Values of group_by

The numbers 0 to 6 are accepted instead of the names, in this order.

Value	One row per	Fields added to the row
did	DID	i_did, did
did_owner	DID and the account or sub-customer that received the call	i_did, did, owner_type (account or customer), i_owner, owner_name
owner	Account or sub-customer	owner_type, i_owner, owner_name
charging_group	Charging group	i_dids_charging_group (0 for none), charging_group (its name)
cli_country	Country of the caller’s number	country_iso, country
cli_country_description	Destination of the caller’s number	prefix, country_iso, country, description
result	Call result	result, result_text

The charging group is the one attached to the DID now, not at the time of the call; when the DID was delegated to you, the group of the delegation wins over the group of the pool entry. The caller’s country is found by the longest destination prefix that matches the CLI.

Values of result

The classic codes in the second column are accepted as well.

Value	Code	Counts
all	1	Every call, failed ones included (default)
incomplete	2	Calls that were not answered, without the internal errors
non_zero_and_errors	3	Calls with a duration above zero and calls that failed with an internal error
non_zero	4	Calls with a duration above zero
complete	5	Answered calls
errors	6	Calls that failed with an internal error

Returns

Name	Type	Description
result	string	OK
report_data	array	The rows, see below
total_rows	int	Number of rows of the whole report, regardless of limit and offset
totals	struct	number_of_calls, connected_calls, duration, billed_duration, revenue, cost and profit of the whole report, regardless of limit and offset
currency	string	Currency of all amounts
start_date, end_date	string	The period used, UTC, YYYY-MM-DD HH:MM:SS
group_by, scope, sort_by, sort_dir	string	The values used, as names
rights	struct	is_root and did_pool, booleans: whether you are the root customer and have the DID pool

Each row of report_data has the fields of its group_by and these figures:

Name	Type	Description
number_of_calls	int	Number of calls
connected_calls	int	Calls with a duration above zero
duration	double	Total duration, seconds
billed_duration	double	Total billed duration, seconds
revenue	double	What you charged your account or sub-customer for the calls
cost	double	What the same calls cost you: the DID vendor’s charge for the root customer, your wholesaler’s charge for a reseller
profit	double	revenue minus cost

result_text is OK for an answered call, SIP error 486 and the like for a SIP failure, Timeout for a call that got no final answer, and the description of the error for an internal error.

Example

request

call("getDidSummaryReport", {
    "start_date": "2026-09-01 00:00:00",
    "end_date": "2026-09-10 23:59:59",
    "group_by": "did_owner",
    "result": "non_zero",
    "limit": 50,
})

response

{
    "result": "OK",
    "report_data": [
        {
            "i_did": 512,
            "did": "380441234567",
            "owner_type": "account",
            "i_owner": 3092,
            "owner_name": "1001",
            "number_of_calls": 92,
            "connected_calls": 92,
            "duration": 3120.0,
            "billed_duration": 3300.0,
            "revenue": 12.4,
            "cost": 4.1,
            "profit": 8.3,
        },
        # … up to 50 rows
    ],
    "total_rows": 17,
    "totals": {
        "number_of_calls": 340,
        "connected_calls": 340,
        "duration": 12034.0,
        "billed_duration": 12600.0,
        "revenue": 51.2,
        "cost": 17.9,
        "profit": 33.3,
    },
    "currency": "USD",
    "start_date": "2026-09-01 00:00:00",
    "end_date": "2026-09-10 23:59:59",
    "group_by": "did_owner",
    "scope": "all",
    "sort_by": "duration",
    "sort_dir": "desc",
    "rights": {"is_root": False, "did_pool": True},
}

Errors

faultCode	faultString	Cause
401	You do not have permissions to use this API call.	The DID pool is not enabled for your customer
402	Unknown group_by: city, Unknown scope: all_dids, Unknown result filter: ok, Unknown sort_by: margin	A value outside the lists above
402	i_account and i_sub_customer are mutually exclusive.	Both were sent
402	start_date must not be later than end_date.	The period is reversed
402	Unrecognized date format in start_date.	start_date or end_date is in none of the accepted formats
402	Parameter limit must be an integer., Parameter i_did is out of range.	A numeric parameter is not a number, or is negative or zero where an ID is expected
402	Unknown clause: 4, Too many patterns (max 50)., Unbalanced ")" in the pattern.	did_clause is not 0 to 3, or the did pattern is not valid
404	Customer not found.	The customer named by i_customer in trusted mode does not exist

Related

• Reports: the DID Summary Reports screen
• DID pool: DIDs, assignments and charging groups
• Users and permissions: the DID Pool right
• Get summary reports
• Manage DIDs
• Call records (CDRs)