Run Entity Aggregation Query
Filter, group and aggregate the records of one entity type (table) in a single call: count, sum, average, minimum, maximum or percentile of number fields, grouped by up to three fields. Filters apply first and use the same filter_groups as Search Entities. A timestamp group-by field can be bucketed by day, week, month, quarter or year; fiscal_year_start_month moves the quarter and year boundaries. Each row holds the group values followed by the aggregate values, in request order. Without limit every group is returned, and more than 10000 groups is an error; with order_by and limit the top groups are returned and truncated reports that more matched. Use this for totals and breakdowns instead of paging Search Entities and adding up records. Only records the caller can read are counted, and archived records are left out. A hidden field is not found, and a sensitive field is refused. Key and name fields cannot be filtered, grouped or aggregated here.
Authentication and permissions
Token requirements: User-based token (OAuth) or Organization-scoped API key or Workspace-scoped API key. Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply.
- Read records as a workspace: team_id is the workspace the caller acts as. Records of databases shared with that workspace (“Can read” or “Can write”) are returned from their owning workspaces; an entity type or schema the workspace cannot reach reads as not found (ListEntities, AggregateEntities, RunEntityAggregationQuery) or matches nothing (SearchEntities). Schema, field and row-access rules still apply: RunEntityAggregationQuery counts only the records the caller can read and refuses a filter, group-by or aggregate on a hidden or sensitive field.
Authorizations
Body
The filters, group-by fields and aggregates, over the type's records that are not archived. A filter names its field by field_key or by field_id, the form a saved view stores. A filter on the key or name field, and a source_filter, are refused. A hidden field is not found; a sensitive field is refused.
Response
Success
One row per group: its group-by values in query.group_by_field_keys order, then its aggregate values in query.aggregates order. A group value is typed by its field: a number, a boolean, an RFC 3339 instant, the bucket's first day (YYYY-MM-DD) for a bucketed field, a record or user ID for a reference field, otherwise text. For an ENUM or MULTI_SELECT field it is the option's value, or the option's ID when a filter would not resolve that value back to the option; either form filters the field. A value is null when the group's records have none. With no group_by_field_keys there is exactly one row, even when no record matches.

