Skip to main content
POST
/
v2
/
entities
/
aggregate
Aggregate Entities
curl --request POST \
  --url https://public.api.serval.com/v2/entities/aggregate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "teamId": "<string>",
  "entitySchemaId": "<string>",
  "entityTypeIds": [
    "<string>"
  ],
  "createdAfter": "2023-11-07T05:31:56Z",
  "createdBefore": "2023-11-07T05:31:56Z"
}
'
{
  "buckets": [
    {
      "createdAtBucketStart": "2023-11-07T05:31:56Z",
      "count": 123
    }
  ]
}

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
​
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

Optional: only count entities created at or after this time.

​
createdBefore
string<date-time> | null

Optional: only count entities created before this time (exclusive).

Response

Success

​
buckets
(Created At Bucket Start · object | Entity Type · object)[]

ENTITY_TYPE buckets are sorted by count descending (name ascending on ties); CREATED_AT buckets are sorted by bucket start ascending.

Set for the CREATED_AT dimension: inclusive start of the time bucket, in UTC.