meta_create_custom_audience

Create a Meta Custom Audience from the visitors of a Pixel, or 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, less the people who sent an event. 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. 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), less 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. 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.

Input

Argument	Type	Required	Description
`advertiserId`	string	yes	Advertiser account ID (`acc_<id>`). Must belong to the active organization.
`name`	string, at least 1 character	yes	Custom Audience name, as it will appear in Ads Manager.
`source`	one of `website`, `lookalike`	yes	What makes the audience. Each other field says which source takes it. Do not send a field of another source.
`excludeEvents`	array of (string, at least 1 character)	no	Only for source `website`, where it is optional. The Pixel events whose people the audience excludes, as the Pixel sends them, for example StartTrial or Purchase. A person who sent one of these events in the retention window is not in the audience. The events of a Pixel show which names it sends.
`pixelId`	string	no	Only for source `website`, where it is required. The Meta id of the Pixel whose visitors make the audience, digits only. Find it with the Pixels read of AdCrunch.
`retentionDays`	integer, 1 to 180	no	Only for source `website`, where it is required. How many days a person stays in the audience after a visit, from 1 to 180. Meta also adds the visits from before the create, up to this many days back.
`urlContains`	array of (string, at least 1 character)	no	Only for source `website`, where it is optional. The texts that the URL of a visited page contains, for example adcrunch.dev/pricing. A visitor of one page that contains one of the texts or more is in the audience. Meta compares with no regard to case. Omit it to include each visitor of the Pixel.
`country`	string	no	Only for source `lookalike`, where it is required. The country of the people of the lookalike, as a two-letter ISO 3166-1 alpha-2 code in capitals, for example US. One country only.
`originAudienceId`	string	no	Only for source `lookalike`, where it is required. The Meta id of the Custom Audience to start from (the seed), digits only. Find it with the Custom Audiences read of AdCrunch. Meta needs at least 100 people of the seed in the country, and refuses a seed that is too small or that it flagged.
`percent`	integer, 1 to 10	no	Only for source `lookalike`, where it is required. The share of the people of the country in the lookalike, from 1 to 10 percent. 1 holds the people most like the seed. A greater percent reaches more people who are less like the seed.

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`consoleUrl`	string	yes	The page of this change in the AdCrunch console. When `get_mutation_status` reports `awaiting_confirmation`, give this URL to the user: a person must confirm the change there before it reaches Meta. You cannot confirm it.
`mutationId`	string	yes	The id of the change. The change has not reached Meta yet. Give this id to `get_mutation_status` to find out how the change ended.

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"
}