Peer Counts
The Peer Counts endpoint is the read-only OpenAPI equivalent of proxyapi.php?reqtype=COUNTPEERS. It returns a count for each configured PBX node and a cluster total.
Endpoint and authentication
GET https://pbx.example.com/pbx/openapi.php/countpeers
GET https://pbx.example.com/pbx/openapi.php/countpeers?tenant=CANISTRACCI
The query-style equivalent is GET openapi.php?object=countpeers&tenant=CANISTRACCI. Only GET is supported.
Use a full or read-only global or tenant API key, sent using X-API-Key, Authorization: Bearer, or the key query parameter. Extension Dial API Keys are not accepted. The existing API key IP restrictions and tenant OpenAPI access setting apply.
| Parameter | Meaning |
|---|---|
tenant | One exact tenant code or name. Required for tenant keys. With a global key, omit it for all tenants, or provide it to filter one tenant. Codes take precedence over display names. Ambiguous names return HTTP 409. Wildcards are not expanded. |
Examples
curl -H "X-API-Key: GLOBAL_READONLY_API_KEY" \
"https://pbx.example.com/pbx/openapi.php/countpeers"
curl -H "X-API-Key: TENANT_READONLY_API_KEY" \
"https://pbx.example.com/pbx/openapi.php/countpeers?tenant=CANISTRACCI"
To obtain a breakdown for multiple tenants, repeat the filtered request for each tenant using a global key or the appropriate tenant keys.
Response and counting rules
{
"node1": 120,
"node2": 85,
"total": 205
}
The JSON properties use the configured node names. Each value is the sum of:
- CHAN_SIP: monitored online peers reported by
sip show peers. This includes OK and LAGGED peers; unmonitored peers are excluded. - PJSIP: contact objects reported by
pjsip list contacts, including contacts regardless of qualification status and configured static contacts.
This preserves the counting meaning of the legacy command. It is not a count of distinct registered endpoints or physical phones: several contacts for one endpoint count separately, and the same peer appearing on several nodes contributes to each node and to the total.
Tenant filtering uses the tenant's actual SIP peer names and PJSIP endpoint AOR assignments, with exact matching. It does not search for the tenant code as an arbitrary substring of a peer name. Custom peer names are included when they belong to that tenant.
Counts are obtained from live Asterisk manager read commands, without registering or unregistering phones, reloading modules, or changing PBX configuration. Nodes are queried sequentially, so the response is not an atomic cluster snapshot.
Empty results and errors
A node without a particular channel driver contributes zero for that technology. A node with no matching peers or contacts contributes zero. With no configured nodes the result is {"total":0}.
If an AMI connection or command fails, or its response cannot be interpreted, the request returns HTTP 502 peer_counts_unavailable. No partial total is returned as a successful response. Missing AMI connection settings also produce 502.
Invalid API keys return 401; denied IP addresses or disabled tenant OpenAPI access return 403; unknown tenants return 404; ambiguous tenant names return 409; unsupported HTTP methods return 405. Database read failures or invalid peer/node configuration return 500. Node names must be unique and cannot be total, which is reserved for the total property. Peer/AOR names queried for a tenant must use letters, digits, underscores, hyphens, dots, @, colons or plus signs and contain at most 255 characters.