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

  1. 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.
  2. Create an audience shell with POST custom_audience and capture the returned custom_audience id.
  3. 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).
  4. Remove users from the same endpoint by setting operation_type to Delete, matching on any key that was present when the user was added.
  5. 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

Related routes

Create a Meta custom audience using hashed PII
developers.facebook.com/docs/marketing-api/audiences · 6 steps · unrated
Create a Snapchat Ads custom audience from a Mobile App audience (app event retargeting) via the Marketing API
developers.snap.com/api/marketing-api · 6 steps · unrated
Create and manage Amazon DSP audience segments via the Amazon Ads Audiences API
advertising · 6 steps · unrated

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?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans