---
title: "Aggregate %alias records server-side"
method: GET
path: "/objects/aggregate"
tags: ["objects"]
---

# Aggregate %alias records server-side

`GET /objects/aggregate`

## Request

- Base URL: `https://api.ontraport.com/1`
- URL: `https://api.ontraport.com/1/objects/aggregate`
- Auth: none declared

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

## Query parameters

- `objectID` integer, required
- `mode` 'single' | 'related' | 'subscriber', required
- `aggregate` string
- `field` string
- `group_by` string
- `condition` string
- `related_object_id` integer
- `relationship_field` string
- `having` string
- `relation_type` string
- `limit` integer
- `offset` integer

## Response `200`

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

- Response
  - `code` integer, required
  - `data` object, required
  - `account_id` integer, required

## Other responses

- `400`: Contract violation: unknown mode, parameter not valid for the mode, bad aggregate function, malformed filters/having
- `403`: No permissions

## Changes

- **2026-09-30** `c102850cff71`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ontraport/apis/ontraport-api/changes/objects/aggregate/get.md)

---

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