Calculate record overlap between two criteria sets
const url = 'https://dev-api.infiniteaudience.ai/v1/discovery/overlap';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"a":{"segment_id":"seg_1a2b3c"},"b":{"audience_id":"aud_9z8y7x"}}'};
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/overlap \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "a": { "segment_id": "seg_1a2b3c" }, "b": { "audience_id": "aud_9z8y7x" } }'Computes the number and percentage of records that appear in both of two criteria sets, plus side-by-side demographic deltas. Requires ‘discovery’ scope.
Each side (a and b) independently accepts exactly one discovery input shape (filters, filter_groups, segment_id, audience_id, or segment_ids + set_logic) — the legacy flat audience_id_a / audience_id_b fields are also still accepted. A side that provides more than one shape, or combines the structured object with its legacy field, returns 400 AMBIGUOUS_INPUT. A side that provides nothing returns 400 NO_INPUT_SPECIFIED.
Each side preserves full group/combinator structure independently: if a side is a segment, audience, or filter groups, each segment’s own AND/OR groups are evaluated intact, multiple composed segments are combined by set_logic, and an audience’s excluded segments are always subtracted (AND NOT), regardless of set_logic — before the two sides are joined for the overlap count.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Side A. Mutually exclusive with audience_id_a.
object
Compound boolean filter groups.
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
Stable identifier (UUID or NanoID). Used to track groups across edits.
One or more filter conditions. All conditions in this array are combined with AND. Provide at least one filter per group.
A single filter condition for audience discovery or job execution
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.
ID of a saved segment.
ID of a saved audience.
IDs of multiple segments to combine (requires set_logic).
How to combine segment_ids: union = match ANY segment (OR); intersection = match EVERY segment (AND).
Side B. Mutually exclusive with audience_id_b.
object
Compound boolean filter groups.
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
Stable identifier (UUID or NanoID). Used to track groups across edits.
One or more filter conditions. All conditions in this array are combined with AND. Provide at least one filter per group.
A single filter condition for audience discovery or job execution
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.
ID of a saved segment.
ID of a saved audience.
IDs of multiple segments to combine (requires set_logic).
How to combine segment_ids: union = match ANY segment (OR); intersection = match EVERY segment (AND).
(Legacy) First audience ID. Mutually exclusive with a.
(Legacy) Second audience ID. Mutually exclusive with b.
Example
{ "a": { "segment_id": "seg_1a2b3c" }, "b": { "audience_id": "aud_9z8y7x" }}Responses
Section titled “Responses”Overlap result with demographic deltas.
object
Overlap as a percentage of the smaller side.
Side-by-side demographic comparison. Each entry: {metric, label, a, b, delta}.
object
Optional paired distribution buckets for side A.
One bucket of a categorical distribution.
object
Optional paired distribution buckets for side B.
One bucket of a categorical distribution.
object
Attribute the paired distributions are bucketed on.
Human-readable label for the distribution attribute.
One bucket of a categorical distribution.
object
One bucket of a categorical distribution.
object
One bucket of a categorical distribution.
object
One bucket of a categorical distribution.
object
Present only when at least one side resolves to a non-filter or mixed-subtype composition. Two cases: “One or both sides had no composable segments” when a side’s composition is empty (counts are all 0); or “Demographic breakdowns are not yet available for non-filter or mixed-subtype compositions” when counts/ overlap were computed directly but demographic_deltas could not be (returned as an empty array in that case).
Example
{ "a_name": "CA Homeowners", "b_name": "TX Families", "a_count": 1204551, "b_count": 988102, "overlap_count": 51233, "overlap_pct": 5.2, "demographic_deltas": [ { "metric": "median_age", "label": "Median age", "a": 44, "b": 39, "delta": -5 } ]}Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Bad Request", "code": "MISSING_SEGMENTS", "message": "segment_ids is required for filter audiences."}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).
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Unauthorized: Missing or invalid Authorization header"}{ "error": "Unauthorized", "code": "TOKEN_EXPIRED", "message": "Your session has expired. Please sign in again."}Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "SCOPE_REQUIRED", "message": "This endpoint requires the purchase scope."}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.
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
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."}