Audiences

Audience definitions and downloads picked up several changes this month that affect how you build, poll, and read them over the API.

AND/OR grouping across list filters

List-based filters in an audience definition now carry real boolean grouping. The condition marker on a list group is read when the definition is transformed, so you can express combinations such as two lists matched with OR and a third required with AND in a single audience. Send it on POST /api/v1/audiences or PUT /api/v1/audiences/{id}, and read it back from GET /api/v1/audiences/{id}.

Download preparation stages and progress

GET /api/v1/audiences/{id}/download now reports normalized preparation stages and job progress for an audience that is still being built, and treats active build states as pollable rather than terminal. Terminal failure reasons are preserved, so a client polling the endpoint can distinguish "still preparing, here is how far along" from "this run failed, and here is why." Requested full-download intent is persisted, so preparation continues even if the requesting client disconnects.

Company counts on company-grain audiences

An audience built at company grain now populates account_count, the number of companies it contains, alongside the existing size field. Audience reads previously carried this field without a producer ever writing it, so integrators rendering a company audience no longer have to infer the unit from the audience type.

contact is the audience type value

The audience type formerly written as elixir is now stored and returned as contact. Both spellings are accepted on write, so existing integrations keep working unchanged, and readers should treat contact as the canonical value on GET /api/v1/audiences and GET /api/v1/audiences/{id}. This rolled out across the platform, so the value is consistent wherever an audience type appears.

Spend Controls

The monthly spend ceiling an organization configures for itself now applies to the two largest sources of metered spend, and refuses over budget with a documented response instead of serving the request.

Budget enforcement on audience downloads

GET /api/v1/audiences/{id}/download consults the organization's configured monthly budget before serving a download. A request over the ceiling is refused with 402 and a body naming the reason and the limits that applied, matching the refusal shape the API key and export surfaces already return.

Budget enforcement on metered data endpoints

The metered data endpoints, including GET /api/v1/lookup and the event tier reads under GET /api/v3/events/web_event, now consult the same budget decision and answer 402 with the shared refusal body when the ceiling is reached. If you meter your own consumption against a configured ceiling, expect 402 on these routes rather than a successful response once the ceiling is hit.

Bug Fixes

• The events API now honors project-level membership on JWT authentication. A user with membership only at project scope receives data from GET /api/v3/events/web_event and the other tier reads instead of 401.

• record_limit on an audience is applied once at the end of the build rather than being dropped, so GET /api/v1/audiences/{id}/download returns the top records up to the limit instead of the full record set.

• A download whose underlying build was cancelled now triggers a rebuild instead of polling indefinitely against a prefix that will never produce output.

• Soft-deleted lists no longer appear as attached in GET /api/v1/campaigns/{id}/lists.

• An export run refused for exceeding a configured spend limit now returns the budget refusal, with its reason code and limits intact, instead of collapsing into a generic server error.

For full endpoint details, parameters, and examples, see our developer documentation.