List all users (admin)
List users with pagination via the admin API.
List every user in the project, one page at a time. Use this for back-office tooling, exports, or audit dashboards. There is no built-in filter — paginate through the full set and filter client-side, or query the underlying auth.users table from Postgres if you need to slice by metadata.
Service-role key required
This endpoint requires the project's service_role key. Never call it from a browser, mobile app, or any client you don't fully control.
Signature
supabase.auth.admin.list_users(page: nil, per_page: nil)Both pagination args are real Ruby keyword arguments — call as list_users(page: 2, per_page: 100).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
page | Integer | Optional | Page number, 1-indexed. Defaults to 1 on the GoTrue side when omitted. |
per_page | Integer | Optional | Users per page. Defaults to 50 on the GoTrue side when omitted. Capped at 1000 server-side. |
Returns
An array of Types::User Structs (id, email, phone, app_metadata, user_metadata, identities, factors, timestamps). The array is empty if the page is past the end of the user list. Total counts and next/last page hints are NOT surfaced on the Ruby return value — paginate by checking whether the returned array is empty or shorter than per_page. Raises Supabase::Auth::Errors::AuthApiError on failure.
Example — fetch the first page
users = supabase.auth.admin.list_users(page: 1, per_page: 50)
users.length # => 50
users.first.email # => "ada@example.com"
users.first.id # => "8d7f5c4b-..."Example — iterate every user
all_users = []
page = 1
loop do
batch = supabase.auth.admin.list_users(page: page, per_page: 100)
break if batch.empty?
all_users.concat(batch)
break if batch.length < 100
page += 1
end
puts "Total users: #{all_users.length}"Example — defaults (page 1, 50 per page)
# Omit both args to get the GoTrue defaults — equivalent to (page: 1, per_page: 50).
supabase.auth.admin.list_usersThe method takes real keyword args — list_users(page: 2) is a true kwarg call, not hash shorthand. Returns a bare Array<User>; total counts and link-header pagination hints are not currently surfaced.