Audiences

Get an audience by ID

Returns the audience with expanded segment metadata — both include-role (segments) and exclude-role (excluded_segments) summaries, each carrying the segment's subtype. Requires 'discovery' scope.

get/v1/audiences/{id}

Request

  • Base URL: https://api.infiniteaudience.ai
  • URL: https://api.infiniteaudience.ai/v1/audiences/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

Response

Audience document with expanded segment metadata.

audience_idstring required
namestring required
status'active' | 'archived' | 'expired' required

active = ready for delivery; archived = soft-deleted via PATCH status:archived (excluded from list by default); expired = past 90-day TTL. Note: pending/failed statuses belong on segments, not audiences.

versioninteger required
quote_idstring nullable

ID of the most recent delivery quote for this audience.

quote_total_centsinteger nullable

Total cost in cents from the most recent delivery quote.

parent_audience_idstring nullable

ID of the audience this was forked from (null if not a fork).

forked_from_snapshot_versioninteger nullable

Snapshot version of the parent audience at the time of forking.

record_countinteger nullable

Total resolved records across all composed segments.

matched_record_countinteger nullable

Records contributed by matched-subtype segments in this audience's composition. Present only when the composition includes at least one included matched segment; null for pure-filter or non-matched compositions.

match_countinteger nullable

Records resolved to a known identity, for an audience created via the direct file-upload flow (POST /v1/match/file). Populated when that upload's matching pipeline completes; null before then or for audiences not created that way — use matched_record_count for a composition-level matched count instead.

input_record_countinteger nullable

Rows in the originally uploaded identity file, for an audience created via POST /v1/match/file. Same population conditions as match_count.

match_ratenumber nullable

match_count / input_record_count, rounded to 4 decimal places. Null unless both match_count and input_record_count are present.

expires_atstring required

ISO date — 90-day hard expiry from creation

version_created_atstring nullable
visibility'org' | 'private' required

org (default) — visible to all members of the org. private — visible only to the creating user.

segment_idsstring[]

Cache of include-role segment IDs (denormalized from segment_refs for query efficiency).

excluded_segment_idsstring[]

Cache of exclude-role segment IDs (denormalized from segment_refs for query efficiency).

set_logic'union' | 'intersection'

How the include-role segments are combined: union = a record matches ANY included segment (OR); intersection = a record must match EVERY included segment (AND). Segments in excluded_segment_ids are always subtracted from that result (AND NOT), regardless of set_logic.

created_atstring date-time required
updated_atstring date-time required
campaign_idstring nullable required

The one campaign this audience belongs to, or null.

Changes

No recorded changes to this operation across all 1 revision of this API.