Skip to content

Opensearch Aggregate

POST
/opensearch/aggregate

Generic, allowlist-bounded GROUP BY over a whitelisted mashup index.

Translates group_by into nested OpenSearch terms aggregations with metric sub-aggs, then applies having / sort / limit to the flattened groups. This is the matrix-walk primitive for TAM design (e.g. count companies by NAICS x state x employee band in one call).

Guardrails: group_by depth is capped at 3, per-level bucket size tapers by depth (_AGG_TERMS_SIZE_BY_DEPTH), the agg list is capped at 10, and returned groups at limit (<=1000). Counts from terms / cardinality are APPROXIMATE on a sharded index. Since mashup_companies/mashup_contacts share one contact-grained index, use uniqExact on COMPANY_ID for true unique-company counts. Mashup aggregations automatically apply the organization’s deliverability policy.

Authorizations

Parameters

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

Generic, allowlist-bounded GROUP BY over a whitelisted mashup index.

Translates to nested OpenSearch terms aggregations (one level per group_by field) with metric sub-aggregations. having / sort / limit are applied to the flattened groups server-side. Counts from terms buckets / cardinality are APPROXIMATE on a sharded index.

object
agg
Any of:
Array<object>
<= 10 items

A single aggregate metric over the grouped rows.

count needs no field (it is the bucket doc count). All other functions require field. alias keys the value in each group’s agg map; it defaults to function when omitted (so two same-function metrics must each carry a distinct alias).

object
alias
Any of:
string
field
Any of:
string
function

Count=doc count per group; uniqExact=cardinality (HLL-approximate); sum/avg/min/max=numeric metric over field.

string
default: count
Allowed values: count uniqExact sum avg min max
filters

Pre-aggregation equality filters, identical semantics to /opensearch/search. RAW UPPERCASE field names.

object
key
additional properties
any
group_by
required

1-3 RAW UPPERCASE keyword fields to group on (e.g. [“COMPANY_NAICS”, “COMPANY_STATE”]). Must be keyword-type fields — the canonical COMPANY_* firmographics are. Capped at 3 dimensions to bound cluster cost. ORDER HIGHEST-CARDINALITY FIRST: deeper dimensions get smaller per-level bucket caps (1000 / 100 / 20), so a low-cardinality field placed last keeps full fidelity while a high-cardinality field placed last may be truncated.

Array<string>
>= 1 items <= 3 items
having
Any of:
object
key
additional properties
object
key
additional properties
number
index
required

Logical index to aggregate. Maps to a whitelisted physical alias.

string
Allowed values: mashup_contacts mashup_companies hem2contact ip2company
limit

Max number of groups returned (after having + sort). Hard-capped at 1000.

integer
default: 100 >= 1 <= 1000
sort
Any of:
Array<object>
object
key
additional properties
string

Responses

200

Successful Response

object
data
required
object
groups
Array<object>
default:
object
agg

Metric values keyed by alias, e.g. {“count”: 1247, “unique_domains”: 1184}.

object
key
additional properties
any
key

The group-by field values for this group, e.g. {“COMPANY_NAICS”: “3311”, “COMPANY_STATE”: “OH”}.

object
key
additional properties
any
index
required
string
took_ms
integer
total_groups
integer
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string