Recuperar usuarios con el endpoint get_users

Aprenda a obtener listas de usuarios mediante el endpoint get_users.

El endpoint GET /api/v2/users le permite obtener una lista de usuarios. Con este endpoint, puede:

• Buscar según diversos criterios
• Seleccionar los campos que se devolverán
• Ordenar los resultados devueltos

Este endpoint tiene consistencia eventual y, por lo tanto, recomendamos usarlo para procesos administrativos internos, como cambiar el nombre para mostrar de un usuario existente.

​

Ejemplo de solicitud

Para buscar usuarios, realiza una solicitud GET al endpoint /api/v2/users. La solicitud debe incluir un token de acceso de la Management API. Pasa la consulta de búsqueda al parámetro q y establece el parámetro search_engine en v3.

Por ejemplo, para buscar un usuario cuyo correo electrónico sea exactamente [e-mail], usa q=email:"[e-mail]":

Si la solicitud se realiza correctamente, recibirás una respuesta como esta:

[
  {
    "email": "[e-mail]",
    "email_verified": false,
    "username": "janedoe",
    "phone_number": "[phone]",
    "phone_verified": false,
    "user_id": "auth0|5457edea1b8f22891a000004",
    "created_at": "",
    "updated_at": "",
    "identities": [
      {
        "connection": "Initial-Connection",
        "user_id": "5457edea1b8f22891a000004",
        "provider": "auth0",
        "isSocial": false
      }
    ],
    "app_metadata": {},
    "user_metadata": {},
    "picture": "",
    "name": "",
    "nickname": "",
    "multifactor": [
      ""
    ],
    "last_ip": "",
    "last_login": "",
    "logins_count": 0,
    "blocked": false,
    "given_name": "",
    "family_name": ""
  }
]

​

Ejemplos de consultas

A continuación, se muestran algunos ejemplos de los tipos de consultas que puede realizar con la Management API.

Caso de uso	Consulta
Buscar todos los usuarios cuyo nombre contiene “john”	name:\*john\*
Buscar todos los usuarios cuyo nombre es exactamente “jane”	name:"jane"
Buscar todos los usuarios cuyo nombre comienza con “john”	name:john*
Buscar usuarios cuyo nombre comienza con “jane” y termina con “smith”	name:jane*smith
Buscar todos los usuarios cuyo correo electrónico es exactamente “[e-mail]”	email:"[e-mail]"
Buscar todos los usuarios cuyo correo electrónico es exactamente “[e-mail]” o “[e-mail]” mediante OR	email:("[e-mail]" OR "[e-mail]")
Buscar usuarios sin correo electrónico verificado	email_verified:false OR NOT \_exists_\:email_verified
Buscar usuarios que tienen el campo user_metadata llamado full_name con el valor “John Smith”	user_metadata.full_name:"John Smith"
Buscar usuarios de una conexión específica	identities.connection:"google-oauth2"
Buscar todos los usuarios que nunca han iniciado sesión	(NOT \_exists_\:logins_count OR logins_count:0)
Buscar todos los usuarios que iniciaron sesión antes de 2018	last_login:[* TO 2017-12-31]
Buscar todos los usuarios cuyo último inicio de sesión fue en diciembre de 2017	last_login:[2017-11 TO 2017-12], last_login:[2017-12-01 TO 2017-12-31]
Buscar todos los usuarios con un número de inicios de sesión >= 100 y <= 200	logins_count:[100 TO 200]
Buscar todos los usuarios con un número de inicios de sesión >= 100	logins_count:[100 TO *]
Buscar todos los usuarios con un número de inicios de sesión > 100 y < 200	logins_count:\{100 TO 200}
Buscar todos los usuarios cuyo dominio de correo electrónico es “exampleco.com”	email.domain:"exampleco.com"

​

Limitaciones

• El endpoint devuelve un máximo de 50 usuarios, aunque haya más usuarios que coincidan con tu consulta.

• Si necesitas devolver más de 50 usuarios, usa el parámetro page para mostrar más páginas de resultados. Cada página contiene 50 usuarios. Por ejemplo, puedes especificar &page=2 para mostrar los resultados 51-100, &page=3 para mostrar los resultados 101-150, y así sucesivamente. Sin embargo, este endpoint nunca devuelve más de 1000 usuarios en total con los mismos criterios de búsqueda, incluso con paginación.

• Hay un límite de 1 MB por usuario para los datos de usuario que se pueden indexar, consultar y devolver mediante el endpoint de búsqueda de usuarios. Para obtener más información sobre cómo esto afecta a los metadatos personalizados de más de 1 MB, consulta Nombres de campos de metadatos y tipos de datos. Debes usar el endpoint get user para recuperar todos los atributos del usuario de perfiles de usuario de gran tamaño.

• De forma predeterminada, el endpoint GET /api/v2/users devuelve los resultados en un orden determinista para que la misma consulta produzca resultados con el mismo orden lógico cada vez. Este comportamiento se controla mediante el parámetro de consulta primary_order:

  • primary_order=true (predeterminado): los resultados de consultas idénticas se ordenan de forma consistente.
  • primary_order=false: los resultados se devuelven en un orden no determinista, lo que puede mejorar el rendimiento en consultas complejas.

• Si tu aplicación no requiere un orden consistente en los resultados de búsqueda y tus consultas son lo bastante breves como para no depender de la paginación, establece primary_order=false para mejorar el rendimiento de las consultas.

• Si necesitas una exportación completa de todos tus usuarios, usa el trabajo de exportación o la extensión User Import / Export.

• Si recibes el error 414 Request-URI Too Large, significa que la cadena de consulta supera la longitud admitida. En ese caso, refina tu búsqueda.

No recomendamos que uses este endpoint para lo siguiente:

• Operaciones que requieren consistencia inmediata. En su lugar, usa el endpoint Get Users by Email o el endpoint Get Users by ID.
• Exportaciones de usuarios. En su lugar, usa el endpoint User Export.
• Operaciones que requieren la búsqueda de usuarios como parte de procesos de autenticación. En su lugar, usa el endpoint Get Users by Email o el endpoint Get Users by ID.
• Buscar usuarios para Account Linking por correo electrónico. En su lugar, usa el endpoint Get Users by Email.

​

Más información

• Sintaxis de consultas de búsqueda de usuarios
• Ordenar los resultados de búsqueda
• Ver los resultados de búsqueda por página
• Exportación masiva de usuarios