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
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 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
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
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

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 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. Full details — Aggregation POST — the 5000-record ceiling.

See also