Find a user

Prerequisites

• Role with users:read (any role except pure content_manager reads through the users:read grant on their default set).

Where

Users → List (/users/list) is the master search. Every row is one user (registered or guest).

Search fields

The search box accepts any of:

Input	Matches
alice@twistcue.dev	users.email (exact-insensitive)
+201123456789	users.phone_e164 (exact)
0193… UUID	users.id (exact)
device:9d3b… prefix	devices.id starts-with
dbg:1234	analytics debug id (fingerprint)

Bare text (no : prefix, not a UUID or email) matches email, display_name, and phone_e164 via ILIKE.

Filters

Side panel on the list page:

Filter	Values	Notes
Status	active / suspended / banned / deleted	Deleted = GDPR-anonymized (email nulled, PII stripped).
Type	guest / registered	Guests are device-keyed only.
Country	ISO-2 code	Based on the user’s most recent device country.
Created between	date range	UTC.
Sort	created_at / last_seen_at / balance / spend
Order	asc / desc

Every filter lives in the URL query string: copy the URL to share the exact view.

Result columns

Column	Meaning
User	Display name (if set), else email or phone. Avatar thumbnail if uploaded.
Country	Most-recent device country.
Status	active / suspended / banned / deleted. Suspended rows show suspended_until on hover.
Balance	Derived from coin_ledger. Total (paid + bonus).
Spend	Sum of completed Purchase.amount_cents (USD-normalized).
Last seen	users.last_seen_at. Guests without recent activity look “cold”.
Created	Signup date (or first device event for guests).

Click any row to open the User 360.

Guest users

Guests have no email or phone, they’re keyed by device.fingerprint and get a synthetic user row. When they sign up, guest data (saves, coins, streaks, watch history) is preserved and merged into the registered user, higher wallet balance wins on merge conflict (per CONSTANTS).

Filter by type=guest to audit guest activity or plan a reactivation push segment.

Pagination

Cursor-based. The list page loads 50 rows; scroll to load more. Copy the URL after scrolling: the cursor is in the query string.

Gotchas

• Email lookup is case-insensitive. Uppercase or lowercase both find the row.
• Phone must be E.164 (+201234567890), not local format. The mobile app normalizes on signup, but hand-entered phones can be off.
• Deleted (anonymized) users don’t return via email search: their email is nulled. You can still find them by user ID from an audit log entry.

API calls

Action	Endpoint
List users	GET /v1/admin/users (query params: q, status, guest, country, createdFrom, createdTo, sort, order, cursor, limit)
Get detail	GET /v1/admin/users/:id

Full details in API: Users, wallet, support.