Skip to main content
POST
Run Entity Aggregation Query

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.
Permissions joined by + are all required; or separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Workspace keys must allow every workspace checked by the request. OAuth access depends on the user’s roles and resource access.
  • 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

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
teamId
string

The ID of the workspace the caller acts as.

entityTypeId
string | null

The entity type to aggregate, with its child types. Exactly one of entity_type_id and entity_type_key. A type outside the databases the workspace reaches (its own and those shared with it) is not found.

entityTypeKey
string | null

Resolved like SearchEntitiesRequest.entity_type_key: the workspace's own type wins over a shared type with the same key.

query
query · object

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.

orderBy
EntityAggregationOrder · object | null

Ranks the groups by one aggregate. Unset orders by each group-by value in turn, ascending, a group with no value last.

limit
integer<int32> | null

The most groups to return, 1 to 10000; with order_by, the top groups. Unset returns every group and fails when there are more than 10000, so a caller totalling the rows never totals a partial list.

Response

200 - application/json

Success

rows
ListValue · object[]

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.

truncated
boolean

More groups matched than limit.