Guides

Audience Intelligence API

Analyze audience demographics and composition to guide targeting and campaign planning.

Overview

The Audience Intelligence API provides audience composition insights for eligible custom audiences. These insights help advertisers and partners better understand who a campaign could reach before activation.

Audience Intelligence is designed for campaign planning and audience evaluation. Rather than measuring campaign performance, it helps you analyze the characteristics of a targetable audience before media is activated.

Audience Intelligence can be used to:

  • Discover new audience opportunities
  • Validate targeting strategies
  • Compare audience options before activation
  • Understand audience composition
  • Refine creative and messaging approaches
  • Improve campaign planning and optimization

Insights include:

  • Audience demographics
  • Geographic distribution
  • Household composition trends
  • Audience size distribution by segment
📌

Important

Audience Intelligence represents the audience available for targeting.

It does not represent users reached by a campaign and should not be used as campaign reporting.

Availability

Supported for Onsite Display only.

How Audience Intelligence fits into campaign planning

Audience Intelligence is most commonly used during audience planning workflows before targeting is activated.

Build Audience

Create or identify an existing custom audience.

Analyze Composition

Review demographic and geographic insights.

Refine Strategy

Adjust targeting, messaging, or creative plans.

Activate

Apply the audience to targeting.

Common use cases

Audience Discovery

Identify new audience opportunities before activation.

Campaign Planning

Validate whether an audience aligns to campaign goals.

Audience Comparison

Compare multiple audiences before choosing one for targeting.

Creative Strategy

Adapt messaging and creative based on audience composition.

How it works

Audience Intelligence analyzes an eligible custom audience and returns audience composition insights across supported dimensions.

These insights represent the targetable audience pool, not campaign delivery results.

📌

Audience Intelligence characteristics

  • Audience characteristics are based on the audience available for targeting.
  • Audience characteristics are not specific to campaign delivery.
  • Audience Intelligence insights represent who the campaign could reach.
  • Audience Intelligence insights do not represent who a campaign has reached.

Supported insight dimensions

Use the dimension parameter to return audience insights for a specific audience characteristic.

Age

Audience age distribution e.g. Ages 18-24, 25-34, etc.

Gender

Audience age distribution e.g. male, female, unknown

Income

Household income distribution e.g. $0-$24,000

DMA

Geographic distribution by DMA

Region

US regional distribution (Midwest, South, West, Northeast)

Residential status

Home ownership composition e.g. home owner, renter

📌

Audience Intelligence constraint

Audience Intelligence only returns data for custom audiences without demographic or geographic overlays.

Before you begin

  • Valid advertiserId
  • Valid custom audienceId
  • Audience must be an eligible rule-based or advanced custom audience in AVAILABLE status
  • Audience must not contain demographic overlays
  • Audience must not contain geographic overlays

Endpoint

POST /api/v1/audiences/intelligence

View technical specifications

Request details

How this request is used

Retrieves audience composition insights for an eligible custom audience.

Key fields and behaviors

  • dimension
    Limits the response to a single audience dimension. Only one dimension filter may be used per request.

  • asOfDate
    Returns insights as of a specific date.

  • dmaLimit
    Only applies when dimension = DMA.

    Limits the number of DMA rows returned.

    Default = 5

Sample requests

Without a filter
{ "advertiserId":1200, "audienceId":12000, "asOfDate":"2025-02-12"
}
With a dimension filter
{ "advertiserId":1200, "audienceId":12000, "asOfDate":"2025-02-12", "dimension": "age"
}
With dma and dmaLimit filter
{ "advertiserId":1200, "audienceId":12000, "asOfDate":"2025-02-12", "dimension": "dma", "dmaLimit":2
}

Response details

What this response returns

Returns audience composition insights grouped by dimension.

Key fields to use - success

  • audienceId
  • asOfDate
  • metrics
    • dimension
    • values
      • key
        Enumerated value representing the audience segment.
      • value
        Share of audience represented by the segment.
      • unit
        Currently only PERCENT.
  • lastUpdatedAt

Dimension object values

How to use these values

  • Key values represent enumerated codes used in API responses.
  • U represents Unknown when applicable.
KeyDescription
AAges 18–24
BAges 25–34
CAges 35–44
DAges 45–54
EAges 55–64
FAges 65+
UUnknown

Key fields to use - failure

  • code
    Failed operation is indicated as failure.

  • details
    Populates the error message depending upon the value of code.

  • message
    Optional. High-level, human-readable summary of the error when available.

  • errors
    Detailed information about one or more errors. This is an array object with fields: field, errorType, description

Error Handling

If the request or an individual item fails, the response includes error information to help identify the issue and determine the corrective action. Use errorType for the error condition, field for the affected request field when applicable, and description for an explanation of the error and, when available, guidance on how to resolve it.
For the complete error response schema and endpoint-specific response definitions, see the API Reference. For guidance on HTTP status codes and how clients should handle them, see API status codes and error handling.

Sample responses

Without a filter
{ "audienceId": 12000, "asOfDate": "2025-02-27", "metrics": [ { "dimension": "AGE", "values": [ { "key": "A", "value": 2.2, "unit": "PERCENT" }, { "key": "B", "value": 8.3, "unit": "PERCENT" }, { "key": "C", "value": 13.1, "unit": "PERCENT" }, { "key": "D", "value": 14.1, "unit": "PERCENT" }, { "key": "E", "value": 16.2, "unit": "PERCENT" }, { "key": "F", "value": 27.8, "unit": "PERCENT" }, { "key": "U", "value": 18.1, "unit": "PERCENT" } ] }, { "dimension": "INCOME", "values": [ { "key": "A", "value": 11.7, "unit": "PERCENT" }, { "key": "B", "value": 18.4, "unit": "PERCENT" }, { "key": "C", "value": 19.1, "unit": "PERCENT" }, { "key": "D", "value": 15.8, "unit": "PERCENT" }, { "key": "E", "value": 18.1, "unit": "PERCENT" }, { "key": "F", "value": 7.2, "unit": "PERCENT" }, { "key": "G", "value": 7.6, "unit": "PERCENT" }, { "key": "U", "value": 2, "unit": "PERCENT" } ] }, { "dimension": "GENDER", "values": [ { "key": "M", "value": 43.4, "unit": "PERCENT" }, { "key": "F", "value": 56.5, "unit": "PERCENT" }, { "key": "U", "value": 0.1, "unit": "PERCENT" } ] }, { "dimension": "REGION", "values": [ { "key": "MIDWEST", "value": 26.2, "unit": "PERCENT" }, { "key": "NORTHEAST", "value": 10.5, "unit": "PERCENT" }, { "key": "SOUTH", "value": 45.7, "unit": "PERCENT" }, { "key": "WEST", "value": 17.7, "unit": "PERCENT" } ] }, { "dimension": "RESIDENTIAL_STATUS", "values": [ { "key": "HOME_OWNER", "value": 69.5, "unit": "PERCENT" }, { "key": "RENTER", "value": 15.9, "unit": "PERCENT" }, { "key": "U", "value": 14.6, "unit": "PERCENT" } ] }, { "dimension": "DMA", "values": [ { "key": "Albany1 GA", "value": 3.6, "unit": "PERCENT" }, { "key": "Albany2 GA", "value": 2.4, "unit": "PERCENT" }, { "key": "Albany3 GA", "value": 2.1, "unit": "PERCENT" }, { "key": "Albany4 GA", "value": 2, "unit": "PERCENT" }, { "key": "Albany5 GA", "value": 1.9, "unit": "PERCENT" } ] } ], "lastUpdatedAt": "2025-03-11T16:41:29.82-04:00"
}
Age filter
{ "audienceId":12000, "asOfDate": "2025-02-12", "metrics": [ { "dimension": "AGE", "values": [ { "key": "A", "value": 412, "unit": "PERCENT"         }, { "key": "B", "value": 41.2, "unit": "PERCENT"         }, { "key": "C", "value": 12.0, "unit": "PERCENT"         }, { "key": "D", "value": 41.2, "unit": "PERCENT"         }, { "key": "E", "value": 41.2, "unit": "PERCENT"         }, { "key": "F", "value": 41.0, "unit": "PERCENT"         }, { "key": "U", "value": 20.0, "unit": "PERCENT"         }       ] } ], "lastUpdatedAt": "2025-02-03T19:35:20.567-04:00"
}
Income filter
{ "audienceId":12000, "asOfDate": "2025-02-12", "metrics": [ { "dimension": "INCOME", "values": [ { "key": "A", "value": 41.2, "unit": "PERCENT"         }, { "key": "B", "value": 41.2, "unit": "PERCENT"         }, { "key": "C", "value": 12.0, "unit": "PERCENT"         }, { "key": "D", "value": 41.2, "unit": "PERCENT"         }, { "key": "E", "value": 41.2, "unit": "PERCENT"         }, { "key": "F", "value": 41.0, "unit": "PERCENT"         }, { "key": "G", "value": 20.0, "unit": "PERCENT"         }, { "key": "U", "value": 20.0, "unit": "PERCENT"         } ] } ], "lastUpdatedAt": "2025-02-03T19:35:20.567-04:00"
}
Gender filter
{ "audienceId":12000, "asOfDate": "2025-02-12", "metrics": [ { "dimension": "GENDER", "values": [ { "key": "M", "value": 41.2, "unit": "PERCENT"         }, { "key": "F", "value": 41.2, "unit": "PERCENT"         }, { "key": "U", "value": 20.0, "unit": "PERCENT"         }       ] } ], "lastUpdatedAt": "2025-02-03T19:35:20.567-04:00"
}
Residential status filter
{ "audienceId":12000, "asOfDate": "2025-02-12", "metrics": [ { "dimension": "RESIDENTIAL_STATUS", "values": [ { "key": "HOME_OWNER", "value": 41.2, "unit": "PERCENT"         }, { "key": "RENTER", "value": 41.2, "unit": "PERCENT"         }, { "key": "U", "value": 41.2, "unit": "PERCENT"         }       ] } ], "lastUpdatedAt": "2025-02-03T19:35:20.567-04:00"
}
With DMA filter and dmaLimit
{ "audienceId":12000, "asOfDate": "2025-02-12", "metrics": [ { "dimension": "DMA", "values": [ { "key": "Albany1 GA", "value": 41.2, "unit": "PERCENT"         }, { "key": "Albany2 GA", "value": 41.2, "unit": "PERCENT"         } ] } ], "lastUpdatedAt": "2025-02-03T19:35:20.567-04:00"
}
Region filter
{ "audienceId":12000, "asOfDate": "2025-02-12", "metrics": [ { "dimension": "REGION", "values": [ { "key": "MIDWEST", "value": 41.2, "unit": "PERCENT"         }, { "key": "SOUTH", "value": 41.2, "unit": "PERCENT"         }, { "key": "WEST", "value": 41.2, "unit": "PERCENT"         }, { "key": "NORTHEAST", "value": 41.2, "unit": "PERCENT"         }, { "key": "U", "value": 41.2, "unit": "PERCENT"         }      ] } ], "lastUpdatedAt": "2025-02-03T19:35:20.567-04:00"
}
Sample response - failure
[ { "code": "failure", "details": [ "string" ],    "message": "string",
    "errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]

Common issues

  • Audience contains demographic overlays
  • Audience contains geographic overlays
  • Unsupported dimension value
  • Limited DMA rows because default dmaLimit was applied
  • Interpreting Audience Intelligence as campaign reporting
  • Audience is not in AVAILABLE status

What happens next

  • Compare audiences before activation
  • Refine audience strategies
  • Adjust creative and messaging plans
  • Apply the audience to targeting
  • Launch campaigns with greater confidence

Related pages

Updated 5 days ago

Did this page help you?