---
title: "Search users"
method: GET
path: "/api/v1/users:search"
tags: ["Users"]
---

# Search users

`GET /api/v1/users:search`

Searches for users across the entire environment by email address, user ID, or external ID. The query must be at least 3 characters and is case-insensitive. Returns a paginated list of matching users with up to 30 results per page. Use the next_page_token from the response to retrieve subsequent pages.

## Query parameters

- `query` string, required
- `page_size` integer
- `page_token` string

## Response `200`

Matching users returned; includes pagination cursors for navigating large result sets.

- UsersSearchUsersResponse
  - `next_page_token` string — Token for retrieving the next page of results. Empty if there are no more pages.
  - `prev_page_token` string — Token for retrieving the previous page of results. Empty if this is the first page.
  - `total_size` integer — Total number of users matching the request criteria, regardless of pagination.
  - `users` UsersUser[] — List of matching users.
    - `create_time` string, date-time — Timestamp when the user account was initially created. Automatically set by the server.
    - `email` string — Primary email address for the user. Must be unique across the environment and valid per RFC 5322.
    - `external_id` string — Your application's unique identifier for this organization, used to link Scalekit with your system.
    - `id` string — Unique system-generated identifier for the user. Immutable once created.
    - `last_login_time` string, date-time — Timestamp of the user's most recent successful authentication. Updated automatically.
    - `memberships` CommonsOrganizationMembership[] — List of organization memberships. Automatically populated based on group assignments.
      - `accepted_at` string, date-time — Timestamp when the user accepted the invitation.
      - `created_at` string, date-time — Timestamp when the invitation was created.
      - `display_name` string — Organization display name. This field stores a user-friendly name for the organization that may be different from the formal name, often used for UI display purposes.
      - `expires_at` string, date-time — Timestamp when the invitation expired.
      - `inviter_email` string — ID of the user who invited this user.
      - `join_time` string, date-time — Timestamp when the membership was created. Automatically set by the server.
      - `membership_status` 'ACTIVE' | 'INACTIVE' | 'PENDING_INVITE' | 'INVITE_EXPIRED'
      - `metadata` object — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).
      - `name` string — Organization name. This field stores the formal organization name used for identification and display purposes.
      - `organization_id` string — Unique identifier for the organization. Immutable and read-only.
      - `permissions` string[] — Effective permissions granted to the user within the organization (including inherited permissions from assigned roles). Lists the specific actions and access rights the user can perform.
      - `provisioning_method` string — How the user was provisioned. Possible values: - `jit_using_sso` (Just-in-time provisioning during SSO login) - `allowed_email_domain` (User joined via allowed email domain matching) - `org_creator` (User created the organization) - `direct_provision` (User was directly provisioned via API or SCIM) - `invitation` (User was invited and accepted an invitation)
      - `roles` CommonsRole[]
        - `display_name` string — Human-readable name for the role
        - `id` string — Role ID
        - `name` string — Attribute name/identifier for the role used in system operations and API calls. This should be a machine-readable identifier that follows naming conventions.
    - `metadata` object — Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).
    - `update_time` string, date-time — Timestamp of the last modification to the user account. Automatically updated by the server.
    - `user_profile` CommonsUserProfile
      - `custom_attributes` object — Custom attributes for extended user profile data and application-specific information. This field stores business-specific user data like department, job title, security clearances, project assignments, or any other organizational attributes your application requires. Unlike system metadata, these attributes are typically managed by administrators or applications and are visible to end users for personalization and business logic. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs.
      - `email_verified` boolean — Indicates if the user's email address has been verified. Automatically updated by the system.
      - `external_identities` CommonsExternalIdentity[] — List of external identity connections associated with the user profile.
        - `connection_id` string — Unique identifier for the external identity connection. Immutable and read-only.
        - `connection_provider` 'OKTA' | 'GOOGLE' | 'MICROSOFT_AD' | 'AUTH0' | 'ONELOGIN' | 'PING_IDENTITY' | 'JUMPCLOUD' | 'CUSTOM' | 'GITHUB' | 'GITLAB' | 'LINKEDIN' | 'SALESFORCE' | 'MICROSOFT' | 'IDP_SIMULATOR' | 'SCALEKIT' | 'ADFS'
        - `connection_type` string — Name of the external identity connection.
        - `connection_user_id` string — Unique identifier for the user in the external identity provider system. Immutable and read-only.
        - `created_time` string, date-time — Timestamp when this external identity connection was first created. Immutable and read-only.
        - `is_social` boolean — Indicates if the identity provider is a social provider (true) or enterprise/custom provider (false). Read-only.
        - `last_login_time` string, date-time — Timestamp of the user's last successful login via this external identity provider. Automatically updated by the system.
        - `last_synced_time` string, date-time — Timestamp of the last data synchronization for this external identity from the provider. Automatically updated by the system.
      - `family_name` string — The user's family name (last name or surname). This field stores the user's last name and is combined with the given name to create the full display name. The family name is used in formal communications, user listings, and organizational directories throughout the system. Maximum 255 characters allowed.
      - `gender` string — The user's gender identity information. This field stores the user's gender identity for personalization, compliance reporting, or organizational analytics purposes. This field supports any string value to accommodate diverse gender identities and should be handled with appropriate privacy considerations according to your organization's policies and applicable regulations.
      - `given_name` string — The user's given name (first name). This field stores the user's first name and is used for personalization, display purposes, and when generating the full display name. The given name appears in user interfaces, formal communications, and user listings throughout the system. Maximum 255 characters allowed.
      - `groups` string[] — The list of group names the user belongs to within the organization. This field stores the user's group memberships for role-based access control, team assignments, and organizational structure. Groups are typically used for permission management, collaborative access, and organizational hierarchy. Each group name represents a distinct organizational unit or team that the user is associated with.
      - `id` string — Unique system-generated identifier for the user profile. Immutable and read-only.
      - `locale` string — The user's preferred language and region settings using BCP-47 format codes. This field customizes the user's experience with localized content, date formats, number formatting, and UI language throughout the system. When not specified, the user inherits the organization's default locale settings. Common values include `en-US`, `en-GB`, `fr-FR`, `de-DE`, and `es-ES`.
      - `metadata` object — Raw attributes received from identity providers during authentication. This field stores the original user profile data as received from external IdP systems (SAML, OIDC, etc.) including provider-specific claims and attributes. These fields preserve the complete set of attributes received from the identity source and are used for mapping, synchronization, and audit purposes. Keys must be 3-25 characters, values must be 1-256 characters, with a maximum of 20 key-value pairs.
      - `name` string — The user's complete display name in formatted form. This field stores the full name as a single string and is typically used when you want to set the complete name rather than using separate given and family names. This name appears in user interfaces, reports, directory listings, and anywhere a formatted display name is needed. This field serves as a formatted display name that complements the individual given_name and family_name fields.
      - `phone_number` string — The user's phone number in E.164 international format. This field stores the phone number for user contact and identification purposes. The phone number must include the country code and be formatted according to E.164 standards (e.g., `+1` for US numbers). This field is optional.
      - `phone_number_verified` boolean — Indicates if the user's phone number has been verified. Automatically updated by the system.
      - `picture` string — The URL to the user's profile picture or avatar image. This field stores the location of the user's profile photo that appears in user interfaces, directory listings, and collaborative features throughout the system. The URL should point to a publicly accessible image file. Supported formats typically include JPEG, PNG, and GIF. This image is used for visual identification and personalization across the platform.
      - `preferred_username` string — The user's preferred username for display and identification purposes. This field stores a custom username that the user prefers to be known by, which may differ from their email or formal name. This username appears in user interfaces, mentions, informal communications, and collaborative features throughout the system. Maximum 512 characters allowed.

## Other responses

- `400` — Bad Request - query must be at least 3 characters and no more than 100 characters.

---

[API](https://skmtc.net/scalekit/apis/scalekit-api-reference.md) · [All operations](https://skmtc.net/scalekit/apis/scalekit-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scalekit/scalekit-api-reference/versions/a40d5d4650e5/schema)