Reference
Get a saved audience
GET /v1/audiences/{id}. One saved audience with its definition and current count.
GET /v1/audiences/{id}
One saved audience with its definition and current count.
| Property | Value |
|---|---|
| Endpoint | GET https://mydatahub.emailmovers.com/v1/audiences/{id} |
| Operation id | getAudience |
| Cost | Free (0 credits) |
| Access | An API key or an OAuth 2.1 token with the scope audiences:read. |
| Tag | Audiences |
Request
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA. |
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/aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" \
-H "Authorization: Bearer $MYDATAHUB_API_KEY"Responses
200: The saved audience.
Headers: RateLimit, RateLimit-Policy.
| Member | Type | Always present | Description |
|---|---|---|---|
id | string | yes | Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA. |
name | string | yes | |
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. |
brief | string or null | yes | The brief it was compiled from, if any. |
current_count | AudienceCountSummary or null | yes | |
current_count.count_id | string | yes | Format: a count id: cnt_ followed by 20 base32 characters (A to Z and 2 to 7), such as cnt_7K2PQ4MAXN3R6TBY5WDZ. |
current_count.dataset_version | string | yes | The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable. |
current_count.contacts | integer (0 or more) | yes | |
current_count.companies | integer (0 or more) | yes | |
current_count.emailable | integer (0 or more) | yes | |
current_count.counted_at | string (date-time) | yes | |
last_refreshed_at | string (date-time) or null | yes | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes | |
created_by | string | yes | Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8. |
url | string (uri) | yes | The audience in the app, mydatahub.emailmovers.com/audiences/{id}. |
Example response
{
"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"
}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. |
| 404 | not-found | No such object for this organisation. |
| 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. |