Counting and retrieval

Once a filter selects the right people, there are four different things you might want back, and they are four different endpoints with four different costs and permissions. Picking the wrong one is the usual cause of a 403 you did not expect or a page-two that never arrives.

Which endpoint for which question

Counting

POST /project/{project}/audience/count takes the audience query filter and returns only the total. It is the endpoint whose number you may act on: exact, uncapped and live, with no sampling anywhere near it.

curl -X POST "$BASE/audience/count" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "filterCompliance": { "sms": "no-opt-out" } }'

Four things worth knowing:

• An empty body counts the whole audience. limit and offset are ignored.
• It carries no contact data, which is why it stays available under the anonymized data policy mode, where /audience/search is disabled. For restricted credentials it is the supported way to answer "how many contacts match this".
• To count who can actually receive, pass filterCompliance. Without it the total is the raw audience, not a sending figure. The consent and reach rules are the same ones a campaign estimate applies. See Counting who can receive.
• It is the endpoint that settles any number a probe suggested. Probes report shape and may be sampled; this is the size.

Where a count drops: the ladder

A total on its own does not say why it is small. Add "ladder": true at the top level of the body and the same call also returns four counts, each one a subset of the one before, so you can see at which step the contacts fall away:

curl -X POST "$BASE/audience/count" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ladder": true, "filterCompliance": { "sms": "no-opt-out" } }'

{
  "metadata": {
    "totalHits": 452,
    "ladder": {
      "audience": 1200,
      "matched": 1200,
      "reachable": 610,
      "consented": 452
    },
    "unknownSegments": []
  }
}

consented is the number of contacts who would actually receive the message. Quote it as the reach of a send; matched alone overstates it. The gaps between rungs tell you what to fix: a big drop from matched to reachable is missing or unusable phone numbers, a big drop from reachable to consented is the consent policy at work. Without filterCompliance (or the explicit consent and reach keys it expands to) there is no reach or consent to apply, so matched, reachable and consented come back equal.

unknownSegments lists any segment uid in root that matches no segment in the project. Such a condition selects nobody, so a zero with an entry here is a typo in the filter, not an empty audience.

Searching and scrolling

Both take the same filter. They differ in how much they will give you and what it costs.

/audience/search uses offset/limit pagination, but the offset is always forced to 0: it is built for a quick look from the beginning, not for walking a result set. Its ceiling is 50 contacts per request and it needs PROJECT_AUDIENCE_READ.

/audience/scroll is the one for large traverses. It returns a cursor in the response metadata that you pass back to get the next page, up to 100 contacts per request. The cursor is a base64 string holding the internal query state and expires after one minute of inactivity, so a traverse has to keep moving: a job that fetches a page, spends five minutes processing it and comes back will find the cursor gone.

It needs PROJECT_AUDIENCE_LIST, which is gated by the subscription plan. That is the usual reason a call that works for one organization is refused for another with the same code.

Retrieving one contact

When you already know who you are looking for, four direct lookups skip the filter entirely.

The id these return is the one every other per-contact call takes, including the contact's events and direct messaging.

Aggregations

POST /audience/aggregations runs your aggregations over the filtered audience and returns results only, with no contact rows and the limit pinned to zero. It needs PROJECT_AGGREGATIONS, which is not generally available and is granted manually by Instasent.

If what you want is a distribution over an attribute rather than a bespoke aggregation, /audience/coverage gives you one with the ordinary read scope, at the cost of being a probe: shape, possibly sampled, never a size.

What the plan lets you see

Two gates decide the fields on a returned contact, and both have to be open: the scopes on your token and the subscription plan of the organization.

What's next

• Query filter: the filter these endpoints take, including cursor mechanics and aggregation shapes.
• Segments: scrolling a saved segment, and reading its cached size.
• Probes: check the filter is selecting on something real before you count it.