---
title: "Perform a server-side search."
method: POST
path: "/_matrix/client/v3/search"
tags: ["Search"]
---

# Perform a server-side search.

`POST /_matrix/client/v3/search`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v3/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/search/post.ts> (a function with typed inputs; its response is checked against the schema)

Performs a full text search across different categories.

## Query parameters

- `next_batch` string

## Request body

- object
  - `search_categories` object, required: Describes which categories to search in and their criteria.
    - `room_events` object: Mapping of category name to search criteria.
      - `event_context` object: Configures whether any context for the events returned are included in the response.
        - `after_limit` integer: How many events after the result are returned. By default, this is `5`.
        - `before_limit` integer: How many events before the result are returned. By default, this is `5`.
        - `include_profile` boolean: Requests that the server returns the historic profile information for the users that sent the events that were returned. By default, this is `false`.
      - `filter` object: This takes a [filter](https://spec.matrix.org/v1.19/client-server-api/#filtering).
        - `limit` integer: The maximum number of events to return, must be an integer greater than 0. Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
        - `not_senders` string[]: A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `senders` filter.
        - `not_types` string[]: A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `types` filter. A `*` can be used as a wildcard to match any sequence of characters.
        - `senders` string[]: A list of senders IDs to include. If this list is absent then all senders are included.
        - `types` string[]: A list of event types to include. If this list is absent then all event types are included. A `*` can be used as a wildcard to match any sequence of characters.
        - `contains_url` boolean: If `true`, includes only events with a `url` key in their content. If `false`, excludes those events. If omitted, `url` key is not considered for filtering.
        - `include_redundant_members` boolean: If `true`, sends all membership events for all events, even if they have already been sent to the client. Does not apply unless `lazy_load_members` is `true`. See [Lazy-loading room members](https://spec.matrix.org/v1.19/client-server-api/#lazy-loading-room-members) for more information. Defaults to `false`.
        - `lazy_load_members` boolean: If `true`, enables lazy-loading of membership events. See [Lazy-loading room members](https://spec.matrix.org/v1.19/client-server-api/#lazy-loading-room-members) for more information. Defaults to `false`.
        - `not_rooms` string[]: A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `rooms` filter.
        - `rooms` string[]: A list of room IDs to include. If this list is absent then all rooms are included.
        - `unread_thread_notifications` boolean: If `true`, enables per-[thread](https://spec.matrix.org/v1.19/client-server-api/#threading) notification counts. Only applies to the `/sync` endpoint. Defaults to `false`.
      - `groupings` object: Requests that the server partitions the result set based on the provided list of keys.
        - `group_by` object[]: List of groups to request.
          - `key` 'room_id' | 'sender': Key that defines the group.
      - `include_state` boolean: Requests the server return the current state for each room returned.
      - `keys` string[]: The keys to search. Defaults to all.
      - `order_by` 'recent' | 'rank': The order in which to search for results. By default, this is `"rank"`.
      - `search_term` string, required: The string to search events for

## Response `200`

Results of the search.

- object
  - `search_categories` object, required: Describes which categories to search in and their criteria.
    - `room_events` object: Mapping of category name to search criteria.
      - `count` integer: An approximate count of the total number of results found.
      - `groups` object: Any groups that were requested. The outer `string` key is the group key requested (eg: `room_id` or `sender`). The inner `string` key is the grouped value (eg: a room's ID or a user's ID).
      - `highlights` string[]: List of words which should be highlighted, useful for stemming which may change the query terms.
      - `next_batch` string: Token that can be used to get the next batch of results, by passing as the `next_batch` parameter to the next call. If this field is absent, there are no more results.
      - `results` object[]: List of results in the requested order.
        - `context` object: Context for result, if requested.
          - `end` string: Pagination token for the end of the chunk
          - `events_after` object[]: Events just after the result.
            - `content` object, required: The body of this event, as created by the client which sent it.
            - `event_id` string, mx-event-id, required: The globally unique identifier for this event.
            - `origin_server_ts` integer, required: Timestamp (in milliseconds since the unix epoch) on originating homeserver when this event was sent.
            - `sender` string, mx-user-id, required: Contains the fully-qualified ID of the user who sent this event.
            - `state_key` string: Present if, and only if, this event is a *state* event. The key making this piece of state unique in the room. Note that it is often an empty string. State keys starting with an `@` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user.
            - `type` string, required: The type of the event.
            - `unsigned` object: Contains optional extra information about the event.
              - …
            - `room_id` string, mx-room-id, required: The ID of the room associated with this event.
          - `events_before` object[]: Events just before the result.
            - `content` object, required: The body of this event, as created by the client which sent it.
            - `event_id` string, mx-event-id, required: The globally unique identifier for this event.
            - `origin_server_ts` integer, required: Timestamp (in milliseconds since the unix epoch) on originating homeserver when this event was sent.
            - `sender` string, mx-user-id, required: Contains the fully-qualified ID of the user who sent this event.
            - `state_key` string: Present if, and only if, this event is a *state* event. The key making this piece of state unique in the room. Note that it is often an empty string. State keys starting with an `@` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user.
            - `type` string, required: The type of the event.
            - `unsigned` object: Contains optional extra information about the event.
              - …
            - `room_id` string, mx-room-id, required: The ID of the room associated with this event.
          - `profile_info` object: The historic profile information of the users that sent the events returned. The key is the user ID for which the profile belongs to.
          - `start` string: Pagination token for the start of the chunk
        - `rank` number: A number that describes how closely this result matches the search. Higher is closer.
        - `result` object: The format used for events when they are returned from API endpoints such as `/sync`, where the `room_id` is implied elsewhere in the response.
          - `content` object, required: The body of this event, as created by the client which sent it.
          - `event_id` string, mx-event-id, required: The globally unique identifier for this event.
          - `origin_server_ts` integer, required: Timestamp (in milliseconds since the unix epoch) on originating homeserver when this event was sent.
          - `sender` string, mx-user-id, required: Contains the fully-qualified ID of the user who sent this event.
          - `state_key` string: Present if, and only if, this event is a *state* event. The key making this piece of state unique in the room. Note that it is often an empty string. State keys starting with an `@` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user.
          - `type` string, required: The type of the event.
          - `unsigned` object: Contains optional extra information about the event.
            - `age` integer: The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
            - `membership` string: The room membership of the user making the request, at the time of the event. This property is the value of the `membership` property of the requesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember) state at the point of the event, including any changes caused by the event. If the user had yet to join the room at the time of the event (i.e, they have no `m.room.member` state), this property is set to `leave`. Homeservers SHOULD populate this property wherever practical, but they MAY omit it if necessary (for example, if calculating the value is expensive, servers might choose to only implement it in encrypted rooms). The property is *not* normally populated in events pushed to application services via the application service transaction API (where there is no clear definition of "requesting user").
            - `prev_content` object: The `content` of the previous state event that was replaced by this event. This field is generated by the local homeserver, and is only returned if the event is a state event, and the client has permission to see the previous event.
            - `redacted_because` object: The event that redacted this event, if any.
            - `replaces_state` string, mx-event-id: The event ID of the state event replaced by this event. This field is generated by the local homeserver, and is only returned if the event is a state event. Unlike `prev_content`, this field is included regardless of history visibility.
            - `transaction_id` string: The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, if the client being given the event is the same one which sent it.
          - `room_id` string, mx-room-id, required: The ID of the room associated with this event.
      - `state` object: The current state for every room in the results. This is included if the request had the `include_state` key set with a value of `true`. The key is the room ID for which the `State Event` array belongs to.

## Other responses

- `400`: Part of the request was invalid.
- `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)