Reference
List saved audiences
GET /v1/audiences. Saved audiences shared across the organisation, with current counts and last refresh.
GET /v1/audiences
Saved audiences shared across the organisation, with current counts and last refresh.
| Property | Value |
|---|---|
| Endpoint | GET https://mydatahub.emailmovers.com/v1/audiences |
| Operation id | listAudiences |
| Cost | Free (0 credits) |
| Access | An API key or an OAuth 2.1 token with the scope audiences:read. |
| MCP tool | list_audiences |
| Tag | Audiences |
Request
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | no | Filter by name. |
limit | query | integer (1 to 100) | no | Items per page, 1 to 100. Default 25. |
cursor | query | string | no | An opaque cursor from next_cursor. Pass it back unchanged. |
MyDataHub-Version | header | string | no | The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window. |
Example request
curl "https://mydatahub.emailmovers.com/v1/audiences" \
-H "Authorization: Bearer $MYDATAHUB_API_KEY"Responses
200: A page of saved audiences.
Headers: RateLimit, RateLimit-Policy.
| 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. |
Example response
{
"data": [
{
"id": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA",
"name": "Marketing directors, Leeds",
"audience": {
"schema": "mydatahub.audience/1",
"dataset": "uk_contacts",
"dataset_version": "2026-W39",
"where": {
"all": [
{
"field": "contact.title",
"op": "matches",
"terms": ["marketing manager"],
"mode": "contains",
"expand": [
"plural_singular",
"department_synonyms",
"ampersand_and",
"abbreviations"
]
},
{
"field": "contact.job_level_rank",
"op": "in",
"values": [1, 2, 3, 4, 5, 6, 8, 9]
},
{
"field": "company.sic_2007",
"op": "in",
"values": ["C"]
},
{
"field": "company.employee_band",
"op": "gte",
"value": "50-99"
},
{
"field": "site.location",
"op": "within_radius",
"centre": {
"place": "Leeds"
},
"radius_miles": 20
},
{
"not": {
"field": "email.address_sha256",
"op": "in_list",
"list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
}
}
]
},
"email_policy": {
"min_deliverability_score": 70,
"allow_catch_all": false
},
"dedupe": "none"
},
"brief": "Marketing managers and above at manufacturers within 20 miles of Leeds",
"current_count": {
"count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ",
"dataset_version": "2026-W39",
"contacts": 12840,
"companies": 3115,
"emailable": 12310,
"counted_at": "2026-09-26T10:14:00Z"
},
"last_refreshed_at": "2026-09-28T06:00:00Z",
"created_at": "2026-09-26T10:20:00Z",
"updated_at": "2026-09-26T10:20:00Z",
"created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8",
"url": "https://mydatahub.emailmovers.com/audiences/aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA"
}
],
"has_more": false,
"next_cursor": null
}Errors
Every error is a problem object with a code and a next_step. Every response carries the RateLimit and RateLimit-Policy headers; see Rate limits.
| Status | Problem codes | When |
|---|---|---|
| 400 | invalid-request, idempotency-key-required, unsupported-version | The request could not be read, or an Idempotency-Key is missing. |
| 401 | authentication-required, account-required | Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required). |
| 403 | insufficient-scope, confirmation-required, business-details-required, licence-acceptance-required, dpa-acceptance-required, agent-budget-exceeded | The token lacks a scope (insufficient-scope, with required_scope and a WWW-Authenticate step-up challenge); no person confirmed the spend and no agent key covers it (confirmation-required, with an approval_url); an agent key's per-order cap or monthly budget does not cover it (agent-budget-exceeded); an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business, which its first order needs (business-details-required); the order needs the Data Licence and Sharing Agreement accepted at the version in force (licence-acceptance-required); or a suppression upload comes before the organisation has accepted the Article 28 data processing agreement in force (dpa-acceptance-required). Nothing is charged. |
| 422 | validation-failed, quote-required, dataset-unavailable | The request is not valid. errors lists every problem with a JSON pointer and did_you_mean. |
| 429 | rate-limited | Too many requests. Wait for Retry-After. |
| Any other failure | internal-error, service-unavailable, tps-screen-expired | Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old. |