Everything about a single profile (entity): looking it up by identity, exploring its attributes, memberships and activity, diagnosing segment membership against FilterQL, tracing where its data came from, and deleting it.
Before you start
- Credentials:
references/auth.md. - Calling conventions, the
/v2vs/apiresponse shapes, and URL-encoding:references/api.md. Identity values (emails with@) must be URL-encoded in the path. - Reads run immediately. Every delete goes through
references/confirmation-gate.md. - Account-specific identity fields:
GET /v2/schema/{table}/idconfig. Common ones:email,_uid,user_id.
Gotchas
- Not found is a 200.
/api/entityanswers a missing profile with HTTP 200,message: "Not Found"(or"Timed out") and a placeholder{"segments": ["not_found", "all"]}. Never present that as a real profile in segmentall; check.messageand thenot_foundsegment, or use/v2/identity, which does return 404. - Value-only lookup means
_uid.GET /api/entity/{table}/{value}looks the value up as_uidonly; it does not search other identity fields. For an email or external id, use/api/entity/{table}/{field}/{value}. - Both deletes are irreversible through the API. Hard delete is async (poll
/api/entity/deletestatus/{request_id}) and defaults toconflicts=true, a greedy identity traversal that can reach identifiers beyond the profile a lookup shows; offer?conflicts=false. Soft delete cannot be undone either: the undelete endpoint is deprecated, returns 401, and has no replacement. - Soft delete returns 200 even when no such profile exists, so a 200 confirms nothing was deleted.
- A FilterQL field missing from the profile is often the root cause of a "why isn't this user in X" question; report it as "field not present", not as a value mismatch.
Modes
Read the mode file before acting in that mode.
| Mode | When | File |
|---|---|---|
| lookup | Find a profile by identity field/value; list its segment memberships; delete a profile (hard or soft) | lookup.md |
| explore | Comprehensive view of one profile: identity, key attributes, memberships, recent activity; compare users; help find a user when no identity is known | explore.md |
| investigate | Why is/isn't this user in segment X (condition-by-condition PASS/FAIL); "what happened to this user" data lineage via ?explain=true |
investigate.md |
Related skills
lytics-audiences: list or scan segment members to find a user, look up a segment by name/slug, or change a segment's FilterQL after a diagnosis shows it is wrong.lytics-schema: identity fields, field types, and mappings when a profile field is missing or mis-mapped.lytics-data-health: recent events on a stream, when a profile's data looks stale or a source stream stopped.