# Find recently active customers

> Rank observed customer activity with canonical identities, exact counts and source coverage.

Canonical page: https://anectico.com/docs/investigate/recent-customers/


## Ask for a current top list

Use recent activity when you need a starting point for investigation or a weekly review.
Activity means **observed errors, person-linked traces and product events**. Editing a
customer's profile does not count. The result orders canonical customers by `last_seen`
descending, then person ID ascending, across the whole measured project window.

```json
{"action":"list_recent_customers","arguments":{"project_id":"PROJECT_UUID","since":"2026-10-15T00:00:00Z","until":"2026-10-16T00:00:00Z","limit":25}}
```

Call that through `execute_read_action`. The command-line equivalent is:

```bash
anectico persons recent --project PROJECT_UUID \
  --since 2026-10-15T00:00:00Z --until 2026-10-16T00:00:00Z --limit 25 -o json
```

Omit both bounds for the last 24 hours. Supply both for an explicit half-open UTC window:
start included, end excluded. The requested duration is at most seven days. Limit defaults
to 25 and must be 1–100. An organization credential must select one project; a project
credential always uses its own. The summary requires `persons:read`, plus `mcp:read` for MCP.
It returns no profiles or aliases; reading those is a separate authorized step.

For REST, POST `/api/v1/persons/recent` with `project_id`, `time_range: {start, end}` and
optional `limit`. Project selection may instead use the existing `project_id` query argument;
if both are supplied they must agree. The organization always comes from the credential.

## Read counts and limits together

Each customer has `person_id`, UTC `last_seen`, `error_count`, `trace_count` and `event_count`.
Integer counts are decimal **strings**, including in JSON; preserve them without converting
to floating-point numbers. A trace shared by several current aliases counts once for that
person. A root that started before the window is not made recent by a later child.

The answer says `ranking_scope: whole_measured_window` and `selection: bounded_current_top_list`.
With `totals_state: exact`, eligible and omitted counts describe every canonical customer with
at least one counted signal in the measured sources. Omitted is eligible minus returned.
If totals say `unknown`, their fields are absent; returned count is never a substitute for
eligible count. Current successful reads compute exact totals together with the ranking.

This is a **current top list**. It has no cursor, frozen audience or enumeration guarantee.
MCP's pagination says `top_list`. A later call may change after new evidence, identity
correction or erasure. Follow a returned canonical ID and permitted person proof link to
investigate; it does not imply permission to read every source or profile field.

## Check source coverage

`read_coverage.sources` states each source's requested interval, effective interval, retention
floor, outcome and history and source availability. Product history can differ from technical
history. `complete` means the retained interval matched the requested one; `partially_covered`
means earlier history was excluded; `outside_retention` means nothing was read for that source.
An unresolved history bound is `unknown`. The overall effective range is the union of the
source ranges actually read; always use the individual source ranges for a specific signal.
Expired history cannot be recovered by this read.

`source_coverage` separately names signals without canonical attribution and signals withheld
because their identities were erased. Those counts do not create additional customers.
Profiles were not requested. An empty result does not prove that no customer was active:
missing instruments, sampling, late delivery or undelivered evidence may leave activity out.
**Upstream completeness is unknown.** Roots outside visible history cannot be reconstructed.

## Handle a refusal

Current canonical attribution is checked for every admitted source key, including customers
outside the returned limit, and checked again before release. The initial identity ceiling is
512 distinct source keys. A larger or more expensive population refuses the entire ranking;
it never selects a sample and calls it global.

`recent_customer_scan_limit` means narrow the time range within the supported bounds. It
returns no ranked rows or totals. `recent_customer_identity_unavailable` means current identity
authority was unavailable or changed; retry the complete read. A dependency or configuration
failure is unavailable, not a measured zero. Do not combine partial top lists to claim a global
ranking or report a refusal as absence.