MMetadata /docs
Docs/Tools/list_audiences

list_audiences

List the account's custom audiences, newest first: the same inventory the Metadata Audiences page shows.

Read audiences

Returns data. Calling it changes nothing, so it is safe in an unattended loop.

What it does

List the account's custom audiences, newest first: the same inventory the Metadata Audiences page shows.

                This is the BROWSE read: one row per audience, any type, searchable by name. Use it to answer "what audiences do I have", to find an audience by name, or to confirm that one the user just built exists. `get_matched_audiences` is a different view and cannot answer these: it lists a row per audience PER CHANNEL, it requires a `type` filter whose enum omits several platform audience types, and it has no name search.

                NOT THE SOURCE FOR CAMPAIGN OR TARGET-GROUP ATTACH. These rows carry no liveness: nothing here says whether the audience has a live segment on the channel you are targeting, and the platform refuses a target group that references one that does not. When you need an audience for a target group's `include[].audiences` / `exclude.audiences`, or for any campaign build, call `get_matched_audiences` for the channel and copy `mdAudienceId`, `type`, `matchCount`, `matchCountType` and `inactive` from ITS rows. Use this tool to work out WHICH audience the user means, never to build the entry you attach.

                PARAMETERS:
                - name: Contains-search on the audience name (optional)
                - type: Array of CustomAudienceType values to filter by (optional; omit for every type)
                - page: Page number, 0-indexed (default: 0)
                - size: Rows per page, 1-100 (default: 25)

                RETURNS:
                One page of audiences, newest first, each carrying:
                - id: Custom Audience ID
                - name: Audience name
                - type: CustomAudienceType (FIRMOGRAPHIC_INCLUDE, CONTACT_LIST, NATIVE_TARGETING_CSV, ...)
                - companies / contacts: the expected companies and contacts, or null while the platform is still counting them
                - status: the audience's own build status. READY, COMPLETED, Finished and DynamicComplete mean it is built; New and WaitingDataNodeCallback mean it is still being built; ACTIVE is the fallback for an audience with no build flow
                - created: when it was created
                Plus `total`, `totalPages`, `page` and `size` for paging.

                Archived audiences are excluded, as on the Audiences page. For one audience's criteria and counts use `get_audience_details` or `get_deep_audience_details`.

Arguments

ArgumentTypeNotes
name string Filter by audience name (contains match). Omit to list every audience.
type array Filter by CustomAudienceType. The platform binds these to a Java enum, so an unlisted value fails the request rather than matching nothing. Omit to list every type.
page integer Page number, 0-indexed.
size integer Rows per page.

Request

Request template, not a complete runnable example. Replace placeholders, empty objects, arrays, and zero values with valid account-specific inputs. Read required fields and nested constraints in the full schema. Confirm the account, connected channels, and referenced assets before calling a write tool.

curl
curl -s -X POST https://mcp-server.metadata.io/mcp \
  -H "Authorization: $METADATA_PAT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_audiences","arguments":{}}}'

Response

No recorded response. This tool needs arguments that only exist inside an account, so no response is recorded here. The request is an illustrative template. Fill required fields and check the current schema before calling it. No response is fabricated.

Other audiences tools:

Browse the tool catalog · machine-readable index