Skip to main content
POST
Aggregate Entities

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.

entitySchemaId
string

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".

groupBy
enum<string>

The dimension to group counts by.

Available options:
ENTITY_AGGREGATION_DIMENSION_UNSPECIFIED,
ENTITY_AGGREGATION_DIMENSION_ENTITY_TYPE,
ENTITY_AGGREGATION_DIMENSION_CREATED_AT,
ENTITY_AGGREGATION_DIMENSION_FIELD_VALUE
granularity
enum<string> | null

Bucket size for the CREATED_AT dimension. Required when group_by is CREATED_AT; ignored for ENTITY_TYPE.

Available options:
ENTITY_AGGREGATION_TIME_GRANULARITY_UNSPECIFIED,
ENTITY_AGGREGATION_TIME_GRANULARITY_DAY,
ENTITY_AGGREGATION_TIME_GRANULARITY_MONTH
entityTypeIds
string[]

Optional restriction to specific entity types within the schema. IDs outside the schema's live types are dropped, never counted. Also the chunking lever for callers that want to bound per-request work on very large schemas.

createdAfter
string<date-time> | null

A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").

Example:

"2025-01-15T01:30:15.000Z"

createdBefore
string<date-time> | null

A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").

Example:

"2025-01-15T01:30:15.000Z"

fieldKey
string | null

The field to group by, by key on the target entity type. Required for the FIELD_VALUE dimension (which also requires exactly one entity_type_ids entry); ignored otherwise.

sumFieldKey
string | null

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

200 - application/json

Success

buckets
EntityAggregationBucket · object[]

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.