users_users_get

Tool

users_users_get

Fetch one end user of this product by id, including their identifiers and metadata bags.

Fetch one end user of this product by id, including their identifiers and metadata bags. Soft-deleted users are still returned (with `deletedAt` set). Identifiers include contact channels (`phone`, `telegram`, `linkedin`, `x`) alongside emails; a channel is always `unverified`.

Behavior

HTTP: GET /users/users/:userId

Arguments

Name	Type	Required	Description
userId	string	•	The opaque user id returned by users_users_create or _list.

Response

Field	Type	Always	Description
id	string	•	Id of this end user. Pass it to any users_users_* tool.
kind	string	•	What kind of person this row is: 'account' (can sign in) or 'contact' (known to the Product, no credential, never signed in). A contact is hidden from the default users_users_list view and is never counted as a retained user.
name	string	•	The user's display name. Null when nobody set one.
tags	array	•	Free labels on this person, stored trimmed, lowercased and de-duplicated.
stage	string	•	The relationship stage, in funnel order: new, contacted, replied, engaged, converted, lost. A real change publishes `users/user.stage-changed`.
bannedAt	string	•	When the user was banned (ISO 8601). Null while they are not banned.
erasedAt	string	•	When this user's personal data was purged for good (ISO 8601). Null while it is intact.
imageUrl	string	•	URL of the user's avatar. Null when there is none.
testUser	boolean	•	Whether this is a test fixture — excluded from metering and from the default listing.
createdAt	string	•	When the user was created (ISO 8601).
deletedAt	string	•	When the user was soft-deleted (ISO 8601). Null while the account is live.
productId	string	•	Product this user belongs to. Never an input — it comes from the calling identity.
updatedAt	string	•	When the user was last changed (ISO 8601).
mergedFrom	string	•	Set when you asked for an id that was merged into this account — it is the id you asked for, and this is the row it now lives in. Null on every ordinary read.
waitlisted	boolean	•	Whether this user is still on the waitlist and cannot sign in yet.
identifiers	array	•	Every identifier of this user, the primary one flagged. To bind the primary address itself, use `primaryEmail` — `identifiers.0` means "the first", not "the primary".
lastTouchAt	string	•	When this person was last touched — the most recent logged interaction (ISO 8601). Null when nobody has logged one. This is when the interaction HAPPENED, not when it was logged.
lockedUntil	string	•	When a failed-attempt lockout expires (ISO 8601). Null when the user is not locked out.
lastSignInAt	string	•	When the user last signed in (ISO 8601). Null if they never have.
primaryEmail	string	•	The user's primary email address, as typed. Null when they have no primary identifier. Bind this rather than `identifiers.0.value`.
requiresReset	boolean	•	Whether the user must set a new password at their next sign-in.
publicMetadata	object	•	Metadata the end user may read; the only bag projected into their access token. Capped at 1.2 KB.
unsafeMetadata	object	•	Metadata the end user may write themselves. Treat it as untrusted.
privateMetadata	object	•	Metadata for the management plane only. Never reaches the end user or a token.
mergedIntoUserId	string	•	The user this person was merged INTO, when they were merged. Null for everybody else — follow it to find where their records went.
primaryIdentifierId	string	•	Id of the primary identifier row. Null when there is no primary identifier.
emailChangeLockedUntil	string	•	Until this instant the user may not start another email change, because somebody reverted one (ISO 8601). Null for a user who never reverted one.

Try it

Fetch one end user of this product by id, including their identifiers and metadata bags.

When to use

Example

Ask your agent something like this:

Fetch one end user of this product by id, including their identifiers and metadata bags.

The agent will invoke users_users_get with these arguments:

{
  "userId": "<userId>"
}