Count records matching criteria

POST

/v1/discovery/count

const url = 'https://dev-api.infiniteaudience.ai/v1/discovery/count';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"filters":[{"field":"example","op":"=","value":["example"]}],"filter_groups":[{"id":"example","filters":[{"field":"example","op":"=","value":["example"]}],"combinator":"AND"}],"segment_id":"example","audience_id":"example","segment_ids":["example"],"set_logic":"union","excluded_segment_ids":["example"],"group_by":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://dev-api.infiniteaudience.ai/v1/discovery/count \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "filters": [ { "field": "example", "op": "=", "value": [ "example" ] } ], "filter_groups": [ { "id": "example", "filters": [ { "field": "example", "op": "=", "value": [ "example" ] } ], "combinator": "AND" } ], "segment_id": "example", "audience_id": "example", "segment_ids": [ "example" ], "set_logic": "union", "excluded_segment_ids": [ "example" ], "group_by": "example" }'

Returns the number of records matching the given criteria. Counts the bytes scanned toward your organization’s compute limit. Requires ‘discovery’ scope. Provide exactly one of: filters (flat array), filter_groups (compound AND/OR groups), segment_id (a saved segment), audience_id (a saved audience), or segment_ids + set_logic (combine multiple segments). filters and filter_groups count as the same input — if both are sent, filter_groups wins. Sending more than one input returns 400 AMBIGUOUS_INPUT; sending none returns 400 NO_INPUT_SPECIFIED. Count, lookup, crosstab, and overlap all preserve full group/combinator structure: each included segment’s own AND/OR groups are evaluated intact, and an audience’s excluded segments are always subtracted (AND NOT), regardless of set_logic.

Authorizations

bearerAuth

Request Body^required

application/json

object

filters

Flat filter array (recommended).

Array<object>

A single filter condition for audience discovery or job execution

object

field

required

The canonical attribute name (e.g. ‘age’, ‘state’)

string

required

Comparison operator

string

Allowed values: = != < <= > >= IN NOT IN BETWEEN LIKE ARRAY_CONTAINS ARRAY_CONTAINS_ANY IS NULL IS NOT NULL

value

One of:

string

filter_groups

Compound boolean filter groups (alternative to filters). Each group has a combinator (AND/OR) and a filters array.

Array<object>

A group of Filter conditions. All filters within a single group are always ANDed together — there is no per-group intra-operator. The combinator attribute is an inter-group operator: it controls how this group is joined to the immediately preceding group in the array. The combinator on the first group (index 0) is always ignored.

Example — (city = "NYC" AND state = "NY") OR (state = "CA"):

  { "id": "g1", "filters": [{"field":"city","op":"=","value":"NYC"},
                            {"field":"state","op":"=","value":"NY"}],
    "combinator": "AND" },
  { "id": "g2", "filters": [{"field":"state","op":"=","value":"CA"}],
    "combinator": "OR" }
] ```
Group g1's `combinator` is irrelevant (it is the first group). Group g2's `combinator: "OR"` means the result is `(g1) OR (g2)`.

object

required

Stable identifier (UUID or NanoID). Used to track groups across edits.

string

filters

required

One or more filter conditions. All conditions in this array are combined with AND. Provide at least one filter per group.

Array<object>

A single filter condition for audience discovery or job execution

object

field

required

The canonical attribute name (e.g. ‘age’, ‘state’)

string

required

Comparison operator

string

Allowed values: = != < <= > >= IN NOT IN BETWEEN LIKE ARRAY_CONTAINS ARRAY_CONTAINS_ANY IS NULL IS NOT NULL

value

One of:

string

combinator

required

Inter-group operator. Joins this group to the previous group in the array. AND narrows the result; OR broadens it. Ignored on the first group (index 0) — that group has no predecessor to join.

string

Allowed values: AND OR

segment_id

ID of a saved segment to count.

string

audience_id

ID of a saved audience to count.

string

segment_ids

IDs of multiple segments to combine (requires set_logic).

Array<string>

set_logic

How to combine segment_ids: union = match ANY segment (OR); intersection = match EVERY segment (AND).

string

Allowed values: union intersection

excluded_segment_ids

Ad-hoc “A minus B” preview — segments to subtract from the segment_ids composition, without persisting an audience. Only meaningful alongside segment_ids; do not send set_logic: 'exclusion' (invalid) — exclusion is always modeled via this separate param.

Array<string>

group_by

Optional attribute to group counts by (e.g. ‘state’, ‘gender’).

string

Responses

200

Record count result.

application/json

object

count

integer

bytes_scanned

integer

estimated_cost_usd

number

matched_count

Only present when the resolved composition includes at least one included matched-subtype segment — the subset of count that came from an identity-resolution match.

integer

groups

Present when group_by is specified.

Array<object>

object

group_value

required

string

count

required

integer

breakdowns

Present by default (unless group_by is set) when the resolved composition supports them — a single filter-based segment/audience or raw filters. Not yet available for non-filter or mixed-subtype compositions.

object

age

Array<object>

object

bucket

string

count

integer

gender

Array<object>

object

value

string

bucket

string

count

integer

geography

Array<object>

object

value

string

bucket

string

count

integer

behavioral

Array<object>

object

value

string

bucket

string

count

integer

financial

Array<object>

object

value

string

bucket

string

count

integer

warnings

Present only when the resolved segment_id/segment_ids/ audience_id composition includes a non-filter or mixed subtype AND group_by/breakdowns were requested — those are not yet available for non-filter or mixed-subtype compositions, so the count is still returned but without the requested grouping.

Array<string>

Example

{
  "groups": [
    {
      "group_value": "California",
      "count": 1200000
    },
    {
      "group_value": "Texas",
      "count": 980000
    }
  ]
}

400

Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

validation_error

{
  "error": "Bad Request",
  "code": "MISSING_SEGMENTS",
  "message": "segment_ids is required for filter audiences."
}

401

Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

missing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the purchase scope."
}

429

Request throttled. Two distinct conditions return 429: Rate limit — too many requests per minute for your tier (error: rate_limit_exceeded); retry after retry_after_seconds. Compute ceiling — org-level BigQuery scan budget exhausted (error: compute_limit_exceeded); resets hourly or on plan upgrade.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit of 60 requests/minute exceeded for tier 'starter'.",
  "retry_after_seconds": 45
}

{
  "error": "compute_limit_exceeded",
  "message": "Org compute ceiling exceeded. Upgrade your plan or wait for the hourly reset."
}

502

The underlying BigQuery query failed, or (AGGREGATION_FLOOR_NOT_MET) the result set is too small to return while preserving individual-level privacy. message is always a friendly, client-safe description — the raw BigQuery error is never returned.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

{
  "error": "Bad Gateway",
  "code": "AGGREGATION_FLOOR_NOT_MET",
  "message": "For privacy reasons, a minimum of 50 records is required to view this information."
}

{
  "error": "Bad Gateway",
  "code": "BQ_TABLE_MISSING",
  "message": "This data is missing — it may have expired or the original upload never finished processing. Try re-uploading, or contact support if this persists."
}

Count records matching criteria

Authorizations

Request Bodyrequired

Responses

200

Example

400

Examples

401

Examples

403

Examples

429

Examples

502

Examples

Request Body^required