---
title: "Cross-entity event aggregation"
method: GET
path: "/api/v1/ackdb/entities/events/aggregate"
tags: ["ackDB"]
---

# Cross-entity event aggregation

`GET /api/v1/ackdb/entities/events/aggregate`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/ackdb/entities/events/aggregate`
- Auth: HTTP bearer

Aggregate events across all entities. Returns counts, distinct entity counts, and optional SUM/AVG/MIN/MAX. Supports GROUP BY event_type, source, month, or entity. Use for analytics like 'total revenue by month' or 'refund count per entity'.

**sumField:** Name of a promoted metadata field for numeric aggregation (e.g. `amount_cents`). Enables SUM, AVG, MIN, MAX in the response. Only works on numeric metadata fields.

**minCount:** Minimum event count threshold (HAVING COUNT >= N). Only groups with at least this many events are returned.

**minSum:** Minimum sum threshold (HAVING SUM >= N). Requires sumField. Only groups whose sum meets this threshold are returned. Use with `groupBy=entity` to find entities above a revenue threshold (e.g., `minSum=100000` for > $1000 in cents).

## Query parameters

- `source` string
- `eventType` string
- `since` string, date-time
- `until` string, date-time
- `groupBy` 'event_type' | 'source' | 'month' | 'entity' | 'person'
- `sumField` string
- `minCount` integer
- `minSum` number
- `graphRoot` string
- `graphScope` 'parents' | 'children' | 'connected'
- `graphMaxDepth` integer
- `graphAsOf` string, date-time
- `graphRelationshipType` string[]
- `personId` string
- `ownership` 'person' | 'company'

## Response `200`

Aggregation results

- object
  - `data` object, required
    - `count` integer, required: Total event count matching filters.
    - `distinctEntities` integer, required: Number of unique entities with matching events.
    - `sum` number: Sum of the specified metadata field (only present when sumField is provided).
    - `avg` number: Average of the specified metadata field (only present when sumField is provided).
    - `min` number: Minimum value of the specified metadata field (only present when sumField is provided).
    - `max` number: Maximum value of the specified metadata field (only present when sumField is provided).
    - `groups` object[]: Grouped results (only present when groupBy is provided).
      - `key` string, required: Group key value.
      - `count` integer, required
      - `distinctEntities` integer, required
      - `sum` number: Sum within this group (if sumField specified).
      - `avg` number: Average within this group (if sumField specified).
      - `min` number: Minimum within this group (if sumField specified).
      - `max` number: Maximum within this group (if sumField specified).
      - `distinctPersons` integer
      - `personId` unknown
      - `personName` unknown
      - `entityId` unknown
      - `entityName` unknown
    - `distinctPersons` integer

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)