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.

Request

Version stringrequired

API Version

Available options2021-04-15

locationId stringrequired

Location identifier

type stringrequired

Audience list type

Available optionslookalikecustomall

source string

Audience data source

Available optionsad_managerintegration

adAccountId stringrequired

Ad account identifier

limit string

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

after string

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

projection string[]

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

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.

application/json

Schema

Schema

oneOf
• object[]
• PaginatedFacebookCustomAudiencesDTO
Array [
idstring
Audience id
namestring
Audience name
descriptionstring
Audience description. Empty string when not set.
subtypestring
How the audience was built. LOOKALIKE for lookalikes; CUSTOM, ENGAGEMENT, WEBSITE, and LEAD for the rest.
approximateCountLowerBoundnumber
Lower bound of the audience size. Facebook floors small audiences — 1000 and 20 are placeholders, not counts.
approximateCountUpperBoundnumber
Upper bound of the audience size
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.
timeUpdatednumber
Last update time as a Unix timestamp in seconds. Equals timeCreated when never edited.
]

Example (auto)

[
  {
    "id": "120250373909070122",
    "name": "Website Visitors - Last 30 Days",
    "description": "",
    "subtype": "ENGAGEMENT",
    "approximateCountLowerBound": 19900000,
    "approximateCountUpperBound": 23400000,
    "deliveryStatus": {
      "code": 200,
      "description": "This audience is ready for use."
    },
    "operationStatus": {
      "code": 200,
      "description": "This audience is ready for use."
    },
    "dataSource": {
      "type": "EVENT_BASED",
      "subType": "WEB_PIXEL_HITS",
      "creationParams": "[]"
    },
    "timeCreated": 1787123977,
    "timeUpdated": 1787123977
  }
]