Replace an entire Meta Custom Audience via the usersreplace endpoint without resetting ad set learning phase
domain: developers.facebook.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Confirm the target Custom Audience has subtype CUSTOM, operation_status Normal, and fewer than 100 million users, since the Replace Users API doesn't support larger audiences or non-CUSTOM subtypes.
POST to /<CUSTOM_AUDIENCE_ID>/usersreplace with a session object (session_id, batch_seq starting at 1, last_batch_flag) and a payload object (schema + hashed data), splitting uploads over 10,000 records into multiple batches under the same session_id.
Set last_batch_flag=true on the final batch to close the session explicitly; otherwise the session auto-terminates 90 minutes after the first batch and later batches are discarded.
Poll the audience's operation_status field, which transitions to replace_in_progress during the swap and back to Normal (or replace_error on failure) when complete.
Do not call POST/DELETE on /<CUSTOM_AUDIENCE_ID>/users while a replace session is in progress — a concurrent second replace call is rejected.
Known gotchas
All /usersreplace errors return error code 2650 with a specific subcode (e.g. 1870158 for a timed-out 90-minute session, 1870144 for audiences ≥100M users) — check the subcode, not just the top-level code.
Unlike POST/DELETE to /users, a successful usersreplace call does not reset the learning phase of ad sets actively using the audience — this is the main reason to prefer it over delete-then-add.
The schema defined in a session's first batch must stay identical across all subsequent batches in that session; changing it mid-session causes errors.
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?