Sign in

v1

latestOpenAPI 3.1.0Serval License2026-07-26202952779.1 KB
Entity API

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.

post/v2/entities/aggregate

Request body

teamIdstring

The ID of the team.

entitySchemaIdstring

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'ENTITY_AGGREGATION_DIMENSION_UNSPECIFIED' | 'ENTITY_AGGREGATION_DIMENSION_ENTITY_TYPE' | 'ENTITY_AGGREGATION_DIMENSION_CREATED_AT' | 'ENTITY_AGGREGATION_DIMENSION_FIELD_VALUE'
granularity'ENTITY_AGGREGATION_TIME_GRANULARITY_UNSPECIFIED' | 'ENTITY_AGGREGATION_TIME_GRANULARITY_DAY' | 'ENTITY_AGGREGATION_TIME_GRANULARITY_MONTH'
entityTypeIdsstring[]

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.

createdAfterstring date-time

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

createdBeforestring date-time

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

fieldKeystring nullable

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.

sumFieldKeystring nullable

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