Get an audience by ID

GET

/v1/audiences/{id}

curl --request GET \
  --url https://dev-api.infiniteaudience.ai/v1/audiences/example \
  --header 'Authorization: Bearer <token>'

• Development API Server

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.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

Responses

200

Audience document with expanded segment metadata.

Media typeapplication/json

object

audience_id

required

string

name

required

string

status

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.

string

Allowed values: active archived expired

version

required

integer

quote_id

ID of the most recent delivery quote for this audience.

string | null

quote_total_cents

Total cost in cents from the most recent delivery quote.

integer | null

parent_audience_id

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

string | null

forked_from_snapshot_version

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

integer | null

linked_campaign_id

ID of the campaign this audience is linked to, if any.

string | null

record_count

Total resolved records across all composed segments.

integer | null

matched_record_count

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.

integer | null

match_count

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.

integer | null

input_record_count

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

integer | null

match_rate

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

number | null

expires_at

required

ISO date — 90-day hard expiry from creation

string

version_created_at

string | null

visibility

required

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

string

Allowed values: org private

segment_refs

required

Composition of segments that define this audience. Each entry specifies a segment and its role (include or exclude) in the set operation.

Array<object>

object

segment_id

required

ID of the referenced segment.

string

role

required

Whether the segment’s records are included in or excluded from the audience.

string

Allowed values: include exclude

segment_ids

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

Array<string>

excluded_segment_ids

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

Array<string>

segments

required

Expanded summaries of the include-role segments, in segment_ids order. Populated on both list and single-GET responses. Best-effort — missing or deleted segment docs are skipped, so this array may be shorter than segment_ids.

Array<object>

Lightweight summary of a constituent segment, expanded server-side from the audience’s composition. Returned on both list and single-GET audience responses. subtype is the segment’s own subtype — use the first entry of segments (the primary included segment) to derive subtype-specific presentation for the audience.

object

id

required

Segment document ID.

string

name

required

Segment display name.

string

record_count

required

Cached record count of the segment. Null if never counted.

integer | null

subtype

required

Subtype of the constituent segment.

string

Allowed values: filter matched similarity propensity

input_record_count

required

Matched subtype only. Count of records in the uploaded identity file. Null otherwise.

integer | null

match_count

required

Matched subtype only. Count of records successfully matched. Null otherwise.

integer | null

excluded_segments

required

Expanded summaries of the exclude-role segments, in excluded_segment_ids order. Same expansion semantics as segments.

Array<object>

Lightweight summary of a constituent segment, expanded server-side from the audience’s composition. Returned on both list and single-GET audience responses. subtype is the segment’s own subtype — use the first entry of segments (the primary included segment) to derive subtype-specific presentation for the audience.

object

id

required

Segment document ID.

string

name

required

Segment display name.

string

record_count

required

Cached record count of the segment. Null if never counted.

integer | null

subtype

required

Subtype of the constituent segment.

string

Allowed values: filter matched similarity propensity

input_record_count

required

Matched subtype only. Count of records in the uploaded identity file. Null otherwise.

integer | null

match_count

required

Matched subtype only. Count of records successfully matched. Null otherwise.

integer | null

set_logic

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.

string

Allowed values: union intersection

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "status": "active",
  "visibility": "org",
  "segment_refs": [
    {
      "role": "include"
    }
  ],
  "segments": [
    {
      "subtype": "filter"
    }
  ],
  "excluded_segments": [
    {
      "subtype": "filter"
    }
  ],
  "set_logic": "union"
}

401

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).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplemissing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the purchase scope."
}

404

Resource not found or not accessible to the calling org.

Media typeapplication/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

key

additional properties

any

Examples

Examplenot_found

{
  "error": "Audience not found"
}