# List saved audiences

> list_audiences: Lists the organisation's saved audiences with their current counts and last refresh, newest first, optionally filtered by name.

Source: https://emailmovers.com/mydatahub/docs/reference/mcp/list_audiences

Lists the organisation's saved audiences with their current counts and last refresh, newest first, optionally filtered by name. Use it to find an aud_ id to count, quote or share. Free; it needs audiences:read. Pass an aud_ id to count_audience for a fresh count. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

| Property | Value |
| --- | --- |
| Tool name | `list_audiences` |
| Position in tools/list | 11 of 22 |
| Cost | Free |
| Scope | `audiences:read` |
| Annotations | readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false |
| Kind | Read only; idempotent, not destructive, closed world |
| REST equivalent | [`GET /v1/audiences`](https://emailmovers.com/mydatahub/docs/reference/rest/list-audiences.md) |

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm. This is what `tools/list` returns from https://mydatahub.emailmovers.com/mcp once v2 launches.

## Input

The schema sets `additionalProperties` to false, so a member that is not listed is refused.

| Member | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | no | Filter by name. |
| `limit` | integer (1 to 100) | no | Items per page, 1 to 100. Default 25. Default `25`. |
| `cursor` | string | no | An opaque cursor from next_cursor. Pass it back unchanged. |

## Example call

The `params` of a `tools/call` request:

```json
{
  "name": "list_audiences",
  "arguments": {}
}
```

## Output

The result carries `structuredContent` that matches this schema, and one line of text that leads with the number.

| Member | Type | Always present | Description |
| --- | --- | --- | --- |
| `data` | array of `SavedAudience` | yes |  |
| `data[].id` | string | yes | Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA. |
| `data[].name` | string | yes |  |
| `data[].audience` | `Audience` | yes | Who you want, as filters grouped by entity (company., site., contact., email., phone., signal.). The server fills its defaults (active companies, named emails, corporate subscribers, the current dataset_version) and returns the effective definition with every count. See [Audience](https://emailmovers.com/mydatahub/docs/audience.md). |
| `data[].brief` | string or null | yes | The brief it was compiled from, if any. |
| `data[].current_count` | `AudienceCountSummary` or null | yes |  |
| `data[].last_refreshed_at` | string (date-time) or null | yes |  |
| `data[].created_at` | string (date-time) | yes |  |
| `data[].updated_at` | string (date-time) | yes |  |
| `data[].created_by` | string | yes | Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8. |
| `data[].url` | string (uri) | yes | The audience in the app, mydatahub.emailmovers.com/audiences/{id}. |
| `has_more` | boolean | yes | Whether another page follows. |
| `next_cursor` | string or null | yes | Pass as cursor to fetch the next page; null on the last page. |

## Errors

A failed call returns `isError` true. The text content leads with the sentence a person acts on, then the whole problem as JSON, with `code`, `detail`, `next_step` and `did_you_mean`. A 401 and a step-up 403 are answered at HTTP level so the client can start authorisation. See [Errors](https://emailmovers.com/mydatahub/docs/errors.md).