---
title: "Searches the user directory."
method: POST
path: "/_matrix/client/v3/user_directory/search"
tags: ["User directory"]
---

# Searches the user directory.

`POST /_matrix/client/v3/user_directory/search`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/user_directory/search`
- Auth: one of:
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v3/user_directory/search/post.ts> (a function with typed inputs; its response is checked against the schema)

Performs a search for users. The homeserver may determine which
subset of users are searched. However, the homeserver MUST at a
minimum consider users who are visible to the requester based
on their membership in rooms known to the homeserver. This means:

-   users that share a room with the requesting user
-   users who are joined to rooms known to the homeserver that have a
    `public` [join rule](#mroomjoin_rules)
-   users who are joined to rooms known to the homeserver that have a
    `world_readable` [history visibility](#room-history-visibility)

The search MUST consider local users to the homeserver, and SHOULD
query remote users as part of the search.

The search is performed case-insensitively on user IDs and display
names preferably using a collation determined based upon the
`Accept-Language` header provided in the request, if present.

## Request body

- object
  - `limit` integer: The maximum number of results to return. Defaults to 10.
  - `search_term` string, required: The term to search for

## Response `200`

The results of the search.

- object
  - `limited` boolean, required: Indicates if the result list has been truncated by the limit.
  - `results` object[], required: Ordered by rank and then whether or not profile info is available.
    - `avatar_url` string, uri: The avatar url, as an [`mxc://` URI](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris), if one exists.
    - `display_name` string: The display name of the user, if one exists.
    - `user_id` string, mx-user-id, required: The user's matrix user ID.

## Other responses

- `429`: This request was rate-limited.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)