List users
list_usersList, search, or count an instance's users (like clerk users list). Use user_id or an exact email_address to look up a single user. Returns data, a page of Backend API user objects without private_metadata, and total_count, the total matching users across all pages. To get a count with minimal data, set limit to 1 and read total_count. Filters match the Backend API list-users query; date filters use Unix epoch milliseconds.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"application_id": "<application_id>",
"instance": "<instance>"
},
"name": "list_users"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum users to return (default 100). | |
| query | No | Text to search for in email addresses, phone numbers, usernames, web3 wallets, user IDs, first names, and last names. | |
| banned | No | Return banned users when true, or users who are not banned when false. | |
| offset | No | Number of users to skip, to page past earlier results. Omit to start from the first user. | |
| user_id | No | Return only users with these Clerk user IDs (user_…). | |
| instance | Yes | Instance to target: "development", "production", or a full instance ID (ins_…). | |
| order_by | No | Field to sort by, prefixed with - for descending or + for ascending, e.g. -last_sign_in_at. Sortable fields: created_at, updated_at, last_sign_in_at, last_active_at, email_address, first_name, last_name, username, phone_number, web3_wallet. Omit to sort by -created_at, newest first. | |
| provider | No | OAuth provider, such as oauth_google. Must be combined with provider_user_id. | |
| username | No | Filter by username. | |
| name_query | No | Case-insensitive partial match on names. | |
| external_id | No | Return only users whose external_id, the ID your own system stored on the user, is one of these values. | |
| web3_wallet | No | Filter by exact web3 wallet addresses. Accepts up to 100 addresses. | |
| phone_number | No | Filter by phone number. | |
| deprovisioned | No | Return deprovisioned users when true, or users who are not deprovisioned when false. | |
| email_address | No | Filter by email address. | |
| application_id | Yes | Clerk application ID (app_…). | |
| username_query | No | Case-insensitive partial match on usernames. | |
| organization_id | No | Filter by organization membership (org_…). Prefix an ID with - to exclude its members or + to include them. Accepts up to 100 IDs. | |
| created_at_after | No | Return users created after this Unix timestamp in milliseconds. | |
| provider_user_id | No | Filter by external account user IDs for the specified provider. Must be combined with provider. Accepts up to 100 IDs. | |
| created_at_before | No | Return users created before this Unix timestamp in milliseconds. | |
| phone_number_query | No | Case-insensitive partial match on phone numbers. | |
| email_address_query | No | Case-insensitive partial match on email addresses. | |
| last_active_at_after | No | Return users whose last session activity was after this Unix timestamp in milliseconds. | |
| last_active_at_since | No | Deprecated inclusive activity filter in Unix epoch milliseconds. Prefer last_active_at_after, which takes precedence when both are set. | |
| last_active_at_before | No | Return users whose last session activity was before this Unix timestamp in milliseconds. | |
| last_sign_in_at_after | No | Return users whose last sign-in was after this Unix timestamp in milliseconds. | |
| last_sign_in_at_before | No | Return users whose last sign-in was before this Unix timestamp in milliseconds. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | ||
| total_count | Yes |