search can answer “how many, by what?” without returning rows. Add groupBy,
the name of one field, and search returns each value of that field with the
number of objects that carry it.
search returns for the kind, with counts
in place of results:
Request
Response
sum(groups.count) + otherCount equals total, except when overlapping is
true. Then an object is counted under every value it has, the counts add up to
more than total, and you must not add them up.
A count uses the same account, permissions and data source as the list it
summarises. It never returns rows. total is the number of objects that match
the search with its filters applied, not the number the account holds. A plain
search of inventory_source reports the same number as its total, so the
two always agree. Earlier previews also returned matched on that plain search;
it is gone, because total now carries that meaning.
Which kinds can be counted
Other kinds do not support
groupBy yet. The listed tools/list schema for
your account is authoritative: accounts that cannot count any kind do not see
the field. Source health is not counted, because it is read per source and not
from the list.
askType and askState are the two things filter.askType and
filter.askState already narrow asks by, and they compose with each other and
with query:
SERVICE_UNAVAILABLE when a place could not be read (retry), and
UNSUPPORTED_FEATURE when a place returned as many asks as one read covers
(narrow the search with query, filter.askType or filter.askState).
Counting media partners
A Buyer account countskind: "seller" by selected, partnerKind, channel
or region, in one database query that reads the same filters, query and
status as the list. total is the total a plain seller search reports. The
counts for selected and partnerKind add up to it under every filter.
The counts for channel and region overlap, because a media partner sells
in several channels and countries and is counted under each. They add up to more
than total, and the response says so with overlapping: true: do not add them
up. Each count equals the total of the same search filtered by that value, and
a media partner that names no channel (or country) is counted under every one,
as the filter returns it. See
Channel and region counts overlap. runsOn, language, topic and offers return
UNSUPPORTED_FEATURE until Apostra holds the creator data behind them, and a
count that needs one advertiser’s partner status (filter.partnerStatus with
filter.advertiserId) returns UNSUPPORTED_FEATURE too, because that status is
read media partner by media partner and a count of it would be short. The
details are in
Find media partners with search.
Counting creatives and event sources across the account
A plainsearch of creative or event_source lists one advertiser at a time:
it needs filter.advertiserId (or, for creative, filter.campaignId). A
grouped count by advertiserId needs neither. Without filter.advertiserId it
counts every active advertiser you can access, in one call, so “how many
creatives do we have?” or “how many conversion event sources are set up?” takes
one request instead of one search per advertiser:
total is the account-wide count, and each group is one advertiser’s share. An
advertiser with none of the kind has no group. To show advertiser names, search
kind: "advertiser"; the count carries only ids. The count covers the same
advertisers a plain search would let you open one by one, so a buyer agent counts
only the advertisers it can read. Archived advertisers are not counted.
The kind’s other filters still apply. For creative that is query,
formatKind, assetType, role, libraryRole, source, promoted,
labels, statuses and isArchived, so active creatives are counted unless
you ask for archived ones. filter.collectionIds needs filter.advertiserId,
because collections belong to one advertiser. For event_source it is query.
Send filter.advertiserId to count one advertiser.
A creative count covers advertisers, not campaigns: groupBy with
filter.campaignId returns VALIDATION_ERROR. To count one campaign’s
creatives, search it without groupBy and read total.
Errors
VALIDATION_ERROR is the code every v3 input refusal carries on the wire.
Correct the request and call again. See Errors for the full
envelope.
Grouping by more than one field, and grouping by time period, are not part of
this contract.
Kinds with no field to count by
A kind declares agroupBy field only when it already filters on that field, so
a count and the list it summarises always agree. These kinds filter by a text
query (and, for conversation, a start time) and nothing else, and neither a
query nor a time range is a value to count by, so they declare none and
groupBy for them returns UNSUPPORTED_FEATURE:
Ask for a list instead, and read
total for the number of matches.