---
title: "List users"
method: GET
path: "/users"
tags: ["Users"]
---

# List users

`GET /users`

Lists all the users in the project. By default, only fully onboarded users are returned. Restricted users (those who haven't completed onboarding requirements like email verification) are included if `include_restricted` is set to `true`. Anonymous users are included if `include_anonymous` is set to `true` (which also includes restricted users).

## Query parameters

- `team_id` string — Only return users who are members of the given team
- `limit` integer — The maximum number of items to return (capped at 1000). Larger result sets must be paged with cursor.
- `cursor` string — The cursor to start the result set from.
- `order_by` 'signed_up_at' | 'last_active_at' — The field to sort the results by. Defaults to signed_up_at
- `desc` 'true' | 'false' — Whether to sort the results in descending order. Defaults to false
- `query` string — A search query to filter the results by. This is a free-text search that is applied to the user's id (exact-match only), display name and primary email.
- `excluded_email_domains` string — A comma-separated list of primary email domains to exclude from the results.
- `include_anonymous` 'true' | 'false' — Whether to include anonymous users in the results. When true, also includes restricted users. Defaults to false
- `only_anonymous` 'true' | 'false' — Whether to return only anonymous users. When true, implies include_anonymous=true. Defaults to false
- `include_restricted` 'true' | 'false' — Whether to include restricted users in the results. Defaults to false

## Response `200`

Successful response

- object
  - `items` object[], required
    - `id` string, required — The unique identifier of the user
    - `primary_email` 'null', nullable — Primary email
    - `primary_email_verified` boolean, required — Whether the primary email has been verified to belong to this user
    - `primary_email_auth_enabled` boolean, required — Whether the primary email is used for authentication. If this is set to `false`, the user will not be able to sign in with the primary email with password or OTP
    - `display_name` 'null', nullable — Human-readable user display name. This is not a unique identifier.
    - `selected_team` object, nullable
      - `created_at_millis` number, required — The time the team was created (the number of milliseconds since epoch, January 1, 1970, UTC)
      - `server_metadata` object, nullable — Server metadata. Used as a data store, only accessible from the server side. You can store secret information related to the team here.
      - `id` string, required — The unique identifier of the team
      - `display_name` string, required — Human-readable team display name. This is not a unique identifier.
      - `profile_image_url` 'null', nullable — URL of the profile image for team. Can be a Base64 encoded image. Must be smaller than 100KB. Please compress and crop to a square before passing in.
      - `client_metadata` object, nullable — Client metadata. Used as a data store, accessible from the client side. Do not store information that should not be exposed to the client.
      - `client_read_only_metadata` object, nullable — Client read-only, server-writable metadata. Used as a data store, accessible from the client side. Do not store information that should not be exposed to the client. The client can read this data, but cannot modify it. This is useful for things like subscription status.
    - `selected_team_id` 'null', nullable — ID of the team currently selected by the user
    - `profile_image_url` 'null', nullable — URL of the profile image for user. Can be a Base64 encoded image. Must be smaller than 100KB. Please compress and crop to a square before passing in.
    - `signed_up_at_millis` number, required — The time the user signed up (identify) => `(the number of milliseconds since epoch, January 1, 1970, UTC)`
    - `client_metadata` object, nullable — Client metadata. Used as a data store, accessible from the client side. Do not store information that should not be exposed to the client.
    - `client_read_only_metadata` object, nullable — Client read-only, server-writable metadata. Used as a data store, accessible from the client side. Do not store information that should not be exposed to the client. The client can read this data, but cannot modify it. This is useful for things like subscription status.
    - `server_metadata` object, nullable — Server metadata. Used as a data store, only accessible from the server side. You can store secret information related to the user here.
    - `last_active_at_millis` number, required — The time the user was last active (identify) => `(the number of milliseconds since epoch, January 1, 1970, UTC)`
    - `is_anonymous` boolean, required
    - `is_restricted` boolean, required — Whether the user is in restricted state (has signed up but not completed onboarding requirements)
    - `restricted_reason` object, nullable — The reason why the user is restricted (e.g., type: "email_not_verified", "anonymous", or "restricted_by_administrator"), null if not restricted
      - `type` 'anonymous' | 'email_not_verified' | 'restricted_by_administrator', required
    - `restricted_by_admin` boolean, required — Whether the user is restricted by an administrator. Can be set manually or by sign-up rules.
    - `restricted_by_admin_reason` 'null', nullable — Public reason shown to the user explaining why they are restricted. Optional.
    - `restricted_by_admin_private_details` 'null', nullable — Private details about the restriction (e.g., which sign-up rule triggered). Only visible to server access and above.
    - `country_code` 'null', nullable — Best-effort ISO country code captured at sign-up time from request geo headers.
    - `risk_scores` object, required — User risk scores used for sign-up risk evaluation.
      - `sign_up` object, required
        - `bot` integer, required
        - `free_trial_abuse` integer, required
  - `pagination` object
    - `next_cursor` 'null', nullable — The cursor to fetch the next page of results. null if there is no next page.

---

[API](https://skmtc.net/hexclave/apis/hexclave-rest-api-3.md) · [All operations](https://skmtc.net/hexclave/apis/hexclave-rest-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hexclave/hexclave-rest-api-3/revisions/9b9326fe08a5/schema)