Skip to content
AdCrunch
Esc
↑↓navigate↵open⌘Jpreview
On this page

meta_list_custom_audiences

List the Custom Audiences of a Meta advertiser.

Ask which audiences an ad set can include or exclude. A Custom Audience is a group of people of the ad account, such as the visitors of your website or a lookalike of them.

Which Custom Audiences does Northwind have, and which ones can an ad set use now?

The agent calls meta_list_custom_audiences. A long list comes one part at a time. The agent reads each part. You see each audience with its source, its size as Meta estimates it, and the words of Meta about its state. An audience that Meta flagged, and one that is too small, cannot serve an ad set. The agent does not propose them. Change what runs on Meta shows where this step comes in the job.

Reference

Available on: Meta

List the Custom Audiences of a Meta ad account: the groups of people that an ad set can include or exclude. Its id goes in customAudiences or excludedCustomAudiences of meta_create_adset, or in originAudienceId of a lookalike that meta_create_custom_audience creates. Returns { id, name, source, approximateCount, usable, operationStatus } per audience. Pick one that is usable. A new audience can show no size and usable false while Meta populates it. When no answer holds a Custom Audience, up to the answer with no nextCursor, the account has none. The answer holds at most limit rows (default 100, maximum 500). When it carries nextCursor, more rows exist: call this tool again with the same arguments and cursor set to that value. When it carries no nextCursor, you have every row.

Input

Argument Type Required Description
advertiserId string yes Advertiser account ID (acc_<id>). Must belong to the active organization — find one with list_advertisers.
cursor string, at least 1 character no The nextCursor of the previous page. Omit it to get the first page. Send it with no change, and with the same filters as the request that answered it: a cursor from a different query gets a 400 invalid_cursor. Do not build or change a cursor.
limit integer, 1 to 500 no The greatest number of rows on the page, from 1 to 500. The default is 100. A greater value gets a 400, with error of invalid_request. Default: 100.

Output

A successful call returns this object in structuredContent.

Field Type Always present Description
customAudiences array of object yes The Custom Audiences of the advertiser, in the order of Meta. The list can be empty when nextCursor is present. Then more Custom Audiences can exist.
customAudiences[].approximateCount object or null yes The bounds of the number of people in the audience, as Meta estimates them. Null when Meta gives none, as for a lookalike that is not active yet.
customAudiences[].approximateCount.lowerBound integer yes The lower bound of the size that Meta estimates.
customAudiences[].approximateCount.upperBound integer yes The upper bound of the size that Meta estimates.
customAudiences[].id string yes The Meta id of the Custom Audience. Send it in customAudiences or excludedCustomAudiences of meta_create_adset, or as originAudienceId of a lookalike with meta_create_custom_audience.
customAudiences[].name string yes The name of the Custom Audience in Meta.
customAudiences[].operationStatus string or null yes The words of Meta about the state of the audience, for example that Meta still populates it. Null when Meta sends none.
customAudiences[].source one of website, customer_list, lookalike, other yes Where the people of the audience come from: website (the visitors that a Pixel saw), customer_list (a list of customers), lookalike (people like those of another audience), or other (a source that AdCrunch cannot create).
customAudiences[].usable boolean yes False when an ad set cannot use the audience: Meta flagged it for integrity reasons, or it is too small or cannot deliver. Do not include or exclude an audience that is not usable.
nextCursor string no Send this value as cursor to get the next page. It is absent on the last page.

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
  • provider_error
  • invalid_cursor
  • organization_unentitled
  • forbidden
  • invalid_request
  • internal_error

Scope

The token must hold observe:read. 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.

  • Read-only. The tool changes nothing.
  • Open world. The tool reaches a system outside AdCrunch, such as an ad platform.

Example

The arguments:

{
  "advertiserId": "acc_1485443900032333",
  "limit": 2
}

The result, in structuredContent:

{
  "customAudiences": [
    {
      "approximateCount": {
        "lowerBound": 12400,
        "upperBound": 14600
      },
      "id": "238000000000001",
      "name": "Visitors 30 days, no trial",
      "operationStatus": "Normal",
      "source": "website",
      "usable": true
    },
    {
      "approximateCount": null,
      "id": "238000000000002",
      "name": "Lookalike 1% US of Visitors 30 days",
      "operationStatus": "This audience is being populated.",
      "source": "lookalike",
      "usable": false
    }
  ]
}

Was this page helpful?