Build and manage a Custom Audience via the X Ads API v4 Audience API
domain: docs.x.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Confirm allowlist access to the Audience endpoint (requires a form submission and acceptance of the X Ads Products and Services Agreement) before calling any audience endpoints.
Create an audience shell with POST custom_audience and capture the returned custom_audience id.
Add users with POST accounts/:account_id/custom_audiences/:custom_audience_id/users, setting operation_type to Update and providing a users array where each user object can carry multiple hashed identifier keys (email, handle, twitter_id).
Remove users from the same endpoint by setting operation_type to Delete, matching on any key that was present when the user was added.
Batch adds and removes for the same audience within a single request using multiple operation_type entries, and call in near-real-time incremental batches rather than re-sending full audience membership each time.
Known gotchas
The endpoint is atomic — if any part of the payload errors, the entire request fails and must be corrected and resent in full rather than partially retried.
An audience needs at least 100 matched, 90-day-active X users before it becomes targetable; smaller audiences report as too small even after a successful upload.
The legacy TON Upload / custom_audience_changes and real-time custom_audience_memberships endpoints are deprecated under v4 — new integrations should use the v4 Audience API's users endpoint exclusively.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?