---
title: meta_list_custom_audiences
description: 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](/mcp/tools/change-what-runs-on-meta) shows where this step comes in the job.

## Reference

**Available on:** [![Meta](/providers/meta.svg)](https://docs.adcrunch.dev/connect/providers)

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](/mcp/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](/mcp/auth) 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:

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

The result, in `structuredContent`:

```json
{
  "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
    }
  ]
}
```