users_users_list

Tool

users_users_list

List the end users of this product, newest first.

List the end users of this product, newest first. Filter by an identifier/name substring and by status. Soft-deleted users are hidden unless `includeDeleted` is true. CONTACTS — people the Product knows who have no credential and have never signed in — are hidden by default, exactly as waitlist signups and test users are; pass `kind: "contact"` to list only them, or `includeContacts: true` to see both. Filter further by `stage` (new, contacted, replied, engaged, converted, lost) and by a single `tag`, both ANDed with everything else. `query` matches a substring of the display name or of ANY identifier's canonical value — an address, a phone in E.164, a handle. Paginate with the opaque `nextCursor`.

Behavior

HTTP: GET /users/users

Arguments

Name	Type	Required	Description
tag	string	—	Return only people carrying this tag. ONE tag, matched against the stored (lowercased) value and ANDed with the other filters.
kind	string	—	Filter by kind: 'account' or 'contact'. Passing 'contact' is how you list contacts — they are hidden otherwise. Omit for accounts only, unless `includeContacts` is true.
limit	string	—	Page size, 1-100. Default 25.
query	string	—	Case-insensitive substring match against the user's identifiers (email) and name.
stage	string	—	Filter by relationship stage: new, contacted, replied, engaged, converted or lost. Omit for every stage.
cursor	string	—	Opaque cursor from a previous response's `nextCursor`. Omit for the first page.
status	string	—	Filter by status: 'active' (not banned, not waitlisted), 'banned', or 'waitlisted'. Omit for all.
includeDeleted	boolean	—	Include soft-deleted users. Default false — deleted users are hidden.
lastTouchAfter	string	—	Only people whose most recent logged interaction happened at or after this instant (ISO 8601). People never touched are EXCLUDED by this filter — list without it to see everyone.
includeContacts	boolean	—	Include CONTACTS. Default false: a contact has no credential and has never signed in, so it is not part of the directory an operator browses — the same rule waitlist signups and test users follow. Use `kind: "contact"` to see only them.
lastTouchBefore	string	—	Only people whose most recent logged interaction happened before this instant (ISO 8601) — the "gone quiet" list. People never touched are EXCLUDED rather than treated as infinitely stale; list without this filter to see everyone.
includeTestUsers	boolean	—	Include TEST USERS. Default false: a test user is a fixture, not a customer — it is excluded from metering and from this listing for the same reason. Ask for it explicitly when you are debugging the fixtures themselves.
includeWaitlisted	boolean	—	Include waitlist signups. Default false: a waitlisted row is somebody who ASKED to join and cannot sign in, so it is not part of the directory an operator browses. Use `status: "waitlisted"` to see only them, or `users_waitlist_list` for the funnel.

Response

Field	Type	Always	Description
users	array	•	The page of users, newest first.
nextCursor	string	•	Pass back as `cursor` to fetch the next page. Null when this page is the last.

Try it

List the end users of this product, newest first.

When to use

Example

Ask your agent something like this:

List the end users of this product, newest first.

The agent will invoke users_users_list with these arguments:

{}