Return masked sample rows matching criteria
const url = 'https://dev-api.infiniteaudience.ai/v1/discovery/lookup';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"],"limit":10}'};
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/lookup \ --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" ], "limit": 10 }'Returns up to 25 masked sample rows matching the criteria. PII attributes are masked or omitted. Requires ‘discovery’ scope.
Provide exactly one of: filters, filter_groups, segment_id, audience_id, or segment_ids + set_logic (same input shapes as /v1/discovery/count). Sending more than one returns 400 AMBIGUOUS_INPUT; sending none returns 400 NO_INPUT_SPECIFIED.
If you pass a segment, audience, or filter groups, full group/combinator structure is preserved — 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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”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 to sample from.
ID of a saved audience to sample from.
IDs of multiple segments to combine (requires set_logic).
How to combine segment_ids: union = match ANY segment (OR); intersection = match EVERY segment (AND).
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).
Responses
Section titled “Responses”Sample rows.
object
Up to limit anonymised sample rows. PII attributes (email, phone, address) are masked or omitted. iag_person_id is always null.
object
Total records matching the criteria (may exceed rows.length, which is capped at limit).
Field names present on the returned rows (after PII masking/omission).
Examplegenerated
{ "rows": [ { "additionalProperty": "example" } ], "total_matched": 1, "bytes_scanned": 1, "estimated_cost_usd": 1, "available_fields": [ "example" ]}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."}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.
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": "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."}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."}