Skip to main content
Facebook AdsVersion: v3

Get custom audiences

GET/ad-publishing/facebook/custom-audience

Retrieve Facebook custom audiences for a location. Without limit the response is a plain array. When limit is provided (max 100) the response is a paginated { customAudiences, paging } envelope; pass after (from paging.next) to fetch the next batch. By default each item is returned in full; pass projection (comma-separated, dot-notation for nested fields, e.g. ?projection=id,name,dataSource.type) to return only the requested fields — any value outside the known field set is rejected.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:adPublishing.readonly
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version

Available optionsv3
Example:v3

Query Parameters

locationIdstringrequired

Location identifier

Example:loc_abc123
typestringrequired

Audience list type

Available optionslookalikecustomall
Example:custom
sourcestring

Audience data source

Available optionsad_managerintegration
Example:ad_manager
adAccountIdstringrequired

Ad account identifier

Example:act_123456
limitstring

Page size for a paginated fetch (max 100). When set, the response is a { customAudiences, paging } envelope instead of a plain array.

Example:25
afterstring

Opaque cursor for the next batch, taken from the previous response paging.next

Example:QVFIU...
projectionstring[]

Fields to return on each item, comma-separated (e.g. ?projection=id,name,dataSource.type). When set, only the requested fields are returned. Nested fields use dot-notation; naming a parent (e.g. dataSource) returns the whole nested object. Any value outside the known field set is rejected. Omit the param entirely to receive the full item as-is.

Available optionsidnamedescriptionapproximateCountLowerBoundapproximateCountUpperBoundsubtypetimeCreatedtimeUpdateddataSourcedataSource.typedataSource.subTypedataSource.creationParams
Example:["id","name","dataSource.type","deliveryStatus.code"]

Response

application/json

A plain array of custom audiences (default), or a { customAudiences, paging } envelope when limit is provided. Lookalike and custom audiences share one shape — subtype distinguishes them. Supplying projection narrows every entry to the requested fields only.

oneOf
  • Array items
    • idstring

    Audience id

    Example:120250373909070122
    namestring

    Audience name

    Example:Website Visitors - Last 30 Days
    descriptionstring

    Audience description. Empty string when not set.

    Example:
    subtypestring

    How the audience was built. LOOKALIKE for lookalikes; CUSTOM, ENGAGEMENT, WEBSITE, and LEAD for the rest.

    Example:ENGAGEMENT
    approximateCountLowerBoundnumber

    Lower bound of the audience size. Facebook floors small audiences — 1000 and 20 are placeholders, not counts.

    Example:19900000
    approximateCountUpperBoundnumber

    Upper bound of the audience size

    Example:23400000
    deliveryStatusobject

    Whether the audience can be used in a campaign right now

    operationStatusobject

    Whether Facebook is still building or refreshing the audience

    dataSourceobject

    Where the audience gets its members from

    timeCreatednumber

    Creation time as a Unix timestamp in seconds, not milliseconds and not ISO-8601.

    Example:1787123977
    timeUpdatednumber

    Last update time as a Unix timestamp in seconds. Equals timeCreated when never edited.

    Example:1787123977