FLfloqer
ackDB

Cross-entity event aggregation

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).

get/api/v1/ackdb/entities/events/aggregate

Request

  • Base URL
    http://localhost:3009
  • Auth
    HTTP bearer

Query parameters

sourcestring

Filter by source type.

eventTypestring

Filter by event type.

sincestring date-time

Filter events after this ISO date.

untilstring date-time

Filter events before this ISO date.

groupBy'event_type' | 'source' | 'month' | 'entity' | 'person'

Group results by a dimension. Person/entity groups exclude events without that owner. Ungrouped totals count all matches.

sumFieldstring

Promoted metadata field for numeric aggregation (e.g. amount_cents). Enables SUM, AVG, MIN, MAX.

minCountinteger

Minimum event count threshold (HAVING COUNT >= N). Only groups meeting this threshold are returned.

minSumnumber

Minimum sum threshold (HAVING SUM >= N). Requires sumField. Only groups whose sum meets this threshold are returned.

graphRootstring

Root entity id or domain.

graphScope'parents' | 'children' | 'connected'

Required when graphRoot is supplied.

graphMaxDepthinteger
graphAsOfstring date-time
graphRelationshipTypestring[]
personIdstring

Filter events stamped with this human; merged IDs resolve to their survivor.

ownership'person' | 'company'

person selects sole-person events; company selects company-associated events; omit for both. Filters before pagination/counts. Personal ownership conflicts with entityId/company graph.

Response

Aggregation results

Example response

{
  "data": {
    "count": 45,
    "distinctEntities": 12,
    "sum": 1250000,
    "avg": 27777.78,
    "min": 5000,
    "max": 99000,
    "groups": [
      {
        "key": "stripe_charge.succeeded",
        "count": 30,
        "distinctEntities": 10
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.