Aggregate Entities
Aggregate live-entity counts for one entity schema (database), grouped by entity type or by creation-time bucket (day or month). Supports optional entity-type restriction and an optional created-at window. This is the scalable way to count entities — counting via paginated search does not scale to large databases.
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 entity schema ("database") to aggregate over. Required — an unscoped aggregate would scan every visible schema's entities, which is timeout-class on large tenants. The schema must be reachable by team_id: the workspace's own, or one shared with it by a workspace-level or org-wide share at "Can read" or "Can write".
Optional, FIELD_VALUE dimension only: a NUMBER field (by key, on the
same single entity type) whose values are summed per bucket — e.g.
group hardware assets by state and sum cost for spend-by-state.
When set, every bucket carries sum alongside count; entities with
no value for the summed field contribute nothing to sums.
Response
Success
ENTITY_TYPE buckets are sorted by count descending (name ascending on ties); CREATED_AT buckets are sorted by bucket start ascending; FIELD_VALUE buckets follow the field's option display order (BOOL: Yes then No), with the empty-value bucket last.
- EntityAggregationBucket
- EntityAggregationBucket
- EntityAggregationBucket

