Skip to main content
POST
Aggregate Entities

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

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 visible to team_id (the team's own, or shared org-wide).

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.