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

Currency aggregation

POST /v1/currencies/aggregate

Counting the number 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
aggregate array no Array 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
groupBy string | array no Not supported for currencies — returns 400 INVALID_PARAMS. The directory has no fields allowed for grouping
filter object no Not 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
success boolean Always true on success
data.count number Number of currencies matching the request
data.aggregates object Results of numeric functions, grouped by field name: data.aggregates.amount.sum and so on. Empty object if the aggregate array is not passed
data.meta.totalRecords number Total number of currencies
data.meta.recordsProcessed number How many records were processed for numeric functions. 0 for a request with only count
data.meta.truncated boolean true if more than 5000 records matched the request and the aggregation was computed over the first 5000

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 is 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
400 INVALID_PARAMS Unknown field in aggregate — the message lists the available numeric fields
400 INVALID_PARAMS Non-numeric field in sum, avg, min, max — the message names the field type
400 INVALID_PARAMS Unknown aggregation function — count, sum, avg, min, max are supported
400 INVALID_PARAMS groupBy was passed — grouping is not available for currencies
400 UNSUPPORTED_FILTER filter was passed — currencies are not filtered server-side
403 SCOPE_DENIED The API key does not have the crm scope
401 TOKEN_MISSING No API key was passed

Full list of common API errors — 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 compute on the Vibecode side, so data.meta.recordsProcessed equals the number of processed currencies. The currency directory contains single-digit record counts, so the 5000-record limit and data.meta.truncated do not trigger for it.

See also