list_cohort_moves
List bulk AP migrations
Detected bulk migrations between Access Points, largest first. A cohort is a gap-≤3-day island of (from_provider, to_provider) mover days that clears three thresholds: at least 25 participants, at least 40 % of them on the busiest day (which rejects a steady drip), and at most 20 active days for the pair over the trailing 40 days (which rejects a recurring partnership).
Every day is the PROBE-OBSERVATION day — the day the change scan saw the SMP record change, not the day the migration was executed — so a cohort is always a [first_day, last_day] range and peak_day is the busiest observation day. Render the range, never a single date.
top_country is derived from the ICD prefix of the participant identifiers, not from business-card country fields. merge_suspect marks a cohort large enough (or whose source provider no longer resolves in the directory) to be a provider merge or a renamed provider rather than that many independent customer decisions — the canonical case is Sovos → Sage, 10,574 participants. Such rows are data events, not customer decisions; verify one before quoting it. The flag is a CURRENT judgment, re-evaluated on every recompute, not frozen at detection.
from/to are OVERLAP bounds (a cohort counts when its range intersects the window), defaulting to the trailing 90 days the detector re-clusters. Mover history begins 2026-07-24, so no cohort predates it. id is a request-lifetime handle for the participant drill-down — never persist one.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Inclusive upper bound of the observation window (`YYYY-MM-DD` UTC); a cohort matches when its `first_day` is at or before it. Defaults to today. | |
| from | No | Inclusive lower bound of the observation window (`YYYY-MM-DD` UTC); a cohort matches when its `last_day` is at or after it. Defaults to 90 days ago. | |
| limit | No | Page size, clamped to [1, 200]. Defaults to 50. | |
| cursor | No | Opaque pagination cursor returned as `next_cursor` by the previous page. | |
| provider | No | Only cohorts involving this Provider key (`/v1/aps/{key}`). Matches EITHER side unless `direction` narrows it. | |
| direction | No | Which side of the `provider` filter to take: `in` = cohorts the provider received, `out` = cohorts it lost, `both` = either. Only meaningful together with `provider`. | both |
| merge_suspect | No | How to treat probable provider merges / slug changes: `include` (default), `exclude` for real customer migrations only, or `only` to review the flagged rows. | include |
| min_participants | No | Only cohorts with at least this many participants. The detector's own floor is 25, so a lower value cannot surface smaller groups. |