ONontraport
objects

Aggregate %alias records server-side

Changed on

Exact aggregation over the same Collection machinery getList uses, discriminated by mode. mode=single aggregates one object type with an optional group_by on its own fields; mode=related groups a child object by its foreign key to a parent with an optional having threshold; mode=subscriber counts distinct subscribers per visible, active tag, sequence, campaign, or membership site. Grouped pages return at most 50 rows and fetch one additional sentinel row: has_more_groups=true means additional groups were omitted and total_groups is null; otherwise total_groups is exact. Group keys are RAW stored values (option keys, record ids) — callers resolve display names themselves. Ungrouped min/max values preserve the aggregated field's numeric or textual type. Database execution failures return HTTP 503 rather than a successful empty result. Responds with { mode, value, matched_count, groups: [{key, value}], total_groups, has_more_groups, error }.

get/objects/aggregate

Request

  • Base URL
    https://api.ontraport.com/1
  • Auth
    none declared

Query parameters

objectIDinteger required

Object type id. mode=single: the aggregated object; mode=related: the PARENT object being grouped; mode=subscriber: the subscribed object (0 = Contact).

mode'single' | 'related' | 'subscriber' required

Aggregation shape: single, related, or subscriber.

aggregatestring

Aggregate function. mode=single: count, sum, avg, min, max. mode=related: count, sum, avg. Not accepted for mode=subscriber (always a distinct count).

fieldstring

Column to aggregate. Required for sum/avg/min/max, not accepted for count. mode=related: a column on the CHILD object.

group_bystring

mode=single only: column to group by. Omit for a scalar result.

conditionstring

Standard JSON condition array (the same format getList accepts, parsed by Collection::SQLFromJSON). mode=related: the condition applies to the CHILD rows. A condition referencing an unknown, inaccessible, or invalid field or operator fails the whole request (never a silently broadened result or hidden-field count oracle).

related_object_idinteger

mode=related only (required): the CHILD object type holding the foreign key.

relationship_fieldstring

mode=related only (required): the foreign-key column ON THE CHILD that points at the parent.

havingstring

mode=related only: JSON {op, value} threshold on the per-parent aggregate, e.g. {"op": ">", "value": 10}. Ops: >, >=, <, <=, =, !=.

relation_typestring

mode=subscriber only (required): tag, sequence, campaign, or membership.

limitinteger

Max groups per page (default and cap: 50).

offsetinteger

Groups to skip (pagination).

Response

Successful aggregation (the data envelope carries "error" when the query itself is refused)

codeinteger required
dataobject required
account_idinteger required

Changes