Facebook AdsVersion: v3

Get custom audience by ID

GET/ad-publishing/facebook/custom-audience/{customAudienceId}

Retrieve one custom audience with its full detail. Returns more than the listing endpoint: Meta adds the fields relevant to the audience subtype (retentionDays and customerFileSource for customer lists, rule and pixelId for website audiences, lookalikeSpec for lookalikes), and this service appends extras describing the local smart-list or CSV source when the audience is a user-provided customer list.

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

Path Parameters

customAudienceIdstringrequired

Custom audience identifier

Example:23851234567890123

Query Parameters

locationIdstringrequired

Location identifier

Example:HChooFuiyPpVYzeJ4HMe

Response

application/json

The audience with the fields relevant to its subtype

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

customerFileSourcestring

How the member list was supplied. Present on customer-list audiences.

Example:USER_PROVIDED_ONLY

retentionDaysnumber

How long a member stays in the audience. 0 means members never expire.

Example:0

ruleobject

Matching rule for a website audience, as Meta returns it. Structure varies with the rule and is passed through unchanged.

pixelIdstring

Pixel backing a website audience

Example:2107520276278738

lookalikeSpecobject

Seed and ratio settings for a lookalike audience, passed through from Meta

lookalikeAudienceIdsstring[]

Ids of lookalikes derived from this audience

Example:["120250373909070122","120250393519390122"]

extrasobject

Local sourcing metadata. Added by this service only for user-provided customer lists that have a matching local record; absent otherwise.