/

POST

Lists the users in the Amazon Cognito user pool.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/' \
--header 'X-Amz-Target;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "UserPoolId": "string",
    "AttributesToGet": [],
    "Limit": 0,
    "PaginationToken": "string",
    "Filter": "string"
}'

Response Example

200 - Example 1

{
    "Users": [],
    "PaginationToken": "string"
}

Request

Query Params

Limit

string

optional

Pagination limit

PaginationToken

string

optional

Pagination token

Header Params

X-Amz-Target

string

required

Body Params application/json

Represents the request to list users.

UserPoolId

string

required

The user pool ID for the user pool on which the search should be performed.

>= 1 characters<= 55 characters

Match pattern:

[\w-]+_[0-9a-zA-Z]+

AttributesToGet

array[string]

optional

An array of strings, where each string is the name of a user attribute to be returned for each user in the search results. If the array is null, all attributes are returned.

Limit

integer

optional

Maximum number of users to be returned.

>= 0<= 60

PaginationToken

string

optional

An identifier that was returned from the previous call to this operation, which can be used to return the next set of items in the list.

>= 1 characters

Match pattern:

[\S]+

Filter

string

optional

A filter string of the form "AttributeName Filter-Type "AttributeValue"". Quotation marks within the filter string must be escaped using the backslash () character. For example, "family_name = "Reddy"".

AttributeName: The name of the attribute to search for. You can only search for one attribute at a time.
Filter-Type: For an exact match, use =, for example, "given_name = "Jon"". For a prefix ("starts with") match, use ^=, for example, "given_name ^= "Jon"".
AttributeValue: The attribute value that must be matched for each user.

If the filter string is empty, ListUsers returns all users in the user pool.

You can only search for the following standard attributes:

username (case-sensitive)
email
phone_number
name
given_name
family_name
preferred_username
cognito:user_status (called Status in the Console) (case-insensitive)
status (called Enabled in the Console) (case-sensitive)
sub

Custom attributes aren't searchable.

For more information, see Searching for Users Using the ListUsers API and Examples of Using the ListUsers API in the Amazon Cognito Developer Guide.

<= 256 characters

Examples

Responses

🟢200Success

application/json

Body

The response from the request to list users.

Users

array[object (UserType) {7}]

optional

The users returned in the request to list users.

Username

string <password>

optional

The user name of the user you want to describe.

>= 1 characters<= 128 characters

Match pattern:

[\p{L}\p{M}\p{S}\p{N}\p{P}]+

Attributes

array[object (AttributeType) {2}]

optional

A container with information about the user type attributes.

UserCreateDate

string <date-time>

optional

The creation date of the user.

UserLastModifiedDate

string <date-time>

optional

The last modified date of the user.

Enabled

boolean

optional

Specifies whether the user is enabled.

UserStatus

enum<string>

optional

The user status. This can be one of the following:

UNCONFIRMED - User has been created but not confirmed.
CONFIRMED - User has been confirmed.
EXTERNAL_PROVIDER - User signed in with a third-party IdP.
ARCHIVED - User is no longer active.
UNKNOWN - User status isn't known.
RESET_REQUIRED - User is confirmed, but the user must request a code and reset their password before they can sign in.
FORCE_CHANGE_PASSWORD - The user is confirmed and the user can sign in using a temporary password, but on first sign-in, the user must change their password to a new value before doing anything else.

Allowed values:

UNCONFIRMEDCONFIRMEDARCHIVEDCOMPROMISEDUNKNOWNRESET_REQUIREDFORCE_CHANGE_PASSWORD

MFAOptions

array[object (MFAOptionType) {2}]

optional

The MFA options for the user.

PaginationToken

string

optional

An identifier that was returned from the previous call to this operation, which can be used to return the next set of items in the list.

>= 1 characters

Match pattern:

[\S]+

🟠480InvalidParameterException

🟠481ResourceNotFoundException

🟠482TooManyRequestsException

🟠483NotAuthorizedException

🟠484InternalErrorException

Modified at 2023-08-15 07:11:07