meta_create_custom_audience

Create a Meta Custom Audience from the visitors of a Pixel, from a list of your customers, or as a lookalike of another audience.

Ask for a group of people that an ad set can include or exclude. A website audience holds the people that your Pixel saw on some pages, except the people who sent an event. A customer list holds the people of the emails and the phone numbers that you give. AdCrunch sends Meta only a hash of each email and of each phone number, and keeps no plaintext copy. A lookalike holds the people of one country who are most like the people of another audience. A Custom Audience has no status, so it spends nothing.

Make an audience of the people who visited adcrunch.dev in the last 30 days and did not start a trial. Then make a 1% lookalike of it in the US.

The agent calls meta_create_custom_audience once for each audience, then get_mutation_status, and you see the id of each new audience. Meta can take some hours to populate a new audience. Meta refuses a lookalike of an audience that is too small, and the agent tells you the words of Meta. Before the first customer list, a person of the ad account must accept the Custom Audience Terms of Meta in Meta Ads Manager. Until then, the change ends with custom_audience_terms_not_accepted, and the agent gives you the page where you accept them. Change what runs on Meta shows how an ad set uses the audiences.

Reference

Available on:

Create a Custom Audience on a live Meta ad account. source selects what makes the audience. website: the people that a Pixel saw in the last retentionDays days (1 to 180), on a URL that contains one of urlContains (omit it for each visitor), except the people who sent one of excludeEvents. Find the Pixel with meta_list_pixels, and the names of its events with meta_list_pixel_events. customer_list: the people of the emails and the phones that you give, 10,000 at most together. Give each phone number with its country code after a +. AdCrunch sends Meta only a hash of each identifier. It keeps no plaintext copy. The ad account must accept the Custom Audience Terms of Meta first. Without them, the change ends with custom_audience_terms_not_accepted, and the message gives the page where a person accepts them. lookalike: the people of one country who are most like the people of the audience originAudienceId, as percent of the country (1 to 10). Find the seed with meta_list_custom_audiences. Meta refuses a seed that is too small or that it flagged, and the answer gives the words of Meta. A Custom Audience has no status and starts no spend. Meta can take some hours to populate it. Then use its id in customAudiences or excludedCustomAudiences of meta_create_adset. Runs asynchronously: returns a mutationId — call get_mutation_status with it to get the id of the new audience. For a customer list, it also gives the counts of Meta in identifiers.

Input

Output

A successful call returns this object in structuredContent.

Failure codes

A failed call has isError set, and structuredContent.error holds one of these codes. Errors describes the shape of a failed call.

• not_found
• provider_not_connected
• missing_write_access
• organization_unentitled
• forbidden
• invalid_request
• internal_error

Scope

The token must hold mutation:write. Auth & scopes lists each scope.

Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

• Writes. The tool can change data.
• Destructive. The tool can make a change that you cannot undo. A client can ask you to confirm before it calls the tool.
• Not idempotent. A second call with the same arguments can change more.
• Open world. The tool reaches a system outside AdCrunch, such as an ad platform.

Example

The arguments:

{
  "advertiserId": "acc_1485443900032333",
  "excludeEvents": [
    "StartTrial"
  ],
  "name": "Visitors 30 days, no trial",
  "pixelId": "812345678901234",
  "retentionDays": 30,
  "source": "website",
  "urlContains": [
    "adcrunch.dev"
  ]
}

The result, in structuredContent:

{
  "consoleUrl": "https://console.adcrunch.dev/activity/mut_k3x9q2v7m4n8p1r5t6w0y2z4",
  "mutationId": "mut_k3x9q2v7m4n8p1r5t6w0y2z4"
}