Reference

List saved audiences

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

Generated from the contractsView as Markdown

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`

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:

{
  "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.
`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.