Return masked sample rows matching criteria
const url = 'https://api.infiniteaudience.ai/v1/discovery/lookup';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"filters":[{"field":"example","op":"=","text_comparison":"exact","trim_whitespace":true,"value":["example"]}],"filter_groups":[{"id":"example","filters":[{"field":"example","op":"=","text_comparison":"exact","trim_whitespace":true,"value":["example"]}],"combinator":"AND"}],"segment_id":"example","audience_id":"example","segment_ids":["example"],"set_logic":"union","excluded_segment_ids":["example"],"limit":10,"fields":["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://api.infiniteaudience.ai/v1/discovery/lookup \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "filters": [ { "field": "example", "op": "=", "text_comparison": "exact", "trim_whitespace": true, "value": [ "example" ] } ], "filter_groups": [ { "id": "example", "filters": [ { "field": "example", "op": "=", "text_comparison": "exact", "trim_whitespace": true, "value": [ "example" ] } ], "combinator": "AND" } ], "segment_id": "example", "audience_id": "example", "segment_ids": [ "example" ], "set_logic": "union", "excluded_segment_ids": [ "example" ], "limit": 10, "fields": [ "example" ] }'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
Flat filter array (recommended).
A single filter condition for audience discovery or job execution
object
Canonical catalog field_name (e.g. age or state). ZIP5 also accepts zip, zip_code, or postal_code as input aliases; saved responses use zip5.
Comparison operator
Optional STRING comparison mode for =, !=, IN, NOT IN, and LIKE, or ARRAY
Optionally trim leading and trailing whitespace on both sides of a STRING or ARRAY
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
object
Canonical catalog field_name (e.g. age or state). ZIP5 also accepts zip, zip_code, or postal_code as input aliases; saved responses use zip5.
Comparison operator
Optional STRING comparison mode for =, !=, IN, NOT IN, and LIKE, or ARRAY
Optionally trim leading and trailing whitespace on both sides of a STRING or ARRAY
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).
Optional non-PII audience fields to preview. Defaults to a small demographic selection. Discover field names with GET /v1/catalog/fields.
Responses
Section titled “Responses”Sample rows.
object
Up to limit sample rows containing only the selected non-PII audience fields.
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": [ {} ], "total_matched": 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.
Public action for correcting the request or retrying later.
object
JSON path to the invalid filter field or value.
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.
Public action for correcting the request or retrying later.
object
JSON path to the invalid filter field or value.
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.
Public action for correcting the request or retrying later.
object
JSON path to the invalid filter field or value.
Examples
{ "error": "SCOPE_REQUIRED", "message": "This endpoint requires the creator scope."}The result is below the minimum population that can be returned while preserving privacy.
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.
Public action for correcting the request or retrying later.
object
JSON path to the invalid filter field or value.
Example
{ "error": "Privacy threshold not met", "code": "AGGREGATION_FLOOR_NOT_MET", "message": "For privacy reasons, a minimum of 50 records is required to view this information."}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 query-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.
Public action for correcting the request or retrying later.
object
JSON path to the invalid filter field or value.
Examples
{ "error": "rate_limit_exceeded", "message": "Rate limit of 100 requests/minute exceeded for tier 'pilot'.", "retry_after_seconds": 45}{ "error": "compute_limit_exceeded", "message": "Org compute ceiling exceeded. Upgrade your plan or wait for the hourly reset."}The underlying analytics query failed, or (AGGREGATION_FLOOR_NOT_MET) a non-discovery route encountered a result below the privacy floor. message is always a friendly, client-safe description — the raw backend 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.
Public action for correcting the request or retrying later.
object
JSON path to the invalid filter field or value.
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."}