Sign in

Aggregate entity records

Changed on

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Computes counts, totals, averages, minimums, maximums and distinct counts over one of the app's entities, grouped by the fields you choose, without returning the records.

Pick the records with query, group them with group_by, date_bucket, or both, and name the values to compute. For example, {"group_by": "status", "sum": "amount"} returns one row per status with its record count and the total of amount. Leave out group_by and date_bucket to get one row over every matching record. That row is returned even when no record matches, with 0 for counts and totals and null for averages, minimums and maximums, unless having rules it out.

Fields can be any field the entity's schema declares, or one every record carries, such as created_date or created_by. sum and avg need fields the schema declares as numbers, and min, max and count_distinct need fields it declares as a string, number, integer or boolean. A stored value of another type is skipped. A date_bucket on created_date or updated_date returns the start of each period as a timestamp. On a date field from the schema it returns the matching part of the stored text, such as 2026-06 for a month, and a stored value that isn't a date is grouped under null.

Deleted records are left out, and row-level security applies, so the values cover only the records the entity's rls read rule lets your credential see. An aggregate reads every matching record and must finish within 30 seconds, with a response under 256 KB. Narrow query when it doesn't. The User entity and entities with field-level read rules aren't supported.

The camelCase spellings groupBy, dateBucket and countDistinct are accepted too.

<Note>This endpoint accepts a personal API key belonging to a user with access to the app, including a read-only key. Workspace API keys are not accepted.</Note>

post/api/apps/{app_id}/entities/{entity_name}/aggregate

Request

  • Base URL: https://app.base44.com
  • URL: https://app.base44.com/api/apps/{app_id}/entities/{entity_name}/aggregate
  • Auth: HTTP bearer

Path parameters

app_idstring required

ID of the app that owns the entity.

entity_namestring required

Name of the entity, exactly as List entity schemas reports it. Don't pass User here. It doesn't fail, but it reads and writes a separate, disconnected set of records stored under that name, not the app's real user accounts, which are managed through their own endpoints.

Request body

queryobject

Filter selecting the records to aggregate, in the same form as q on List entity records. Leave it out to aggregate every record you can read.

group_bystring[]

Up to 4 fields to group by, as a list or a single field name. Each row holds one combination of their values. Leave it out, along with date_bucket, for one row over all matching records.

countboolean

Whether each row includes count, the number of records in the group.

sumstring[]

Number fields to total, as a list or a single field name. Each adds sum_<field> to the rows.

avgstring[]

Number fields to average, as a list or a single field name. Each adds avg_<field> to the rows.

minstring[]

Fields whose smallest value to return, as a list or a single field name. Each adds min_<field> to the rows.

maxstring[]

Fields whose largest value to return, as a list or a single field name. Each adds max_<field> to the rows.

count_distinctstring nullable

One field whose distinct values to count, leaving out null. Adds count_distinct_<field> to the rows.

havingobject

Filter on the computed values, applied after grouping. Name count or a computed field such as sum_amount, with a value to match or with $eq, $ne, $gt, $gte, $lt, $lte, $in or $nin.

sortstring nullable

Group field or computed field to sort the rows by, prefixed with - for descending. Without it, the order of the rows isn't defined.

limitinteger

Maximum number of rows to return, from 1 to 1000.

Example request

{
  "query": {
    "status": "paid"
  },
  "group_by": [
    "status"
  ],
  "date_bucket": {
    "field": "created_date",
    "unit": "month"
  },
  "count": true,
  "sum": [
    "amount"
  ],
  "avg": [
    "amount"
  ],
  "min": [
    "created_date"
  ],
  "max": [
    "amount"
  ],
  "count_distinct": "customer_email",
  "having": {
    "count": {
      "$gt": 1
    }
  },
  "sort": "-sum_amount",
  "limit": 100
}

Response

The computed values.

rowsobject[] required

One row per group. A row holds each group field and the date_bucket field under its own name, then count and the sum_<field>, avg_<field>, min_<field>, max_<field> and count_distinct_<field> values you asked for. In those computed names, a dot in the field name becomes _. Date values, such as a date_bucket or a min_created_date, are UTC timestamps in ISO 8601 format with an offset.

truncatedboolean required

true when more groups matched than limit, so some were left out.

Example response

{
  "rows": [
    {
      "count": 128,
      "status": "paid",
      "sum_amount": 20480.5
    }
  ]
}

Changes