Reference
Refresh a saved audience
POST /v1/audiences/{id}/refresh. Recount a saved audience on the current dataset version and return the difference.
POST /v1/audiences/{id}/refresh
Recount a saved audience on the current dataset version and return the difference. The audience.refreshed webhook carries the same object. Free.
| Property | Value |
|---|---|
| Endpoint | POST https://mydatahub.emailmovers.com/v1/audiences/{id}/refresh |
| Operation id | refreshAudience |
| Cost | Free (0 credits) |
| Access | An API key or an OAuth 2.1 token with the scope audiences:write. |
| 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 -X POST "https://mydatahub.emailmovers.com/v1/audiences/aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA/refresh" \
-H "Authorization: Bearer $MYDATAHUB_API_KEY"Responses
200: The refresh and its diff.
Headers: RateLimit, RateLimit-Policy.
| Member | Type | Always present | Description |
|---|---|---|---|
audience_id | string | yes | Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA. |
previous | AudienceCountSummary or null | yes | |
previous.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. |
previous.dataset_version | string | yes | The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable. |
previous.contacts | integer (0 or more) | yes | |
previous.companies | integer (0 or more) | yes | |
previous.emailable | integer (0 or more) | yes | |
previous.counted_at | string (date-time) | yes | |
current | AudienceCountSummary | yes | The headline numbers of one count of an audience. |
current.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.dataset_version | string | yes | The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable. |
current.contacts | integer (0 or more) | yes | |
current.companies | integer (0 or more) | yes | |
current.emailable | integer (0 or more) | yes | |
current.counted_at | string (date-time) | yes | |
diff | object | yes | |
diff.contacts | integer | yes | |
diff.companies | integer | yes | |
diff.emailable | integer | yes | |
diff.new_records | integer (0 or more) | yes | Records in the audience that were not before. |
diff.removed_records | integer (0 or more) | yes |
Example response
{
"audience_id": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA",
"previous": {
"count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ",
"dataset_version": "2026-W39",
"contacts": 12840,
"companies": 3115,
"emailable": 12310,
"counted_at": "2026-09-26T10:14:00Z"
},
"current": {
"count_id": "cnt_Q3N5X2M7K4P6R2T4V4W6",
"dataset_version": "2026-W40",
"contacts": 13054,
"companies": 3160,
"emailable": 12520,
"counted_at": "2026-10-05T06:00:00Z"
},
"diff": {
"contacts": 214,
"companies": 45,
"emailable": 210,
"new_records": 231,
"removed_records": 17
}
}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. |