For AI agents: markdown of this page — /docs-content-en/telephony/lines/aggregate.md documentation index — /llms.txt

Aggregate application lines

POST /v1/telephony-lines/aggregate

Counts the external lines added by the application. Counting is the only aggregation function that applies to lines.

Standard fields: a line has no numeric fields and no fields to group by. number, name and serverName are strings, and crmAutoCreate is a boolean. Therefore sum, avg, min, max and groupBy are rejected with 400 INVALID_PARAMS.

User fields (UF): a line has none, so they do not enable numeric functions or grouping either.

Request fields (body)

Field Type Required Description
Fieldaggregate Typearray Requiredno DescriptionArray of aggregations. For lines, only the element { "field": "*", "function": "count" } applies. Without the parameter, count is returned
Fieldfilter Typeobject Requiredno DescriptionOnly an empty object {} is accepted: filtering by line fields is not supported, and any key inside returns 400 UNSUPPORTED_FILTER

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/telephony-lines/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [{ "field": "*", "function": "count" }]
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/telephony-lines/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [{ "field": "*", "function": "count" }]
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/telephony-lines/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [{ field: '*', function: 'count' }],
  }),
})

const { success, data } = await res.json()
console.log('Application lines:', data.count)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/telephony-lines/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [{ field: '*', function: 'count' }],
  }),
})

const { success, data } = await res.json()

Other scenarios

The blocks below are request bodies.

The same count without the aggregate array:

JSON 
{}

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.count Typenumber DescriptionNumber of application lines
Fielddata.aggregates Typeobject DescriptionResults of numeric aggregations. Always an empty object for lines
Fielddata.meta.totalRecords Typenumber DescriptionTotal number of application lines
Fielddata.meta.recordsProcessed Typenumber DescriptionNumber of records fetched. count fetches no records, so the value is 0
Fielddata.meta.truncated Typeboolean DescriptionWhether the number was computed over only part of the records. Always false for lines: count fetches no records and is not truncated

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 2,
    "aggregates": {},
    "meta": {
      "totalRecords": 2,
      "recordsProcessed": 0,
      "truncated": false
    }
  }
}

Error response example

400 — a filter was passed:

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "telephony-lines aggregate does not support filter[]; B24 method \"telephony.externalLine.get\" takes no list parameters at all. Filter keys received: NUMBER. The full collection is returned in one page — filter it on your side."
  }
}

Errors

HTTP Code Description
HTTP400 CodeUNSUPPORTED_FILTER DescriptionAt least one key was passed in filter — filtering by line fields is not supported
HTTP400 CodeINVALID_PARAMS Descriptioncount was passed with a field other than "*"
HTTP400 CodeINVALID_PARAMS DescriptionThe function sum, avg, min or max was passed — a line has no numeric fields. The message names the field type or reports that the field was not found
HTTP400 CodeINVALID_PARAMS DescriptiongroupBy was passed — a line has no fields to group by
HTTP400 CodeINVALID_PARAMS DescriptionUnknown aggregation function. The message lists the allowed ones
HTTP400 CodeINVALID_PARAMS Descriptionaggregate was passed as an empty array
HTTP400 CodeINVALID_PARAMS Descriptionop, field or function was passed at the root of the body without the aggregate array
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeKEY_INACTIVE DescriptionThe API key is inactive or revoked
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the telephony scope
HTTP429 CodeRATE_LIMITED DescriptionRequest rate limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is temporarily unavailable — retry the request later

Full list of common API errors — Errors.

Known specifics

The count covers the same lines the list returns. data.count matches meta.total of GET /v1/telephony-lines: lines rented from Voximplant or connected via SIP are not counted. To list them, use GET /v1/voximplant-lines.

Sorting in the body is ignored. The order field does not affect the response and does not cause an error.

See also