> ## Documentation Index > Fetch the complete documentation index at: https://docs.serval.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /sections/api-reference/openapi-spec-v2.yaml post /v2/entities/aggregate openapi: 3.1.0 info: title: Serval Public API description: Serval Public API contact: name: Serval url: https://serval.com email: support@serval.com license: name: Serval License url: https://serval.com/license version: 2.0.0 servers: - url: https://public.api.serval.com security: - BearerAuth: [] tags: - name: Access Policy API - name: Access Policy Approval Procedure API - name: Access Profile API - name: Access Relationship API - name: Access Request API - name: Agent Session API - name: App Instance API - name: App Resource API - name: App Resource Role API - name: Approval Delegation API - name: Approval Request API - name: Audit Log API - name: Change Blackout API - name: Change Model API - name: Custom Field API - name: Custom Service API - name: Entity API - name: Entity Field Mapping API - name: Entity Ingestion Config API - name: Entity Type API - name: Folder API - name: Group API - name: Guidance API - name: Help Agent API - name: Journey API - name: Knowledge API - name: Knowledge Base API - name: Report API - name: SLA API - name: Schedule API - name: Tag API - name: Team API - name: Team User API - name: Ticket API - name: Topic API - name: User API - name: User Relationship API - name: Workflow API - name: Workflow Approval Procedure API - name: Workflow Run API paths: /v2/entities/aggregate: post: tags: - Entity API summary: Aggregate Entities description: >- 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. operationId: svrelay.publicv2.PublicAPIServiceV2.AggregateEntities requestBody: content: application/json: schema: $ref: '#/components/schemas/svstore.publicapi.AggregateEntitiesRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: >- #/components/schemas/svstore.publicapi.AggregateEntitiesResponse default: description: Error content: application/json: schema: $ref: '#/components/schemas/connect.error' security: - BearerAuth: [] components: schemas: svstore.publicapi.AggregateEntitiesRequest: type: object properties: teamId: type: string title: team_id description: The ID of the team. x-stainless-terraform-configurability: optional entitySchemaId: type: string title: entity_schema_id description: |- 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). x-stainless-terraform-configurability: optional groupBy: $ref: '#/components/schemas/svstore.publicapi.EntityAggregationDimension' title: group_by description: The dimension to group counts by. x-stainless-terraform-configurability: optional granularity: $ref: >- #/components/schemas/svstore.publicapi.EntityAggregationTimeGranularity title: granularity description: |- Bucket size for the CREATED_AT dimension. Required when group_by is CREATED_AT; ignored for ENTITY_TYPE. nullable: true x-stainless-terraform-configurability: optional entityTypeIds: type: array items: type: string title: entity_type_ids description: |- 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. x-stainless-terraform-configurability: optional createdAfter: $ref: '#/components/schemas/google.protobuf.Timestamp' title: created_after description: 'Optional: only count entities created at or after this time.' nullable: true x-stainless-terraform-configurability: optional createdBefore: $ref: '#/components/schemas/google.protobuf.Timestamp' title: created_before description: 'Optional: only count entities created before this time (exclusive).' nullable: true x-stainless-terraform-configurability: optional title: AggregateEntitiesRequest additionalProperties: false svstore.publicapi.AggregateEntitiesResponse: type: object properties: buckets: type: array items: $ref: '#/components/schemas/svstore.publicapi.EntityAggregationBucket' title: buckets description: >- ENTITY_TYPE buckets are sorted by count descending (name ascending on ties); CREATED_AT buckets are sorted by bucket start ascending. x-stainless-terraform-configurability: optional title: AggregateEntitiesResponse additionalProperties: false connect.error: type: object properties: code: type: string examples: - not_found enum: - canceled - unknown - invalid_argument - deadline_exceeded - not_found - already_exists - permission_denied - resource_exhausted - failed_precondition - aborted - out_of_range - unimplemented - internal - unavailable - data_loss - unauthenticated description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. x-stainless-terraform-configurability: optional message: type: string description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. x-stainless-terraform-configurability: optional detail: $ref: '#/components/schemas/google.protobuf.Any' x-stainless-terraform-configurability: optional title: Connect Error additionalProperties: true description: >- Error type returned by Connect: https://connectrpc.com/docs/go/errors/#http-representation svstore.publicapi.EntityAggregationDimension: type: string title: EntityAggregationDimension enum: - ENTITY_AGGREGATION_DIMENSION_UNSPECIFIED - ENTITY_AGGREGATION_DIMENSION_ENTITY_TYPE - ENTITY_AGGREGATION_DIMENSION_CREATED_AT svstore.publicapi.EntityAggregationTimeGranularity: type: string title: EntityAggregationTimeGranularity enum: - ENTITY_AGGREGATION_TIME_GRANULARITY_UNSPECIFIED - ENTITY_AGGREGATION_TIME_GRANULARITY_DAY - ENTITY_AGGREGATION_TIME_GRANULARITY_MONTH google.protobuf.Timestamp: type: string format: date-time description: A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z"). svstore.publicapi.EntityAggregationBucket: type: object oneOf: - $ref: >- #/components/schemas/svstore.publicapi.EntityAggregationBucket.CreatedAtBucketStart - $ref: >- #/components/schemas/svstore.publicapi.EntityAggregationBucket.EntityType title: EntityAggregationBucket google.protobuf.Any: type: object properties: type: type: string x-stainless-terraform-configurability: optional value: type: string format: binary x-stainless-terraform-configurability: optional debug: type: object additionalProperties: true x-stainless-terraform-configurability: optional additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. svstore.publicapi.EntityAggregationBucket.CreatedAtBucketStart: type: object title: Created At Bucket Start properties: createdAtBucketStart: $ref: '#/components/schemas/google.protobuf.Timestamp' title: created_at_bucket_start description: |- Set for the CREATED_AT dimension: inclusive start of the time bucket, in UTC. x-stainless-terraform-configurability: optional count: type: integer title: count format: int32 description: Number of live entities in the bucket. x-stainless-terraform-configurability: optional required: - createdAtBucketStart additionalProperties: false description: |- Set for the CREATED_AT dimension: inclusive start of the time bucket, in UTC. svstore.publicapi.EntityAggregationBucket.EntityType: type: object title: Entity Type properties: entityType: $ref: '#/components/schemas/svstore.publicapi.EntityTypeAggregationKey' title: entity_type description: 'Set for the ENTITY_TYPE dimension: the type this bucket counts.' x-stainless-terraform-configurability: optional count: type: integer title: count format: int32 description: Number of live entities in the bucket. x-stainless-terraform-configurability: optional required: - entityType additionalProperties: false description: 'Set for the ENTITY_TYPE dimension: the type this bucket counts.' svstore.publicapi.EntityTypeAggregationKey: type: object properties: entityTypeId: type: string title: entity_type_id x-stainless-terraform-configurability: optional entityTypeName: type: string title: entity_type_name x-stainless-terraform-configurability: optional title: EntityTypeAggregationKey additionalProperties: false securitySchemes: BearerAuth: type: http scheme: bearer ````