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

Aggregate order statuses

POST /v1/order-statuses/aggregate

Counts statuses grouped by type or notify. The entity has no numeric fields, so numeric functions (sum, avg) do not apply — the main scenario is count with a filter or grouping.

Standard fields

All status fields are categorical — suitable only for groupBy and filter:

Field Purpose
type Group by type: O (order) or D (delivery)
notify Group by whether a notification is sent

The full list of aggregatable fields is shown in the table above.

Request fields (body)

Parameter Type Req. Description
aggregate array no Array of aggregations. For statuses the main option is count (no other functions, there are no numeric fields). The count format is { "field": "*", "function": "count" }. Without the parameter — count of records taking the filter into account
filter object no Filtering — the same fields as in GET /v1/order-statuses. Filtering syntax
groupBy string | string[] no Field or array of fields to group by (maximum 5)
groupOrderBy array no Group sorting: [{ "field": "count", "direction": "desc" }]
groupLimit number no Limit on the number of returned groups (1-1000)

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/order-statuses/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "type"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/order-statuses/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "type"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/order-statuses/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    groupBy: 'type',
  }),
})

const { success, data } = await res.json()
console.log('Status distribution:', data.groups)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/order-statuses/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    groupBy: 'type',
  }),
})

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

Other scenarios

Count records — count with field "*", the fastest request without fetching records. Without the aggregate array the result is the same:

JSON 
{ "aggregate": [{ "field": "*", "function": "count" }] }

How many statuses have notification enabled:

JSON 
{
  "filter": { "notify": true }
}

Group by both axes at once:

JSON 
{
  "groupBy": ["type", "notify"]
}

Response fields

Field Type Description
success boolean Always true on success
data.count number Total number of statuses matching the filter
data.aggregates object Aggregation results — for statuses it stays empty (no numeric fields in aggregatable)
data.groups array Groups (only with groupBy)
data.meta.totalRecords number Total number of records
data.meta.recordsProcessed number Number of processed records
data.meta.truncated boolean true if there are more than 5000 records
data.meta.groupTotal number Number of groups before groupLimit
data.meta.groupsTruncated boolean Whether the group list was truncated by groupLimit

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 9,
    "aggregates": {},
    "groups": [
      { "type": "O", "count": 6, "aggregates": {} },
      { "type": "D", "count": 3, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 9,
      "recordsProcessed": 9,
      "truncated": false,
      "groupTotal": 2,
      "groupsTruncated": false
    }
  }
}

Without groupBy, the data.groups field is absent from the response.

Error response example

400 — unknown field in groupBy:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'foo' is not aggregatable on this entity. Available: type, notify."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS Unknown function or nonexistent field — the message contains a list of allowed fields
400 INVALID_PARAMS More than 5 fields passed in groupBy
400 INVALID_PARAMS Reserved keywords in groupBy: count, aggregates, meta, groups
403 SCOPE_DENIED The API key does not have the sale scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of general API errors — Errors.

Known specifics

Only count makes sense. Since the status schema has no numeric fields in aggregatable, the sum / avg / min / max functions always return an empty aggregates. To count statuses, use count (without aggregate) with a filter or grouping.

Small data volume. On a Bitrix24 account the number of statuses is measured in dozens, so meta.truncated (which triggers only above 5000 records) is never activated for this entity.

See also