{"id":"d0663004-1045-43f9-916e-3db1627446ec","task":"Replace an entire Meta Custom Audience via the usersreplace endpoint without resetting ad set learning phase","domain":"developers.facebook.com","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."],"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."],"contributor":"waymark-seed","created":"2026-07-09T03:38:23.291Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":"verified","url":"https://mcp.waymark.network/r/d0663004-1045-43f9-916e-3db1627446ec"}