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

Currency aggregation

POST /v1/currencies/aggregate

Count of currencies and numeric aggregations over exchange rates and other numeric fields of the directory.

Supports the count function and the numeric functions sum, avg, min, max over the fields amount, amountCnt, sort, decimals. Grouping via groupBy is not available for currencies — the directory has no fields allowed for grouping, so any groupBy returns 400 INVALID_PARAMS.

Request fields (body)

Parameter Type Required Description
Parameteraggregate Typearray Requiredno DescriptionArray of aggregations. Counting — { "field": "*", "function": "count" }. Numeric functions — { "field": "<field>", "function": "sum" | "avg" | "min" | "max" } over the fields amount, amountCnt, sort, decimals. Without the parameter only count is returned
ParametergroupBy Typestring | array Requiredno DescriptionNot supported for currencies — returns 400 INVALID_PARAMS. The directory has no fields allowed for grouping
Parameterfilter Typeobject Requiredno DescriptionNot supported for currencies — any key returns 400 UNSUPPORTED_FILTER

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

const { success, data } = await res.json()
console.log('Sum of rates:', data.aggregates.amount.sum)

JavaScript — OAuth application

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

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

Other scenarios

The total number of currencies in your Bitrix24 account — the fastest request, without fetching records:

JSON 
{}

Minimum and maximum exchange rate:

JSON 
{ "aggregate": [{ "field": "amount", "function": "min" }, { "field": "amount", "function": "max" }] }

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionAggregation result: record count, function values and selection details
Fielddata.count Typenumber DescriptionNumber of currencies matching the request
Fielddata.aggregates Typeobject DescriptionResults of numeric functions, grouped by field name: data.aggregates.amount.sum and so on. Empty object if the aggregate array is not passed
Fielddata.meta.totalRecords Typenumber DescriptionTotal number of currencies
Fielddata.meta.recordsProcessed Typenumber DescriptionHow many records were processed for numeric functions. 0 for a request with only count
Fielddata.meta.truncated Typeboolean Descriptiontrue when the numbers were computed over only some of the records that match the filter: fewer records were read than data.count promised — including when more than 5000 matched the filter — or the slice was cut short by a sub-page error. The size of the gap is reported in data.meta.recordsShortfall, the interrupted slice in data.meta.pageErrorSample. Always present, and false on a complete response. If the request has neither groupBy nor a numeric function, no records are fetched and the flag is always false

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 7,
    "aggregates": {
      "amount": { "sum": 59, "avg": 8.428571428571429 }
    },
    "meta": {
      "totalRecords": 7,
      "recordsProcessed": 7,
      "truncated": false
    }
  }
}

Without the aggregate array the data.aggregates field is an empty object, and data.meta.recordsProcessed equals 0.

Error response example

400 — field not available for aggregation:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'nope' not found. Available numeric fields: amount, amountCnt, sort, decimals."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionUnknown field in aggregate — the message lists the available numeric fields
HTTP400 CodeINVALID_PARAMS DescriptionNon-numeric field in sum, avg, min, max — the message names the field type
HTTP400 CodeINVALID_PARAMS DescriptionUnknown aggregation function — count, sum, avg, min, max are supported
HTTP400 CodeINVALID_PARAMS DescriptiongroupBy was passed — grouping is not available for currencies
HTTP400 CodeUNSUPPORTED_FILTER Descriptionfilter was passed — currencies are not filtered server-side
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

Known specifics

count does not fetch records, numeric functions do. count is computed in a single request at any volume, so data.meta.recordsProcessed equals 0. The functions sum, avg, min, max fetch records and are computed on the Vibecode side, so data.meta.recordsProcessed equals the number of processed currencies. The currency directory holds only a handful of records, so the 5000-record ceiling is never reached for it.

The truncation marker travels with the number itself. When a response arrives with meta.truncated: true, the marker truncated: true sits inside every field object in data.aggregates and on every element of data.groups, and data.meta.warnings gains a warning with the code AGGREGATE_TRUNCATED. A client that reads only the number itself therefore sees that it was computed over only some of the records. None of these markers appear on a complete response. For full details, see Aggregation POST — the 5000-record ceiling.

See also