---
title: "Aggregate Entities"
method: POST
path: "/v2/entities/aggregate"
tags: ["Entity API"]
---

# Aggregate Entities

`POST /v2/entities/aggregate`

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.

## Request body

- SvstorePublicapiAggregateEntitiesRequest
  - `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` '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'
  - `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 — A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").
  - `createdBefore` string, date-time — A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").
  - `fieldKey` string, 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.
  - `sumFieldKey` string, 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 `200`

Success

- SvstorePublicapiAggregateEntitiesResponse
  - `buckets` SvstorePublicapiEntityAggregationBucket[] — 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.
    - union
      - object — Set for the CREATED_AT dimension: inclusive start of the time bucket, in UTC.
        - `createdAtBucketStart` string, date-time, required — A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z").
        - `count` integer — Number of live entities in the bucket.
        - `sum` number, double, nullable — Total of the requested sum_field_key over the bucket's entities. Set on every bucket iff the request named a sum_field_key.
      - object — Set for the ENTITY_TYPE dimension: the type this bucket counts.
        - `entityType` SvstorePublicapiEntityTypeAggregationKey, required
          - `entityTypeId` string
          - `entityTypeName` string
        - `count` integer — Number of live entities in the bucket.
        - `sum` number, double, nullable — Total of the requested sum_field_key over the bucket's entities. Set on every bucket iff the request named a sum_field_key.
      - object — Set for the FIELD_VALUE dimension: the field value this bucket counts.
        - `fieldValue` SvstorePublicapiEntityFieldValueAggregationKey, required
          - `value` string — The stored value: the enum option's value (e.g. "in_use") or "true"/"false" for BOOL fields. Empty for the bucket of entities that have no value for the field.
          - `displayName` string — Display label: the enum option's display name, "Yes"/"No" for BOOL fields, or "No value" for the empty-value bucket.
        - `count` integer — Number of live entities in the bucket.
        - `sum` number, double, nullable — Total of the requested sum_field_key over the bucket's entities. Set on every bucket iff the request named a sum_field_key.

## Other responses

- `default` — Error

---

[API](https://skmtc.net/serval/apis/serval-public-api.md) · [All operations](https://skmtc.net/serval/apis/serval-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/serval/serval-public-api/versions/0549515e9384/schema)