Get demographic breakdown for a segment

GET

/v1/segments/{id}/demographics

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

• Development API Server

Returns a BigQuery-computed demographic breakdown for the segment. This is the segment-level primary path: the breakdown is evaluated directly over the segment’s own filter definition — no audience composition (set_logic or exclusions) is applied. For a composed view, use GET /v1/audiences/{id}/demographics on a referencing audience. Works for every subtype: matched, similarity, and propensity segments bridge through a materialized scratch id-set (a 1-membership composition) so the same catalog-driven breakdown logic can run against them. Response is cached server-side for 20 minutes. Requires ‘discovery’ scope.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

Segment document ID.

Responses

200

Demographic breakdown.

Media typeapplication/json

object

segment_id

required

string

segment_name

required

string

total_count

required

Total records matching the segment’s filter definition.

integer

age_breakdown

required

Array<object>

object

label

required

Age bucket label.

string

pct

required

Percentage of total_count in this bucket (0-100, rounded).

number

geo_breakdown

required

Array<object>

object

label

required

Geography value (e.g. state).

string

count

required

integer

breakdown_extra

Present only when the query returns a behavioral or financial breakdown alongside age/geo.

Array<object>

object

label

required

string

pct

required

number

extra_field

Name of the attribute behind breakdown_extra. Present only alongside breakdown_extra.

string

generated_at

required

string format: date-time

Example

{
  "segment_id": "seg_abc123",
  "segment_name": "Sun Belt homeowners",
  "total_count": 182400,
  "age_breakdown": [
    {
      "label": "25-34",
      "pct": 22
    },
    {
      "label": "35-44",
      "pct": 31
    }
  ],
  "geo_breakdown": [
    {
      "label": "AZ",
      "count": 61200
    },
    {
      "label": "TX",
      "count": 121200
    }
  ],
  "generated_at": "2026-07-05T18:04:11.000Z"
}

400

Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.

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

Examplevalidation_error

{
  "error": "Bad Request",
  "code": "MISSING_SEGMENTS",
  "message": "segment_ids is required for filter audiences."
}

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"
}

502

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.

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": "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."
}