Get demographic breakdown for an audience
const url = 'https://api.infiniteaudience.ai/v1/audiences/example/demographics';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.infiniteaudience.ai/v1/audiences/example/demographics \ --header 'Authorization: Bearer <token>'Returns a computed demographic breakdown for the audience, evaluated over the audience as a composition: its include-role segments combined per set_logic, minus any excluded segments. Works for every composition — pure-filter, a single non-filter subtype (matched, similarity, propensity), or a genuine mix — via a materialized scratch id-set bridge for compositions that include a non-filter segment. Response is cached server-side for 20 minutes. A population or individual demographic cell below the 50-record privacy floor returns 422 without a partial breakdown. Requires ‘discovery’ scope.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Audience document ID.
Responses
Section titled “Responses”Demographic breakdown.
object
object
object
object
Examplegenerated
{ "audience_id": "example", "audience_name": "example", "total_count": 1, "age_breakdown": [ { "label": "example", "pct": 1 } ], "geo_breakdown": [ { "label": "example", "count": 1 } ], "breakdown_extra": [ { "label": "example", "pct": 1 } ], "extra_field": "example", "generated_at": "2026-04-15T12:00:00Z"}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."}Resource not found or not accessible to the calling org.
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": "Audience not found"}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."}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."}